docs/xserver: document xserver.extraLayouts

1 files changed, 130 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml
index 798d1fbdfd85..6928a977a9ea 100644
--- a/nixos/doc/manual/configuration/x-windows.xml
+++ b/nixos/doc/manual/configuration/x-windows.xml
@@ -157,4 +157,134 @@
    versions.
   </para>
  </simplesect>
+ <simplesect xml:id="custom-xkb-layouts">
+  <title>Custom XKB layouts</title>
+  <para>
+   It is possible to install custom
+   <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">
+    XKB
+   </link>
+   keyboard layouts using the option
+   <option>
+    <link linkend="opt-services.xserver.extraLayouts">
+     services.xserver.extraLayouts
+    </link>
+   </option>.
+   As a first example, we are going to create a layout based on the basic US
+   layout, with an additional layer to type some greek symbols by pressing the
+   right-alt key.
+  </para>
+  <para>
+   To do this we are going to create a <literal>us-greek</literal> file
+   with a <literal>xkb_symbols</literal> section.
+  </para>
+<programlisting>
+xkb_symbols &quot;us-greek&quot;
+{
+  include &quot;us(basic)&quot;            // includes the base US keys
+  include &quot;level3(ralt_switch)&quot;  // configures right alt as a third level switch
+
+  key &lt;LatA&gt; { [ a, A, Greek_alpha ] };
+  key &lt;LatB&gt; { [ b, B, Greek_beta  ] };
+  key &lt;LatG&gt; { [ g, G, Greek_gamma ] };
+  key &lt;LatD&gt; { [ d, D, Greek_delta ] };
+  key &lt;LatZ&gt; { [ z, Z, Greek_zeta  ] };
+};
+</programlisting>
+  <para>
+   To install the layout, the filepath, a description and the list of
+   languages must be given:
+  </para>
+<programlisting>
+<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {
+  description = "US layout with alt-gr greek";
+  languages   = [ "eng" ];
+  symbolsFile = /path/to/us-greek;
+}
+</programlisting>
+  <note>
+  <para>
+   The name should match the one given to the
+   <literal>xkb_symbols</literal> block.
+  </para>
+  </note>
+  <para>
+   The layout should now be installed and ready to use: try it by
+   running <literal>setxkbmap us-greek</literal> and type
+   <literal>&lt;alt&gt;+a</literal>. To change the default the usual
+   <option>
+    <link linkend="opt-services.xserver.layout">
+     services.xserver.layout
+    </link>
+   </option>
+   option can still be used.
+  </para>
+  <para>
+   A layout can have several other components besides
+   <literal>xkb_symbols</literal>, for example we will define new
+   keycodes for some multimedia key and bind these to some symbol.
+  </para>
+  <para>
+   Use the <emphasis>xev</emphasis> utility from
+   <literal>pkgs.xorg.xev</literal> to find the codes of the keys of
+   interest, then create a <literal>media-key</literal> file to hold
+   the keycodes definitions
+  </para>
+<programlisting>
+xkb_keycodes &quot;media&quot;
+{
+ &lt;volUp&gt;   = 123;
+ &lt;volDown&gt; = 456;
+}
+</programlisting>
+  <para>
+    Now use the newly define keycodes in <literal>media-sym</literal>:
+  </para>
+<programlisting>
+xkb_symbols &quot;media&quot;
+{
+ key.type = &quot;ONE_LEVEL&quot;;
+ key &lt;volUp&gt;   { [ XF86AudioLowerVolume ] };
+ key &lt;volDown&gt; { [ XF86AudioRaiseVolume ] };
+}
+</programlisting>
+  <para>
+    As before, to install the layout do
+  </para>
+<programlisting>
+<xref linkend="opt-services.xserver.extraLayouts"/>.media = {
+  description  = "Multimedia keys remapping";
+  languages    = [ "eng" ];
+  symbolsFile  = /path/to/media-key;
+  keycodesFile = /path/to/media-sym;
+};
+</programlisting>
+  <note>
+  <para>
+   The function <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;
+   </literal> can be useful if you prefer to keep the layout definitions
+   inside the NixOS configuration.
+  </para>
+  </note>
+  <para>
+    Unfortunately, the Xorg server does not (currently) support setting a
+    keymap directly but relies instead on XKB rules to select the matching
+    components (keycodes, types, ...) of a layout. This means that components
+    other than symbols won't be loaded by default. As a workaround, you
+    can set the keymap using <literal>setxkbmap</literal> at the start of the
+    session with:
+  </para>
+<programlisting>
+<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";
+</programlisting>
+  <para>
+   To learn how to write layouts take a look at the XKB
+  <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">
+   documentation
+  </link>. More example layouts can also be found
+  <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">
+   here
+  </link>.
+  </para>
+</simplesect>
 </chapter>