Whoa. What?
Yeah.
Here's the deal: the new-style (Inkscape::)XML::* APIs were originally created with the intent to allow alternate internal document representations. For instance, one document might have a simple in-memory document based on in-memory XML::SimpleNodes, while another might have nodes backed by a remote database (with its own wrapper XML::Node subclasses). This ability would be beneficial for things like inkboard, as well as properly implementing DOM.
The problem is that the continuing use of sp_repr_new prevents us taking advantage of this ability. As long as nodes are created independently of the document they'll ultimately be added to, all documents have to be using the same node classes so that nodes are interchangeable.
So, the plan is to begin creating all nodes via XML::Document::createElement, XML::Document::createTextNode, and XML::Document::createComment.
In theory you should be able to get the right XML::Document * from the parent node you intend to attach the new node to (via XML::Node::document), but because of the behavior required by sp_repr_new, not all parents are guaranteed to have a valid document, preventing us from doing things the simple way.
So, right now, you've got several places you can potentially get the required XML::Document * from, in order of roughly decreasing preference:
SPDocument *, using sp_document_repr_doc()
SPObject *, via the SPDocument * you get from SP_OBJECT_DOCUMENT
SPDesktop * (SPView *), via the SPDocument * from ->doc()
SPEventContext *, via the SPDocument * from SP_EVENT_CONTEXT_DOCUMENT
Thankfully, it won't be this bad forever. Once sp_repr_new is gone and some other changes are made, we'll be able to get document pointers in more convenient ways.
-mental