[illumos-Developer] Layout of man sections

[Albert Lee]

On Sun, Jun 26, 2011 at 9:40 PM, Yuri Pankov <yuri.pankov at gmail.com> wrote:
> Hi,
>
> I guess I already know the answer, but have to ask anyway.. :-)
>
> What do you all think about dropping the (useless, as there shouldn't be
> duplicate pages) manpage section suffixes (there's more than 60 for
> section 3, for example) and switching the sections to match those found
> on BSD and Linux systems:
>
> 1, 2, 3 and 9 not changed
> 1m (system administrator) becomes 8
> 4 (formats) becomes 5
> 5 (misc, standards, env., etc.) becomes 7
> 7 (special files) becomes 4
>
> There's no defined reason for doing this really (other than me using
> other OSes and finding the differences disturbing).
>
> Thanks in advance for any feedback..
>

We are an SVR4 derivative, so we use System V man page section names,
whereas BSD followed the convention from System III and earlier (and
Linux uses the BSD scheme). (I don't know why it changed between
System III and V, though. Does anyone? [1]).

System V used to be much more common than it is today, so the section
names only became a "problem" as other Unixes died out. One possible
way to kill two birds with one stone is to give man(1) a "BSD
compatibility" feature when invoked as 'man <section> <name>' where it
translates BSD names to SysV.

The suffixes have bothered me for a while, but I think the
classification of functions by library is useful and the right
solution is to make man search with suffixes (so that e.g. both 'man
-s 3SOCKET bind' and 'man -s 3 bind' work).

I'd be okay with aliasing section 1M to 8, which is not reserved for
anything else (although we already have a few pieces of software using
8, probably due to lazy packaging).

[1] Still haven't found where SVID, the SysV standard, specifies the sections
-Albert