doc/keymap-format-text-v1: add title and intro

Signed-off-by: Ran Benita <ran234@gmail.com>

diff --git a/doc/keymap-format-text-v1.md b/doc/keymap-format-text-v1.md
index 27e561e..eda6ebb 100644 (file)
--- a/doc/keymap-format-text-v1.md
+++ b/doc/keymap-format-text-v1.md
@@ -1,11 +1,20 @@
-# The `xkb_keycodes` section
+# The XKB keymap text format, V1
+
+This document describes the `XKB_KEYMAP_FORMAT_TEXT_V1` keymap format,
+as implemented by libxkbcommon.
+
+A keymap consists of a single top-level `xkb_keymap` block, underwhich
+are nested the following sections.
+
+
+## The `xkb_keycodes` section

 
 This is the simplest section type, and is the first one to be
 compiled. The purpose of this is mostly to map between the
 hardware/evdev scancodes and xkb keycodes. Each key is given a name
 by which it can be referred to later, e.g. in the symbols section.
 
 
 This is the simplest section type, and is the first one to be
 compiled. The purpose of this is mostly to map between the
 hardware/evdev scancodes and xkb keycodes. Each key is given a name
 by which it can be referred to later, e.g. in the symbols section.
 

-## Keycode statements
+### Keycode statements

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -35,7 +44,7 @@ If there's a conflict, like the same name given to different keycodes,
 or same keycode given different names, it is resolved according to the
 merge mode which applies to the definitions.
 
 or same keycode given different names, it is resolved according to the
 merge mode which applies to the definitions.
 

-## Alias statements
+### Alias statements

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -45,7 +54,7 @@ Allows to refer to a previously defined key (here `<COMP>`) by another
 name (here `<MENU>`). Conflicts are handled similarly to keycode
 statements.
 
 name (here `<MENU>`). Conflicts are handled similarly to keycode
 statements.
 

-## LED name statements
+### LED name statements

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -58,7 +67,7 @@ index. The LED may be referred by this name later in the compat
 section and by the user.
 
 
 section and by the user.
 
 

-# The `xkb_types` section
+## The `xkb_types` section

 
 This section is the second to be processesed, after `xkb_keycodes`.
 However, it is completely independent and could have been the first to
 
 This section is the second to be processesed, after `xkb_keycodes`.
 However, it is completely independent and could have been the first to


