doc: Document keyboard layout.

* doc/guix.texi (Keyboard Layout): New node.
(Bootloader Configuration): Remove examples and refer to it.
(X Window): Add cross-reference.

1 files changed, 108 insertions, 18 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index fb3fef689a..63405bcf49 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -251,6 +251,7 @@ System Configuration
 * File Systems::                Configuring file system mounts.
 * Mapped Devices::              Block device extra processing.
 * User Accounts::               Specifying user accounts.
+* Keyboard Layout::             How the system interprets key strokes.
 * Locales::                     Language and cultural convention settings.
 * Services::                    Specifying system services.
 * Setuid Programs::             Programs running with root privileges.
@@ -10132,6 +10133,7 @@ instance to support new system services.
 * File Systems::                Configuring file system mounts.
 * Mapped Devices::              Block device extra processing.
 * User Accounts::               Specifying user accounts.
+* Keyboard Layout::             How the system interprets key strokes.
 * Locales::                     Language and cultural convention settings.
 * Services::                    Specifying system services.
 * Setuid Programs::             Programs running with root privileges.
@@ -10992,6 +10994,108 @@ Note that the ``root'' account is not included here.  It is a
 special-case and is automatically added whether or not it is specified.
 @end defvr
 
+@node Keyboard Layout
+@section Keyboard Layout
+
+To specify what each key of your keyboard does, you need to tell the operating
+system what @dfn{keyboard layout} you want to use.  The default, when nothing
+is specified, is the US English QWERTY layout for 105-key PC keyboards.
+However, German speakers will usually prefer the German QWERTZ layout, French
+speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
+or bépo, and they might even want to further customize the effect of some of
+the keys.  This section explains how to get that done.
+
+@cindex keyboard layout, definition
+There are three components that will want to know about your keyboard layout:
+
+@itemize
+@item
+The @emph{bootloader} may want to know what keyboard layout you want to use
+(@pxref{Bootloader Configuration, @code{keyboard-layout}}).  This is useful if
+you want, for instance, to make sure that you can type the passphrase of your
+encrypted root partition using the right layout.
+
+@item
+The @emph{operating system kernel}, Linux, will need that so that the console
+is properly configured (@pxref{operating-system Reference,
+@code{keyboard-layout}}).
+
+@item
+The @emph{graphical display server}, usually Xorg, also has its own idea of
+the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
+@end itemize
+
+Guix allows you to configure all three separately but, fortunately, it allows
+you to share the same keyboard layout for all three components.
+
+@cindex XKB, keyboard layouts
+Keyboard layouts are represented by records created by the
+@code{keyboard-layout} procedure of @code{(gnu system keyboard)}.  Following
+the X Keyboard extension (XKB), each layout has four attributes: a name (often
+a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
+optional variant name, an optional keyboard model name, and a possibly empty
+list of additional options.  In most cases the layout name is all you care
+about.  Here are a few example:
+
+@example
+;; The German QWERTZ layout.  Here we assume a standard
+;; "pc105" keyboard model.
+(keyboard-layout "de")
+
+;; The bépo variant of the French layout.
+(keyboard-layout "fr" "bepo")
+
+;; The Catalan layout.
+(keyboard-layout "es" "cat")
+
+;; The Latin American Spanish layout.  In addition, the
+;; "Caps Lock" key is used as an additional "Ctrl" key,
+;; and the "Menu" key is used as a "Compose" key to enter
+;; accented letters.
+(keyboard-layout "latam"
+                 #:options '("ctrl:nocaps" "compose:menu"))
+
+;; The Russian layout for a ThinkPad keyboard.
+(keyboard-layout "ru" #:model "thinkpad")
+
+;; The "US international" layout, which is the US layout plus
+;; dead keys to enter accented characters.  This is for an
+;; Apple MacBook keyboard.
+(keyboard-layout "us" "intl" #:model "macbook78")
+@end example
+
+See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
+for a complete list of supported layouts, variants, and models.
+
+@cindex keyboard layout, configuration
+Let's say you want your system to use the Turkish keyboard layout throughout
+your system---bootloader, console, and Xorg.  Here's what your system
+configuration would look like:
+
+@lisp
+;; Using the Turkish layout for the bootloader, the console,
+;; and for Xorg.
+
+(operating-system
+  ;; ...
+  (keyboard-layout (keyboard-layout "tr"))  ;for the console
+  (bootloader (bootloader-configuration
+                (bootloader grub-efi-bootloader)
+                (target "/boot/efi")
+                (keyboard-layout keyboard-layout))) ;for GRUB
+  (services (modify-services %desktop-services
+              (slim-service-type config =>
+                (slim-configuration
+                  (inherit config)
+                  (xorg-configuration
+                    (xorg-configuration             ;for Xorg
+                      (keyboard-layout keyboard-layout))))))))
+@end lisp
+
+In the example above, for GRUB and for Xorg, we just refer to the
+@code{keyboard-layout} field defined above, but we could just as well refer to
+a different layout.
+
 @node Locales
 @section Locales
 
@@ -13399,7 +13503,8 @@ If this is @code{#f}, Xorg uses the default keyboard layout---usually US
 English (``qwerty'') for a 105-key PC keyboard.
 
 Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
-layout in use when Xorg is running.
+layout in use when Xorg is running.  @xref{Keyboard Layout}, for more
+information on how to specify the keyboard layout.
 
 @item @code{extra-config} (default: @code{'()})
 This is a list of strings or objects appended to the configuration file.  It
@@ -23651,23 +23756,8 @@ The number of seconds to wait for keyboard input before booting.  Set to
 If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
 layout, usually US@tie{}English (``qwerty'').
 
-Otherwise, this must be a @code{keyboard-layout} object.  For instance, the
-following example defines a standard German keyboard layout:
-
-@example
-(keyboard-layout "de")
-@end example
-
-@noindent
-while the example below designates the bépo layout for French:
-
-@example
-(keyboard-layout "fr" "bepo")
-@end example
-
-The layout name and variant must match an existing layout in the
-@code{xkeyboard-config} package under the @file{share/X11/xkb/symbols}
-directory.
+Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
+Layout}).
 
 @quotation Note
 This option is currently ignored by bootloaders other than @code{grub} and