From 381d2c36e1242f849a55f4622e50b9a69cb92842 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Fri, 11 Oct 2024 11:45:46 +0200 Subject: docs: use consistent markup for footnotes Unfortunately, the definition of the footnote syntax requires the author to use the awkward escaped space "\ " in the really common case of "footnote marker at end of word or sentence"; and in fact the rST documentation's examples of footnote syntax contain only artificial examples that do *not* use the syntax. This resulted in ugly rendering of footnotes throughout QEMU's documentation. Ensure the space is escaped whenever the footnote must attach to the preceding word, and also use a named reference for clarity. Reviewed-by: Peter Maydell Signed-off-by: Paolo Bonzini --- docs/devel/atomics.rst | 6 +++--- docs/devel/build-system.rst | 2 +- docs/devel/loads-stores.rst | 2 +- docs/devel/maintainers.rst | 4 ++-- docs/devel/migration/mapped-ram.rst | 4 ++-- 5 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/atomics.rst b/docs/devel/atomics.rst index 6bf032f900..95c7b77c01 100644 --- a/docs/devel/atomics.rst +++ b/docs/devel/atomics.rst @@ -204,7 +204,7 @@ They come in six kinds: before the second with respect to the other components of the system. Therefore, unlike ``smp_rmb()`` or ``qatomic_load_acquire()``, ``smp_read_barrier_depends()`` can be just a compiler barrier on - weakly-ordered architectures such as Arm or PPC\ [#]_. + weakly-ordered architectures such as Arm or PPC\ [#alpha]_. Note that the first load really has to have a _data_ dependency and not a control dependency. If the address for the second load is dependent @@ -212,7 +212,7 @@ They come in six kinds: than actually loading the address itself, then it's a _control_ dependency and a full read barrier or better is required. -.. [#] The DEC Alpha is an exception, because ``smp_read_barrier_depends()`` +.. [#alpha] The DEC Alpha is an exception, because ``smp_read_barrier_depends()`` needs a processor barrier. On strongly-ordered architectures such as x86 or s390, ``smp_rmb()`` and ``qatomic_load_acquire()`` can also be compiler barriers only. @@ -295,7 +295,7 @@ Acquire/release pairing and the *synchronizes-with* relation ------------------------------------------------------------ Atomic operations other than ``qatomic_set()`` and ``qatomic_read()`` have -either *acquire* or *release* semantics [#rmw]_. This has two effects: +either *acquire* or *release* semantics\ [#rmw]_. This has two effects: .. [#rmw] Read-modify-write operations can have both---acquire applies to the read part, and release to the write. diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst index fa1c59d9fd..d42045a232 100644 --- a/docs/devel/build-system.rst +++ b/docs/devel/build-system.rst @@ -333,7 +333,7 @@ into each emulator: ``default-configs/targets/*.mak`` These files mostly define symbols that appear in the ``*-config-target.h`` - file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` + file for each emulator\ [#cfgtarget]_. However, the ``TARGET_ARCH`` and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and ``target/`` subdirectories that are compiled into each target. diff --git a/docs/devel/loads-stores.rst b/docs/devel/loads-stores.rst index ec627aa9c0..9471bac859 100644 --- a/docs/devel/loads-stores.rst +++ b/docs/devel/loads-stores.rst @@ -95,7 +95,7 @@ guest CPU state in case of a guest CPU exception. This is passed to ``cpu_restore_state()``. Therefore the value should either be 0, to indicate that the guest CPU state is already synchronized, or the result of ``GETPC()`` from the top level ``HELPER(foo)`` -function, which is a return address into the generated code [#gpc]_. +function, which is a return address into the generated code\ [#gpc]_. .. [#gpc] Note that ``GETPC()`` should be used with great care: calling it in other functions that are *not* the top level diff --git a/docs/devel/maintainers.rst b/docs/devel/maintainers.rst index 5c907d901c..88a613ed74 100644 --- a/docs/devel/maintainers.rst +++ b/docs/devel/maintainers.rst @@ -99,9 +99,9 @@ members of the QEMU community, you should make arrangements to attend a `KeySigningParty `__ (for example at KVM Forum) or make alternative arrangements to have your key signed by an attendee. Key signing requires meeting another -community member **in person** [#]_ so please make appropriate +community member **in person**\ [#2020]_ so please make appropriate arrangements. -.. [#] In recent pandemic times we have had to exercise some +.. [#2020] In recent pandemic times we have had to exercise some flexibility here. Maintainers still need to sign their pull requests though. diff --git a/docs/devel/migration/mapped-ram.rst b/docs/devel/migration/mapped-ram.rst index d352b546e9..b08c2b433c 100644 --- a/docs/devel/migration/mapped-ram.rst +++ b/docs/devel/migration/mapped-ram.rst @@ -44,7 +44,7 @@ Use-cases The mapped-ram feature was designed for use cases where the migration stream will be directed to a file in the filesystem and not -immediately restored on the destination VM [#]_. These could be +immediately restored on the destination VM\ [#alternatives]_. These could be thought of as snapshots. We can further categorize them into live and non-live. @@ -70,7 +70,7 @@ mapped-ram in this scenario is portability since background-snapshot depends on async dirty tracking (KVM_GET_DIRTY_LOG) which is not supported outside of Linux. -.. [#] While this same effect could be obtained with the usage of +.. [#alternatives] While this same effect could be obtained with the usage of snapshots or the ``file:`` migration alone, mapped-ram provides a performance increase for VMs with larger RAM sizes (10s to 100s of GiBs), specially if the VM has been stopped beforehand. -- cgit 1.4.1