Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

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

by EvanCarroll (Chaplain)
on Aug 19, 2007 at 19:45 UTC ( [id://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?

Replies are listed 'Best First'.
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 (κς,πμ,πλ)
A reply falls below the community's threshold of quality. You may see it by logging in.

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others chanting in the Monastery: (7)
As of 2024-04-19 10:32 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found