Re: [PATCH v3 1/2] docs: Convert qemu-cpu-models.texi to rST

[Peter Maydell]

On Thu, 20 Feb 2020 at 14:20, Kashyap Chamarthy <address@hidden> wrote:
>
> This doc was originally written by Daniel P. Berrangé
> <address@hidden>, introduced via commit[1]: 2544e9e4aa (docs: add
> guidance on configuring CPU models for x86, 2018-06-27).
>
> In this patch:
>
>   - 1-1 conversion of Texinfo to rST, besides a couple of minor
>     tweaks that are too trivial to mention.   (Thanks to Stephen
>     Finucane on IRC for the suggestion to use rST "definition lists"
>     instead of bullets in some places.)
>
>     Further modifications will be done via a separate patch.
>
>   - rST and related infra changes: for building the manual page,
>     Makefile fixes, clean up references to qemu-cpu-models.texi, etc.
>
> [1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa
>
> Signed-off-by: Kashyap Chamarthy <address@hidden>
> ---
> v2: Fix rST conversion, man page creation, Makefile changes, et al
>     (thanks, Peter Maydell)
> ---
>  MAINTAINERS                     |   2 +-
>  Makefile                        |  10 +-
>  docs/qemu-cpu-models.texi       | 677 --------------------------------
>  docs/system/conf.py             |   3 +
>  docs/system/index.rst           |   1 +
>  docs/system/qemu-cpu-models.rst | 514 ++++++++++++++++++++++++
>  qemu-doc.texi                   |   5 -
>  7 files changed, 524 insertions(+), 688 deletions(-)
>  delete mode 100644 docs/qemu-cpu-models.texi
>  create mode 100644 docs/system/qemu-cpu-models.rst

> @@ -1056,6 +1055,8 @@ $(call define-manpage-rule,interop,\
>
>  $(call define-manpage-rule,system,qemu-block-drivers.7)
>
> +$(call define-manpage-rule,system,qemu-cpu-models.7)

The new manpage should be added to the existing define-manpage-rule
invocation for the system manual: the last argument is a space
separated list of all the manpages in the manual, like this:

$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7)

> +
>  $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
>         @mkdir -p "$(MANUAL_BUILDDIR)"
>         $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \



> -@c man begin AUTHOR
> -Daniel P. Berrange
> -@c man end

> diff --git a/docs/system/conf.py b/docs/system/conf.py
> index 7ca115f5e0..7cc9da9508 100644
> --- a/docs/system/conf.py
> +++ b/docs/system/conf.py
> @@ -18,5 +18,8 @@ html_theme_options['description'] = u'System Emulation 
> User''s Guide'
>  man_pages = [
>      ('qemu-block-drivers', 'qemu-block-drivers',
>       u'QEMU block drivers reference',
> +     ['Fabrice Bellard and the QEMU Project developers'], 7),
> +    ('qemu-cpu-models', 'qemu-cpu-models',
> +     u'QEMU CPU Models',
>       ['Fabrice Bellard and the QEMU Project developers'], 7)
>  ]

The old manpage/documentation credits Dan as the author,
so that's what we should specify in the conf.py line,
rather than 'Fabrice and the project devs' (which we
use for qemu-block-drivers.7 because that's what the
old texi version of that file specified as the authors).


> +Preferred CPU models for Intel x86 hosts
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The following CPU models are preferred for use on Intel hosts.
> +Administrators / applications are recommended to use the CPU model that
> +matches the generation of the host CPUs in use. In a deployment with a
> +mixture of host CPU models between machines, if live migration
> +compatibility is required, use the newest CPU model that is compatible
> +across all desired hosts.
> +
> +* Intel Xeon Processor (Skylake, 2016)
> +
> +  * ``Skylake-Server``
> +  * ``Skylake-Server-IBRS``

This reverses the old ordering of these lists, which consistently
had the QEMU CPU model names as the 'term' and the explanations
as the 'definition' of a definition-list. Now we have the
'explanation' first and the 'terms' second...

> +* AMD EPYC Processor (2017)
> +
> +  * ``EPYC``
> +  * ``EPYC-IBPB``
> +
> +* ``Opteron_G5`` – AMD Opteron 63xx class CPU (2012)
> +
> +* ``Opteron_G4`` – AMD Opteron 62xx class CPU (2011)
> +
> +* ``Opteron_G3`` – AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
> +
> +* ``Opteron_G2`` – AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
> +
> +* ``Opteron_G1`` – AMD Opteron 240 (Gen 1 Class Opteron, 2004)

...but here we become inconsistent, switching back to
term first and explanation second. I think the
term-first approach of the original texi makes more sense,
as we're trying to document the behaviour of the various
CPU models QEMU supports.

rST is not a fan of having multiple definition list items
sharing a definition, which is probably why you ended up with
the list approach you did, but we can do:

``Skylake-Server``, ``Skylake-Server-IBRS``
    Intel Xeon Processor (Skylake, 2016)

``Skylake-Client``, ``Skylake-Client-IBRS``
    Intel Core Processor (Skylake, 2015)

Or we can actually document what the difference is between
a "Skylake-Server" and a "Skylake-Server-IBRS", rather than
leaving the user to guess :-), in which case we could write

``Skylake-Server``
    Intel Xeon Processor (Skylake, 2016)
``Skylake-Server-IBRS``
    Like ``Skylake-Server`` but with extra magic

(or whatever the difference is...)

Regardless of how we format this, we should be consistent
in using the same format throughout the document.

thanks
-- PMM