From garys@opusnet.com  Fri Aug 19 00:43:54 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 43F1916A422
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 19 Aug 2005 00:43:54 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id F2ADD43D45
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 19 Aug 2005 00:43:53 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AB484C200A0; Thu, 18 Aug 2005 17:43:52 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7J0ivst001117
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 18 Aug 2005 17:44:57 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7J0iqqw001116;
	Thu, 18 Aug 2005 17:44:52 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <hmu0hmsqkb.0hm@mail.opusnet.com>
Date: Thu, 18 Aug 2005 17:44:52 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: keyboard(4) manpage hides behind Xorg version
X-GNATS-Notify:

>Number:         85104
>Category:       docs
>Synopsis:       keyboard(4) manpage hides behind Xorg version
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Aug 19 00:50:20 GMT 2005
>Closed-Date:    Mon Aug 22 03:26:30 GMT 2005
>Last-Modified:  Mon Aug 22 03:26:30 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

On systems with X11 installed, the FreeBSD keyboard(4) manpage can
be hidden by the X11 version:

    $ man -w keyboard
    /usr/X11R6/man/man4/keyboard.4x.gz

    $ man -wa keyboard
    /usr/X11R6/man/man4/keyboard.4x.gz
    /usr/share/man/man4/keyboard.4.gz

It seems wrong to force users to use and to know to use:

    man -M /usr/share/man keyboard

or have them fix up /etc/manpath.config and have the X11
version ignored instead.

>How-To-Repeat:
>Fix:

Debatable.  This could be considered a sysadmin's problem.

Both manpages seem out of place in section 4, so I suggest
moving moving FreeBSD's to section 7 and worry about all
of the misplaced X11 manpages in a different PR.

Unfortunately, references to keyboard(4) in these manpages would need
to change to keyboard(7):

kbdcontrol.1
vidcontrol.1
pcvt.4
screen.4
syscons.4
syscons.4
vt.4
sc.4
sc.4
kbdmap.5
keymap.5
moused.8

I'll write manpage patches if some change is agreed upon.
>Release-Note:
>Audit-Trail:

From: Dejan Lesjak <dejan.lesjak@ijs.si>
To: bug-followup@freebsd.org,
 garys@opusnet.com
Cc:  
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Mon, 22 Aug 2005 02:07:04 +0200

 Getting keyboard manpage seems to work as expected here:
 
 % man -w keyboard
 /usr/share/man/man4/keyboard.4.gz
 
 % man -wa keyboard
 /usr/share/man/man4/keyboard.4.gz
 /usr/X11R6/man/man4/keyboard.4x.gz
 
 Putting manpages from X11 into 4x was done exactly so there would be an easy 
 way to get to them - see PR ports/25576.
 Could it be that you have misconfigured manpath.config or MANPATH variable set 
 perhaps?

