doc/README: convert to reStructuredText

diff --git a/doc/README b/doc/README.rst
similarity index 66%
rename from doc/README
rename to doc/README.rst
index 9cc4748b321c9ea2ba77b813ce76cf3184c8a6f8..8cac38d04b05d9a5db2f3559f4791f528bfabfa4 100644 (file)
--- a/doc/README
+++ b/doc/README.rst
@@ -1,16 +1,17 @@
-== Overview ==
+Overview
+========
 
 This package contains files that can be used to alter your keyboard
 layout in the system console, within X.org, or anywhere else that
 uses xkb (for example, most Wayland compositors):
 
-  * Your physical "Alt" keys act like "Ctrl" keys
-  * Your physical "Ctrl" keys act like "Alt" keys
-  * Your physical "Caps Lock" key acts like the "Alt" key
+* Your physical "Alt" keys act like "Ctrl" keys
+* Your physical "Ctrl" keys act like "Alt" keys
+* Your physical "Caps Lock" key acts like the "Alt" key
 
-In other words, we put those keys where they lived on the space-cadet
-keyboard <https://en.wikipedia.org/wiki/Space-cadet_keyboard>. This
-makes Emacs (and any readline-based application) easier to use, I
+In other words, we put those keys where they lived on the
+`space-cadet keyboard <https://en.wikipedia.org/wiki/Space-cadet_keyboard>`_.
+This makes Emacs (and any readline-based application) easier to use, I
 promise.
 
 (The console map probably only works on i386 qwerty keyboards, because
@@ -18,46 +19,50 @@ that's all I have.)
 
 The files:
 
-1. src/console.map
+#. **src/console.map**
 
    This affects the Linux system console and virtual terminals; that
    is, the things that you switch between with Ctrl-Alt-FN, and the
    thing that you're looking at before you start your graphical
    desktop environment. The console.map file is input for the
-   "loadkeys" utility that is part of KBD project
-   <http://kbd-project.org/> and is provided by sys-apps/kbd on
-   Gentoo.
+   *loadkeys* utility that is part of the
+   `KBD project <http://kbd-project.org/>`_ and is provided by
+   sys-apps/kbd on Gentoo.
 
-2. src/Xmodmap
+#. **src/Xmodmap**
 
    This affects the X.org system, and your graphical terminals. It
    should be fed into the "xmodmap" utility that is part of X.org
    and which is provided by x11-apps/xmodmap on Gentoo.
 
-3. src/xkb/symbols/emacs-keys
+#. **src/xkb/symbols/emacs-keys**
 
-   This is an xkb <https://xkbcommon.org/> keyboard layout file and it
+   This is an `xkb <https://xkbcommon.org/>`_ keyboard layout file and it
    affects anything that uses libxkbcommon for keyboard support. That
    of course includes X11 itself, but the main reason this file exists
    is to support Wayland. Under X11, the Xmodmap file is easier.
 
 
-== Installation ==
+Installation
+============
 
-The build system installs each of these files to $(datadir)/emacs-keys.
+The build system installs each of these files to ``$(datadir)/emacs-keys``.
 
 The console.map and Xmodmap files can be loaded directly from that
 location; for example,
 
+.. code-block:: console
+
   $ loadkeys /usr/share/emacs-keys/console.map
   $ xmodmap /usr/share/emacs-keys/Xmodmap
 
 But you probably don't want to do that every time you log in.
 
-=== Xmodmap ===
+Xmodmap
+-------
 
 For the Xmodmap file, you would typically add something like the
-following to your ~/.xinitrc,
+following to your ``~/.xinitrc``::
 
   emacsmodmap=/usr/share/emacs-keys/Xmodmap
   if [ -f $emacsmodmap ]; then
@@ -68,12 +73,13 @@ following to your ~/.xinitrc,
 The call to xmodmap doesn't work unless you do it twice, and don't ask
 me why.
 
-=== console.map ===
+console.map
+-----------
 
 If you're lucky enough to use OpenRC, the console map can be loaded
-automatically. OpenRC starts a "keymaps" service at boot time. The
+automatically. OpenRC starts a *keymaps* service at boot time. The
 configuration file for that service is usually located at
-/etc/conf.d/keymaps, and if you set, for example,
+``/etc/conf.d/keymaps``, and if you set, for example::
 
   extended_keymaps="/usr/share/emacs-keys/console.map"
 
@@ -82,23 +88,26 @@ default one when the system boots.
 
 Systemd can probably do this too, but you're on your own there.
 
-=== xkb ===
+xkb
+---
 
 The xkb layout needs to be installed where libxkbcommon will look for
 it. Rather than muck with system paths, we assume that you'll be
 configuring the keyboard for only one user (i.e. you). The per-user
-xkb configuration typically goes in $XDG_CONFIG_HOME/xkb, and the
-variable $XDG_CONFIG_HOME defaults to ~/.config in your home
+xkb configuration typically goes in ``$XDG_CONFIG_HOME/xkb``, and the
+variable ``$XDG_CONFIG_HOME`` defaults to ~/.config in your home
 directory. Your ultimate goal is therefore to make the
 xkb/symbol/emacs-keys file available under ~/.config.
 
 The best way to do this is with a symlink:
 
+.. code-block:: console
+
   $ ln -s /usr/share/emacs-keys/xkb/ ~/.config/
 
 Now, to use it, all you have to do is tell whatever program you're
-using to use the "emacs-keys" xkb_layout. For example, the Sway window
-manager can be configured with,
+using to use the *emacs-keys* xkb_layout. For example, the Sway window
+manager can be configured with::
 
   input type:keyboard {
     xkb_layout "emacs-keys"