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

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

POD vs XML 2 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • 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, Python's Docstrings and C#'s "XML Comments" are pretty bad, too

      So where does that leave us? There are lots of bad documentation formats -- both in terms of reading as source and authoring. So the best you can possibly hope for is to separate the display from the authoring, which is basically re-inventing SGML or XML (your choice). Even those options aren't wart-free.

      So taking all that into account, POD sucks, but it sucks much less than all of the other alternatives. Put another way, 20 well-written pages trumps 3 beautifully formatted pages or 5 metadata rich (and reusable) pages.

      But sometimes 20 pages of well-written text need the occasional table, hyperlink or bulleted list. POD goes about 80% of the way of hitting the 80/20 rule.

      So, anyone up for addressing POD's deficiencies in its well-defined area of applicability?

      We're working on it, and in a POD-friendly manner.

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.