From owner-freebsd-doc@FreeBSD.ORG Mon Aug 22 02:00:43 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5BC8A16A41F for ; Mon, 22 Aug 2005 02:00:43 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id EDEF143D46 for ; Mon, 22 Aug 2005 02:00:42 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id j7M20g46054099 for ; Mon, 22 Aug 2005 02:00:42 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7M20gIv054098; Mon, 22 Aug 2005 02:00:42 GMT (envelope-from gnats) Date: Mon, 22 Aug 2005 02:00:42 GMT Message-Id: <200508220200.j7M20gIv054098@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Giorgos Keramidas Cc: Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Giorgos Keramidas List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 22 Aug 2005 02:00:43 -0000 The following reply was made to PR docs/85104; it has been noted by GNATS. From: Giorgos Keramidas To: "Gary W. Swearingen" 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" wrote: >Giorgos Keramidas 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