Peter Maydell <[email protected]> writes:
> On Tue, 29 Sep 2020 at 09:20, Markus Armbruster <[email protected]> wrote:
>>
>> Peter Maydell <[email protected]> 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 <[email protected]>'], 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.
