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 3 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 a nicer way to tie in docstrings to the code. There's not enough predefined (but optional!) metadata. There's no good well-defined way to extend it if you want to go for it.

    Most people, though, seem to complain that POD isn't doing what they want, when what they want isn't what POD's supposed to do. (And I know you're not in this camp, Matt)

    So, anyone up for addressing POD's deficiencies in its well-defined area of applicability?
    • 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.