How do I install a keyboard layout?

Question

I have a keyboard layout file that I want to install on 17.10, but I fail to make it work.

How is it supposed to be done?

So far I have tried

• Guessing how to do it based on existing files in /usr/share/X11/xkb/symbols/ and the appearance of /usr/share/X11/xkb/rules/evdev.xml
• Guessing what a "variant" is, how to add it, what fields need to be updated, where the contents of this symbols file should be placed
• Guessing that placing it with a unique name directly in /symbols/ means I have to add it as a <layout> in evdev.xml. Still no idea whether that is true, nor which field -- if any -- is supposed to correspond to the file name
• Guessing that placing it inside an existing file in /symbols/ means I have to add it as a "variant". No idea whether that is true

It would help if there was some way to avoid the guessing. I don't need a crash-course in the architecture, just a non-ambiguous way to make the keyboard layout...

1. show up in the keyboard layout settings dialog, and...
2. produce the correct input

So far the farthest I've come is #1 -- but don't ask me how, because I don't know which part did it.

---

Update

Exactly this has been done

• The contents of the symbols file that I linked to is in /usr/share/X11/xkb/symbols/svorak-a5

• The following block has been inserted into /usr/share/X11/xkb/rules/evdev.xml right before the pre-existing element sequence <layout> <configItem> <name>se:

   <layout>
     <configItem>
       <name>svorak-a5</name>
   &lt;shortDescription&gt;sva5&lt;/shortDescription&gt;
   &lt;description&gt;Svorak A5&lt;/description&gt;
   &lt;languageList&gt;
     &lt;iso639Id&gt;swe&lt;/iso639Id&gt;
   &lt;/languageList&gt;
  
  </configItem>
   </layout>
  

• /var/lib/xkb contains no .xkms.

Answer 1

First you should give the layout variant a name; see /usr/share/X11/xkb/symbols/se for examples. Then add it to /usr/share/X11/xkb/symbols/se and add a corresponding entry to /usr/share/X11/xkb/rules/evdev.xml.

Edit:

I tested the steps in the "update" section of your question, and it worked fine for me after having rebooted. The layout is shown in a submenu of Swedish (Sweden).

For testing subsequent changes, rebooting isn't necessary, but this command should suffice:

systemctl restart keyboard-setup

Edit II:

I have a theory (untested) on why the layout isn't working as robustly as you would wish. Try to change the two first lines in svorak-a5:

partial alphanumeric_keys
xkb_symbols "svorak" {

to

default partial alphanumeric_keys
xkb_symbols "basic" {