Bug#617580: console-setup: Poor documentation for configuring the keyboard

[Jorgen Grahn <grahn+debian@snipabacken.se>]

Package: console-setup
Version: 1.68
Severity: normal


I've just upgraded to Squeeze, trying to find a way to bring back my
old heavily customized X11 keymap.  I think I can state my problem in
the cleanest way by describing how I did my search:

- First I notice there is no xorg.conf.  That's OK -- /usr/share/doc/
  explains that the keyboard config has been unified.
- Then I easily find /etc/default/keyboard, containing the new config.
  Trying to learn about this file is difficult though -- hard to tell
  which package it belongs to. Candidates are 'kbd', 'keyboard',
  'console-setup'. "man -k keyboard" or "man -k kbd" gives no hints.
  I eventually find /etc/console-setup, and from that one
  /usr/share/doc/keyboard-configuration/.
- The keyboard-configuration README mentions setupcon(1). However,
  that one doesn't document the file format, and has no "SEE ALSO".
  => It should at least "SEE ALSO" ckbcomp(1).
  Unusual for Debian, it omits the reference material and just
  says "Please look at the README file for more information" under
  "BASIC USAGE". There is no "FILES" section.
  => The manpage should contain that info, *or* it should at least
  give the full path to the file.  I *think* the one it means is
  /usr/share/doc/console-setup/README.gz, but that one contains
  all kinds of information which is irrelevant in this situation
  (in addition to information which *is* relevant, provided Debian
  hasn't modified the behavior from the "factory default").

I have no elegant solution to this ... but please try to find some
way to make it easier to find the needed information. It's normally
not this hard in Debian to find stuff out from reading man pages
and /usr/share/doc/.

regards,
Jorgen

-- System Information:
Debian Release: 6.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: powerpc (ppc)

Kernel: Linux 2.6.32-5-powerpc
Locale: LANG=sv_SE, LC_CTYPE=sv_SE (charmap=ISO-8859-1)
Shell: /bin/sh linked to /bin/dash

Versions of packages console-setup depends on:
ii  console-terminus              4.30-2     Fixed-width fonts for fast reading
ii  debconf                       1.5.36.1   Debian configuration management sy
ii  keyboard-configuration        1.68       system-wide keyboard preferences
ii  xkb-data                      1.8-2      X Keyboard Extension (XKB) configu

Versions of packages console-setup recommends:
ii  kbd                           1.15.2-2   Linux console font and keytable ut

Versions of packages console-setup suggests:
ii  locales                 2.11.2-10        Embedded GNU C Library: National L
ii  lsb-base                3.2-23.2squeeze1 Linux Standard Base 3.2 init scrip

-- debconf information:
* console-setup/codeset47: . Combined - Latin; Slavic Cyrillic; Greek
  console-setup/fontface47: Fixed
  console-setup/fontsize-text47: 16
  console-setup/charmap47: UTF-8
  console-setup/codesetcode: Uni2
  console-setup/store_defaults_in_debconf_db: true
  console-setup/fontsize-fb47: 16
  console-setup/use_system_font:
  console-setup/fontsize: 16