By popular request, I have released an underdocumented beta of my new Pod parser framework. It's called Pod::Simple, and it's entering CPAN as Pod-Simple-0.90.tar.gz right now. If your nearest CPAN mirror doesn't have it yet, you can get it right from here: http://members.spinn.net/~sburke/Pod-Simple-0.90.tar.gz
I'm sure people have many questions that would have been answered in the documentation, if it were complete. Feel free to ask me! You can ask on the list, since I'm sure if you have a question, then others probably have the same question. Also, interested developers should look at the .t files, which contain hundreds of examples of Pod input and the XML output that it should produce. I suppose I should say a few words of introduction to Pod::Simple. So here goes: Pod is meant to be easy to write, but it's not easy to parse. However, Pod::Simple handles all the syntactic vagarities of Pod, and basically it gives you (as a programmer who wants to process Pod) some interface thru which you can mostly pretend that Pod is just like XML -- namely, that tags are nested properly, that elements often carry useful data as attributes in their start-tags, and so on. Even the style of the interfaces should be very familiar to programmers used to munging XML. As I have said before, I want Pod::Simple (once it is more tested and is completely documented) to replace Pod::Parser, which I want to deprecate. I want all the important formatters (and processors) to change from using Pod::Parser to using Pod::Simple. I hope this should be straightforward and actually /pleasant/, and I will help out wherever possible. The current Pod::Simple dist even contains some rudimentary modules for turning Pod into plaintext or HTML. The HTML module (Pod::Simple::HTML) is not finished yet; but I intend it to replace the current (appalling) Pod::Html soon. Formatter authors may want to look at the source to Pod::Simple::HTML and Pod::Simple::Text. My goals for Pod::Simple have been to make it comply to perlpodspec, to make it do as much work as possible for the programmer who's writing a Pod processor, and to make it as robust and forgiving as possible (i.e., to DWIM) in treating malformed Pod input. Pod may be a "simple" markup language, but there's no reason why it shouldn't have good, solid, modern parser interfaces. The mere facts that some older Pod parsers were bad and that some of the older documentation for the Pod format was sketchy, don't make Pod a bad language. It just means that people want it to Do What I Mean, and are frustrated when it doesn't. I have tried to make things all better now. The code inside Pod::Simple is some of the hardest I've ever written in my life. It feels like I ended up pulling out every mind-bending trick I used in HTML::TreeBuilder and then some. Hopefully the resulting code is still quite readable, without revealing how hard it was to come up with. And much more importantly, I hope I have gotten the API to totally hide the complexity of the underlying code. Moreover, the code seems to be passably fast on typical cases. Even on perltoc.pod (a case of almost pathological complexity and length) it is quite well-behaved. In writing Pod::Simple, I have thought mostly of the tasks of writing Pod formatters. I would like to hear from the authors of other sorts of Pod processors (i.e., authors of Pod utilities) to hear if they see ways I can make the Pod::Simple modules easier for them to use -- in thinking more about formatting than general processing tasks, I may have overlooked useful features. Now, everyone, Try It And See. -- Sean M. Burke http://www.spinn.net/~sburke/