David Haller said the following on 12/17/2013 11:42 PM:
Lack of documentation? There are some perl-programs in section 1 (e.g. "frozen-bubble") and probably some modules in section 3 (instead of 3pm).
And for the index the op searched, how about konqueror's "man:" io-slave, just enter 'man:(3p)' into konqueror's adress bar for the index of perl documentation (well, the konq from 3.5.10 and 4.7 are both broken and list all manpages in section 3 even if specifying 3pm). But well, it's a HTML-like index of manpages;)
And then there's e.g. tkman.
But do NOT forget about perldoc. Its -q, -f and -v options are extremely useful, c.f. e.g.: perldoc -v '$/' even though you could read up on that stuff in man perlfaq* perlvar perlfunc, perldoc's function is much more pratical. But generally man is faster than perldoc.
-dnh, documentation fetishist
I come from Aviation where documentation is an obsession that exceeds even that I encountered in the military and government. I recognise all that 'perldoc' can do. No criticisms there. But I also see that all the permutations of using MAN you describe are about what is available under "MAN". And that is the point I was trying to make. KISS as one command and not having to do lots of options because it is all set up in /etc/manpath.config and the environment variable. Yes you are right when you point out that the tools that build the the MAN index db come with the package. But those tools make use of what is in /etc/manpath.config. If a user adds new stuff ... ~/mydevelopmentsprojects/man ... then that needs to be added so that it gets indexed. Not different with perl documentation. By default MAN91) wants things in man/troff format, so ether convert, or supply the information to convert-on-the-fly using pos2man. I don't want to have different things for different apps, I want consistency. I want 'apropos' and 'man' to work with everything. I don't want to try using 'man', have it fail, then wonder if I should use 'perlpod'. There is the presumption implicit in that each language should have its own tools for doing documentation, that C code uses 'man', that there is another for shell scripts even if they are in /usr/bin, another for perl scripts so that 'man spamassassin' would not work but 'perlpod Mail::SpamAssassin' would. And so forth for awk, python and all the rest. Well $OBSCENITY that! Please note, that the cognitive load even of that example when dealing with "Mail::SpamAssassin" needs to the modules group -- "Mail" and that module name is in CamelCase. Compare with the simplicity of the MAN(1) version. There's nothing wrong with using perlpod. There's also noting wrong with using perl one-liners or shell one liners on the command line instead of scripts. maybe they are just use-once-and-throw-away. But I'd rather the Old Unix Way of having a general tool and its 'smarts' in a config file that having a lot of different, language specific ways of reading the documentation. Maybe I'm lazy. Maybe I'm 'A bear of Little brain and long-winded ways of doing things confuse me'. Maybe I believe in KISS. personally I like using apropos, as I've said many times. Using LOCATE(1) is good as well :-) Running "locate '*.pod'" would have answered the OPs original question as to the "WHERE", but not about how to read the documentation. Ah, and while 'man pod2man' returned nothing, 'locate pod2man' told me that the program was in /usr/bin. The "file ($locate pod2man)" tells me its a perl script and 'pod2man --help' produces the POD in man page format. If I want that accessible to MAN(1) I better use "pod2man $(locate pod2man)" and put the result in the man page hierarchy, possibly in the part I've reserved for pod-conversions :-) and entered in /etc/manpath.config. Then when 'mkwhatis' runs tonight, it will get indexed and 'man pod2man' will now work. Of course I can also run "file /usr/bin/* | grep 'Perl script'" to see what else is there and see what else doesn't already have a MAN page. Although since not every perl script will have embedded POD, perhaps this is a better way of finding those that do and are candidates for 'pod2man': grep -l "=head1" /usr/bin/* -- Better be despised for too anxious apprehensions, than ruined by too confident security. -- Edmund Burke -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org