doc: Improve README

README.md

@@ -1,9 +1,10 @@
 # libxkbcommon
 
-libxkbcommon is a keyboard keymap compiler and support library which
+**libxkbcommon** is a keyboard keymap compiler and support library which
 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.
+Extension) specification.  It also contains a module for handling *Compose*
+and dead keys and a separate *registry* library for listing available keyboard
+layouts.
 
 [XKB]: doc/introduction-to-xkb.md
 
@@ -18,38 +19,51 @@ and dead keys and a separate library for listing available keyboard layouts.
 
 libxkbcommon is built with [Meson](http://mesonbuild.com/):
 
-    meson setup build
-    meson compile -C build
-    meson test -C build # Run the tests.
+```bash
+meson setup build
+meson compile -C build
+meson test -C build # Run the tests.
+```
 
 To build for use with Wayland, you can disable X11 support while still
 using the X11 keyboard configuration resource files thusly:
 
-    meson setup build \
-        -Denable-x11=false \
-        -Dxkb-config-root=/usr/share/X11/xkb \
-        -Dx-locale-root=/usr/share/X11/locale
-    meson compile -C build
+```bash
+meson setup build \
+    -Denable-x11=false \
+    -Dxkb-config-root=/usr/share/X11/xkb \
+    -Dx-locale-root=/usr/share/X11/locale
+meson compile -C build
+```
+
+<details>
+<summary>Complete list of user options</summary>
+@include meson_options.txt
+</details>
 
 ## API
 
-While libxkbcommon's API is somewhat derived from the classic XKB API as found
+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
 expose fewer internal details to clients.
 
 See the [API Documentation](https://xkbcommon.org/doc/current/modules.html).
 
 ## Dataset
 
-libxkbcommon does not distribute a keymap dataset itself, other than for
-testing purposes.  The most common dataset is xkeyboard-config, which is used
-by all current distributions for their X11 XKB data.  More information on
-xkeyboard-config is available here:
-    https://www.freedesktop.org/wiki/Software/XKeyboardConfig
+libxkbcommon *does not distribute a keyboard layout dataset itself*, other than
+for testing purposes.  The most common dataset is **xkeyboard-config**, which is
+used by all current distributions for their X11 XKB data.  Further information
+on xkeyboard-config is available at its [homepage][xkeyboard-config-home] and at
+its [repository][xkeyboard-config-repo].
 
-The dataset for Compose is distributed in libX11, as part of the X locale
+The dataset for *Compose* is distributed in [libX11], as part of the X locale
 data.
 
+[xkeyboard-config-home]: https://www.freedesktop.org/wiki/Software/XKeyboardConfig
+[xkeyboard-config-repo]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
+[libX11]: https://gitlab.freedesktop.org/xorg/lib/libx11
+
 ## Relation to X11
 
 See [Compatibility](doc/compatibility.md) notes.
@@ -63,15 +77,16 @@ xkbcommon is maintained in git at
     https://github.com/xkbcommon/libxkbcommon
 
 Patches are always welcome, and may be sent to either
-    <[email protected]> or <[email protected]>
+<[email protected]> or <[email protected]>
 or in a [GitHub](https://github.com/xkbcommon/libxkbcommon) pull request.
 
 Bug reports (and usage questions) are also welcome, and may be filed at
 [GitHub](https://github.com/xkbcommon/libxkbcommon/issues).
 
-The maintainers are
-- Daniel Stone <[email protected]>
-- Ran Benita <[email protected]>
+The maintainers are:
+- [Daniel Stone](mailto:[email protected])
+- [Ran Benita](mailto:[email protected])
+- [Pierre Le Marre](mailto:[email protected])
 
 ## Credits
 

doc/Doxyfile.in

@@ -15,7 +15,8 @@ JAVADOC_AUTOBRIEF      = YES
 
 OPTIMIZE_OUTPUT_FOR_C  = YES
 
-EXTENSION_MAPPING      = no_extension=md
+EXTENSION_MAPPING      = no_extension=md \
+                         txt=md
 
 SORT_MEMBER_DOCS       = NO
 
@@ -53,6 +54,8 @@ FULL_SIDEBAR           = NO
 
 HTML_EXTRA_STYLESHEET  = doc/doxygen-extra.css
 
+HTML_EXTRA_FILES       = meson_options.txt
+
 TIMESTAMP              = NO
 
 ENUM_VALUES_PER_LINE   = 1

meson.build

@@ -1044,6 +1044,7 @@ You can disable the documentation with -Denable-docs=false.''')
 
     doxygen_input = [
         'README.md',
+        'meson_options.txt',
         'doc/debugging.md',
         'doc/diagrams/xkb-configuration.dot',
         'doc/diagrams/xkb-keymap-components.dot',