From: garys@opusnet.com (Gary W. Swearingen)
To: Dejan Lesjak <dejan.lesjak@ijs.si>
Cc: bug-followup@freebsd.org, garys@opusnet.com
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Sun, 21 Aug 2005 17:43:55 -0700

 Dejan Lesjak <dejan.lesjak@ijs.si> writes:
 
 > Getting keyboard manpage seems to work as expected here:
 >
 > % man -w keyboard
 > /usr/share/man/man4/keyboard.4.gz
 >
 > % man -wa keyboard
 > /usr/share/man/man4/keyboard.4.gz
 > /usr/X11R6/man/man4/keyboard.4x.gz
 >
 > Putting manpages from X11 into 4x was done exactly so there would be an easy 
 > way to get to them - see PR ports/25576.
 > Could it be that you have misconfigured manpath.config or MANPATH variable set 
 > perhaps?
 
 Neither (untouched "manpath.config", no MANPATH), but my PATH obviously
 doesn't work well with the installed "manpath.config".
 
 Of course I could fix this with manpath.config, but
 it seems like too much learning to make (normal?) users do, esp.
 without telling them about it, not even in the Handbook.
 
 Besides, I think "man path" stuff is OK; it SHOULD make the X11
 manpage the default, since that's the keyboard I'm using.  But there
 ought to be a way to get to the FreeBSD manpage without using a long
 pathname.  But if it's too hard to implement, then the situation
 should just be noted in the docs somewhere. (I can think about that
 later if the manual system won't be "fixed".)
 
 I noticed the .4x. but it didn't occur to me to try "man 4x keyboard",
 since I thought the "4" was for "man4".  But this doesn't help me
 because "man 4 keyboard" still brings up keyboard(4x) manpage.
 
 Thanks for looking into it.

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:07:09 +0300

 On 2005-08-22 00:50, "Gary W. Swearingen" <garys@opusnet.com> wrote:
 >Dejan Lesjak <dejan.lesjak@ijs.si> writes:
 >
 >> Getting keyboard manpage seems to work as expected here:
 >>
 >> % man -w keyboard
 >> /usr/share/man/man4/keyboard.4.gz
 >>
 >> % man -wa keyboard
 >> /usr/share/man/man4/keyboard.4.gz
 >> /usr/X11R6/man/man4/keyboard.4x.gz
 >>
 >> Putting manpages from X11 into 4x was done exactly so there would be an easy
 >> way to get to them - see PR ports/25576.
 >> Could it be that you have misconfigured manpath.config or MANPATH variable set
 >> perhaps?
 >
 >  Neither (untouched "manpath.config", no MANPATH), but my PATH obviously
 >  doesn't work well with the installed "manpath.config".
 >
 >  Of course I could fix this with manpath.config, but
 >  it seems like too much learning to make (normal?) users do, esp.
 >  without telling them about it, not even in the Handbook.
 
 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$
 
 >  I noticed the .4x. but it didn't occur to me to try "man 4x keyboard",
 >  since I thought the "4" was for "man4".  But this doesn't help me
 >  because "man 4 keyboard" still brings up keyboard(4x) manpage.
 
 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 :-/
 

From: Dejan Lesjak <dejan.lesjak@ijs.si>
To: bug-followup@freebsd.org,
 garys@opusnet.com
Cc:  
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Mon, 22 Aug 2005 03:23:47 +0200

 Gary W. Swearingen wrote:
 >  Neither (untouched "manpath.config", no MANPATH), but my PATH obviously
 >  doesn't work well with the installed "manpath.config".
 
 Ah, I see now. Changing $PATH so that /usr/X11R6/bin comes in front changes 
 the search order of manpages aswell:
 
 % echo $PATH
 /sbin:/bin:/usr/sbin:/usr/bin:/usr/games:/usr/local/sbin:/usr/local/bin:/usr/X11R6/bin:/home/lesi/bin
 % man -w keyboard 
 /usr/share/man/man4/keyboard.4.gz
 
 % echo $PATH 
 /usr/X11R6/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/games:/usr/local/sbin:/usr/local/bin:/home/lesi/bin
 % man -w keyboard
 /usr/X11R6/man/man4/keyboard.4x.gz
 
 I could still argue though that changing PATH is as advanced as changing 
 MANPATH, but it doesn't feel like it :)
 So with default PATH and man path, user should get FreeBSD keyboard manpage 
 first and could explicitly specify 'man 4x keyboard' to get X11 manpage which 
 is what ports/25576 was trying to address.
 But then again if you change PATH so X11 stuff is first perhaps it is expected 
 to also get manpages for X11 first?
 You guys will know best in any case so I'll just stop theorizing :)

From: garys@opusnet.com (Gary W. Swearingen)
To: Giorgos Keramidas <keramida@ceid.upatras.gr>
Cc: bug-followup@freebsd.org
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Sun, 21 Aug 2005 18:27:45 -0700

 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 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".  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

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
 

From: garys@opusnet.com (Gary W. Swearingen)
To: Dejan Lesjak <dejan.lesjak@ijs.si>
Cc: bug-followup@freebsd.org
Subject: Re: docs/85104: keyboard(4) manpage hides behind Xorg version
Date: Sun, 21 Aug 2005 20:10:48 -0700

 Dejan Lesjak <dejan.lesjak@ijs.si> writes:
 
 > I could still argue though that changing PATH is as advanced as changing 
 > MANPATH, but it doesn't feel like it :)
 > So with default PATH and man path, user should get FreeBSD keyboard manpage 
 > first and could explicitly specify 'man 4x keyboard' to get X11 manpage which 
 > is what ports/25576 was trying to address.
 
 It sounds like Giorgos is arguing the same way, so you outvote me.
 
 But don't you HAVE to change the default path after installing X11?  I
 sure hope the ports system isn't messin' with my "profile".  And where
 do we learn to put more-custom directories at the end of PATH instead
 of the beginning (where I think they belong)?  The several examples of
 PATH setting in the Handbook show both theories (even within the same
 PATH), with mine favored, including: PATH=/usr/X11R6/bin:$PATH;
 
 (One theory is that more-custom directories should override less-custom
 ones so you can easily "replace" their programs; the other theory is
 that doing so makes it too easy to get unexpected custom behavior from
 less-custom programs.)
 
 > But then again if you change PATH so X11 stuff is first perhaps it is expected 
 > to also get manpages for X11 first?
 
 Yes, but it's not expected (by me) to be so hard to display both
 manpages.
 
 
 But this will only waste a small amount of time for a small fraction
 of FreeBSD users, so it's no big deal.  Suspend or close the PR.
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Mon Aug 22 03:25:48 GMT 2005 
State-Changed-Why:  
Gary, who submitted this PR, says it's ok to close it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85104 
>Unformatted:
