Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much

docs for CPAN

by cmac (Monk)
on Feb 09, 2009 at 02:51 UTC ( #742318=perlquestion: print w/replies, xml ) Need Help??
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
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...)


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'?
    We're not surrounded, we're in a target-rich environment!
      My system doesn't seem to have a $MANPATH environment variable.
      echo $MANPATH
      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,

        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)

      ...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 :-))

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://742318]
Approved by GrandFather
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (2)
As of 2018-04-26 21:41 GMT
Find Nodes?
    Voting Booth?