StreetLight
/
libxkbcommon
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation 

- Add introduction to XKB
- Embrace Doxygen features
- More cross links
master
Pierre Le Marre 2023-05-13 05:30:11 +02:00 committed by Ran Benita
parent 183761ac24
commit fc664cf1cc
10 changed files with 470 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -1,13 +1,18 @@
# libxkbcommon
libxkbcommon is a keyboard keymap compiler and support library which
processes a reduced subset of keymaps as defined by the XKB (X Keyboard
processes a reduced subset of keymaps as defined by the [XKB] \(X Keyboard
Extension) specification. It also contains a module for handling Compose
and dead keys and a separate library for listing available keyboard layouts.
[XKB]: doc/introduction-to-xkb.md
## Quick Guide
See [Quick Guide](doc/quick-guide.md).
See [Introduction to XKB][XKB] to learn the essentials of XKB.
See [Quick Guide](doc/quick-guide.md) for an introduction on how to use this
library.
## Building
@ -29,7 +34,7 @@ using the X11 keyboard configuration resource files thusly:
## API
While libxkbcommon's API is somewhat derived from the classic XKB API as found
in X11/extensions/XKB.h and friends, it has been substantially reworked to
in `X11/extensions/XKB.h` and friends, it has been substantially reworked to
expose fewer internal details to clients.
See the [API Documentation](https://xkbcommon.org/doc/current/modules.html).
@ -47,7 +52,7 @@ data.
## Relation to X11
See [Compatibility](doc/compat.md) notes.
See [Compatibility](doc/compatibility.md) notes.
## Development

10
doc/Doxyfile.in
View File

@ -14,10 +14,12 @@ EXTENSION_MAPPING = no_extension=md
SORT_MEMBER_DOCS = NO
QUIET = YES
QUIET = $(DOXYGEN_QUIET)
WARN_IF_UNDOCUMENTED = NO
WARN_AS_ERROR = $(DOXYGEN_WARN_AS_ERROR)
INPUT = @INPUT@
FILE_PATTERNS = *.c \
@ -45,3 +47,9 @@ ENUM_VALUES_PER_LINE = 1
SEARCHENGINE = NO
GENERATE_LATEX = NO
HAVE_DOT = YES
DOTFILE_DIRS = doc/diagrams
DOT_IMAGE_FORMAT = svg

18
doc/compat.md → doc/compatibility.md
View File

@ -1,4 +1,8 @@
# Compatibility
# Compatibility {#xkbcommon-compatibility}
@tableofcontents{html:2}
## XKB support {#xkb-v1-compatibility}
Relative to the XKB 1.0 specification implemented in current X servers,
xkbcommon has removed support for some parts of the specification which
@ -6,14 +10,17 @@ introduced unnecessary complications. Many of these removals were in fact
not implemented, or half-implemented at best, as well as being totally
unused in the standard dataset.
Notable removals:
- geometry support
### Notable removals
- geometry support @anchor geometry
@anchor geometry-support
+ there were very few geometry definitions available, and while
xkbcommon was responsible for parsing this insanely complex format,
it never actually did anything with it
+ hopefully someone will develop a companion library which supports
keyboard geometries in a more useful format
- KcCGST (keycodes/compat/geometry/symbols/types) API
@anchor KcCGST-support
+ use RMLVO instead; KcCGST is now an implementation detail
+ including pre-defined keymap files
- XKM support
@ -37,7 +44,8 @@ Notable removals:
On the other hand, some features and extensions were added.
Notable additions:
### Notable additions
- 32-bit keycodes
- extended number of modifiers (planned)
- extended number of groups (planned)
@ -45,7 +53,7 @@ Notable additions:
+ such levels are ignored by x11/xkbcomp.
- key names (e.g. `<AE11>`) can be longer than 4 characters.
## Compose support
## Compose support {#compose-support}
Relative to the standard implementation in libX11 (described in the
Compose(5) man-page), some features are not supported:

75
doc/diagrams/xkb-configuration.dot Normal file
View File

@ -0,0 +1,75 @@
digraph {
node [shape=box]
subgraph process {
RMLVO [
label=<<i>End user configuration</i><br/><b>RMLVO:</b> <b>R</b>ules, <b>M</b>odel, <b>L</b>ayout, <b>V</b>ariant, <b>O</b>ptions>,
penwidth=3,
href="@ref RMLVO-intro",
];
RMLVO_resolution [
label=<<i>RMLVO resolution</i><br/>Determine KcCGST using the specified rules file:<br/>match the given model, layout, variant and options fields>,
style=rounded,
color=blue
];
KcCGST [
label=<<i>Layout database configuration</i><br/><b>KcCGST:</b> <b>K</b>ey<b>c</b>odes, <b>C</b>ompat, <b>G</b>eometry, <b>S</b>ymbols, <b>T</b>ypes>,
penwidth=3,
href="@ref KcCGST-intro"
];
KcCGST_resolution [
label=<<i>KcCGST resolution</i><br/>Construct the keymap from its components>,
style=rounded,
color=blue
];
Keymap [
label=<<i>Window server configuration</i><br/><b>Complete keymap</b>>,
penwidth=3,
href="@ref keymap-intro"
];
}
database [shape=none, label=<
<table border="0" cellborder="1" cellspacing="0" cellpadding="4">
<tr><td><b>Layout Database</b></td></tr>
<hr/>
<tr><td port="rules">Rules files</td></tr>
<tr><td port="keycodes">Keycodes files</td></tr>
<tr><td port="compat">Compat files</td></tr>
<tr><td port="geometry">(Geometry files)</td></tr>
<tr><td port="symbols">Symbols files</td></tr>
<tr><td port="types">Types files</td></tr>
</table>
>];
{ rank = same; KcCGST; database }
edge [
color=blue,
arrowhead=normal,
style=bold
]
{
rankdir="TB";
RMLVO -> RMLVO_resolution -> KcCGST -> KcCGST_resolution -> Keymap
}
edge [
color=dimgrey,
arrowhead=vee,
style=solid
]
RMLVO:e -> database:rules:e [constraint=false];
KcCGST:e -> database:keycodes:w [constraint=false];
KcCGST:e -> database:compat:w [constraint=false];
KcCGST:e -> database:symbols:w [constraint=false];
KcCGST:e -> database:types:w [constraint=false];
database:rules:w -> RMLVO_resolution:e [constraint=false];
database:keycodes:e -> KcCGST_resolution [constraint=false];
database:compat:e -> KcCGST_resolution [constraint=false];
database:symbols:e -> KcCGST_resolution [constraint=false];
database:types:e -> KcCGST_resolution [constraint=false];
}

22
doc/doxygen-extra.css
View File

@ -8,6 +8,26 @@ div#top, div.header, div.contents {
display: none;
}
span.TODO::before {
dl.todo dt::before {
content: '🚧 ';
}
span.todo::before {
content: '🚧 ';
}
/* Append external links with a distinctive icon */
a[href^="http://"]::after,
a[href^="https://"]::after
{
content: "";
width: 11px;
height: 11px;
margin-left: 4px;
/* Bootstrap icon: https://icons.getbootstrap.com/icons/box-arrow-up-right/ */
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='currentColor' class='bi bi-box-arrow-up-right' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z'/%3E%3Cpath fill-rule='evenodd' d='M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z'/%3E%3C/svg%3E");
background-position: center;
background-repeat: no-repeat;
background-size: contain;
display: inline-block;
}

207
doc/introduction-to-xkb.md Normal file
View File

@ -0,0 +1,207 @@
# Introduction to XKB {#xkb-intro}
__XKB__ stands for “X Keyboard Extension”. It may refer to either:
- a [protocol](@ref xkb-the-protocol)
- a [keyboard layout configuration](@ref xkb-the-config)
- a [text format](@ref xkb-the-text-format)
## XKB the protocol {#xkb-the-protocol}
A __protocol__ for the [X Windows System], that extends the core protocol.
_xkbcommon’s_ API is somehow derived from this API, but has been
substantially reworked to function as a library instead of a protocol,
and exposes fewer internal details to clients.
_xkbcommon_ does not depend on a particular windows system; for instance
it is used by the [Wayland] protocol.
_xkbcommon_ provides the <code>[xkbcommon-x11]</code> module to interface
a client with an X server using the XKB protocol. Relevant links:
- [The X Window System Protocol][X Protocol]
- [The X Keyboard Extension: Protocol Specification][XKB Protocol]
- [xkbcommon-x11]
## XKB the keyboard keymap configuration {#xkb-the-config}
In order to use [the protocol](@ref xkb-the-protocol), one must first load a
[complete keymap]. The keymap usually comes from the OS _layout database_,
which is commonly [xkeyboard-config]. Since keymaps may have definitions in
common, the database actually stores their basic components separately to allow
maximum composability and coherence. A recipe to compose a keymap from its
components is called a _keymap configuration_.
In XKB, there are several ways to define a keymap configuration. They all aim to
produce a [complete keymap]. The following diagram presents an overview.
Then they are presented hereinafter, ordered from end user to low-level
implementation.
@dotfile xkb-configuration "XKB keymap configurations"
<dl>
<dt>
RMLVO: <u>R</u>ules, <u>M</u>odel, <u>L</u>ayout, <u>V</u>ariant,
<u>O</u>ptions @anchor RMLVO-intro
</dt>
<dd>
This is the configuration the end user usually faces in the UI.
The idea is to expose high level concepts such as [keyboard model] and
[keyboard layout] to the user, then to _map_ them to the corresponding set
of low-level configuration files (see [KcCGST]).
@note The RMLVO configurations actually available to the end user is managed
by the `xkbregistry`. It uses an XML file, the _registry_, which exposes and
documents the set of RMLVO settings in the layout database.
The RMLVO configuration consists of the following components:
<dl>
<dt>Rules</dt>
<dd>
The rules define the _mapping_ from high to low level components.
The rules _component_ is the file containing the set of rules to use.
It is usually implicit and set by the system.
See the [rules file format](@ref rule-file-format) for further details.
</dd>
<dt>Model</dt>
<dd>
The name of the model of the keyboard hardware in use.
It may depend on:
- The _location_ and _language_ of the user, because languages may
require [specific keys][language input keys] for their input methods,
such as the _muhenkan_ key on Japanese keyboard and the _Hanja_ key
for Korean keyboards. The keyboard are usually classified by the
[standard][keyboard standard] it is based on, e.g. ANSI, ISO, JIS,
ABNT.
- The keyboard _vendor:_ keyboard may have a set of keys that are not
standard, or may be specific to an OS.
</dd>
<dt>Layout</dt>
<dd>
The identifier of the general layout to use. It usually refers to a
country or a language.
</dd>
<dt>Variant</dt>
<dd>
Any minor variants on the general layout. It may be national variants
</dd>
<dt>Options</dt>
<dd>
Set of extra options to customize the standard layouts.
Examples: switch modifiers keys, location of the compose key, etc.
</dd>
</dl>
</dd>
<dt>
KcCGST: <u>K</u>ey<u>c</u>odes, <u>C</u>ompat, <u>G</u>eometry,
<u>S</u>ymbols, <u>T</u>ypes @anchor KcCGST-intro
</dt>
<dd>
This is the low-level configuration of XKB and how the files are actually
organized in the _layout database_.
It is not really intuitive or straight-forward for the uninitiated.
@note _xkbcommon_ [does not offer an API for KcCGST](@ref KcCGST-support):
it is considered an implementation detail.
Instead, [RMLVO] is the preferred way for the user to configure XKB.
The KcCGST configuration consists of the following components:
<dl>
<dt>Key codes</dt>
<dd>
A translation of the raw [key codes] from the keyboard into
symbolic names.
</dd>
<dt>Compatibility</dt>
<dd>
A specification of what internal actions modifiers and various
special-purpose keys produce.
</dd>
<dt>Geometry</dt>
<dd>
A description of the physical layout of a keyboard.
@attention This legacy feature is [not supported](@ref geometry-support)
by _xkbcommon_.
</dd>
<dt>Key symbols</dt>
<dd>
A translation of symbolic key codes into actual [key symbols] (keysyms).
</dd>
<dt>Key types</dt>
<dd>
Types describe how a pressed key is affected by active [modifiers]
such as Shift, Control, Alt, etc.
</dd>
</dl>
</dd>
<dt>Complete Keymap @anchor keymap-intro</dt>
<dd>
A complete keymap is a _self-contained_ text file with all the [KcCGST]
components needed to configure a keyboard. This is the result of the
_resolution_ of the [RMLVO] and [KcCGST] configurations. This is also the
format used by X11 and Wayland when prompted to _serialize_ the keymap in use.
@note This is a low-level configuration. [RMLVO] is the preferred way for the
end user to configure XKB, but some _power users_ may need it for _avanced_
configurations.
See the [XKB text format] for further details.
</dd>
</dl>
@note Layout making use of dead keys require a [Compose](@ref compose) file. The
same applies when if using a [Compose key].
[key codes]: @ref keycode-def
[key symbols]: @ref keysym-def
[levels]: @ref level-def
[modifiers]: @ref modifier-def
[RMLVO]: @ref RMLVO-intro
[KcCGST]: @ref KcCGST-intro
[complete keymap]: @ref keymap-intro
[Compose key]: https://en.wikipedia.org/wiki/Compose_key
[XKB text format]: @ref xkb-the-text-format
## XKB the text format {#xkb-the-text-format}
A __text format__ to define keyboard keymaps. XKB 1.0 is the specification
implemented in current X servers. The format supported by _xkbcommon_
is very close to XKB 1.0, with some removals and additions. See the
[compatibility] page for further details.
The format supported by _xkbcommon_ is documented at the page
“[The XKB keymap text format, V1][keymap-text-format-v1]”.
The documentation of the _original_ XKB 1.0 format is much more scarce than
for the protocol. Some priceless resources are:
- [Ivan Pascal's XKB documentation][ivan-pascal]
- [An Unreliable Guide to XKB Configuration][unreliable-guide]
- [ArchWiki XKB page][arch-wiki]
[X Windows System]: https://en.wikipedia.org/wiki/X_Window_System
[X Protocol]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#Keyboards
[XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html
[xkbcommon-x11]: @ref x11-overview
[Wayland]: https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_keyboard
[compatibility]: @ref xkb-v1-compatibility
[keymap-text-format-v1]: @ref keymap-text-format-v1
[ivan-pascal]: https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/
[unreliable-guide]: https://www.charvolant.org/doug/xkb/html/index.html
[arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension
[keyboard model]: https://en.wikipedia.org/wiki/Computer_keyboard
[keymap]: https://en.wikipedia.org/wiki/Keyboard_layout
[keyboard layout]: https://en.wikipedia.org/wiki/Keyboard_layout
[xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
[keyboard standard]: https://en.wikipedia.org/wiki/Computer_keyboard#Types_and_standards
[language input keys]: https://en.wikipedia.org/wiki/Language_input_keys
@todo Explain how to configure XKB, with examples

174
doc/keymap-format-text-v1.md
View File

@ -1,8 +1,8 @@
# The XKB keymap text format, V1
# The XKB keymap text format, V1 {#keymap-text-format-v1}
<!--
NOTE:
• The Markdown supported in doxygen is limitated and buggy.
• The Markdown supported in Doxygen is limited and buggy.
Current issues and solutions:
• In headers, only plain text is supported.
• Use the language tag “c” for block code to give them a nice (approximated)
@ -15,16 +15,27 @@ as implemented by libxkbcommon.
The standard database of keyboard configuration data is
[xkeyboard-config].
[xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
NOTE: Due to the complexity of the format, this document is still is construction.
@note Due to the complexity of the format, this document is still is construction.
Some additional resources are:
- [Ivan Pascal's XKB documentation](https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/)
- [An Unreliable Guide to XKB Configuration](https://www.charvolant.org/doug/xkb/html/index.html)
- [The X Keyboard Extension: Protocol Specification](https://www.x.org/releases/current/doc/kbproto/xkbproto.html)
- [ArchWiki XKB page](https://wiki.archlinux.org/index.php/X_keyboard_extension)
@note
- [Ivan Pascal's XKB documentation][ivan-pascal]
- [An Unreliable Guide to XKB Configuration][unreliable-guide]
- [The X Keyboard Extension: Protocol Specification][XKB Protocol]
- [How to enhance XKB configuration][xkeyboard-config doc]
- [ArchWiki XKB page][arch-wiki]
[xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
[ivan-pascal]: https://web.archive.org/web/20190724015820/http://pascal.tsu.ru/en/xkb/
[unreliable-guide]: https://www.charvolant.org/doug/xkb/html/index.html
[XKB Protocol]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html
[xkeyboard-config doc]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/docs/README.enhancing
[arch-wiki]: https://wiki.archlinux.org/index.php/X_keyboard_extension
@tableofcontents{html:2}
<!--
## Table of contents
1. [Terminology][terminology]
@ -37,6 +48,7 @@ Some additional resources are:
8. [Virtual modifier statements][virtual modifier statements]
9. [Modifiers bindings][modifiers bindings]
10. [Key actions][actions]
-->
[terminology]: @ref terminology
[introduction]: @ref introduction
@ -75,8 +87,8 @@ Some additional resources are:
- A _character:_ e.g. `a` and `A` for Latin scripts,
`alpha` “α” and `ALPHA` “Α” for Greek, etc.
- A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding repectively
to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent)
- A _dead key:_ e.g. `dead_grave` and `dead_diaeresis`, corresponding
respectively to the [grave accent](https://en.wikipedia.org/wiki/Grave_accent)
and the [diaeresis](https://en.wikipedia.org/wiki/Diaeresis_%28diacritic%29)
diacritics.
@ -84,7 +96,7 @@ Some additional resources are:
that does not generate a character by itself, but modifies the character
generated by the key struck(s) immediately after.
- A <em>[modifier]⁠:</em> e.g. `Shift_L`, `Control_R`, `Caps_Lock`.
See herinafter.
See hereinafter.
- A _system action:_ e.g. the arrow `Left`, `Pause`, `Escape`, `F1`.
The complete list of keysyms is defined in `xkbcommon/xkbcommon-keysyms.h`.
@ -165,12 +177,12 @@ Some additional resources are:
<dd>Active while depressed; e.g. the usual Shift.</dd>
<dt><a name="latched-mod-def">Latched</a></dt>
<dd>
Actived when pressed and deactivated after the next
Activated when pressed and deactivated after the next
non-modifier key press.
</dd>
<dt><a name="locked-mod-def">Locked</a></dt>
<dd>
Actived when pressed and deactivated when pressed again;
Activated when pressed and deactivated when pressed again;
e.g. the usual Caps Lock.
</dd>
</dl>
@ -263,7 +275,7 @@ Some additional resources are:
<dl>
<dt><em>Physical</em> indicator</dt>
<dd>
Typcally a labelled LED on the keyboard, e.g. “Caps Lock” and
Typically a labelled LED on the keyboard, e.g. “Caps Lock” and
“Num Lock”.
</dd>
<dt><em>Logical</em> indicator</dt>
@ -280,7 +292,7 @@ Some additional resources are:
Because indicators are customizable, if one misses a “Num Lock”
LED, one could define instead the “Caps Lock” _indicator_ to
activate its LED when the “Num Lock” _modifier_ is active.
- _Virtual_ indicators are not assiociated to a physical indicator.
- _Virtual_ indicators are not associated to a physical indicator.
Their effect is only visible for programs monitoring them.
Note that the meanings of _real_ and _virtual_ is slightly
@ -295,7 +307,7 @@ Some additional resources are:
<dd>
The _complete_ definition of the
mapping of raw keycodes to symbols and actions.
It fully defines the behaviour of a keyboard.
It fully defines the behavior of a keyboard.
See [xkb_keymap] for further details.
</dd>
@ -324,20 +336,70 @@ Some additional resources are:
## Introduction to the XKB text format {#introduction}
The XKB text format uses a language similar to the C program language.
The XKB text format uses a syntax similar to the [C programming language][C].
<span class="TODO">TODO:</span> general comment on syntax: section,
values, etc.
@todo general comment on syntax: section, values, etc.
<span class="TODO">TODO:</span> the import mecanism
@todo the import mechanism
<span class="TODO">TODO:</span> recommended ways to feed xkbcommon
@todo recommended ways to feed xkbcommon
[C]: https://en.wikipedia.org/wiki/C_(programming_language)#Syntax
### Keywords
@todo keywords, other settings such as “SetMods”
<!--
TODO: SetMods is not a keyword, but how call it for using-facing doc?
There are many keywords
The key words are _case-insensitive_, e.g. the following strings denote
the same key word: `SETMODS`, `SetMods`, `setMods` and `setmods`.
-->
### Literals
<dl>
<dt>String literal</dt>
<dd>
A string is surrounded by double quotes: “<code>&quot;</code>”.
The following _escape sequences_ are supported:
| Escape sequence | Meaning |
| ------------------ | ------------------------------------------------------- |
| `\\` | Backslash “`\`” |
| `\b` | Backspace |
| `\e` | Escape |
| `\f` | Form feed |
| `\n` | Line feed (newline) |
| `\r` | Carriage return |
| `\t` | Horizontal tabulation |
| `\v` | Vertical tabulation |
| `\` + octal number | Corresponding ASCII character: `\0` → NULL, `\42` → `"` |
@note The string _encoding_ is unspecified and not validated, but for best
results, stick to ASCII.
<!-- TODO: check UTF-8 encoding result -->
</dd>
<dt>Number literal</dt>
<dd>
A number can be written in three forms:
- _decimal integer:_ `1`, `123`, etc.
- _decimal floating-point number:_ `1.23`, etc.
- _hexadecimal integer:_ prefixed with `0x`: `0x123`, `0xff`, `0xAB`, etc.
</dd>
</dl>
## The “xkb_keymap” block {#the-xkb_keymap-block}
A <strong>[keymap]</strong> consists of a single top-level `xkb_keymap`
block, underwhich are nested the following sections:
block, under which are nested the following sections:
<dl>
<dt><code>[xkb_keycodes]</code></dt>
@ -761,12 +823,12 @@ satisfied the LED is lit.
### Default values
<span class="TODO">TODO:</span> e.g. `setMods.clearLocks= True;`
@todo e.g. `setMods.clearLocks= True;`
## The “xkb_symbols” section {#the-xkb_symbols-section}
<span class="TODO">TODO:</span> complete this section.
@todo complete this section.
This section is the fourth to be processed, after `xkb_keycodes`,
`xkb_types` and `xkb_compat`.
@ -850,7 +912,7 @@ level 1 and `XKB_KEY_Q` for level 2.
#### Actions
<span class="TODO">TODO:</span> how to bind key actions
@todo how to bind key actions
For further details see [key actions][actions].
@ -878,11 +940,11 @@ statement only defines the Group3 of a mapping:
#### Additional attributes
<span class="TODO">TODO:</span> virtualmodifiers, repeats
@todo virtualmodifiers, repeats
## Virtual modifier statements {#virtual-modifier-statements}
<span class="TODO">TODO:</span> rework this section
@todo rework this section
Statements of the form:
@ -933,7 +995,7 @@ modifier `LevelThree` in `xkeyboard-config`.
In order to define and use a modifier, one must:
1. Define its behaviour and [keysym] binding in the
1. Define its behavior and [keysym] binding in the
<code>[xkb_compat]</code> section:
```c
@ -941,7 +1003,7 @@ In order to define and use a modifier, one must:
// we do not need to add it here.
virtual_modifiers LevelThree;
// Set defaults. They are overriden if set directly in the xkb_symbols.
// Set defaults. They are overridden if set directly in the xkb_symbols.
interpret.repeat= False; // only applied on first level
setMods.clearLocks= True;
latchMods.clearLocks= True;
@ -981,7 +1043,7 @@ In order to define and use a modifier, one must:
// • The condition is equivalent to
// ISO_Level3_Shift+AnyOfOrNone(all), but since
// the previous statement ISO_Level3_Shift+Any is more
// specififc, it will be matched before this one.
// specific, it will be matched before this one.
interpret ISO_Level3_Shift {
// Activate the LevelThree modifier (depressed mode)
action= SetMods(modifiers=LevelThree);
@ -1083,7 +1145,7 @@ In order to define and use a modifier, one must:
## Key actions {#key-actions}
<span class="TODO">TODO:</span> list of all actions and their parameters
@todo list of all actions and their parameters
The following table provide an overview of the available actions:
@ -1093,18 +1155,18 @@ The following table provide an overview of the available actions:
| [Modifier action] | `SetMods` | | Modifies the _depressed_ modifiers |
| ^ | `LatchMods` | | Modifies the _latched_ modifiers |
| ^ | `LockMods` | | Modifies the _locked_ modifiers |
| [Group action] | `SetGroup` | | <span class="TODO">TODO</span> |
| ^ | `LatchGroup` | | <span class="TODO">TODO</span> |
| ^ | `LockGroup` | | <span class="TODO">TODO</span> |
| [Legacy action] | `MovePointer` | `MovePtr` | <span class="TODO">TODO</span> |
| ^ | `PointerButton` | `PtrBtn` | <span class="TODO">TODO</span> |
| ^ | `LockPointerButton` | `LockPtrBtn` | <span class="TODO">TODO</span> |
| ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="TODO">TODO</span> |
| ^ | `SetControls` | | <span class="TODO">TODO</span> |
| ^ | `LockControls` | | <span class="TODO">TODO</span> |
| ^ | `TerminateServer` | `Terminate` | <span class="TODO">TODO</span> |
| ^ | `SwitchScreen` | | <span class="TODO">TODO</span> |
| ^ | `Private` | | <span class="TODO">TODO</span> |
| [Group action] | `SetGroup` | | <span class="todo">TODO</span> |
| ^ | `LatchGroup` | | <span class="todo">TODO</span> |
| ^ | `LockGroup` | | <span class="todo">TODO</span> |
| [Legacy action] | `MovePointer` | `MovePtr` | <span class="todo">TODO</span> |
| ^ | `PointerButton` | `PtrBtn` | <span class="todo">TODO</span> |
| ^ | `LockPointerButton` | `LockPtrBtn` | <span class="todo">TODO</span> |
| ^ | `SetPointerDefault` | `SetPtrDflt` | <span class="todo">TODO</span> |
| ^ | `SetControls` | | <span class="todo">TODO</span> |
| ^ | `LockControls` | | <span class="todo">TODO</span> |
| ^ | `TerminateServer` | `Terminate` | <span class="todo">TODO</span> |
| ^ | `SwitchScreen` | | <span class="todo">TODO</span> |
| ^ | `Private` | | <span class="todo">TODO</span> |
Common syntax:
- Boolean values:
@ -1115,7 +1177,7 @@ Common syntax:
[modifier action]: @ref modifiers-actions
<span class="TODO">TODO:</span> default values
@todo default values
There are 3 modifiers actions:
@ -1155,7 +1217,7 @@ There are 3 modifiers actions:
</dd>
</dl>
<span class="TODO">TODO:</span> highlight that there is reference counting for
@todo highlight that there is reference counting for
the modifiers, e.g. to manage multiple physical keys for the same modifier.
These actions perform different tasks on key press and on key release:
@ -1240,7 +1302,7 @@ These actions perform different tasks on key press and on key release:
<!-- </tbody> -->
</table>
<span class="TODO">TODO:</span> Finish
@todo Finish
### Group actions {#group-actions}
@ -1251,25 +1313,25 @@ There are 3 group actions:
<dl>
<dt>SetGroup</dt>
<dd>
<span class="TODO">TODO</span>
<span class="todo">TODO</span>
</dd>
<dt>LatchGroup</dt>
<dd>
<span class="TODO">TODO</span>
<span class="todo">TODO</span>
</dd>
<dt>LockGroup</dt>
<dd>
<span class="TODO">TODO</span>
<span class="todo">TODO</span>
</dd>
</dl>
<span class="TODO">TODO:</span> Describe each action
@todo Describe each action
### Unsupported legacy actions {#legacy-actions}
[legacy action]: @ref legacy-actions
The following legacy actions are kept for compatibility only: they are parsed
@attention The following legacy actions are kept for compatibility only: they are parsed
and validated but have no effect. This allows to use keymaps defined in
<code>[xkeyboard-config]</code> for both X11 and Wayland.
@ -1283,16 +1345,16 @@ and validated but have no effect. This allows to use keymaps defined in
| `LockPointerButton` | `LockPointerBtn` | |
| `SetPointerDefault` | `SetPtrDflt` | |
<span class="TODO">TODO:</span> Describe each action
@todo Describe each action
#### Control flags actions
<span class="TODO">TODO:</span> `SetControls`, `LockControls`
@todo `SetControls`, `LockControls`
#### Server actions
<span class="TODO">TODO:</span> `TerminateServer`, `SwitchScreen`
@todo `TerminateServer`, `SwitchScreen`
#### Private action
<span class="TODO">TODO:</span> `Private`
@todo `Private`

15
doc/rules-format.md
View File

@ -1,24 +1,25 @@
The rules file
The rules file {#rule-file-format}
==============
The purpose of the rules file is to map between configuration values
that are easy for a user to specify and understand, and the
configuration values xkbcomp uses and understands.
xkbcomp uses the xkb_component_names struct, which maps directly to
xkbcomp uses the `xkb_component_names` struct, which maps directly to
include statements of the appropriate sections, called for short
KcCGST (see doc/keymap-format-text-v1.txt; 'G' stands for "geometry",
which is not supported). These are not really intuitive or straight-
forward for the uninitiated.
[KcCGST](@ref KcCGST-intro) (see the [XKB introduction](@ref xkb-intro);
'G' stands for "geometry", which is not supported). These are not
really intuitive or straight-forward for the uninitiated.
Instead, the user passes in a xkb_rule_names struct, which consists
Instead, the user passes in a `xkb_rule_names` struct, which consists
of the name of a rules file (in Linux this is usually "evdev"), a
keyboard model (e.g. "pc105"), a set of layouts (which will end up
in different groups, e.g. "us,fr"), variants (used to alter/augment
the respective layout, e.g. "intl,dvorak"), and a set of options
(used to tweak some general behavior of the keyboard, e.g.
"ctrl:nocaps,compose:menu" to make the Caps Lock key act like Ctrl
and the Menu key like Compose). We call these RMLVO.
and the Menu key like Compose). We call these
[RMLVO](@ref RMLVO-intro).
Format of the file
------------------

4
meson.build
View File

@ -792,9 +792,11 @@ You can disable the documentation with -Denable-docs=false.''')
doxygen_input = [
'README.md',
'doc/diagrams/xkb-configuration.dot',
'doc/doxygen-extra.css',
'doc/introduction-to-xkb.md',
'doc/quick-guide.md',
'doc/compat.md',
'doc/compatibility.md',
'doc/user-configuration.md',
'doc/rules-format.md',
'doc/keymap-format-text-v1.md',

7
scripts/doxygen-wrapper
View File

@ -5,4 +5,11 @@
DOXYGEN="$1"
DOXYFILE="$2"
ABS_TOP_SRCDIR="$3"
# Set environment variables that are unset
if [ -z "$DOXYGEN_WARN_AS_ERROR" ]
then export DOXYGEN_WARN_AS_ERROR="NO"
fi
if [ -z "$DOXYGEN_QUIET" ]
then export DOXYGEN_QUIET="YES"
fi
cd "$ABS_TOP_SRCDIR" && exec "$DOXYGEN" "$DOXYFILE"