For the last couple of days I've been grappling with POD.
POD is a real pain in the ass. It's fairly decent to author (for the right kind of docs), but there really are no good and complete parsers for it. I've done this rant before so I won't bore you with it again.
Anyway, I've now re-written Pod::SAX twice in two days. Originally it used Pod::Tree, but I decided in the end I wasn't willing to fight against it's bugs and crappy parsing (e.g. it always gave buggy results when parsing strings) and/or wait for a module update.
So then I switched to Pod::POM, which being an Andy Wardley module I expected to be first rate. But it seemed to be focused too strongly on outputting POD to either a string or a filehandle, rather than on doing something like SAX over the top.
So finally I've gone full circle and back to Pod::Parser. Now I really hate Pod::Parser, because it seems almost entirely focussed on outputting some alternative format to Pod to a file or STDOUT. But it *is* possible to circumvent that. So I did. And although I had to write my own link parsing code, and my own E parser, and my own code for doing nested =item tags, and my own code for... (well you get the picture)... it's now pretty decent, and I'm happier with it's output.
0.03 is now on CPAN.
Seems to me things like Pod::Parser and so on could be reimplemented in Pod::SAX, right? Pod::SAX could become the new central module at the heart of it all? But I'm not a SAX/XML guy [yet], so I don't really know.
Re:POD::SAX as a building block
Matts on 2002-06-13T15:16:18
Sadly it's really hard to persuade non-XML people to use SAX, and I'm really sick and tired of trying in the face of ignorance.
The reality is you're absolutely right - people could use Pod::SAX as a much simpler Pod parser. But they won't, because they see XML and moan that it's harder than plain perl. *shrug*Re:POD::SAX as a building block
jdavidb on 2002-06-13T15:28:54
I'd be interested in reading anything along the lines of "Here's why SAX is the greatest thing since sliced bread" aimed at people who understand but have not used XML. Any links you can recommend?
Re:POD::SAX as a building block
darobin on 2002-06-17T14:59:47
I'd say that's our weakness. There's not much out there about SAX for that kind of audience. I think that somehow we were so convinced of SAX's simplicity that we more or less silently thought everyone with minimal XML knowledge would find it obvious. Experience shows that that's not the case, and people do seem to try to look for complexity where we can't see it. There must be a reason
:) There are however a few resources. Some of Kip's articles on xml.com do talk about SAX, with some nifty examples. A fair amount of the SAX code on CPAN is really simple and shows just how trivial it can be (for that you might want to look inside XML::Filter::BufferText or XML::RDDL. The first is a really simple SAX filter, and the second has trivial SAX handler and driver). You also have http://sax.perl.org/. And of course, #axkit, #axkit-dahut, and the perl-xml list which are often the best places to get info.
Part of the problem here is also that there's no good answer to the question as you phrase it. SAX is more a generic approach to solving problems than a solution in itself. There are cases in which SAX definitely beats sliced bread, and others in which it sucks. And telling between the two does require some experience and a "feel" for what'll work as there's no set of rules that can really help you decide.
Re:POD::SAX as a building block
jdavidb on 2002-06-17T16:46:38
Thanks for the info!
There are cases in which SAX definitely beats sliced bread, and others in which it sucks.
Of course. I knew that going in. Even Perl isn't suited for everything, and good Perl programmers almost universally admit it, I think. (Although issues for which Perl is not suited are fewer and further between as time goes by, it seems.) If I thought SAX adherents wanted to throw SAX at every problem, I wouldn't trust it and wouldn't be asking.
:) But since I've seen people I respect (e.g. Matt) talk about SAX, while also showing that they are quite competent with solving problems without SAX (at least Time::Piece, and probably SpamAssassin (does SpamAssassin involve SAX?)), then I know that I'm looking at a useful technology that's worth learning. Someday. Re:POD::SAX as a building block
autarch on 2002-06-13T15:38:36
Well, I for one am not a big XML fan but I like SAX a lot. I like event-based parsing a lot too. Hell, I wrote one of my own for Mason. In retrospect, I wonder if I should have just used SAX. But at the time, Perl SAX tools were not plentiful as they are today. Oh well, a Mason-to-SAX module would be simple to add.
Anyway, Pod::SAX looks quite interesting and I'm hoping to use it for translating the Mason book (which is in POD) to HTML for the masonbook.com website (nothing there yet folks, sorry).
I've used POD::POM for custom HTML translation and that worked pretty well too, though it could use some more docs in a few areas and I ended up poking about in the POD::POM code.Re:POD::SAX as a building block
ask on 2002-06-13T22:45:54
We want a lightning talk. Or a 2 page tutorial.
And are you finding Pod::Escapes useful?
That reminds me: now that my book is done, I can finally go back to finishing up the new Pod parser, which I am tempted to declare the reference implementation, for lack of any particular alternative.
Re:Pod
Matts on 2002-06-14T07:34:17
I'm using Pod::Parser for the main parsing. For figuring out what type a =item block is I borrowed the code from Pod::Tree. For extracting links, I borrowed the code from Pod::ParseLink. For E thingies, I just embeded a shed load of hash entries for transforming them;-)
I haven't used Pod::Escapes, and I have no idea what's a good test for perlpodspec compliancy.
