[illumos-Developer] Man page section reorganization

[Gary Mills]

Was it here that I saw a brief discussion of man page reorganization?
I no longer have the original messages, but I do have a few comments.

Yes, one problem is the divergence in section numbers between SysV and
BSD Unix.  That's not the major problem, however.  It is: how to
handle duplicate names.  The way to do this depends on who you are.
Ordinary users, at least the few who still use the CLI, want to see
the commands in section 1.  This is the MANPATH we provide at work:

    /usr/sfw/man,1,1m,l:/opt/SUNWspro/man:/usr/man:/usr/sfw/man,3,4,5,7,6,8,n:/usr/local/man:/opt/csw/man:/usr/X11/man:/usr/dt/man:/usr/openwin/man

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?

Sysadmins want to see commands in section 1m and file information in
sections 4 and 5.  Even the latter are disappearing as file formats
become undocumented, replaced by comprehensive system administration
commands.

Developers want to see functions and system calls.  They are condemned
to using `man -l' because there's no other way to see all of the
section suffixes.  Fortunately there are so few developers and they
are sufficiently technically-inclined that they can figure out these
things on their own.

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