Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Matts (1087)

Matts
  (email not shown publicly)
I work for MessageLabs [messagelabs.com] in Toronto, ON, Canada. I write spam filters, MTA software, high performance network software, string matching algorithms, and other cool stuff mostly in Perl and C.

Journal of Matts (1087)

Thursday June 13, 2002
09:06 AM

Pod

[ #5630 ]

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.


List all Journal entries
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Pod 9 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.

  • 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.

    --
    J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
    • 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*

      • 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?

        --
        J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers

        • 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 example

          --

          -- Robin Berjon [berjon.com]

          • 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.

            --
            J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
      • 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'v

      • We want a lightning talk. Or a 2 page tutorial.
        --

        -- ask bjoern hansen [askbjoernhansen.com], !try; do();

  • Have you been making good effort to make your Pod processor perlpodspec-compliant?

    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.

    • 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.
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.