Slash Boxes
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.
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 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