docs: Create defs.rst.inc as a place to define substitutions

Rather than accumulating generally useful rST substitution
definitions in individual rST files, create a defs.rst.inc where we
can define these.  To start with it has the |qemu_system| definition
from qemu-block-drivers.rst.

Add a comment noting a pitfall where putting literal markup in the
definition of |qemu_system| makes it misrender manpage output; this
means the point-of-use must handle the literal markup (which is
almost always done by having it inside a parsed-literal block).

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200228153619.9906-15-peter.maydell@linaro.org

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/defs.rst.inc b/docs/defs.rst.inc
new file mode 100644
index 0000000..ae80d2f
--- /dev/null
+++ b/docs/defs.rst.inc
@@ -0,0 +1,11 @@
+..
+   Generally useful rST substitution definitions. This is included for
+   all rST files as part of the epilogue by docs/conf.py.  conf.py
+   also defines some dynamically generated substitutions like CONFDIR.
+
+   Note that |qemu_system| is intended to be used inside a parsed-literal
+   block: the definition must not include extra literal formatting with
+   ``..``: this works in the HTML output but the manpages will end up
+   misrendered with following normal text incorrectly in boldface.
+
+.. |qemu_system| replace:: qemu-system-x86_64