doc/keymap: add documentation for xkb_symbols (#205)

1 files changed, 103 insertions, 3 deletions

diff --git a/doc/keymap-format-text-v1.md b/doc/keymap-format-text-v1.md
index eda6ebb..67c58fa 100644
--- a/doc/keymap-format-text-v1.md
+++ b/doc/keymap-format-text-v1.md
@@ -351,11 +351,110 @@ satisfied the LED is lit.
 
 ## The `xkb_symbols` section
 
-This section is the fourth to be processed, after `xkb_keycodes`,
-`xkb_types` and `xkb_compat`.
+NOTE: This section is incomplete.
 
-TODO
+This section is the fourth to be processed, after `xkb_keycodes`, `xkb_types`
+and `xkb_compat`.
+
+Statements of the form:
+
+    xkb_symbols "basic" {
+        ...
+    }
+
+Declare a symbols map named `basic`. Statements inside the curly braces will
+affect only affect the symbols map.
+
+A map can have various flags applied to it above the statement, separated by
+whitespace:
+
+    partial alphanumeric_keys
+    xkb_symbols "basic" {
+        ...
+    }
+
+The possible flags are the following:
+
+  * `partial` - Indicates that the map doesn't cover a complete keyboard
+  * `default` - Marks the symbol map as the default map in the file when no
+  explicit map is specified. If no map is marked as a default, the first map in
+  the file is the default.
+  * `hidden` - Variant that can only be used internally
+  * `alphanumeric_keys` - Indicates that the map contains alphanumeric keys
+  * `modifier_keys` - Indicates that the map contains modifier keys
+  * `keypad_keys` - Indicates that the map contains keypad keys
+  * `function_keys` - Indicates that the map contains function keys
+  * `alternate_group` - Indicates that the map contains keys for an alternate
+    group
+
+If no `*_keys` flags are supplied, then the map is assumed to cover a complete
+keyboard.
+
+At present, except for `default`, none of the flags affect key processing in
+libxkbcommon, and only serve as metadata.
+
+### Name statements
+
+Statements of the form:
+
+    name[Group1] = "US/ASCII";
+    groupName[1] = "US/ASCII";
+
+Gives the name "US/ASCII" to the first group of symbols. Other groups can be
+named using a different group index (ex: `Group2`), and with a different name.
+A group must be named.
+
+`group` and `groupName` mean the same thing, and the `Group` in `Group1` is
+optional.
+
+### Include statements
 
+Statements of the form:
+
+    include "nokia_vndr/rx-51(nordic_base)
+
+Will include data from another `xkb_symbols` section, possibly located in
+another file. Here it would include the `xkb_symbols` section called
+`nordic_base`, from the file `rx-51` located in the `nokia_vndr` folder, itself
+located in an XKB include path.
+
+### Key statement
+
+Statements of the form:
+
+    key <AD01> { [ q, Q ] };
+
+Describes the mapping of a keycode `<AD01>` to a given group of symbols. The
+symbols are `q` and `Q` in this example.
+
+The possible keycodes are the keycodes defined in the `xkb_keycodes` section.
+
+Symbols are named using the symbolic names from the
+`xkbcommon/xkbcommon-keysyms.h` file. A group of symbols is enclosed in brackets
+and separated by commas. Each element of the symbol arrays corresponds to a
+different modifier level.
+
+#### Groups
+
+Each group represents a list of symbols mapped to a keycode:
+
+    name[Group1]= "US/ASCII";
+    name[Group2]= "Russian";
+    ...
+    key <AD01> { [ q, Q ],
+                 [ Cyrillic_shorti, Cyrillic_SHORTI ] };
+
+The long-form syntax can also be used to represent groups:
+
+    key <AD01> {
+        symbols[Group1]= [ q, Q ],
+        symbols[Group2]= [ Cyrillic_shorti, Cyrillic_SHORTI ]
+    };
+
+Groups can also be omitted, but the brackets must be present. The following
+statement only defines the Group3 of a mapping:
+
+    key <AD01> { [], [], [ q, Q ] };
 
 ## Virtual modifier statements
 
@@ -366,3 +465,4 @@ Statements of the form:
 Can appear in the `xkb_types`, `xkb_compat`, `xkb_symbols` sections.
 
 TODO
+