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

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

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

Let's switch to plain string.  Can do in my tree.

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

I think readers of the HTML version will appreciate the version
information.

Similar situation as for the licensing information: your patch doesn't
make things worse[*], but we found something to improve during review.

>          You can add a TODO if you want one, of course.

Thanks!


[*] I guess it would for PDF, if we still supported PDF.