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)

Friday December 14, 2001
11:45 AM

POD vs XML

[ #1649 ]

I was just reading in ziggy's journal that some people wanted to replace POD with XML because XML is sexier. And well, I'm an XML guy, so you'd think I'd be all for that.

I'm not. But not why you might think I'm not.

Let me just say right out that POD sucks. It really really sucks. It is fantastic though for what it was designed for, unfortunately it was really designed in Perl 4's day, and so while it's kinda good at documenting a module or script with a few functions, it's pretty bad at documenting an OO module with parameters and a class hierarchy, and so on.

POD is also pretty bad for extensibility - so many people have tried to add things like footnotes or tables to POD, and most have failed pretty badly.

Finally, and this really is the biggy: the POD spec is like the Perl spec. Non-existant. And yet there's many POD parsers (and only one Perl parser - perl), and they probably all get it wrong (despite the release of perlpodspec.pod). Take L... you can actually parse the same L different ways depending on what spec you read. And if you parse it the way perlpodspec says, you break documents in the wild...

XML solves all of these problems. But, it doesn't solve some of the problems that POD *does* solve, such as being easy to author (I know *I* find XML easy to author, but most other people don't (and you don't count, robin!)).

What I'd personally advocate is a better plugability layer for docs than =begin. That would allow us XML geeks to have tons of metadata that most people couldn't give a shit about. The plugability layer should work like an XML parser in many ways - where you get more information if more information is available, and it should work like SAX in some ways - it should present the same API to the user no matter what "plugin" doc format they've decided to use.

Anyway, I guess I've become one of ziggy's hated "ideas" people rather than an implementor :-)


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 vs XML 9 Comments More | Login | Reply /

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

  • Considering that one has to write documentation *first* in order to use POD. Too much complexity in what should be simple isn't really addressing the problem of not enough people document their modules. It's like people bitching about CPAN.pm yet they are usually the ones who either don't have a version or never bothered to read the documentation on what the appropriate version string is supposed to be. Close to 40% of the modules on CPAN either lack a version or POD or both. This isn't something XML is rea

  • I don't know that I'd go so far as to say that I hate the ideas people in Perl. Some of them have done some amazing work, spurring on patchers and committers. If anything, I'd classify myself in the ideas camp rather than the patchers. (Schwern accuses me of giving coming up with the idea for Semi::Semicolons; I rest my case about the ideafolk being mostly useless :-)

    I remember a couple of years ago falling into the "Replace POD to XML" camp, until tchrist set me straight. I've also been painfully aw

  • One of the things I notice when most people start going on about changing POD to do umpteen zillion things is they start off by profoundly missing the point. POD is a low-pain way of writing simple docs, low-pain enough so it's generally even less hassle than writing the code you're documenting. POD really doesn't do footnotes, or endnotes, or tables of contents, or hyperlinked documentation (yeah, I know, L does, but it's broken by design), or...

    It is deficient in some ways. L is just wrong. We could use
    • Let's get a few things straight.
      1. Usage of POD across CPAN is a separate issue, as is proper versioning of modules.
      2. POD is designed to simplify writing manpages
      3. *roff syntax really sucks. Kudos to the folks at Bell Labs for writing classic texts directly using *roff.
      4. POD sucks as a documentation format and as an authoring format
      5. POD sucks much less than *roff as an authoring format
      6. HTML is about 5 steps backwards, even starting with *roff
      7. TeX, TexInfo and TeX variants are pretty darn bad, too
      8. JavaDoc, Pyth
    • Yeah, I think we're in total agreement...

      The way I see addressing the problem is to create a POD API (not sure if POM is the right thing - I think we'd miss a streaming API) such that we could rip out POD and replace it with XML, when we needed that sort of power (or choose markup language X). It would have to cope with some sort of extensibility mechanism like XML Namespaces, so that we could define metadata tags (I use tags in the loosest sense of the word - they could be POD formatting constructs) in a
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.