From f250876ff72ac228b8ad13adbf0be19306b8d94c Mon Sep 17 00:00:00 2001 From: Richard Hansen Date: Fri, 6 Dec 2024 19:17:24 -0500 Subject: [PATCH] README.md: Demote sections, add title section Convention for Markdown is to have a single `#` section for the page title, then put all other sections at `##` or lower. --- README.md | 63 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 39e9457..e63fffb 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ [![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 @@ -10,7 +13,7 @@ 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 @@ -18,14 +21,14 @@ 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,9 +322,9 @@ 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 @@ -329,7 +332,7 @@ 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,7 +348,7 @@ 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 @@ -353,7 +356,7 @@ 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