Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
In case of computer trouble, especially when it's coding trouble, the manual is your best friend. The manual will tell you what the possibilities are and how things should be used. Most manuals have examples to get you started and they explain the unknown.
But someone disagreed. He didn't like manuals. He had read some but now just tries to figure out things himself. He only reads the synopsis. So of course I asked why he didn't read manuals.

"They're too long and too hard to understand", he said. Together we looked at some documentation. He was using DBI, so I fired up perldoc DBI and immediately understood what he meant. We read the frightening manual. While the synopsis of this particular document describes all important syntax, it's not useful at all to start coding right away. There's the mysterious $dbh and $sth. Only those who still have the courage to continue reading will know that those aren't DataBase Hell and SomeTHing.
Then, we looked at perlop, because I wanted to show how one can use alternative delimiters. (Note: his code had \" all over the place) I knew where to look, just because I had once read the entire document when I had the time. But if you don't know what's in there, the only way to find out, is to actually scan everything.
Both documents we looked at have thousands of lines and most of the time you only need a few of them.

Together, we came to the following conclusion:
Lengthy documentation should have tables of contents.

Using perl -ne'print "$_\n" if /^=/' /usr/share/perl/5.6.1/pod/perlop.pod | pod2text we made ourselves a rough index. Similarly, perl -ne'print "$_\n" if /^=/' `perldoc -l DBI` | pod2text created a useable outline of the DBI document. It was still too much information, but it was useable.

What do you think: should all lengthy Perl documentation have a table of contents?

2;0 juerd@ouranos:~$ perl -e'undef christmas' Segmentation fault 2;139 juerd@ouranos:~$


In reply to Who's afraid of the manual? by Juerd

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



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (2)
As of 2021-12-08 03:52 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    R or B?



    Results (34 votes). Check out past polls.

    Notices?