Re: [PATCH v6 08/21] docs/interop: Convert qemu-ga-ref to rST

[Peter Maydell]

On Tue, 29 Sep 2020 at 09:20, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > Convert qemu-ga-ref to rST format. This includes dropping
> > the plain-text, pdf and info format outputs for this document;
> > as with all our other Sphinx-based documentation, we provide
> > HTML and manpage only.
> >

> > --- a/docs/interop/conf.py
> > +++ b/docs/interop/conf.py
> > @@ -19,4 +19,6 @@ html_theme_options['description'] = u'System Emulation 
> > Management and Interopera
> >  man_pages = [
> >      ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
> >       ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
> > +    ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference',
> > +     [], 7),
> >  ]
>
> Why do you make the description a unicode legacy literal?  I see it
> matches existing entries.  I'd like to know regardless :)

I was probably just copying some other example of how to
write the man_pages[] definition. This also all used to have
to work with Python 2.7, which might or might not be relevant here.

> > -@titlepage
> > -@title Guest Agent Protocol Reference Manual
> > -@subtitle QEMU version @value{VERSION}
>
> There is no obvious equivalent to @value{VERSION} in
> docs/interop/qemu-ga-ref.rst.
>
> The manual page generated from it has the version in the footer.  Good.
>
> I can't find it in the generated HTML.  Not so good, but it wasn't there
> before the patch, either.
>
> The generated PDF had it on the title page.
>
> Suggest to add a TODO comment like the one about the licensing
> information.

So the version is in the manual page, as it was before the conversion,
and it's not in the HTML version, which it wasn't before the
conversion. That doesn't sound to me like there's anything here
to do... You can add a TODO if you want one, of course.

thanks
-- PMM