[illumos-Developer] Man page section reorganization

[Mike Gerdts]

On Tue, Jun 28, 2011 at 7:43 AM, Gary Mills <mills at cc.umanitoba.ca> wrote:
> 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.

Yeah, I've recently noticed that as well.  It seems as though the
MANPATH it constructs should be more along the lines of:

/usr/local/share/man,1:/usr/share/man,1,1m,1s,1t,1c:/opt/sunstudio12.1/man,1:/usr/sfw/man,1:/usr/local/share/man:/usr/share/man:/opt/sunstudio12/man:/usr/sfw/man

Notice that the 1* sections appear in the list first, followed by all
the rest.  Presumably the code would look in each man (or share/man)
directory for directories matching 1* to form the section list.  This
would get rid of some of the special case code for /usr/share/man.

-- 
Mike Gerdts
http://mgerdts.blogspot.com/