@@ -81,7 +90,7 @@ affected by the modifier state. Yet more common examples are
 `TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
 (where Caps Lock may also choose the second level), etc.
 
 `TWO_LEVEL` (with Shift choosing the second level), `ALPHABETIC`
 (where Caps Lock may also choose the second level), etc.
 

-## Type definitions
+### Type definitions

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -91,7 +100,7 @@ The above would create a new type named `FOUR_LEVEL`.
 The body of the definition may include statements of the following
 forms:
 
 The body of the definition may include statements of the following
 forms:
 

-### `level_name` statements
+#### `level_name` statements

 
     level_name[Level1] = "Base";
 
 
     level_name[Level1] = "Base";
 


@@ -103,7 +112,7 @@ for anything.
 Note: A level may be specified as Level[1-8] or just a number (can
 be more than 8).
 
 Note: A level may be specified as Level[1-8] or just a number (can
 be more than 8).
 

-### `modifiers` statement
+#### `modifiers` statement

 
     modifiers = Shift+Lock+LevelThree;
 
 
     modifiers = Shift+Lock+LevelThree;
 


@@ -114,7 +123,7 @@ being considered when matching the modifier state against the type.
 The other modifiers, whether active or not, are masked out in the
 calculation.
 
 The other modifiers, whether active or not, are masked out in the
 calculation.
 

-### `map` entry statements
+#### `map` entry statements

 
     map[Shift+LevelThree] = Level4;
 
 
     map[Shift+LevelThree] = Level4;
 


@@ -127,7 +136,7 @@ above, if in the current keyboard state the `Shift` and `LevelThree`
 modifiers are active, while the `Lock` modifier is not, then the
 keysym(s) in the 4th level of the group will be returned to the user.
 
 modifiers are active, while the `Lock` modifier is not, then the
 keysym(s) in the 4th level of the group will be returned to the user.
 

-### `preserve` statements
+#### `preserve` statements

 
     map[Shift+Lock+LevelThree] = Level5;
     preserve[Shift+Lock+LevelThree] = Lock;
 
     map[Shift+Lock+LevelThree] = Level5;
     preserve[Shift+Lock+LevelThree] = Lock;


@@ -151,12 +160,12 @@ type's modifiers; these modifiers are then "preserved" and not
 reported as consumed.
 
 
 reported as consumed.
 
 

-# The `xkb_compat` section
+## The `xkb_compat` section

 
 This section is the third to be processed, after `xkb_keycodes` and
 `xkb_types`.
 
 
 This section is the third to be processed, after `xkb_keycodes` and
 `xkb_types`.
 

-## Interpret statements
+### Interpret statements

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -237,7 +246,7 @@ or set the key's repeat setting. You should note the following:
 The body of the statement may include statements of the following
 forms (all of which are optional):
 
 The body of the statement may include statements of the following
 forms (all of which are optional):
 

-### `useModMapMods` statement
+#### `useModMapMods` statement

 
     useModMapMods = level1;
 
 
     useModMapMods = level1;
 


@@ -245,13 +254,13 @@ When set to `level1`, the interpret will only match levels which are
 the first level of the first group of the keys. This can be useful in
 conjunction with e.g. a `virtualModifier` statement.
 
 the first level of the first group of the keys. This can be useful in
 conjunction with e.g. a `virtualModifier` statement.
 

-### `action` statement
+#### `action` statement

 
     action = LockMods(modifiers=NumLock);
 
 Bind this action to the matching levels.
 
 
     action = LockMods(modifiers=NumLock);
 
 Bind this action to the matching levels.
 

-### `virtualModifier` statement
+#### `virtualModifier` statement

 
     virtualModifier = NumLock;
 
 
     virtualModifier = NumLock;
 


@@ -261,13 +270,13 @@ modifier must be declared at the top level of the file with a
 
     virtual_modifiers NumLock;
 
 
     virtual_modifiers NumLock;
 

-### `repeat` statement
+#### `repeat` statement

 
     repeat = True;
 
 Set whether the key should repeat or not. Must be a boolean value.
 
 
     repeat = True;
 
 Set whether the key should repeat or not. Must be a boolean value.
 

-## LED map statements
+### LED map statements

 
 Statements of the form:
 
 
 Statements of the form:
 


@@ -283,14 +292,14 @@ The body of the statement describes the conditions of the keyboard
 state which will cause the LED to be lit. It may include the following
 statements:
 
 state which will cause the LED to be lit. It may include the following
 statements:
 

-### `modifiers` statement
+#### `modifiers` statement

 
     modifiers = ScrollLock;
 
 If the given modifiers are in the required state (see below), the
 LED is lit.
 
 
     modifiers = ScrollLock;
 
 If the given modifiers are in the required state (see below), the
 LED is lit.
 

-### `whichModState` statment
+#### `whichModState` statment

 
     whichModState = Latched+Locked;
 
 
     whichModState = Latched+Locked;
 


@@ -315,14 +324,14 @@ indicator "Num Lock" {
 Whenever the NumLock modifier is locked, the Num Lock LED will light
 up.
 
 Whenever the NumLock modifier is locked, the Num Lock LED will light
 up.
 

-### `groups` statement
+#### `groups` statement

 
     groups = All - group1;
 
 If the given groups are in the required state (see below), the LED is
 lit.
 
 
     groups = All - group1;
 
 If the given groups are in the required state (see below), the LED is
 lit.
 

-### `whichGroupState` statement
+#### `whichGroupState` statement

 
     whichGroupState = Effective;
 
 
     whichGroupState = Effective;
 


@@ -340,7 +349,7 @@ Note: the above conditions are disjunctive, i.e. if any of them are
 satisfied the LED is lit.
 
 
 satisfied the LED is lit.
 
 

-# The `xkb_symbols` section
+## The `xkb_symbols` section

 
 This section is the fourth to be processed, after `xkb_keycodes`,
 `xkb_types` and `xkb_compat`.
 
 This section is the fourth to be processed, after `xkb_keycodes`,
 `xkb_types` and `xkb_compat`.


@@ -348,7 +357,7 @@ This section is the fourth to be processed, after `xkb_keycodes`,
 TODO
 
 
 TODO
 
 

-# Virtual modifier statements
+## Virtual modifier statements

 
 Statements of the form:
 
 
 Statements of the form: