# xkeyboard-config-user-hw-extras

User-contributed XKB extension: hardware keyboard models, geometry definitions,
and symbol options not (yet) available in upstream xkeyboard-config.

## Why this package exists

XKB was redesigned from scratch years ago, dropping keyboard geometry support entirely.

Nowadays — IMHO — karma comes back. There are many great keyboards on the market,
but if somebody starts to "create his/her own typing feel" on a new Linux box, they
get presented the standard IBM 105 from 1986. Direct UX FAILURE!

Wouldn't it be the greatest breakthrough in User Experience if the user's keyboard
was already there, visualized? (like it would have been possible, if geometry support
had not been dropped)

This package tries to extend the old geometry infrastructure, so further development
of "configure keyboard" tools may take the right path.

## What's included

**Models:** `cherrymx20s`, `cherrymx30s`, `cherrymxboard30` (Cherry MX family)
- `MX 2.0S`: actually only its name and USB-IDs are incorporated.  The visual will map to `MX 3.0S` (somebody may want to create the real geometry)

**Option:** `userhw:type_and_check` — AltGr symbol layer:
- `AltGr+h` → ✔  `AltGr+H` → ℏ (Planck constant)
- `AltGr+k` → ✘  `AltGr+K` → κ (Kappa)
- `AltGr+ü/ö/ä` → ☐/☑/☒ (ballot boxes)
- Extended keypad symbols
- Shift cancels Caps Lock (`shift:breaks_caps` behaviour)

## Installation

```bash
dnf copr enable st0ff64/xkeyboard-config-user-hw-extras
dnf install xkeyboard-config-user-hw-extras
```

For xkbcomp-based tools (keyboard geometry preview):
```bash
dnf install xkeyboard-config-user-hw-extras-compat
```

## Package architecture

The source tree uses flat `.extra` files. Each filename encodes its installation target:

```
<subdir>.<name>.extra  →  symlinked for libxkbcommon as  <subdir>/<name>
```

### Without `-compat` (main package only)

All `.extra` files are symlinked into `/usr/share/xkeyboard-config.d/user-hw-extras/`:

| Source file | Symlink target (subsystem) |
|---|---|
| `geometry.userhw.extra` | `geometry/userhw` |
| `keycodes.userhw.extra` | `keycodes/userhw` |
| `symbols.userhw.extra` | `symbols/userhw` |
| `rules.evdev.xml.extra` | `rules/evdev.xml` |
| `rules.evdev.extra` | `rules/evdev` |

Discovered by **libxkbregistry** (libxkbcommon ≥ 1.13) — KDE Plasma, GNOME, etc.

`rules.userhw.xml.extra` is **not installed** without `-compat` (system-path only).

### With `-compat` (xkbcomp compatibility)

The `-compat` subpackage extends xkbcomp-based tools (keyboard preview, setxkbmap):
> ❗ATTENTION: this installation method is neither recommended, nor will it ever be accepted upstream (most likely).\
> The author has taken as much responsibility using the availble hooking mechanisms, as possible, to prevent system damage.
>
> For new **geometries** to be available after X11/Wayland restart, the /usr/share/xkeyboard-config-2/rules/evdev file needs to be patched / appended.
>
> This is due to the fact, that older tools use `/usr/share/X11/xkb/rules/evdev` as a single source of truth, unlike libxkbregistry - which provides ways for extension (used without `-compat`), apart from having dropped Keyboard Geometry Support.

| Source file | Action |
|---|---|
| `geometry.userhw.extra` | symlink → `/usr/share/X11/xkb/geometry/userhw` |
| `keycodes.userhw.extra` | symlink → `/usr/share/X11/xkb/keycodes/userhw` |
| `symbols.userhw.extra` | symlink → `/usr/share/X11/xkb/symbols/userhw` |
| `rules.userhw.xml.extra` | symlink → `/usr/share/X11/xkb/rules/userhw.xml` (documentation) |
| `rules.evdev.extra` | **unlink** subsystem symlink + **append** `BEGIN_USER_HW_EXTRAS`…`END_USER_HW_EXTRAS` block to `/usr/share/X11/xkb/rules/evdev` |

The `rules.evdev.extra` subsystem symlink is removed when `-compat` is installed to
prevent double-application of rules (libxkbcommon would otherwise see our rules
both via xkeyboard-config.d/ and via the patched system evdev).

On uninstall of `-compat`: system evdev is restored from `backup.evdev` (saved at install time).
On `xkeyboard-config` upgrade: evdev is re-patched automatically via `%triggerpostun`.

## Repository

- **GitLab:** https://gitlab.com/copr-projekte/user-hw-extras
- **COPR:** https://copr.fedorainfracloud.org/coprs/st0ff64/xkeyboard-config-user-hw-extras/

## License

Apache-2.0
