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

[Daniel P . Berrangé]

On Fri, Feb 21, 2020 at 03:16:29PM +0000, Peter Maydell wrote:
> 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).

I agree that listing Fabrice explicitly here is wrong
since he didn't write any of it.

As the author, I don't feel a need for my name to be
explicitly credited here. QEMU is a collaborative project
and other people add text to this over time. Indeed IME
explicitly listing an individual  encourages users to
directly email the individual person with questions,
instead of using the mailing list / irc / forums.

Thus I would personally prefer if we just used

  "The QEMU Project maintainers"

as the author credit

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

Yep, the model name used for the "-cpu NAME" arg is the most
important piece of information IMHO. The human description is
just a side note.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|