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.pitsidianakis@linaro.org>
---
 docs/devel/testing/main.rst     |  4 ++--
 docs/system/images.rst          |  2 +-
 docs/system/keys.rst.inc        | 22 +++++++++++-----------
 docs/system/linuxboot.rst       |  2 +-
 docs/system/mux-chardev.rst.inc | 16 ++++++++--------
 5 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
index 6b18ed875cd91e961d07b3afa3179c7fba0e5fe3..2b5cb0c148048e3a81d2db8c4a9500591880997f 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 a5551173c9789323ceb150c51fd68c6d4ef80d71..43706969fddae7bcb83de172b1a04b5c6cffe0f1 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 59966a3fe7cf2cbb6a19dacd48612b768b7a1e96..f33f1acd08607c93d2ef250e3ca183f41f237658 100644
--- a/docs/system/keys.rst.inc
+++ b/docs/system/keys.rst.inc
@@ -1,23 +1,23 @@
 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
+:kbd:`Ctrl+Alt+f`
    Toggle full screen
 
-Ctrl-Alt-+
+:kbd:`Ctrl+Alt++`
    Enlarge the screen
 
-Ctrl-Alt\--
+:kbd:`Ctrl+Alt+-`
    Shrink the screen
 
-Ctrl-Alt-u
+:kbd:`Ctrl+Alt+u`
    Restore the screen's un-scaled dimensions
 
-Ctrl-Alt-n
+:kbd:`Ctrl+Alt+n`
    Switch to virtual console 'n'. Standard console mappings are:
 
    *1*
@@ -29,8 +29,8 @@ Ctrl-Alt-n
    *3*
       Serial port
 
-Ctrl-Alt-g
+:kbd:`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 2328b4a73d55b47d731497d57ddb1a837ef5d7dd..f7573ab80aa269bac870d7e6e5596a8f02fbd5f3 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 84ea12cbf58f9550154411f8951e6f608179a091..45d0b2c1d76c382a29076502b4f1234db5e25bb6 100644
--- a/docs/system/mux-chardev.rst.inc
+++ b/docs/system/mux-chardev.rst.inc
@@ -1,27 +1,27 @@
 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
+:kbd:`Ctrl+a h`
    Print this help
 
-Ctrl-a x
+:kbd:`Ctrl+a x`
    Exit emulator
 
-Ctrl-a s
+:kbd:`Ctrl+a s`
    Save disk data back to file (if -snapshot)
 
-Ctrl-a t
+:kbd:`Ctrl+a t`
    Toggle console timestamps
 
-Ctrl-a b
+:kbd:`Ctrl+a b`
    Send break (magic sysrq in Linux)
 
-Ctrl-a c
+:kbd:`Ctrl+a c`
    Rotate between the frontends connected to the multiplexer (usually
    this switches between the monitor and the console)
 
-Ctrl-a Ctrl-a
+:kbd:`Ctrl+a Ctrl+a`
    Send the escape character to the frontend

---
base-commit: 7698afc42b5af9e55f12ab2236618e38e5a1c23f
change-id: 20250703-docs_rst_improvements-1f0cb3c578d6

--
γαῖα πυρί μιχθήτω

Manos Pitsidianakis <manos.pitsidianakis@linaro.org> writes:

> 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.pitsidianakis@linaro.org>
> ---
>  docs/devel/testing/main.rst     |  4 ++--
>  docs/system/images.rst          |  2 +-
>  docs/system/keys.rst.inc        | 22 +++++++++++-----------
>  docs/system/linuxboot.rst       |  2 +-
>  docs/system/mux-chardev.rst.inc | 16 ++++++++--------
>  5 files changed, 23 insertions(+), 23 deletions(-)

I would be better to split this into a commit per-file so we can merge
the easy ones quickly.

>
> diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
> index 6b18ed875cd91e961d07b3afa3179c7fba0e5fe3..2b5cb0c148048e3a81d2db8c4a9500591880997f 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 a5551173c9789323ceb150c51fd68c6d4ef80d71..43706969fddae7bcb83de172b1a04b5c6cffe0f1 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 59966a3fe7cf2cbb6a19dacd48612b768b7a1e96..f33f1acd08607c93d2ef250e3ca183f41f237658 100644
> --- a/docs/system/keys.rst.inc
> +++ b/docs/system/keys.rst.inc
> @@ -1,23 +1,23 @@
>  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
> +:kbd:`Ctrl+Alt+f`
>     Toggle full screen
>  
> -Ctrl-Alt-+
> +:kbd:`Ctrl+Alt++`
>     Enlarge the screen
>  
> -Ctrl-Alt\--
> +:kbd:`Ctrl+Alt+-`
>     Shrink the screen
>  
> -Ctrl-Alt-u
> +:kbd:`Ctrl+Alt+u`
>     Restore the screen's un-scaled dimensions

This still renders weirdly as a semi-title type thing. You do get the
nice keyboard icons if you format this as a table, e.g:

.. list-table:: Multiplexer Keys
  :widths: 10 90
  :header-rows: 1

  * - Key Sequence
    - Action
  * - :kbd:`Ctrl+Alt+f`
    - Toggle full screen
  * - :kbd:`Ctrl+Alt++`
    - Enlarge the screen
  * - :kbd:`Ctrl+Alt+-`
    - Shrink the screen
  * - :kbd:`Ctrl+Alt+u`
    - Restore the screen's un-scaled dimensions
  * - :kbd:`Ctrl+Alt+n`
    - Switch to virtual console 'n'. Standard console mappings are:
      *1*
      Target system display
      *2*
      Monitor
      *3*
      Serial port
  * - :kbd:`Ctrl+Alt+g`
    - Toggle mouse and keyboard grab.

Although the console mappings still look a bit weird.

>  
> -Ctrl-Alt-n
> +:kbd:`Ctrl+Alt+n`
>     Switch to virtual console 'n'. Standard console mappings are:
>  
>     *1*
> @@ -29,8 +29,8 @@ Ctrl-Alt-n
>     *3*
>        Serial port
>  
> -Ctrl-Alt-g
> +:kbd:`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 2328b4a73d55b47d731497d57ddb1a837ef5d7dd..f7573ab80aa269bac870d7e6e5596a8f02fbd5f3 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 84ea12cbf58f9550154411f8951e6f608179a091..45d0b2c1d76c382a29076502b4f1234db5e25bb6 100644
> --- a/docs/system/mux-chardev.rst.inc
> +++ b/docs/system/mux-chardev.rst.inc
> @@ -1,27 +1,27 @@
>  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
> +:kbd:`Ctrl+a h`
>     Print this help
>  
> -Ctrl-a x
> +:kbd:`Ctrl+a x`
>     Exit emulator
>  
> -Ctrl-a s
> +:kbd:`Ctrl+a s`
>     Save disk data back to file (if -snapshot)
>  
> -Ctrl-a t
> +:kbd:`Ctrl+a t`
>     Toggle console timestamps
>  
> -Ctrl-a b
> +:kbd:`Ctrl+a b`
>     Send break (magic sysrq in Linux)
>  
> -Ctrl-a c
> +:kbd:`Ctrl+a c`
>     Rotate between the frontends connected to the multiplexer (usually
>     this switches between the monitor and the console)
>  
> -Ctrl-a Ctrl-a
> +:kbd:`Ctrl+a Ctrl+a`
>     Send the escape character to the frontend

Ditto here.

>
> ---
> base-commit: 7698afc42b5af9e55f12ab2236618e38e5a1c23f
> change-id: 20250703-docs_rst_improvements-1f0cb3c578d6

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro