Updated the documentation to describe the new functionality

This commit is contained in:
Maarten van Gompel 2021-03-15 14:15:10 +01:00 committed by Hiltjo Posthuma
parent 444ceabde3
commit 5fd07406ae
2 changed files with 70 additions and 4 deletions

View File

@ -10,7 +10,7 @@ Installation
$ make
$ make install
This will create by default `svkbd-intl`, which is svkbd using an international
This will create by default `svkbd-mobile-intl`, which is svkbd using an international
layout with multiple layers and overlays, and optimised for mobile devices.
You can create svkbd for additional layouts by doing:
@ -31,11 +31,12 @@ The following layouts are available:
diacritics and other variants, as well as some emoji. The layers are:
* a basic qwerty layer
* a layer for numeric input, arrows, and punctuation
* a layer for function keys, media keys, and arrows
* a cyrillic layer (ЙЦУКЕН based); the э key is moved to an overlay on е
* a dialer/numeric layer
* an arrow layer
* ``mobile-plain`` - This is a plain layout with only a qwerty layer and numeric/punctuation layer. It was
originally made for [sxmo](https://sr.ht/~mil/Sxmo/).
* ``mobile-simple`` - This is a more minimalistic layout that is more similar to what Android and iOS offer.
* **Traditional layouts**:
* ``en`` - An english layout without layers (QWERTY)
* ``de`` - A german layout (QWERTZ)
@ -74,10 +75,31 @@ overlay functionality with the ``-O`` flag or by setting the environment variabl
also a key on the function layer of the keyboard itself to enable/disable this behaviour on the fly. Its label shows
``≅`` when the overlay functionality is enabled and ``≇`` when not.
Svkbd has been optimised for use on mobile devices with a touchscreen and implements press-on-release
behaviour (which can be disabled), it also works fine on normal desktop systems with a regular mouse.
Advanced Usage
---------------
Svkbd has an extra output mode where all keypresses are printed to standard output. Optionally, you can also disable the
default X11 keypress emulation. This gives you the freedom to use svkbd in other contexts and use simple pipes to
connect it to other tools:
$ svkbd-mobile-intl -n -o | cowsay
This becomes especially useful if you want things like haptic feedback or audio feedback upon keypress. This is
deliberately not implemented in svkbd itself (we want to keep things simple after all), but can be accomplished using
the external tool [clickclack](https://git.sr.ht/~proycon/clickclack):
$ svkbd-mobile-intl -o | clickclack -V -f keypress.wav
Notes
---------
This virtual keyboard does not actually modify the X keyboard layout, the ``mobile-intl``, ``mobile-plain`` and ``en`` layouts simply rely on a standard US QWERTY layout (setxkbmap us) being activated, the other layouts (``de``, ``ru``, ``sh``) require their respective XKB keymaps to be active.
This virtual keyboard does not actually modify the X keyboard layout, the ``mobile-intl``, ``mobile-plain``,
``mobile-simple`` and ``en`` layouts simply rely on a standard US QWERTY layout (setxkbmap us) being activated, the
other layouts (``de``, ``ru``, ``sh``) require their respective XKB keymaps to be active.
If you use another XKB layout you will get unpredictable output that does not match the labels on the virtual keycaps!

46
svkbd.1
View File

@ -1,4 +1,4 @@
.Dd August 4, 2020
.Dd March 15, 2021
.Dt SVKBD 1
.Os
.Sh NAME
@ -41,11 +41,17 @@ One row of keys takes up 1/heighfactor of the screen's total height.
Comma separated list of layers to enable (by name). If not set, all layers
in the layout will be available.
The layer names are defined by the layout you compiled.
.It Fl n
Do not simulate key presses for X
.It Fl R
Disable press-on-release
.It Fl s Ar layer
The layer to show on program start-up (by name). If not set, the first
layer of the layout will be shown.
.It Fl O
Disable overlay functionality.
.It Fl o
Print pressed keys to standard output
.It Fl v
Show the version information.
.El
@ -63,6 +69,42 @@ Set this to 0 if you want to disable overlay functionality.
Affects the vertical space taken by the keyboard.
One row of keys takes up 1/heighfactor of the screen's total height.
.El
.Sh XRESOURCES
The appearance of svkbd can be configured via xresources:
.Bl -tag -width Ds
.It Ev svkbd.font
An Xft font specification like "Monospace:bold:size=20".
.It Ev svkbd.background
The background colour for the keycaps (in #rrggbb syntax)
.It Ev svkbd.foreground
The foreground colour for the keycaps (in #rrggbb syntax)
.It Ev svkbd.shiftforeground
The foreground colour for the secondary labels (shift layer) on the keycaps
.It Ev svkbd.shiftbackground
The background colour for the secondary labels (shift layer) on the keycaps
.It Ev svkbd.abcforeground
.It Ev svkbd.abcbackbround
The colour for alphabetical keys
.It Ev svkbd.abcshiftbackground
.It Ev svkbd.abcshiftforeground
The colour for the secondary labels (shift layer) on alphabetical keys
.It Ev svkbd.pressforeground
.It Ev svkbd.pressforebackground
The colour for keys when held pressed
.It Ev svkbd.highlightforeground
.It Ev svkbd.highlightforebackground
The colour for keys when hovering over them or just after release
.It Ev svkbd.highlightshiftforeground
.It Ev svkbd.highlightshiftforebackground
The colour for the secondary label on keys when hovering over them or just
after release
.It Ev svkbd.overlayforeground
.It Ev svkbd.overlaybackground
The colour for keys when they are part of an overlay
.It Ev svkbd.overlayshiftforeground
.It Ev svkbd.overlayshiftbackground
The colour for the secondary label on keys when they are part of an overlay
.El
.Sh SEE ALSO
.Xr XParseGeometry 3
.Sh AUTHORS
@ -70,3 +112,5 @@ One row of keys takes up 1/heighfactor of the screen's total height.
.An Enno Boland Aq Mt gottox@s01.de
.An Miles Alan Aq Mt m@milesalan.com
.An Maarten van Gompel Aq Mt proycon@anaproy.nl
.An Tetrakist Aq Mt tetrakist@mutandum.com
.An Stacy Aq Mt stacy@stacyharper.net