|go ahead... be a heretic|
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?