docs/89325: [PATCH] Clarification of kbdmap(5), atkbd(4) and kbdcontrol(1) manpages

[Oliver Fromme]

>Number:         89325
>Category:       docs
>Synopsis:       [PATCH] Clarification of kbdmap(5), atkbd(4) and kbdcontrol(1) manpages
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Nov 20 20:30:34 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Oliver Fromme
>Release:        FreeBSD 6.0-STABLE i386
>Organization:
secnetix GmbH & Co. KG, Munich Germany
		http://www.secnetix.de/bsd
>Environment:
System: FreeBSD epia.fromme.com 6.0-STABLE FreeBSD 6.0-STABLE #0: Fri Nov  4 21:35:33 CET 2005     olli at epia.fromme.com:/usr/src/sys/i386/compile/EPIA  i386

>Description:

NOTE:  PR has been re-sent because of wrong Reply-To
       address in the previous one!

When I tried to configure my keyboard under syscons so that
I can use Ctrl-Left and Ctrl-Right to jump word-wise left
and right, it turned out that the documentation was somewhat
sub-optimal.  There is no "big picture", and information is
spread across various manual pages, which are sometimes not
even mentioned in the "SEE ALSO" sections.  In fact, I had
to resort to reading kernel sources to find out the number
of function keys that are supported, among other things --
this isn't documented at all.

The small patch below clarifies a few things in the kbdmap(5)
manual page and points people in the right direction who try
to do similar things.

>How-To-Repeat:

man 5 kbdmap

>Fix:

--- src/usr.sbin/kbdcontrol/kbdcontrol.1.orig	Sat Aug  6 16:45:18 2005
+++ src/usr.sbin/kbdcontrol/kbdcontrol.1	Sun Nov 20 20:42:27 2005
@@ -118,6 +118,9 @@
 .Ar keymap_file .
 You may load the keyboard map file from a menu-driven command,
 .Xr kbdmap 1 .
+The format of keyboard map files is documented in the
+.Xr kbdmap 5
+manual page.
 .It Fl d
 Dump the current keyboard map onto stdout.
 The output may be redirected to a file and can be loaded
--- src/usr.sbin/kbdcontrol/kbdmap.5.orig	Sat Aug 21 14:58:09 2004
+++ src/usr.sbin/kbdcontrol/kbdmap.5	Sun Nov 20 20:24:15 2005
@@ -165,7 +165,15 @@
 function key,
 where
 .Ar N
-is a decimal number.
+is a decimal number in the range from 1 to 96.
+Refer to the
+.Xr atkbd 4
+manual page for a list of predefined function keys.
+You can use the
+.Fl f
+option of the 
+.Xr kbdcontrol 1
+utility to assign arbitrary strings to funktion keys.
 .It lshift
 Act as left shift key.
 .It rshift
--- src/share/man/man4/atkbd.4.orig	Thu Dec 16 00:01:45 2004
+++ src/share/man/man4/atkbd.4	Sun Nov 20 20:51:45 2005
@@ -70,6 +70,11 @@
 by the
 .Xr kbdcontrol 1
 command.
+You can use a keyboard map file (see
+.Xr kbdmap 5 )
+to map them to arbitrary keys, particularly
+the functions in the range from 65 to 96
+which are not used by default.
 .Pp
 .Bl -tag -width "Function Key Number" -compact
 .It "Function Key number"
@@ -114,6 +119,8 @@
 Right GUI Key
 .It 64
 Menu
+.It "65, 66,...96"
+free (not used by default)
 .El
 .Pp
 See the man page for the
@@ -209,6 +216,7 @@
 .Xr pcvt 4 ,
 .Xr psm 4 ,
 .Xr syscons 4 ,
+.Xr kbdmap 5 ,
 .Xr loader 8
 .Sh HISTORY
 The

>Release-Note:
>Audit-Trail:
>Unformatted: