Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
Good meditation! Here is my wishlist:
  • Moose made part of the standard distro, and a perl switch to turn it on.
  • A totally new documentation format, can we all just agree pod sucks... It's so old and dated. It comes off as a markup that was made for documenting the intention of code as to eliminate the need to comment-explain in source. It is instead used for writing verbose tutorials that sit uncomfortable and awkwardly in the middle of source.

    My solution would be some sort of wiki-powered pod, to which perldoc could sync to and read from the online Wiki. I'm not saying this wiki needs to be anon; and, I'm not putting any stipulations on its implementation. It should probably start off as an RFC right about now. Community powered, centralized documentation would ensure that perl stays a leg up on the doc component of the language, and it would alleviate the devs needs to doc everything. So often I find myself debunking bad docs, and then too lazy to push up an elaborate patch in the current sub-par format. I should clarify the word "doc" in this paragraph is a reference to tutorials, how-tos, use cases etc., not mere internal explanation. It is also my personal opinion that Textile is a superior markup to pod.

    As to the archaic pod, I think it serves a good purpose documenting code, but one feature I would like to see in it is the ability to further notate what the code chuck is you're documenting. I don't want to have to keep a sub in sync, inside of a pod block.

    Bottom line: Tutorials should not be in pod. They are not pod material, they are too often an interference to the terseness of perl. Put them online, and let's let the community take a crack at detailing the use of the code, and leave POD to the internal function of the code and dev-notes, i.e., what in most other languages is known as *comments* (as compared to "the documentation").

So thats my two cents, the two things I see perl5 most inept in can be almost totally fixed with the inclusion of Moose, and a better documentation system. (though I know how well accepted any criticism of pod will be)



Evan Carroll
www.EvanCarroll.com

In reply to Re: what would you like to see in perl5.12? by EvanCarroll
in thread what would you like to see in perl5.12? by ysth

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others scrutinizing the Monastery: (11)
    As of 2014-09-17 15:25 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (89 votes), past polls