I suppose I would put the XML::Twig::Elt docs into XML::Twig::Elt itself (or, if you have the code for XML::Twig::Elt inside XML/Twig.pm, put the pod into XML/Twig/Elt.pod). The docs are so long, it's hard to get one's head around it all. Maybe even an XML/Twig/Tutorial.pod would be nice (is there one and I'm not aware of it? If so - please put that in XML::Twig's pod! :->). The tutorial itself could just be a cookbook TOC - and there could be XML/Twig/Tutorial/NewTwig.pod (starting without any XML), XML/Twig/Tutorial/Load.pod (loading from string/file), XML/Twig/Tutorial/Handlers.pod, etc.

Too flexible:

$ perldoc XML::Twig | grep -i same.*as | wc -l
     51
[download]

Don't get me wrong - XML::Twig is great. It has made me look good in my job (which is always important). And the fact that my successor on that project is creating XML by simply printing it out is, I'm sure, going to come back and bite him in the arse. (It's not quite the same physical project - just the same idea.) It just provides, in my experience, a significant learning curve. That said, when I chose to use it, I did look at as many of the XML parsers and handlers as I could on CPAN before choosing XML::Twig. And choose it I did. Because, as you sort of implied, it's the most perlish solution, IMO.

Let's see what I can do:

I suppose I would put the XML::Twig::Elt docs into XML::Twig::Elt

See, I hate that. I have answered countless questions about XML::Parser with just a link to the docs for XML::Parser::Expat, because a lot of people don't realize that part of the doc is there. And I hate navigating the docs for basically all DOM modules, because the method I want to read about is always in an other class, hence in an other file. But I have an HTML version of the docs where you can expand/collapse levels, at http://xmltwig.com/xmltwig/twig_dev.html . It has some quirks, but it is what I use normally.

Maybe even an XML/Twig/Tutorial.pod would be nice

There is a tutorial at http://xmltwig.com/xmltwig/tutorial/index.html . It wasn't written in POD but rather in XML, with all the source code in separate files, so it might be difficult for me to create a POD from it (is there an HTM2POD converter somewhere?)

I found many ways to set the tag (gi, set_gi, tag, set_tag, ... did I miss any?)

Actually set_gi and set_tag are the only 2 ways, the other ones just return the tag. I apologize for this one. I am an SGML guy and tags were called gi's back in the days, but after being mocked for years by the young XML crowd I finally broke down and added tag and set_tag as aliases for gi and set_gi respectively. So yes, guilty here, but most of my code uses the gi form, so I am kinda reluctant to deprecate it ;--(

You have a lot of options which duplicate each other. This simply helps obscure the unique options

Agreed. There (of course!) reasons for a lot of those:

• methods like tag/gi as already mentioned, where the domain vocabulary has changed in the lifetime of the module,
• methods that are internally the same but represent different things for the users: first_child_text and field are synonyms, as are has_atts and att_nb, but I thought it made sense to express them differently,
• methods that have a "Twig style" name but that also exist in the DOM or in HTML::Tree, like descendants and getElementsByTagName, and I agree this is probably overkill. Or at least I could document them separately,
• finally, and once again I guess I have to take the blame, some aliases are quite whimsical, like sort_children_by_value and sort_children_on_value, which are both available because I couldn't decide which one I prefered

In the end I guess all those aliases are a somewhat conscious design decision, to include everything and the kitchen sink in XML::Twig, to the point of indeed overwhelming users whith too many methods. It was also part of my master plan for for generating lucrative training gigs (no success there so far ;--(

I also found (maybe this is just me) that paste was counterintuitive.

You are not first one to think like this. I even added the, rather cryptic now that I read it again, The element is pasted sentence to the docs to warn users about it. I have now added a longer explanation. Note also that the method explecitely checks (and croaks) if the arguments appear to be reversed.

Thank you for your comments. As mentioned I slightly tweaked the docs, and I moved the paragraph about additional resources to the very top of the POD, so hopefully users will have an easier time going through the learning curve. I think that's the best I can do right now. I have known that I will have to rethink the docs and try to come up with more material for the tutorial for quite a while, but I keep finding new things to code instead!

I don't know anything about an HTM2POD converter, but holli has a very nice method for Turning HtmlDoc into Book.

HTH,




Update: There is an XML2POD example as part of Matt Sergeant's XML::LibXML 1.40 distribution.



planetscape

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 ;-)