@@ -204,18 +204,18 @@
204204 XKB
205205 </link>
206206 keyboard layouts using the option
207− <option>
208− <link linkend="opt-services.xserver.extraLayouts">
209− services.xserver.extraLayouts
210− </link>
211− </option>.
207+ <option><link linkend="opt-services.xserver.extraLayouts">
208+ services.xserver.extraLayouts</link></option>.
209+ </para>
210+ <para>
212211 As a first example, we are going to create a layout based on the basic US
213212 layout, with an additional layer to type some greek symbols by pressing the
214213 right-alt key.
215214 </para>
216215 <para>
217− To do this we are going to create a <literal>us-greek</literal> file
218− with a <literal>xkb_symbols</literal> section.
216+ Create a file called <literal>us-greek</literal> with the following
217+ content (under a directory called <literal>symbols</literal>; it's
218+ an XKB peculiarity that will help with testing):
219219 </para>
220220<programlisting>
221221xkb_symbols "us-greek"
@@ -231,14 +231,13 @@ xkb_symbols "us-greek"
231231};
232232</programlisting>
233233 <para>
234− To install the layout, the filepath, a description and the list of
235− languages must be given:
234+ A minimal layout specification must include the following:
236235 </para>
237236<programlisting>
238237<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {
239238 description = "US layout with alt-gr greek";
240239 languages = [ "eng" ];
241− symbolsFile = /path/to/us-greek;
240+ symbolsFile = /yourpath/symbols/us-greek;
242241}
243242</programlisting>
244243 <note>
@@ -248,9 +247,27 @@ xkb_symbols "us-greek"
248247 </para>
249248 </note>
250249 <para>
251− The layout should now be installed and ready to use: try it by
252− running <literal>setxkbmap us-greek</literal> and type
253− <literal><alt>+a</literal>. To change the default the usual
250+ Applying this customization requires rebuilding several packages,
251+ and a broken XKB file can lead to the X session crashing at login.
252+ Therefore, you're strongly advised to <emphasis role="strong">test
253+ your layout before applying it</emphasis>:
254+<screen>
255+<prompt>$ </prompt>nix-shell -p xorg.xkbcomp
256+<prompt>$ </prompt>setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY
257+</screen>
258+ </para>
259+ <para>
260+ You can inspect the predefined XKB files for examples:
261+<screen>
262+<prompt>$ </prompt>echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"
263+</screen>
264+ </para>
265+ <para>
266+ Once the configuration is applied, and you did a logout/login
267+ cycle, the layout should be ready to use. You can try it by e.g.
268+ running <literal>setxkbmap us-greek</literal> and then type
269+ <literal><alt>+a</literal> (it may not get applied in your
270+ terminal straight away). To change the default, the usual
254271 <option>
255272 <link linkend="opt-services.xserver.layout">
256273 services.xserver.layout