docs for CPAN

cmac has asked for the wisdom of the Perl Monks concerning the following question:

I have a new module pretty much ready to submit to CPAN, and I'm writing documentation. So far a file called ABC.pod is close to done, and the following questions occur:

1. When I do "sudo make install" on my module, it seems to post a 'man' page:

Installing /usr/local/share/man/man3/XYZ::ABC.3
[download]

but a 'man XYZ::ABC' command on my FreeBSD 6.3 doesn't find it. Any ideas what's wrong?

2. ABC.pod has gotten about as big as anyone should want to look at, but there's still more stuff to describe. (Arrays are involved, which makes for lots of methods.) I want to make two subsidiary POD documents, one for the more esoteric methods and one to describe compatibility features with a module that mine replaces.

Q2: are there any guidelines for naming subsidiary .pod files? The L<> description in perlpod is clear enough, but doesn't include much about where/how it will recognize a page.

Q3: can anyone give me a link to a page or pages about the 'man' system? (I admit I haven't Googled for this yet but hopefully y'all are feeling indulgent toward dumb newbies...)

Thanks,
cmac
www.animalhead.com

Comment on docs for CPAN Download Code

Replies are listed 'Best First'.
Re: docs for CPAN by jasonk (Parson) on Feb 09, 2009 at 02:59 UTC
Any ideas what's wrong? You probably need to add /usr/local/share/man to your $MANPATH environment variable. can anyone give me a link to a page or pages about the 'man' system? Did you try 'man man'? www.jasonkohles.com We're not surrounded, we're in a target-rich environment!	[reply]
Re^2: docs for CPAN by cmac (Monk) on Feb 09, 2009 at 03:14 UTC
My system doesn't seem to have a $MANPATH environment variable. `echo $MANPATH` [download] yields a blank line! Yet many man commands produce output. `man man` doesn't include anything about the file naming conventions for man, nor about formatting codes although the conversion from .pod would hopefully take care of that... Anyway thanks for answering, cmac	[reply] [d/l] [select]
Re^3: docs for CPAN by jethro (Monsignor) on Feb 09, 2009 at 03:33 UTC
Check out the command 'manpath' which is used by 'man' to get the paths to search for manpages (at least on linux) Usually at the end of every man page is a paragraph 'See also' where you can find the names of other man pages that are thematically linked. In my case I see nroff mentioned (which is the name of the utility and of the language that the man pages use). Also I see man(7) which is another man page of man, just in another section. You can read that by issuing 'man 7 man' (if your version of man is similar to mine)	[reply]
Re^4: docs for CPAN by cmac (Monk) on Feb 09, 2009 at 16:57 UTC
Re^5: docs for CPAN by jethro (Monsignor) on Feb 10, 2009 at 02:20 UTC
Re^2: docs for CPAN by Bloodnok (Vicar) on Feb 09, 2009 at 17:52 UTC
...or run `man` with the `-M` option: `man -M/usr/local/share/man 3 ABC`, `man -M/usr/local/share/man -s 3 ABC` etc. - whichever options your system `man(1)` command implements in support of re-directing `man(1)` to an alternative location... A user level that continues to overstate my experience :-))	[reply] [d/l] [select]