Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

Re: what would you like to see in perl5.12?

by EvanCarroll (Chaplain)
on Aug 19, 2007 at 19:45 UTC ( #633650=note: print w/ replies, xml ) Need Help??


in reply to what would you like to see in perl5.12?

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


Comment on Re: what would you like to see in perl5.12?
Re^2: what would you like to see in perl5.12?
by Anonymous Monk on Aug 20, 2007 at 09:01 UTC
    You do understand your suggestions have less than zero chance of being considered, much less approved?

      You do understand your anonymous comment has a less than zero chance of being considered constructively?

      Now if you make anonymous criticism but you justify said criticism, I might have a shred of respect for your opinion.

      Cheers,
      Ovid

      New address of my CGI Course.

        If you wanna play dumb... last check, CORE was set. Confuses pod with 'perldoc', pod with perl documentation, and then suggests wiki as better format, and continually craps on pod and how he hates pod because pod is crap.
Re^2: what would you like to see in perl5.12?
by stefp (Vicar) on Aug 28, 2007 at 15:59 UTC
Re^2: what would you like to see in perl5.12?
by massa (Hermit) on Aug 05, 2008 at 14:40 UTC
    I agree with the inclusion of Moose, but disagree with pod-bashing. :-)
    []s, HTH, Massa (κς,πμ,πλ)

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://633650]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chilling in the Monastery: (5)
As of 2014-08-31 04:59 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (294 votes), past polls