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:~$

Replies are listed 'Best First'.
Re: Who's afraid of the manual?
by gmax (Abbot) on Jan 03, 2002 at 16:04 UTC
    In most Unix machines these lines also make you a ready-to-use HTML manual, with a pre-built index.
    $ locate $ podselect your_path_to_dbi/ | pod2html > DBI.html
    podselect and pod2html are part of PodParser, and should come pre-installed with Perl in most flavors of Unix.

    A shortcut that skips the locate pass, as pointed by Juerd
    $ podselect `perldoc -l` | pod2html > DBI.html
    _ _ _ _ (_|| | |(_|>< _|
      A module's path can be found using perldoc -l.

      I like pod2html, thanks.

      Still, I think a ToC should be in every doc, not just html versions

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

        The results of pod2html are nice - the program itself is a bit rusty - but that's not my point. I agree that a ToC should be in every doc, but what use is it when running commandline perldoc - you can't click on a chapter in the ToC and jump to it.

        Man, writing documentation is harder than writing the code! I recently designed a website to move some of the example usages OUT of my POD to make the POD more accessible, it was getting very large.

        I must point out my new discovery of CSS (blush). While designing that website, i was determined to not include the POD docs, because the point of the website was hold content not in the docs. However, when trying to link to other CPAN mirror's, i noticed that none of them were as up-to-date as i would like, and most of them did not turn URL's into links.

        So, i ran pod2html on my module and the CSS stylesheets took care of the rest. The result.

        Writing documentation is hard! ;)


        (the triplet paradiddle)
Re: Who's afraid of the manual?
by davorg (Chancellor) on Jan 03, 2002 at 14:36 UTC
Re: Who's afraid of the manual?
by Beatnik (Parson) on Jan 03, 2002 at 13:45 UTC
    Altho I do agree manuals can be REALLY handy, I must stress one of the 3 virtues of a Perl programmer... Yes, I do mean the lazyness.

    To many, Perl is the next best thing since sliced bread. Admit it or not but alot of people want to learn Perl and want to learn it as fast as possible. You'd be lying if you yourself were not peeking ahead in Perl books you were reading (like I did). My point being, it's all normal... but only those willing to learn alot, will eventually teach others.

    There is no certificate stating you are a qualified Perl Programmer (altho I do have 3 of those around here somewhere, next to my HTML Programmer certificate). People can claim to be a Perl programmer rather fast (and unfortunatly they do).

    This is a wonderfull Perl community and many have asked dumb/silly questions, many have asked questions that have been asked dozens of times before, many have ignored the manuals and asked what they wanted to know. It's nothing to be embarassed about. Answering those questions politly might just learn you something more yourself. How many times do you look up things in books and manpages, things you didn't really know alot about, things that bothered others? In some way others are motivating you to learn while they learn.

    Just my 2 cents...

    ... Quidquid perl dictum sit, altum viditur.

      I agree with you. I use to be one of those monks that would rather post my question to PM rather then looking for it in perldoc or a book. I learned through the replies of a few monks that I should be doing a better search for my answer before posting my question. I now spend a few hours looking for my answer before braking down and posting. I've learned so much using this method and I find myself posting less code related questions and helping less experienced monks more. Honestly, I hate posting questions about my code because I feel I should be able to find it, but many times I can not. Thank god for all of the fellow monks because I probably would have given up on Perl along time ago.

      Another satisfied monk.
Re: Who's afraid of the manual?
by Fengor (Pilgrim) on Jan 03, 2002 at 13:18 UTC
    My opinion is that good documentation allows you to find what you are looking for quickly. So I'm all for content tables in lengthy doc's (make that alll lengthy docs not only perl doc's ;)

    The bad thing about lengthy documentation is that it can be hard to read just because of the mass of information. A table of contents takes this whole mass of information and breaks it up in smaller more manageable parts.

    The two advantages of this are:

    • It's easier to find what u are searching for (humans tend o remember chapter numbers better than line numbers ;)
    • The documentation will be more read. Since you can read small chapter when u have a little bit of time left and read a longer chapter when you have more time

    just my 0.02 Euro

    PS: just another crazy idea popped in mynd right now: Doc::Random - The fortune of Docs ;-)

    -- Terry Pratchett, "Reaper Man"

Re: Who's afraid of the manual?
by Chmrr (Vicar) on Jan 03, 2002 at 13:19 UTC

    I agree -- the console-based perldoc is not the most easy to navigate beast around. However, it's very easy for other implementations of POD viewers to make tables of contents (Case in point: DBI and perlop pages from Perhaps the question to ask is, rather, should the command-line perldoc be made to print out tables of contents?

    perl -pe '"I lo*`+$^X$\"$]!$/"=~m%(.*)%s;$_=$1;y^`+*^e v^#$&V"+@( NO CARRIER'

Re: Who's afraid of the manual?
by TomK32 (Monk) on Jan 03, 2002 at 16:49 UTC
    As a TeX-User I don't see any sense in doing a additional ToC. It's better (i.e. easier to update) to collect all the =heads and generate the ToC automagically and maybe add the line/page.
    Don't forget: We don't do anything twice

    Uhh and my opinion on manuals in general (if you care):
    I won't read them until I need them!

    paco for president
    TomK32 - just a geek trying to change the world

      Well I like the TeX approach myself and i like the idea of an automagically created ToC, but as Juerd pointed out the possibility to create a ToC automagically should be in every Documentation not just TeX and HTML.


      -- Terry Pratchett, "Reaper Man"

Re: Who's afraid of the manual?
by jmcnamara (Monsignor) on Jan 03, 2002 at 20:16 UTC

    As a one-liner I would prefer something like this: perl -nle 'print "\t"x($1-1),$2 if /^=head(\d)\s+(.*)/' /somepath/perlop.pod Or as a short program:
    #!/usr/bin/perl -l # Call the program as follows: # perl perlop # perl Parse::RecDescent my $podfile = `perldoc -l @ARGV[0]`; exit if $?; open POD, $podfile or die "$podfile: $!.\n"; while (<POD>) { print " " x ($1-1), $2 if /^=head(\d)\s+(.*)/; }
    What do you think: should all lengthy Perl documentation have a table of contents?

    Unfortunately, it is too late to add a table of contents as a requirement for Perl documentation. However, it shouldn't be difficult to extend the above methodology to read a pod file, generate a table of contents, add it to a copy of the original pod as a section after NAME and redirect it to pod2text.


      perl -nle 'print "\t"x($1-1), $2 if /^=head(\d)\s+(.*)/' /somepath/perlop.pod
      Actually, I like the =item's to be in there too, and with that, =over comes in handy too. So full pod parsing is not really overkill :)
      Why the =item's? Because in many cases they provide a list of available function/method calls.

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

Re: Who's afraid of the manual?
by dws (Chancellor) on Jan 03, 2002 at 22:22 UTC
    In case of computer trouble, especially when it's coding trouble, the manual is your best friend.

    When I've been in trouble coding, I've generally found that the source code is my best friend, unless I need a "theory of operations" discussion, or need examples that I can't find in code.

    POD documentation is an interesting case, because you generally won't get it unless you also have code.