[PULL,v3,17/18] docs: avoid footnotes consisting of just URLs

Commit Message

Paolo Bonzini Oct. 11, 2024, 3:32 p.m. UTC

Replace the footnotes with inline links whenever the footnote text
consists of nothing but the URL.  While at it, make the link texts
consistent in the surrounding areas, for example avoiding usage of
"here" for the link's text.

In the case of acpi-bits.rst this fixes a build failure with Sphinx
8.1.0, because the FOSDEM link was duplicated in the paragraph and the
new version is a lot stricter about unreferenced footnotes.

Reviewed-by: Peter Maydell <[e-mail]>
Signed-off-by: Paolo Bonzini <[e-mail]>
---
 docs/devel/testing/acpi-bits.rst | 26 +++++++++++++-------------
 docs/specs/rapl-msr.rst          | 25 ++++++++++++-------------
 2 files changed, 25 insertions(+), 26 deletions(-)

Patch

diff --git a/docs/devel/testing/acpi-bits.rst b/docs/devel/testing/acpi-bits.rst
index 78aeb6aa3c4..9a4d716ebff 100644
--- a/docs/devel/testing/acpi-bits.rst
+++ b/docs/devel/testing/acpi-bits.rst
@@ -30,15 +30,20 @@  OS modules are generally written using low level languages such as C and
 low level assembly machine language. Writing test routines in a low level
 language makes things more cumbersome. These and other reasons makes using
 bios-bits very attractive for testing bioses. More details on the inspiration
-for developing biosbits and its real life uses can be found in [#a]_ and [#b]_.
+for developing biosbits and its real life uses were presented `at Plumbers
+in 2011 <Plumbers_>`__ and `at Linux.conf.au in 2012 <Linux.conf.au_>`__.
 
-For QEMU, we maintain a fork of bios bits in gitlab along with all the
-dependent submodules `here <https://gitlab.com/qemu-project/biosbits-bits>`__.
-This fork contains numerous fixes, a newer acpica and changes specific to
-running these functional QEMU tests using bits. The author of this document
-is the sole maintainer of the QEMU fork of bios bits repository. For more
-information, please see author's `FOSDEM talk on this bios-bits based test
-framework <https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/>`__.
+For QEMU, we maintain a fork of bios bits in `gitlab`_, along with all
+the dependent submodules.  This fork contains numerous fixes, a newer
+acpica and changes specific to running these functional QEMU tests using
+bits. The author of this document is the current maintainer of the QEMU
+fork of bios bits repository. For more information, please see `the
+author's FOSDEM presentation <FOSDEM_>`__ on this bios-bits based test framework.
+
+.. _Plumbers: https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/867/original/bits.pdf
+.. _Linux.conf.au: https://www.youtube.com/watch?v=36QIepyUuhg
+.. _gitlab: https://gitlab.com/qemu-project/biosbits-bits
+.. _FOSDEM: https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/
 
 *********************************
 Description of the test framework
@@ -148,8 +153,3 @@  Under ``tests/functional/`` as the root we have:
 
 Author: Ani Sinha <[e-mail]>
 
-References:
------------
-.. [#a] https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/867/original/bits.pdf
-.. [#b] https://www.youtube.com/watch?v=36QIepyUuhg
-.. [#c] https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/
diff --git a/docs/specs/rapl-msr.rst b/docs/specs/rapl-msr.rst
index 1202ee89bee..aaf0db9f91b 100644
--- a/docs/specs/rapl-msr.rst
+++ b/docs/specs/rapl-msr.rst
@@ -9,11 +9,12 @@  The consumption is reported via MSRs (model specific registers) like
 MSR_PKG_ENERGY_STATUS for the CPU package power domain. These MSRs are 64 bits
 registers that represent the accumulated energy consumption in micro Joules.
 
-Thanks to the MSR Filtering patch [#a]_ not all MSRs are handled by KVM. Some
-of them can now be handled by the userspace (QEMU). It uses a mechanism called
-"MSR filtering" where a list of MSRs is given at init time of a VM to KVM so
-that a callback is put in place. The design of this patch uses only this
-mechanism for handling the MSRs between guest/host.
+Thanks to KVM's `MSR filtering <msr-filter-patch_>`__ functionality,
+not all MSRs are handled by KVM. Some of them can now be handled by the
+userspace (QEMU); a list of MSRs is given at VM creation time to KVM, and
+a userspace exit occurs when they are accessed.
+
+.. _msr-filter-patch: https://patchwork.kernel.org/project/kvm/patch/[e-mail]/
 
 At the moment the following MSRs are involved:
 
@@ -92,9 +93,12 @@  found by the sysconf system call. A typical value of clock ticks per second is
 package has 4 cores, 400 ticks maximum can be scheduled on all the cores
 of the package for a period of 1 second.
 
-The /proc/[pid]/stat [#b]_ is a sysfs file that can give the executed time of a
-process with the [pid] as the process ID. It gives the amount of ticks the
-process has been scheduled in userspace (utime) and kernel space (stime).
+`/proc/[pid]/stat <stat_>`__ is a procfs file that can give the executed
+time of a process with the [pid] as the process ID. It gives the amount
+of ticks the process has been scheduled in userspace (utime) and kernel
+space (stime).
+
+.. _stat: https://man7.org/linux/man-pages/man5/proc.5.html
 
 By reading those metrics for a thread, one can calculate the ratio of time the
 package has spent executing the thread.
@@ -148,8 +152,3 @@  Current Limitations
 - Only the Package Power-Plane (MSR_PKG_ENERGY_STATUS) is reported at the
   moment.
 
-References
-----------
-
-.. [#a] https://patchwork.kernel.org/project/kvm/patch/[e-mail]/
-.. [#b] https://man7.org/linux/man-pages/man5/proc.5.html