Re: [Qemu-devel] [PULL v2 000/180] QAPI patches for 2017-01-16

[Markus Armbruster]

Peter Maydell <address@hidden> writes:

> On 17 January 2017 at 13:24, Markus Armbruster <address@hidden> wrote:
>> Peter Maydell <address@hidden> writes:
>>> (1) if it doesn't actually cause a change in the output, we
>>> should either just delete the use of VERSION entirely, or move
>>> it to somewhere outside of @subtitle which does actually
>>> appear somewhere. There's no point in putting in the version
>>> info if it doesn't get into the final output, whether
>>> it generates a warning or not.
>>
>> It does affect PDF output.  PDF is generated by texi2pdf, which uses
>> different command line options, and setting VERSION works fine there.
>
> Mmm, but if it's useful information we should be displaying
> it in all our documentation formats, not just tucking it
> away in something that only appears in the PDF.
> Conversely, if we're happy for some of our document formats
> not to contain it we could save ourselves the grief of
> having to work around this bug by dropping the @subtitle entirely.

Yes, that's why I wrote we need to decide whether we want the
information that is now in @subtitle in the formats where @subtitle
currently doesn't appear.

> As an aside, how useful is the PDF output anyway? In 2017
> there seems to me quite a good argument for just creating
> HTML...

We do generate HTML.  We also generate PDF.  It's better for printing
(if you're so inclined), and it costs us next to nothing: a couple of
lines in the top-level Makefile.  See commit 20cc999 "Documentation: Add
build support for documentation in pdf format" (January 2010) and also
commit ad23988 "build-sys: remove dvi doc generation" (in this series).