Added the EXAMPLE section and try to make the text slightly more informative.

Grammar and Spelling Reviewed by: mpp

While mpp kindly checked grammar and spelling, any technical errors
remaining in the man pages are entirely of mine.

1 files changed, 109 insertions, 26 deletions

diff --git a/usr.sbin/kbdcontrol/kbdcontrol.1 b/usr.sbin/kbdcontrol/kbdcontrol.1
index ebac0d9..c759172 100644
--- a/usr.sbin/kbdcontrol/kbdcontrol.1
+++ b/usr.sbin/kbdcontrol/kbdcontrol.1
@@ -12,43 +12,52 @@
 .\"
 .\"     @(#)kbdcontrol.1
 .\"
-.Dd May 22, 1994
-.Dt kbdcontrol 1
+.Dd June 30, 1999
+.Dt KBDCONTROL 1
 .Os FreeBSD
 .Sh NAME
 .Nm kbdcontrol
-.Nd a utility for manipulating the syscons keyboard driver section
+.Nd a utility for manipulating the syscons console driver
 .Sh SYNOPSIS
 .Nm
 .Op Fl dFx
-.Op Fl b Ar duration.pitch | Ar [quiet.]belltype
+.Op Fl b Ar duration.pitch | Ar belltype
 .Op Fl r Ar delay.repeat | Ar speed
-.Op Fl l Ar mapfile
+.Op Fl l Ar keymap_file
 .Op Fl f Ar # Ar string
 .Op Fl h Ar size
-.Op Fl L Ar mapfile
+.Op Fl L Ar keymap_file
 .Sh DESCRIPTION
 The
 .Nm
-command is used to set various keyboard related options for the syscons 
-console driver, such as keymap, keyboard repeat & delay rates, bell 
+command is used to set various keyboard related options for the
+.Xr syscons 4
+console driver and the keyboard drivers,
+such as key map, keyboard repeat and delay rates, bell 
 characteristics etc.
 .Pp
+Keyboard options may be automatically configured at system boot time by
+setting variables in
+.Pa /etc/rc.conf .
+See
+.Sx Boot Time Configuration
+below.
+.Pp
 The following command line options are supported:
 .Bl -tag -width indent
-.It Fl b Ar duration.pitch | Ar [quiet.]belltype
-Set the bell duration in miliseconds and pitch in hertz. 
+.It Fl b Ar duration.pitch | Ar belltype
+Set the bell duration in milliseconds and pitch in hertz. 
 If a 
 .Ar belltype
 argument is specified, it may be one of 
-.Ar normal
+.Cm normal
 which set sound parameters back to normal values, or 
-.Ar visual
+.Cm visual
 which set the bell to visual mode, i.e. flashes the screen instead.
 If 
 .Ar belltype
 is preceded by the word
-.Ar quiet. ,
+.Cm quiet. ,
 the bell will not be rung when the ringing process is in the background vty.
 .It Fl r Ar delay.repeat | Ar speed
 Set keyboard
@@ -60,24 +69,33 @@ and
 rates, or if a
 .Ar speed
 argument is specified, it may be one of 
-.Ar slow
+.Cm slow
 (1000.504),
-.Ar fast
+.Cm fast
 (250.34)
 or
-.Ar normal
+.Cm normal
 (500.126).
-.It Fl l Ar mapfile
+.It Fl l Ar keymap_file
 Install keyboard map file from
-.Ar mapfile .
+.Ar keymap_file .
+You may load the keyboard map file from a menu-driven command, 
+.Xr kbdmap 1 .
 .It Fl d
 Dump the current keyboard map onto stdout.
+The output may be redirected to a file and can be loaded
+back to the kernel later by the
+.Fl l
+option above.
 .It Fl f Ar # Ar string
-.BI "\-f\ " #\ string
+.\".BI "\-f\ " #\ string
 Set function key number
 .Ar #
 to send
 .Ar string .
+Refer to the man page for the keyboard driver
+.Pq e.g. Xr atkbd 4
+for available function keys and their numbers.
 .It Fl F
 Set function keys back to the standard definitions.
 .It Fl x
@@ -86,21 +104,86 @@ Use hexadecimal numbers in keyboard map dump.
 Set history buffer size to
 .Ar size
 lines.
-.It Fl L Ar mapfile
+.It Fl L Ar keymap_file
 Load keyboard map file from
-.Ar mapfile
+.Ar keymap_file
 and write the 
 .Ft "struct keymap"
 compiled from it to stdout.
+This option is primarily intended for programmers and is probably
+of little use under normal circumstances.
+.El
+.Sh KEYBOARD CONFIGURATION
+.Ss Boot Time Configuration
+You may set variables in
+.Pa /etc/rc.conf
+or
+.Pa /etc/rc.conf.local
+in order to configure the keyboard at boot time.
+The following is the list of relevant variables.
+.Pp
+.Bl -tag -width foo_bar_var -compact
+.It Ar keymap
+Specifies a keyboard map file for the
+.Fl l
+option.
+.It Ar keyrate
+Sets the keyboard repeat rate for the
+.Fl r
+option.
+.It Ar keychange
+Lists function key strings for the
+.Fl f
+option.
 .El
+.Pp
+See
+.Xr rc.conf 5 
+for details.
+.Ss Driver Configuration
+The keyboard device driver may let you change default configuration
+options, such as the default keyboard map, so that you do not need to set up
+the options at boot time.
+See keyboard driver manuals
+.Pq e.g. Xr atkbd 4 , Xr ukbd 4
+for details.
 .Sh FILES
-.Bl -tag -width /usr/share/syscons/keymaps -compact
-.Pa /usr/share/syscons/keymaps
-.Sh "BUGS"
+.Bl -tag -width /usr/share/syscons/keymaps/foo_bar -compact
+.It Pa /usr/share/syscons/keymaps/*
+keyboard map files.
+.Sh EXAMPLE
+The following command will load the keyboard map file
+.Pa /usr/share/syscons/keymaps/ru.koi8-r.kbd .
+.Pp
+.Dl kbdcontrol -l /usr/share/syscons/keymaps/ru.koi8-r.kbd
+.Pp
+So long as the keyboard map file resides in
+.Pa /usr/share/syscons/keymaps ,
+you may abbreviate the file name as
+.Pa ru.koi8-r .
+.Pp
+.Dl kbdcontrol -l ru.koi8-r
+.Pp
+The following command will make the function key 10 emit "telnet myhost".
+.Pp
+.Dl kbdcontrol -f 10 \&"telnet myhost\&"
+.Pp
+In order to get the visual effect for bell, but prevent the screen
+from flushing if the bell is to ring in the background screen,
+run the following command.
+.Pp
+.Dl kbdcontrol -b quiet.visual
+.Pp
+.Sh BUGS
 Report when found.
-.Sh "SEE ALSO"
+.Sh SEE ALSO
+.Xr kbdmap 1 ,
 .Xr vidcontrol 1 ,
+.Xr atkbd 4 ,
 .Xr keyboard 4 ,
-.Xr screen 4
+.Xr screen 4 ,
+.Xr syscons 4 ,
+.Xr ukbd 4 ,
+.Xr rc.conf 5 .
 .Sh AUTHORS
 .An Søren Schmidt Aq sos@FreeBSD.org