From: Manos Pitsidianakis <manos.pitsidiana...@linaro.org>
Sphinx supports the :kbd: role for notating keyboard input. They get
formatted as <kbd> HTML elements in the readthedocs theme we currently
use for Sphinx.
Besides the better visual formatting, it also helps with accessibility
as screen readers can announce the semantics of the <kbd> element to the
user.
Signed-off-by: Manos Pitsidianakis <manos.pitsidiana...@linaro.org>
Message-ID: <20250709-docs_rst_improvements-v2-1-cb5096ad0...@linaro.org>
Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
---
docs/devel/testing/main.rst | 4 +--
docs/system/images.rst | 2 +-
docs/system/keys.rst.inc | 49 +++++++++++++++++----------------
docs/system/linuxboot.rst | 2 +-
docs/system/mux-chardev.rst.inc | 38 ++++++++++++++-----------
5 files changed, 51 insertions(+), 44 deletions(-)
diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
index 6b18ed875c..2b5cb0c148 100644
--- a/docs/devel/testing/main.rst
+++ b/docs/devel/testing/main.rst
@@ -604,9 +604,9 @@ below steps to debug it:
2. Add "V=1" to the command line, try again, to see the verbose output.
3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
in the container right before testing starts. You could either manually
- build QEMU and run tests from there, or press Ctrl-D to let the Docker
+ build QEMU and run tests from there, or press :kbd:`Ctrl+d` to let the
Docker
testing continue.
-4. If you press Ctrl-D, the same building and testing procedure will begin, and
+4. If you press :kbd:`Ctrl+d`, the same building and testing procedure will
begin, and
will hopefully run into the error again. After that, you will be dropped to
the prompt for debug.
diff --git a/docs/system/images.rst b/docs/system/images.rst
index a5551173c9..43706969fd 100644
--- a/docs/system/images.rst
+++ b/docs/system/images.rst
@@ -30,7 +30,7 @@ Snapshot mode
If you use the option ``-snapshot``, all disk images are considered as
read only. When sectors in written, they are written in a temporary file
created in ``/tmp``. You can however force the write back to the raw
-disk images by using the ``commit`` monitor command (or C-a s in the
+disk images by using the ``commit`` monitor command (or :kbd:`Ctrl+a s` in the
serial console).
.. _vm_005fsnapshots:
diff --git a/docs/system/keys.rst.inc b/docs/system/keys.rst.inc
index 59966a3fe7..c28ae1a227 100644
--- a/docs/system/keys.rst.inc
+++ b/docs/system/keys.rst.inc
@@ -1,36 +1,37 @@
During the graphical emulation, you can use special key combinations from
-the following table to change modes. By default the modifier is Ctrl-Alt
+the following table to change modes. By default the modifier is :kbd:`Ctrl+Alt`
(used in the table below) which can be changed with ``-display`` suboption
``mod=`` where appropriate. For example, ``-display sdl,
-grab-mod=lshift-lctrl-lalt`` changes the modifier key to Ctrl-Alt-Shift,
-while ``-display sdl,grab-mod=rctrl`` changes it to the right Ctrl key.
+grab-mod=lshift-lctrl-lalt`` changes the modifier key to :kbd:`Ctrl+Alt+Shift`,
+while ``-display sdl,grab-mod=rctrl`` changes it to the right :kbd:`Ctrl` key.
-Ctrl-Alt-f
- Toggle full screen
+.. list-table:: Multiplexer Keys
+ :widths: 10 90
+ :header-rows: 1
-Ctrl-Alt-+
- Enlarge the screen
+ * - Key Sequence
+ - Action
-Ctrl-Alt\--
- Shrink the screen
+ * - :kbd:`Ctrl+Alt+f`
+ - Toggle full screen
-Ctrl-Alt-u
- Restore the screen's un-scaled dimensions
+ * - :kbd:`Ctrl+Alt++`
+ - Enlarge the screen
-Ctrl-Alt-n
- Switch to virtual console 'n'. Standard console mappings are:
+ * - :kbd:`Ctrl+Alt+-`
+ - Shrink the screen
- *1*
- Target system display
+ * - :kbd:`Ctrl+Alt+u`
+ - Restore the screen's un-scaled dimensions
- *2*
- Monitor
+ * - :kbd:`Ctrl+Alt+n`
+ - Switch to virtual console 'n'. Standard console mappings are:
- *3*
- Serial port
+ - *1*: Target system display
+ - *2*: Monitor
+ - *3*: Serial port
+ * - :kbd:`Ctrl+Alt+g`
+ - Toggle mouse and keyboard grab.
-Ctrl-Alt-g
- Toggle mouse and keyboard grab.
-
-In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and
-Ctrl-PageDown to move in the back log.
+In the virtual consoles, you can use :kbd:`Ctrl+Up`, :kbd:`Ctrl+Down`,
:kbd:`Ctrl+PageUp` and
+:kbd:`Ctrl+PageDown` to move in the back log.
diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
index 2328b4a73d..f7573ab80a 100644
--- a/docs/system/linuxboot.rst
+++ b/docs/system/linuxboot.rst
@@ -26,5 +26,5 @@ virtual serial port and the QEMU monitor to the console with
the
|qemu_system| -kernel bzImage -drive file=rootdisk.img,format=raw \
-append "root=/dev/sda console=ttyS0" -nographic
-Use Ctrl-a c to switch between the serial console and the monitor (see
+Use :kbd:`Ctrl+a c` to switch between the serial console and the monitor (see
:ref:`GUI_keys`).
diff --git a/docs/system/mux-chardev.rst.inc b/docs/system/mux-chardev.rst.inc
index 84ea12cbf5..c87ba31362 100644
--- a/docs/system/mux-chardev.rst.inc
+++ b/docs/system/mux-chardev.rst.inc
@@ -1,27 +1,33 @@
During emulation, if you are using a character backend multiplexer
(which is the default if you are using ``-nographic``) then several
commands are available via an escape sequence. These key sequences all
-start with an escape character, which is Ctrl-a by default, but can be
+start with an escape character, which is :kbd:`Ctrl+a` by default, but can be
changed with ``-echr``. The list below assumes you're using the default.
-Ctrl-a h
- Print this help
+.. list-table:: Multiplexer Keys
+ :widths: 20 80
+ :header-rows: 1
-Ctrl-a x
- Exit emulator
+ * - Key Sequence
+ - Action
-Ctrl-a s
- Save disk data back to file (if -snapshot)
+ * - :kbd:`Ctrl+a h`
+ - Print this help
-Ctrl-a t
- Toggle console timestamps
+ * - :kbd:`Ctrl+a x`
+ - Exit emulator
-Ctrl-a b
- Send break (magic sysrq in Linux)
+ * - :kbd:`Ctrl+a s`
+ - Save disk data back to file (if -snapshot)
-Ctrl-a c
- Rotate between the frontends connected to the multiplexer (usually
- this switches between the monitor and the console)
+ * - :kbd:`Ctrl+a t`
+ - Toggle console timestamps
-Ctrl-a Ctrl-a
- Send the escape character to the frontend
+ * - :kbd:`Ctrl+a b`
+ - Send break (magic sysrq in Linux)
+
+ * - :kbd:`Ctrl+a c`
+ - Rotate between the frontends connected to the multiplexer (usually this
switches between the monitor and the console)
+
+ * - :kbd:`Ctrl+a Ctrl+a`
+ - Send the escape character to the frontend
--
2.47.2
