Manos Pitsidianakis <manos.pitsidiana...@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.pitsidiana...@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
