Manpage interpreter

[Giorgos Keramidas]

On 2004-12-24 13:37, Nikolas Britton <freebsd at nbritton.org> wrote:
>Giorgos Keramidas wrote:
>>>It's even been known to happen that man pages can get revised (though
>>>I think my experience with this was with OpenBSD).
>>

>> This happens with FreeBSD all the time too.  When something is
>> confusing, and the freebsd-doc team learns about it, we do try to
>> reword the confusing parts, even rewrite entire sections of the
>> manpages.
>>
>> The important bit here is that we have to be told what *is* confusing :)
>
> 1. The man page for nice is misleading, it says to use "nice -n num#
> command" but we all know that won't work "nice: Badly formed number." it
> should say "nice -/+num# command"

What version of FreeBSD are you using?  The manpage matches the behavior
of the utility here, but this is FreeBSD 6.0-CURRENT.

  % $ nice -n 12 ls -l /dev/null
  % crw-rw-rw-  1 root  wheel    2,   2 Dec 24 21:40 /dev/null
  %
  % $ nice -n +12 ls -l /dev/null
  % crw-rw-rw-  1 root  wheel    2,   2 Dec 24 21:40 /dev/null
  %
  % $ nice -n -12 ls -l /dev/null
  % nice: setpriority: Permission denied
  % crw-rw-rw-  1 root  wheel    2,   2 Dec 24 21:40 /dev/null

The manpage also says:

  % COMPATIBILITY
  %     The traditional -increment option has been deprecated but is
  %     still supported.

> 2. Secion 7.2.3 (Utilizing Multiple Sound Sources) implies that
> hw.snd.maxautovchans is only usefull for kernel loadable sound modules,
> this is not true:
>
> "To set the number of virtual channels, there are two sysctl knobs
> which, if you are the root user, can be set like this:
>
> # sysctl hw.snd.pcm0.vchans=4
> # sysctl hw.snd.maxautovchans=4
>
> The above example allocates four virtual channels, which is a practical
> number for everyday use. hw.snd.pcm0.vchans is the number of virtual
> channels pcm0 has, and is configurable once a device has been attached.
> hw.snd.maxautovchans is the number of virtual channels a new audio
> device is given when it is attached using kldload(8). Since the pcm
> module can be loaded independently of the hardware drivers,
> hw.snd.maxautovchans can store how many virtual channels any devices
> which are attached later will be given."

I see.  Do you think it's ok if I mention attaching at boot time too,
e.g. like this?

      The above example allocates four virtual channels, which is a
      practical number for everyday use. hw.snd.pcm0.vchans is the number
      of virtual channels pcm0 has, and is configurable once a device has
      been attached.  hw.snd.maxautovchans is the number of virtual
  -   channels a new audio device is given when it is attached using
  -   kldload(8).
  +   channels a new audio device is given when it is attached at boot
  +   time or when loaded as a module with kldload(8).

Does this seem better? :-)

- Giorgos