On Fri, Feb 21, 2020 at 03:16:29PM +0000, Peter Maydell wrote:
> On Thu, 20 Feb 2020 at 14:20, Kashyap Chamarthy <kcham...@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
