From patchwork Wed Mar 20 23:04:35 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 1516 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 5A5B416DB6; Wed, 20 Mar 2019 23:06:28 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTP id CAE5616DB6 for ; Wed, 20 Mar 2019 23:06:27 +0000 (GMT) Received: from localhost ([127.0.0.1]:56198 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h6kHz-000829-9l for patchwork@mira.cbaines.net; Wed, 20 Mar 2019 19:06:27 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43172) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h6kHh-0007sF-4P for guix-patches@gnu.org; Wed, 20 Mar 2019 19:06:10 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h6kHf-0003Ro-4C for guix-patches@gnu.org; Wed, 20 Mar 2019 19:06:09 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:38921) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h6kHe-0003RQ-No for guix-patches@gnu.org; Wed, 20 Mar 2019 19:06:06 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h6kHe-0005iS-Gt for guix-patches@gnu.org; Wed, 20 Mar 2019 19:06:06 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#34929] [PATCH 12/12] doc: Document keyboard layout. Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 20 Mar 2019 23:06:06 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34929 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 34929@debbugs.gnu.org Received: via spool by 34929-submit@debbugs.gnu.org id=B34929.155312311121847 (code B ref 34929); Wed, 20 Mar 2019 23:06:06 +0000 Received: (at 34929) by debbugs.gnu.org; 20 Mar 2019 23:05:11 +0000 Received: from localhost ([127.0.0.1]:52459 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h6kGk-0005gD-0r for submit@debbugs.gnu.org; Wed, 20 Mar 2019 19:05:10 -0400 Received: from eggs.gnu.org ([209.51.188.92]:56833) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h6kGd-0005da-Oo for 34929@debbugs.gnu.org; Wed, 20 Mar 2019 19:05:04 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:36741) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h6kGY-0002WA-Fu; Wed, 20 Mar 2019 19:04:58 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=57670 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1h6kGX-0004wC-VI; Wed, 20 Mar 2019 19:04:58 -0400 From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Thu, 21 Mar 2019 00:04:35 +0100 Message-Id: <20190320230435.25458-12-ludo@gnu.org> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190320230435.25458-1-ludo@gnu.org> References: <20190320230435.25458-1-ludo@gnu.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches * 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 +@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" 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") +@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 @@ -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 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