Bug 85104
| Summary: | keyboard(4) manpage hides behind Xorg version | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Gary W. Swearingen <garys> |
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
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? 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. 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 :-/ 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 :)
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 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 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 Gary, who submitted this PR, says it's ok to close it. |
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. 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.