[illumos-Developer] Layout of man sections

[Erik Trimble]

On 6/26/2011 8:09 PM, Garrett D'Amore wrote:
> I concur largely.  The seperate sections may help when similar symbols are provided by different libraries (perhaps for different languages.)
>
> I would not mind seeing a number without a suffix search the other sections starting with the same number though.
>
> Albert Lee<trisk at opensolaris.org>  wrote:
>
>> 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
>>

I'm generally with Garrett and Albert here, in that subsection searching 
is nice (with the stipulation that bare numbers do wildcard searches for 
that number AND all subsections beginning with that number)


While I'm normally a stickler for trying to maintain the "SysV" feel of 
Solaris, if the SVID doesn't actually ever specify where man pages are 
supposed to be, I'd be in favor of moving to the BSD/Linux 
conventions.   It would likely make adding 3rd party software more 
consistent.  There's no need to retain the old convention numbering if 
there's no real reason, other than tradition.

-- 
Erik Trimble
Java Platform Group Infrastructure
Mailstop:  usca22-317
Phone:  x17195
Santa Clara, CA
Timezone: US/Pacific (UTC-0800)