[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#34929] [PATCH 12/12] doc: Document keyboard layout.
From: |
Ludovic Courtès |
Subject: |
[bug#34929] [PATCH 12/12] doc: Document keyboard layout. |
Date: |
Thu, 21 Mar 2019 00:04:35 +0100 |
* doc/guix.texi (Keyboard Layout): New node.
(Bootloader Configuration): Remove examples and refer to it.
(X Window): Add cross-reference.
---
doc/guix.texi | 126 ++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 108 insertions(+), 18 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index e2bd84493b..f339d52808 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.
@@ -10091,6 +10092,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.
@@ -10951,6 +10953,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
address@hidden Keyboard Layout
address@hidden 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.
+
address@hidden keyboard layout, definition
+There are three components that will want to know about your keyboard layout:
+
address@hidden
address@hidden
+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.
+
address@hidden
+The @emph{operating system kernel}, Linux, will need that so that the console
+is properly configured (@pxref{operating-system Reference,
address@hidden).
+
address@hidden
+The @emph{graphical display server}, usually Xorg, also has its own idea of
+the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
address@hidden itemize
+
+Guix allows you to configure all three separately but, fortunately, it allows
+you to share the same keyboard layout for all three components.
+
address@hidden XKB, keyboard layouts
+Keyboard layouts are represented by records created by the
address@hidden 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:
+
address@hidden
+;; 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" keys 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")
address@hidden example
+
+See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
+for a complete list of supported layouts, variants, and models.
+
address@hidden 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:
+
address@hidden
+;; 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))))))))
address@hidden lisp
+
+In the example above, for GRUB and for Xorg, we just refer to the
address@hidden field defined above, but we could just as well refer to
+a different layout.
+
@node Locales
@section Locales
@@ -13356,7 +13460,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
@@ -23130,23 +23235,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 address@hidden (``qwerty'').
-Otherwise, this must be a @code{keyboard-layout} object. For instance, the
-following example defines a standard German keyboard layout:
-
address@hidden
-(keyboard-layout "de")
address@hidden example
-
address@hidden
-while the example below designates the bépo layout for French:
-
address@hidden
-(keyboard-layout "fr" "bepo")
address@hidden example
-
-The layout name and variant must match an existing layout in the
address@hidden 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
--
2.21.0
- [bug#34929] [PATCH 04/12] bootloader: Add a 'keyboard-layout' field., (continued)
- [bug#34929] [PATCH 05/12] services: xorg: Remove unused #:guile parameter., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 07/12] services: sddm, slim, gdm: Take an <xorg-configuration> record., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 09/12] vm: 'virtualized-operating-system' inherits from the user's bootloader config., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 06/12] services: xorg: Define and <xorg-configuration> record type., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 08/12] services: xorg: Add a 'keyboard-layout' field in <xorg-configuration>., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 10/12] gnu: Add loadkeys-static., Ludovic Courtès, 2019/03/20
- [bug#34929] [PATCH 12/12] doc: Document keyboard layout.,
Ludovic Courtès <=
- [bug#34929] [PATCH 11/12] system: Initialize console keyboard layout in the initrd., Ludovic Courtès, 2019/03/20
[bug#34929] [PATCH 00/12] Provide uniform keyboard layout configuration, Julien Lepiller, 2019/03/24