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 DBI.pm
$ podselect your_path_to_dbi/DBI.pm | pod2html > DBI.html
podselect and pod2html are part of PodParser, and should come pre-installed with Perl in most flavors of Unix.
update
A shortcut that skips the locate pass, as pointed by Juerd
$ podselect `perldoc -l DBI.pm` | pod2html > DBI.html
_ _ _ _
(_|| | |(_|><
_|
| [reply] [Watch: Dir/Any] [d/l] [select] |
|
| [reply] [Watch: Dir/Any] [d/l] |
|
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! ;)
jeffa
L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
F--F--F--F--F--F--F--F--
(the triplet paradiddle)
| [reply] [Watch: Dir/Any] |
Re: Who's afraid of the manual?
by davorg (Chancellor) on Jan 03, 2002 at 14:36 UTC
|
| [reply] [Watch: Dir/Any] |
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...
Greetz
Beatnik
... Quidquid perl dictum sit, altum viditur. | [reply] [Watch: Dir/Any] |
|
Beatnik,
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.
Thanks,
Dru
Another satisfied monk.
| [reply] [Watch: Dir/Any] |
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
-fen
PS: just another crazy idea popped in mynd right now: Doc::Random - The fortune of Docs ;-)
--
"WHAT CAN THE HARVEST HOPE FOR IF NOT THE CARE OF THE REAPER MAN"
-- Terry Pratchett, "Reaper Man" | [reply] [Watch: Dir/Any] |
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 http://www.perldoc.com) 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'
| [reply] [Watch: Dir/Any] [d/l] [select] |
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 | [reply] [Watch: Dir/Any] |
|
| [reply] [Watch: Dir/Any] |
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 toc.pl perlop
# perl toc.pl 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.
--
John.
| [reply] [Watch: Dir/Any] [d/l] [select] |
|
| [reply] [Watch: Dir/Any] [d/l] |
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.
| [reply] [Watch: Dir/Any] |