Create a custom setxkbmap option - linux

Question

Oddly, this seems like it should be something that's been done before: I want to swap the numbers and symbols on the 1–0 keys across the top of my keyboard so that:
When I hit the 6 key, an * is typed instead of a 6.
When I hit Shift+6 the number 6 will display instead of an *.
There were several other modifications that I wanted to make, but quickly found that others had already accomplished these layout modifications before using options for setxkbmap (like caps:swapescape, for example).
Given the above, this is a 3-part question:
Is there an option for swapping numbers and symbols on the top row of my keyboard?
Whether there is or not, is there any way to find out if such a thing exists without having to manually browse the *.lst and *.xml files in /usr/share/X11/xkb/rules/?
Finally, if I were to create an option for setxkbmap, what would be an ideal approach, and how would I see about contributing my option back to the community?
As for question 3:
I have attempted to create the option without success (setxkbmap silently fails and I'm not even confident in my approach).
I can't find where the project is hosted.
Aside from man setxkbmap and various blog posts that touch on the topic, I've been unable to find any documentation on any of this.

Answer 1

Question 2:
For a list of all options available, you can execute localectl list-x11-keymap-options. This seems to only provide you with the options themselves, not the descriptions, so a better approach may be to execute the following on the XKB *.lst files:
for f in /usr/share/X11/xkb/rules/*.lst; do sed -ne '/^\! option$/{s///; :a' -e 'n;p;ba' -e '}' $f; done | sort -u
(sed reference)*
If you're looking for something related to swapping numbers, you can append | grep -i num, revealing several options for working with the numpad/keypad. Unfortunately, I think that all of the layouts have the numbers laid out in the templates related to alphanumeric characters, meaning they're built in to the regional layouts themselves (or the variant, in the case of dvorak).
Question 1:
There are three approaches that you can take.
Override layouts using xmodmap
You can create a somewhat versatile approach by creating an .Xmodmap file in your home to override mappings, as described on the Arch Wiki here.
Here is an example configuration: https://github.com/karma0/layouts/blob/master/home/.Xmodmap
Steps:
Drop .Xmodmap in your home.
Add the line xmodmap $HOME/.Xmodmap to your .profile
A quick and dirty, but flexible approach:
Run xkbcomp -xkb $DISPLAY xkbmap to generate a file xkbmap with your current configuration in it.
Modify it to match the desired configuration. Here's an example:
Original:
key <AE01> { [ 1, exclam ] };
key <AE02> { [ 2, at ] };
key <AE03> { [ 3, numbersign ] };
key <AE04> { [ 4, dollar ] };
key <AE05> { [ 5, percent ] };
key <AE06> { [ 6, asciicircum ] };
key <AE07> { [ 7, ampersand ] };
key <AE08> { [ 8, asterisk ] };
key <AE09> { [ 9, parenleft ] };
key <AE10> { [ 0, parenright ] };
Modified:
key <AE01> { [ exclam, 1 ] };
key <AE02> { [ at, 2 ] };
key <AE03> { [ numbersign, 3 ] };
key <AE04> { [ dollar,i 4 ] };
key <AE05> { [ percent, 5 ] };
key <AE06> { [ asciicircum, 6 ] };
key <AE07> { [ ampersand, 7 ] };
key <AE08> { [ asterisk, 8 ] };
key <AE09> { [ parenleft, 9 ] };
key <AE10> { [ parenright, 0 ] };
Execute the command xkbcomp -w 0 xkbmap $DISPLAY to load the new configuration.
Get the command to run at startup using xinitrc or similar.
Modify your layout and add a new variant
Open up your favorite layout file (likely under /usr/share/X11/xkb/symbols). We'll use the us file for this example.
Find your favorite variant within the file; workman-intl if you're like me.
Assuming you want to replicate the workman-intl layout, you can duplicate that section, and modify it similar to how I did here (note that this is copy/pasted from the intl template and the first and second columns are simply swapped):
partial alphanumeric_keys
xkb_symbols "workman-programmer" {
include "us(workman-intl)"
name[Group1]= "English (Workman, intl., with dead keys and num/sym swapped)";
key <AE01> { [ exclam, 1, exclamdown, onesuperior ] };
key <AE02> { [ at, 2, twosuperior, dead_doubleacute ] };
key <AE03> { [ numbersign, 3, threesuperior, dead_macron ] };
key <AE04> { [ dollar, 4, currency, sterling ] };
key <AE05> { [ percent, 5, EuroSign, dead_cedilla ] };
key <AE06> { [ dead_circumflex,6, onequarter, asciicircum ] };
key <AE07> { [ ampersand, 7, onehalf, dead_horn ] };
key <AE08> { [ asterisk, 8, threequarters, dead_ogonek ] };
key <AE09> { [ parenleft, 9, leftsinglequotemark, dead_breve ] };
key <AE10> { [ parenright, 0, rightsinglequotemark, dead_abovering ] };
};
The xkb_symbols line defines the name of your variation; the include line borrows everything you need from the variation of your choice within the file (here, it's the workman-intl variation in the us layout). Then, the definitions you want are what follows.
4. Add your new definition to /usr/share/xkb/rules/base.xml to the end of the variantList tag. Here's the one I used:
<variant>
<configItem>
<name>workman-programmer</name>
<description>English (Workman, intl., with dead keys and num/sym swapped)</description>
</configItem>
</variant>
Add the new variant and description to the ! variant section of /usr/share/X11/xkb/rules/base.lst as:
workman-programmer us: English (Workman, intl., with dead keys and num/sys swapped)'
Restart your Xorg server.
Setup the setxkbmap command to run using the new variant. Here's the one for this demonstration: setxkbmap -layout us -variant workman-programmer -option
Question 3:
Try as you might, you're not going to find the documentation until you start looking for xkb documentation, which is situated within the xorg ecosystem.
The best write-up out there is probably this one:
https://www.charvolant.org/doug/xkb/html/index.html
QUOTE:
Before you read this, please understand that I never wanted to write this document, being grossly under-qualified, but I always wanted to read it, and this was the only way.
Additionally, here are a list of links as well to get started on learning all of the intricacies of the xkb system in xorg: https://www.x.org/wiki/XKB/
Note: most of the documentation references relative paths within xkb as it is installed on your system. This is typically under /usr/share/X11/xkb
If you wish to contribute, this project lives under the xorg, which provides developer documentation here: https://www.x.org/wiki/guide/, or better, here: https://www.x.org/wiki/Development/