Merge pull request #1 from rhansen/readme

README.md: Document the purpose of this fork

README.md

@@ -1,31 +1,34 @@
 [![Kofi](https://badgen.net/badge/icon/kofi?icon=kofi&label)](https://ko-fi.com/rvaiya)
+[![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions)
 
-# Impetus
+# keyd
 
-[![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions)
+A key remapping daemon for Linux.
+
+## Impetus
 
 Linux lacks a good key remapping solution. In order to achieve satisfactory
 results a medley of tools need to be employed (e.g xcape, xmodmap) with the end
 result often being tethered to a specified environment (X11). keyd attempts to
 solve this problem by providing a flexible system wide daemon which remaps keys
 using kernel level input primitives (evdev, uinput).
 
-# Note on v2
+## Note on v2
 
 The config format has undergone several iterations since the first
 release. For those migrating their configs from v1 it is best
 to reread the man page. 
 
 See also: [changelog](docs/CHANGELOG.md).
 
-# Goals
+## Goals
 
   - Speed       (a hand tuned input loop written in C that takes <<1ms)
   - Simplicity  (a [config format](#sample-config) that is intuitive)
   - Consistency (modifiers that [play nicely with layers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128) by default)
   - Modularity  (a UNIXy core extensible through the use of an [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) mechanism)
 
-# Features
+## Features
 
 keyd has several unique features many of which are traditionally only
 found in custom keyboard firmware like [QMK](https://github.com/qmk/qmk_firmware)
@@ -57,9 +60,9 @@ Some of the more interesting ones include:
 
  - A tool for programming individual key up/down events.
 
-# Dependencies
+## Dependencies
 
-## Required Build Dependencies
+### Required Build Dependencies
 
   * Your favourite C11 compiler
   * POSIX-compatible `make` (e.g., [GNU
@@ -68,13 +71,13 @@ Some of the more interesting ones include:
   * [Python](https://www.python.org/) 3.8 or newer
   * [scdoc](https://git.sr.ht/~sircmpwn/scdoc)
 
-## Optional Build Dependencies
+### Optional Build Dependencies
 
   * [bash](https://www.gnu.org/software/bash/) (for the `usb-gadget` virtual
     keyboard driver)
   * [systemd](https://systemd.io/) (for system services)
 
-## Optional Runtime Dependencies
+### Optional Runtime Dependencies
 
   * [bash](https://www.gnu.org/software/bash/) (for the `usb-gadget` virtual
     keyboard driver)
@@ -84,23 +87,23 @@ Some of the more interesting ones include:
   * [dbus-python](https://pypi.org/project/dbus-python/) (only for KDE support)
   * [systemd](https://systemd.io/) (for system services)
 
-# Installation
+## Installation
 
-## From a Pre-Built Package
+### From a Pre-Built Package
 
 Binary packages for some distributions exist.  These are kindly maintained by
 community members; the keyd developers do not take responsibility for them.  If
 you wish to add yours below, please open a PR.
 
-### Alpine Linux
+#### Alpine Linux
 
 [keyd](https://pkgs.alpinelinux.org/packages?name=keyd) package maintained by [@jirutka](https://github.com/jirutka).
 
-### Arch
+#### Arch
 
 [Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) package maintained by Arch packagers.
 
-### Debian
+#### Debian
 
 Experimental `keyd` and `keyd-application-mapper` packages can be found in the
 CI build artifacts of the [work-in-progress Debian package
@@ -114,17 +117,17 @@ sponsor its upload is encouraged to contact
 [@rhansen](https://github.com/rhansen) (also see the [Debian ITP
 bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1060023)).
 
-### Fedora
+#### Fedora
 
 [COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) package maintained by [@alternateved](https://github.com/alternateved).
 
-### openSUSE
+#### openSUSE
 
 [opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) package maintained by [@bubbleguuum](https://github.com/bubbleguuum).
 
 Easy install with `sudo zypper in keyd`.
 
-### Ubuntu
+#### Ubuntu
 
 Experimental `keyd` and `keyd-application-mapper` packages can be found in the
 [`ppa:keyd-team/ppa`
@@ -133,7 +136,7 @@ archive](https://launchpad.net/~keyd-team/+archive/ubuntu/ppa).
 If you wish to help maintain this PPA, please contact
 [@rhansen](https://github.com/rhansen).
 
-## From Source
+### From Source
 
 > [!NOTE]
 > The default branch (`master`) is the development branch; it contains the
@@ -142,7 +145,7 @@ If you wish to help maintain this PPA, please contact
 > announced on the [releases page](https://github.com/rvaiya/keyd/releases);
 > these versions are known to work.
 
-### From a Source Code Distribution Tarball
+#### From a Source Code Distribution Tarball
 
   1. Download the desired tarball:
        * Releases can be found on the [releases
@@ -172,7 +175,7 @@ If you wish to help maintain this PPA, please contact
      sudo make install
      ```
 
-### From Git
+#### From Git
 
   1. Install [Git](https://git-scm.com/), [GNU
      Autoconf](https://www.gnu.org/software/autoconf/), and [GNU
@@ -200,7 +203,7 @@ If you wish to help maintain this PPA, please contact
   5. Follow steps 3 and later from [installation from a source code distribution
      tarball](#from-a-source-code-distribution-tarball).
 
-# Quickstart
+## Quickstart
 
 1. Install and start keyd (e.g `sudo systemctl enable keyd --now`)
 
@@ -239,7 +242,7 @@ Some mice (e.g the Logitech MX Master) are capable of emitting keys and
 are consequently matched by the wildcard id. It may be necessary to
 explicitly blacklist these.
 
-## Application Specific Remapping (experimental)
+### Application Specific Remapping (experimental)
 
 - Add yourself to the keyd group:
 
@@ -268,14 +271,14 @@ display server initialization logic (e.g ~/.xinitrc) unless you are running Gnom
 
 See the man page for more details.
 
-## SBC support
+### SBC support
 
 Experimental support for single board computers (SBCs) via usb-gadget
 has been added courtesy of Giorgi Chavchanidze.
 
 See [usb-gadget.md](src/vkbd/usb-gadget.md) for details.
 
-# Sample Config
+## Sample Config
 
 	[ids]
 
@@ -292,7 +295,7 @@ See [usb-gadget.md](src/vkbd/usb-gadget.md) for details.
 	f = /
 	...
 
-# Recommended config
+## Recommended config
 
 Many users will probably not be interested in taking full advantage of keyd.
 For those who seek simple quality of life improvements I can recommend the
@@ -319,17 +322,17 @@ control (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce
 the letter A you can now simply tap shift and then a instead of having to hold
 it. Finally it remaps insert to S-insert (paste on X11).
 
-# FAQS
+## FAQS
 
-## What about xmodmap/setxkbmap/*?
+### What about xmodmap/setxkbmap/*?
 
 xmodmap and friends are display server level tools with limited functionality.
 keyd is a system level solution which implements advanced features like
 layering and [oneshot](https://docs.qmk.fm/#/one_shot_keys)
 modifiers.  While some X tools offer similar functionality I am not aware of
 anything that is as flexible as keyd.
 
-## What about [kmonad](https://github.com/kmonad/kmonad)?
+### What about [kmonad](https://github.com/kmonad/kmonad)?
 
 keyd was written several years ago to allow me to easily experiment with
 different layouts on my growing keyboard collection. At the time kmonad did not
@@ -345,15 +348,15 @@ in Haskell). Having said that, it supplies (in the author's opinion) the
 most valuable features in less than 2000 lines of C while providing
 a simple language agnostic config format.
 
-## Why doesn't keyd implement feature X?
+### Why doesn't keyd implement feature X?
 
 If you feel something is missing or find a bug you are welcome to file an issue
 on github. keyd has a minimalist (but sane) design philosophy which
 intentionally omits certain features (e.g execing arbitrary executables
 as root). Things which already exist in custom keyboard firmware like QMK are
 good candidates for inclusion.
 
-# Contributing
+## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 IRC Channel: #keyd on oftc