Date: Mon, 22 Aug 2005 02:00:42 GMT From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: freebsd-doc@FreeBSD.org Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version Message-ID: <200508220200.j7M20gIv054098@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/85104; it has been noted by GNATS.
From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: "Gary W. Swearingen" <garys@opusnet.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Mon, 22 Aug 2005 04:50:13 +0300
On 2005-08-21 18:27, "Gary W. Swearingen" <garys@opusnet.com> wrote:
>Giorgos Keramidas <keramida@ceid.upatras.gr> writes:
>> The average Joe Random User has to learn about "apropos" and "man -k"
>> though. This is the canonical way of looking for manpages related to a
>> topic, and invoking either one of "apropos" or "man -k" shows there are
>> two manpages:
>>
>> % giorgos@gothmog:/home/giorgos$ man -k ^keyboard
>> % keyboard(4) - pc keyboard interface
>> % keyboard(4x) - Keyboard input driver
>> % giorgos@gothmog:/home/giorgos$
>
> OK, so JRU now knows about the two manpages. Show me what commands JRU
> uses to view each one (regardless of JRU's PATH value, I hope). But
> don't bother unless it's better than my awkward solution below.
The default PATH makes sure that /usr/{bin,sbin} programs are searched
before /usr/X11R6 and so are their manpages. The following commands
should then bring up different manpages:
% man 4 keyboard
% man 4x keyboard
>> The correct way to bring up manpages of section XX is to use "man XX",
>> so you shouldn't really expect to see keyboard(4x) by running:
>>
>> % man 4 keyboard
>>
>> The correct command:
>>
>> % man 4x keyboard
>>
>> pulls the correct manpage, so I don't see what the problem is :-/
>
> The problem is that JRU might, and I do, get the keyboard(4x) manpage
> no matter which of your commands we use, and as you say we "shouldn't
> really expect to see keyboard(4x) by running: man 4 keyboard".
This particular JRU and you have probably changed PATH so that X11R6 is
before /usr/bin and /usr/sbin. This is not a documentation bug or a bug
of man(1), I'm afraid.
> The other problem is that in order to see keyboard(4), one might have
> to do all this and know enough to do it:
>
> $ man -wa keyboard
> /usr/X11R6/man/man4/keyboard.4x.gz
> /usr/share/man/man4/keyboard.4.gz
> $ man -M /usr/share/man keyboard
Exactly. Fiddling with PATH in non-standard ways comes with a cost, but
not such a great cost. How difficult is it to use apropos(1), find out
that there are multiple manpages and then use -M /path/to/man? IMHO,
it's not too much to expect by someone who knows enough about PATH and
changing its default value.
Considering that -M is the very first option described in the man(1)
manpage, it shouldn't be very difficult to find out how to locate and
read manpages from arbitrary paths.
- Giorgos
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508220200.j7M20gIv054098>