use Perl

• POD isnt' so bad (Score:2)

  by hfb (74)

  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
  • Re:POD isnt' so bad (Score:1)

    by darobin (1316)

    I don't think Matt's idea was to add complexity. He wants to add power. Now, I know that the two often walk in pairs, the latter as the intention and the former as the result.

    I'm not in the camp of people that want to make Perl's documentation XML-based [mpe.mpg.de] (though I've come closer to it since that post, mostly for "enterprise" stuff and not for core Perl) but I could definitely use some extra metadata. The ActiveState people have been working on that (IIRC) and I'd love to hear about the output of th

    --
    

    -- Robin Berjon [berjon.com]
    • Re:POD isnt' so bad (Score:1)

      by TorgoX (1933)

      There's always writing HTML in the editor of your choice, and feeding it to Pod::HTML2Pod. It's crazy, but aren't we all?
      Try it some time!
• "Hated" ideas people? (Score:2)

  by ziggy (25)

  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
  • Replace Parrot with a scheme engine? (Score:1)

    by pdcawley (485)

    Can't say I've come across that meme in the wild.
    
    Plenty of scepticism about the whole Perl 6 enterprise, but I've not seen the 'use scheme' thing.
    • Re:Replace Parrot with a scheme engine? (Score:2)

      by Elian (119)

      The 'use scheme' stuff's part of the aftermath of the LL1 workshop held at MIT in November. links off of the website for it [mit.edu] somewhere.
• Maybe we need to nail the problem (Score:2)

  by Elian (119)

  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
  • Re:Maybe we need to nail the problem (Score:2)

    by ziggy (25)

    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
  • Re:Maybe we need to nail the problem (Score:1)

    by Matts (1087)

    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