docs/85104: keyboard(4) manpage hides behind Xorg version

[Giorgos Keramidas]

The following reply was made to PR docs/85104; it has been noted by GNATS.

From: Giorgos Keramidas <keramida at ceid.upatras.gr>
To: "Gary W. Swearingen" <garys at opusnet.com>
Cc: bug-followup at 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 at opusnet.com> wrote:
 >Giorgos Keramidas <keramida at 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 at gothmog:/home/giorgos$ man -k ^keyboard
 >> % keyboard(4)              - pc keyboard interface
 >> % keyboard(4x)             - Keyboard input driver
 >> % giorgos at 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