svn commit: r263110 - head/share/man/man4

[Warner Losh]

On Mar 14, 2014, at 10:41 AM, John-Mark Gurney <jmg at funkthat.com> wrote:

> Warner Losh wrote this message on Fri, Mar 14, 2014 at 08:30 -0600:
>> On Mar 14, 2014, at 3:13 AM, Christian Brueffer <brueffer at FreeBSD.org> wrote:
>> 
>>> On 3/14/14 2:54 AM, John-Mark Gurney wrote:
>>>> John Nielsen wrote this message on Thu, Mar 13, 2014 at 16:28 -0600:
>>>>> On Mar 13, 2014, at 10:19 AM, John-Mark Gurney <jmg at freebsd.org> wrote:
>>>>> 
>>>>>> Author: jmg
>>>>>> Date: Thu Mar 13 16:19:36 2014
>>>>>> New Revision: 263110
>>>>>> URL: http://svnweb.freebsd.org/changeset/base/263110
>>>>>> 
>>>>>> Log:
>>>>>> remove link to the missing AMD Geode LX SB man page... we can add it
>>>>>> back once someone cares enough to write one..
>>>>> 
>>>>> You mean like this one?
>>>>> http://svnweb.freebsd.org/base/head/share/man/man4/man4.i386/glxsb.4
>>>> 
>>>> The problems of checking on an amd64 box... :(
>>>> 
>>>> Actually, how are we suppose to handle links to arch dependant man
>>>> pages in arch independant man pages?  I did this check on an amd64 box,
>>>> so the page glxsb didn't get installed...  Should we just always
>>>> install these man pages on all arches then?  Or are we fine w/
>>>> references to non-existant pages (on some arches)?
>>>> 
>>>> Or should glxsb.4 be moved to an arch independant dir?
>>>> 
>>> 
>>> I wonder if it makes sense to keep arch-dependent man directories at
>>> all.  I.e., if I prepare an ARM disk image on my amd64 laptop, I really
>>> want to have the arm manpages available on that amd64 box.
>>> 
>>> Does anyone see a reason not to move man4/man4.${ARCH}/*.4 to man4?
>>> We're talking about 60 manpages here, so space is not really an issue.
>> 
>> Historically there was the separation because xp on one platform might be
>> radically different from xp on another platform. The other reason was confusion
>> because it wasn?t always clear if device foo actually worked on platform X.
> 
> We have less of that issue now, but it could still be.. but issues like
> that can be addressed other ways, though kernel config, release notes,
> etc..   I doubt people use manpages as a guage if a device worked on
> their arch...  Plus, if the device is shared and known not to work on
> a specific arch, that should be listed in the BUGS section of the man
> page.. :)

Yea, kinda my point :)

>> Do we have any collisions like that? If so, we need to resolve those first.
> 
> Doesn't look like it...
> $ grep ^_ Makefile  | sed -e 's/.4.*//' | wc -l
>      86
> $ grep ^_ Makefile  | sed -e 's/.4.*//' | sort -u | wc -l
>      86
> 
> It's also telling that besides i386 and amd64 specific man pages, we
> only have one mips specific man page in man4…

True enough, I hadn’t looked...

> This won't address the other man pages for arch specific utilities
> and libraries though, like sunlabel…

True, but those are niche things, so it is less important :)

>> Also, it would be good to tag the ones that are arm specific as such somehow.
> 
> Should we just tag the pages w/ a section listing relevant architectures,
> or break the beauty of single digit section numbers and do 4.i386?

Tag in the man page itself, either in its own unique section, or in BUGS.

> I just realized that we host man pages on FreeBSD.org, how do we make
> sure we get all of them for all arches?  Looks like we don't, as
> glxsb.4 isn't available…

I’d move them all into man4, which will solve this problem. The ones that are truly arch specific
should have BUGS entries added for them.

Warner