I was thinking about taking this to email, but thought that others might like to jump in, or read this thread in the archives ... if they're really, really bored.

Your tutorial: Damn, I wish I had found it when I was writing my XML generator. :-) I would have one tiny suggestion. And I mean tiny. You said you're making it more prominent. My suggestion is to also make it prominent at the end of your perldoc. Specifically, in the SEE ALSO section. Same for the xmltwig.com site as a whole, and for the twig_dev.html page specifically. Key parts of your site should be mentioned in the SEE ALSO section to help idiots like me figure out that there really is important info on the xmltwig site that I would be interested in reading before submitting stupid requests (like "make a tutorial!") in public, making me look stupid, which is different only in the fact it's public now ;-), and wasting your time in defending the fact it already exists ;-). The latter part is hopefully a concern at least ;-)

As for gi/tag - I did miss one. set_name. I would suggest beefing up the docs on why I would want to choose one naming convention over another. For example, "If you're used to the SGML terms, use gi. If you're new to XML, these are called tags. Don't use name." Or something like that ;-)

I do understand why you're avoiding deprecating gi. Note, however, that just because something is deprecated doesn't mean it ever has to stop being there. Marking "gi" as "DEPRECATED - use tag/set_tag instead" doesn't mean you ever remove the gi code. It just tells users which one to pick for new code. IMO, that would be a good thing: it makes things clearer for us XML newbies, and would steer everyone to use the same language, since this is XML::Twig, not SGML::Twig that we're talking about here ;-)