[illumos-Developer] Man page section reorganization

[Gary Mills]

On Mon, Jun 27, 2011 at 09:37:06PM -0500, Mike Gerdts wrote:
> On Mon, Jun 27, 2011 at 9:15 PM, Gary Mills <mills at cc.umanitoba.ca> wrote:
> > Notice how we had to split off some of the command sections so that
> > ordinary users would not be confused by functions and files with the
> > same names at the commands they really wanted.  This is too
> > complicated.  Is there a better way?
> 
> Do not set MANPATH and let man(1) do the work for you, based on the
> contents of PATH.

My MANPATH example was from Solaris 10, where this magic is not
available.

> http://mail.opensolaris.org/pipermail/indiana-discuss/2008-January/003524.html

That is quite nice, although it only expands sections for certain
man page directories.  This example is from Solaris 11 Express:

    $ print $PATH   
    /usr/local/bin:/usr/bin:/opt/sunstudio12.1/bin:/usr/ccs/bin:/usr/sfw/bin:/usr/dt/bin:/usr/openwin/bin:/usr/sbin
    $ man -p
    /usr/local/share/man:/usr/share/man,1,1m,1s,1t,1c:/opt/sunstudio12.1/man:/usr/sfw/man:/usr/share/man

Obviously, $PATH only works for commands.  It eliminates duplicate
names by selecting the first one.  In searching for commands, the man
command should do the same.  Since the majority of CLI users only want
commands, this works pretty well.  It's not helpful if they are looking
for library functions or system calls.

Here's an example:

    $ man -l malloc
    malloc (3f)	-M /opt/SUNWspro/man
    malloc (3c)	-M /usr/man
    malloc (3malloc)   -M /usr/man

In this case, there's no way that the man command can determine which
one the user wants to see.

-- 
-Gary Mills-        -Unix Group-        -Computer and Network Services-