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

[Kashyap Chamarthy <kchamart@redhat.com>]

On Fri, Feb 21, 2020 at 03:16:29PM +0000, Peter Maydell wrote:
> On Thu, 20 Feb 2020 at 14:20, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> > @@ -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)

Ah, will fix.

[...]

> > +++ 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).

Yeah, I first felt strange adding "Fabrice and the QEMU Project
developers".  But as you've guessed I just picked what you used for
'qemu-block-drivers.7'.  That's why I mentioned Dan and his original
commit ID in my commit message, for clear posterity.

As Dan says in his follow-up, a file indeed usually gets modified over
time.  And given the follow-up interaction between you and Dan, in the
next iteration, I'll change it to: "The QEMU Project developers".

(While I agree that we should be careful to not mix attribution changes
with the noise of rST conversion, maybe in this case a seperate commit
is an overkill; hope it is okay if I call it out in the commit message.)

> > +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...

Yeah, as you guessed, I was trying to wrangle with rST syntax.

> > +* 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.

True, I'll stick with the term-first approach, and get rid of the
inconsistency.

> 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...)

(The difference is the -IBRS models have 'spec-ctrl' CPU flag baked in.)

And yes, I like the latter approach — explicitly spelling it out reduces
cogntive load for the readers.

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

Agree, will fix.  Thanks for the eagle eyes, as usual. :-)

[...]


-- 
/kashyap