Re: [PATCH 18/18] docs/system: convert Texinfo documentation to rST

From: Peter Maydell <peter.maydell@linaro.org>
To: Paolo Bonzini <pbonzini@redhat.com>
Cc: QEMU Developers <qemu-devel@nongnu.org>
Subject: Re: [PATCH 18/18] docs/system: convert Texinfo documentation to rST
Date: Thu, 27 Feb 2020 12:26:04 +0000	[thread overview]
Message-ID: <CAFEAcA_721QV7FKjmnFHUZsvHrACkFsu2hya_CeMe2wqOFoB_A@mail.gmail.com> (raw)
In-Reply-To: <20200226113034.6741-19-pbonzini@redhat.com>

On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Apart from targets.rst, which was written by hand, this is an automated
> conversion obtained with the following command:
>
>   makeinfo --force -o - --docbook \
>     -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \
>     -D 'qemu_system     QEMU_SYSTEM_MACRO' \
>     $texi | pandoc -f docbook -t rst+smart | perl -e '
>       $/=undef;
>       $_ = <>;
>       s/^-  − /-  /gm;
>       s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
>       s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
>       s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
>       s/:\n\n::$/::/gm;
>       print' > $rst
>
> In addition, the following changes were made manually:
>
> - target-i386.rst and target-mips.rst: replace CPU model documentation with
>   an include directive
>
> - monitor.rst: replace the command section with a comment
>
> - images.rst: add toctree
>
> - invocation.rst and ivshmem.rst: annotate more parsed-literal blocks
>
> Content that is not @included remains exclusive to qemu-doc.texi.

My Sphinx doesn't like this:

Warning, treated as error:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/system/target-arm.rst:using
"math" markup without a Sphinx math extension active, please use one
of the math extensions described at
http://sphinx-doc.org/en/master/ext/math.html

This is all down to the I2C/I2S usage of superscript; this fixes it:

diff --git a/docs/system/defs.rst.inc b/docs/system/defs.rst.inc
index bf50b442b27..0ea4df966ca 100644
--- a/docs/system/defs.rst.inc
+++ b/docs/system/defs.rst.inc
@@ -1,2 +1,4 @@
 .. |qemu_system| replace:: ``qemu-system-x86_64``
 .. |qemu_system_x86| replace:: ``qemu_system_x86``
+.. |I2C| replace:: I\ :sup:`2`\ C
+.. |I2S| replace:: I\ :sup:`2`\ S
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index fcd8f43eef2..0490be55871 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -94,7 +94,7 @@ and \"Terrier\") emulation includes the following peripherals:

 -  TI ADS7846 touchscreen controller on SSP bus

--  Maxim MAX1111 analog-digital converter on I\ :math:`^2`\ C bus
+-  Maxim MAX1111 analog-digital converter on |I2C| bus

 -  GPIO-connected keyboard controller and LEDs

@@ -102,7 +102,7 @@ and \"Terrier\") emulation includes the following
peripherals:

 -  Three on-chip UARTs

--  WM8750 audio CODEC on I\ :math:`^2`\ C and I\ :math:`^2`\ S busses
+-  WM8750 audio CODEC on |I2C| and |I2S| busses

 The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
 following elements:
@@ -117,7 +117,7 @@ following elements:
 -  On-chip Real Time Clock

 -  TI TSC2102i touchscreen controller / analog-digital converter /
-   Audio CODEC, connected through MicroWire and I\ :math:`^2`\ S busses
+   Audio CODEC, connected through MicroWire and |I2S| busses

 -  GPIO-connected matrix keypad

@@ -139,7 +139,7 @@ Nokia N800 and N810 internet tablets (known also
as RX-34 and RX-44 /
    controllers driven through SPI bus

 -  National Semiconductor LM8323-controlled qwerty keyboard driven
-   through I\ :math:`^2`\ C bus
+   through |I2C| bus

 -  Secure Digital card connected to OMAP MMC/SD host

@@ -148,10 +148,10 @@ Nokia N800 and N810 internet tablets (known also
as RX-34 and RX-44 /
 -  Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
    TI TUSB6010 chip - only USB host mode is supported

--  TI TMP105 temperature sensor driven through I\ :math:`^2`\ C bus
+-  TI TMP105 temperature sensor driven through |I2C| bus

 -  TI TWL92230C power management companion with an RTC on
-   I\ :math:`^2`\ C bus
+   |I2C| bus

 -  Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
    through CBUS
@@ -163,10 +163,10 @@ devices:

 -  64k Flash and 8k SRAM.

--  Timers, UARTs, ADC and I\ :math:`^2`\ C interface.
+-  Timers, UARTs, ADC and |I2C| interface.

 -  OSRAM Pictiva 96x16 OLED with SSD0303 controller on
+-  Timers, UARTs, ADC and |I2C| interface.

 -  OSRAM Pictiva 96x16 OLED with SSD0303 controller on
-   I\ :math:`^2`\ C bus.
+   |I2C| bus.

 The Luminary Micro Stellaris LM3S6965EVB emulation includes the
 following devices:
@@ -175,7 +175,7 @@ following devices:

 -  256k Flash and 64k SRAM.

--  Timers, UARTs, ADC, I\ :math:`^2`\ C and SSI interfaces.
+-  Timers, UARTs, ADC, |I2C| and SSI interfaces.

 -  OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
    SSI.

thanks
-- PMM

