Doc: fix malformed links and some typos

master
Pierre Le Marre 2023-11-14 10:10:50 +01:00 committed by Wismill
parent 00e3058e7b
commit 79502700a6
3 changed files with 19 additions and 15 deletions

View File

@ -132,7 +132,7 @@ implementation.
</dd> </dd>
<dt>Key symbols</dt> <dt>Key symbols</dt>
<dd> <dd>
A translation of symbolic key codes into actual [key symbols] (keysyms). A translation of symbolic key codes into actual [key symbols] \(keysyms).
</dd> </dd>
<dt>Key types</dt> <dt>Key types</dt>
<dd> <dd>

View File

@ -7,10 +7,12 @@ 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 include statements of the appropriate sections, called for short
[KcCGST](@ref KcCGST-intro) (see the [XKB [KcCGST] \(see the [XKB introduction]; 'G' stands for "geometry",
introduction](doc/introduction-to-xkb.md); which is not supported). These are not really intuitive nor
'G' stands for "geometry", which is not supported). These are not straightforward for the uninitiated.
really intuitive or straight-forward for the uninitiated.
[KcCGST]: @ref KcCGST-intro
[XKB introduction]: @ref xkb-intro
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 of the name of a rules file (in Linux this is usually "evdev"), a

View File

@ -11,14 +11,14 @@ libxkbcommon searches the following paths for XKB configuration files:
- `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME` - `$XDG_CONFIG_HOME/xkb/`, or `$HOME/.config/xkb/` if the `$XDG_CONFIG_HOME`
environment variable is not defined environment variable is not defined
- `$HOME/.xkb/` - `$HOME/.xkb/`
- `$XKB_CONFIG_EXTRA_PATH` if set, otherswise `<sysconfdir>/xkb` (on most - `$XKB_CONFIG_EXTRA_PATH` if set, otherwise `<sysconfdir>/xkb` (on most
distributions this is `/etc/xkb`) distributions this is `/etc/xkb`)
- `$XKB_CONFIG_ROOT` if set, otherwise `<datadir>/X11/xkb/` (path defined by the - `$XKB_CONFIG_ROOT` if set, otherwise `<datadir>/X11/xkb/` (path defined by the
`xkeyboard-config` package, on most distributions this is `xkeyboard-config` package, on most distributions this is
`/usr/share/X11/xkb`) `/usr/share/X11/xkb`)
A keymap created with `xkb_keymap_new_from_names()` will look up those paths in A keymap created with `xkb_keymap::xkb_keymap_new_from_names()` will look up
order until the required data is found. those paths in order until the required data is found.
**Note: Where libxkbcommon runs in a privileged context, only the system **Note: Where libxkbcommon runs in a privileged context, only the system
(datadir) path is available.** (datadir) path is available.**
@ -31,23 +31,25 @@ Each directory should have one or more of the following subdirectories:
- `symbols` - `symbols`
- `types` - `types`
The majority of user-specific configuration involve modifying key symbols and The majority of user-specific configurations involve modifying key symbols and
this is what this document focuses on. For use-cases where a user may need to this is what this document focuses on. For use-cases where a user may need to
add new key types or compat entries the general approach remains the same. A add new key types or compat entries the general approach remains the same. A
detailed description for how to add those types or compat entries is out of detailed description for how to add those types or compat entries is out of
scope for this document. scope for this document.
You should never need to add user-specific keycodes. Where a keycode is missing, You should never need to add user-specific keycodes. Where a keycode is missing,
the addition should be filed in the upstream xkeyboard-config project. the addition should be filed in the upstream [xkeyboard-config] project.
[xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
## RMLVO vs KcCGST ## RMLVO vs KcCGST
Due to how XKB is configured, there is no such thing as a "layout" in XKB Due to how XKB is configured, there is no such thing as a "layout" in XKB
itself, or, indeed, any of the rules, models, variant, options (RMLVO) decribed itself, or, indeed, any of the rules, models, variant, options (RMLVO) described
in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the in `struct xkb_rule_names`. RMLVO names are merely lookup keys in the
rules file provided by xkeyboard-config to map to the correct keycode, compat, rules file provided by xkeyboard-config to map to the correct keycode, compat,
geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data
is the one used by XKB and libxbkcommon to map keys to actual symbols. is the one used by XKB and libxkbcommon to map keys to actual symbols.
For example, a common RMLVO configuration is layout "us", variant "dvorak" and For example, a common RMLVO configuration is layout "us", variant "dvorak" and
option "terminate:ctrl_alt_bksp". Using the default rules file and model option "terminate:ctrl_alt_bksp". Using the default rules file and model
@ -64,7 +66,7 @@ xkb_keymap {
``` ```
A detailed explanation of how rules files convert RMLVO to KcCGST is out of A detailed explanation of how rules files convert RMLVO to KcCGST is out of
scope for this document. See [the rules file](md_doc_rules-format.html) page scope for this document. See the page “@ref rule-file-format ""” instead.
instead. instead.
@ -76,7 +78,7 @@ The default rules files (usually `evdev`) have a catch-all to map a layout, say
"foo", and a variant, say "bar", into the "bar" section in the file "foo", and a variant, say "bar", into the "bar" section in the file
`$xkb_base_dir/symbols/foo`. `$xkb_base_dir/symbols/foo`.
This is sufficient to define a new keyboard layout. The example below defines This is sufficient to define a new keyboard layout. The example below defines
the keyboard layout "banana" with an optional variant "orange" the keyboard layout "banana" with an optional variant "orange":
``` ```
$ cat $XDG_CONFIG_HOME/xkb/symbols/banana $ cat $XDG_CONFIG_HOME/xkb/symbols/banana
@ -117,7 +119,7 @@ symbols. The effect of this section is to swap the numbers and symbols in the
top-most row (compared to the US layout) but otherwise use the US layout. top-most row (compared to the US layout) but otherwise use the US layout.
The "orange" variant uses the "banana" symbols and includes a different section The "orange" variant uses the "banana" symbols and includes a different section
to define the eurosign. It does not specificially override any symbols. to define the eurosign. It does not specifically override any symbols.
The exact details of how `xkb_symbols` work is out of scope for this document. The exact details of how `xkb_symbols` work is out of scope for this document.