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
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
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.