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)
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
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:
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
- 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
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||