Thanks, that's exactly what I need.

For recording the information in the element, I would use the regular att() feature. E.g. $elt->set_att('#line', $line);

That follows the example of #PCDATA which uses # for a "special" name used like an identifier.

A more direct answer to the last question is yes, document an extension mechanism rather than relying on the object's implementation. Simply providing a hashref where users can store their stuff is an sufficient. A fancier way would be to provide a way to manage it so different users don't clobber each other, but convention can do just as well: tell them to use their fully-qualified module name as the start of the key.

—John