Fold into XML::LibXML?

[frioux]

This is a valiant effort, and I can admit that I have ignored the advice to use XML::LibXML before because the doc is so lacking. But hosting example docs for XML::LibXML on RTD is totally weird. Formatting them as POD and putting them in something like XML::LibXML::Manual or even XML::LibXML::Examples would be much more helpful. If you have questions I can help with that.

[grantm]

I'm not sure it's a weird as you think (minor nitpick, it's not actually hosted on Read the Docs it's just built using the same toolchain). There's plenty of precedent for writing about CPAN modules in a form that isn't hosted on CPAN.

Having written plenty of POD, I used this project as an opportunity to try something different and I've got to say overall the experiment was a success. The ability to quote sections of source Perl and XML files in the text is very useful. If I change one of the example scripts then the relevant references in the text update as well as the reference to the output produced by the script. To do the same thing in POD would either involve manually syncing the snippets of code and output into the POD or writing code to do it.

The XPath Sandbox probably wouldn't be possible in a POD module viewed via metacpan and integrating the "Try It" links from http://grantm.github.io/perl-libxml-by-example/xpath.html would be much harder.

A couple of thoughts come to mind

• The tutorial could be linked to from the LibXML POD
• The GitHub repo could be moved under https://github.com/Perl-XML if that made people feel more comfortable

I'd be interested in what other people think.

[frioux]

Well far be it from me to change how you run your project. I just know that if it's not POD it's not installed on my laptop, and if it's not installed on my laptop I'm probably not going to notice that it exists. Other people surely do things differently, it just doesn't seem worth it to self-host when it ends up meaning that the doc is a special snowflake. As for pod generation: yes, you'd have to use a library for that, but you are using a library/program to parse the reST, so I honestly don't see a huge difference.