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

[Marc-André Lureau]

Hi

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

It would be quite easy to add to the rest of the docs, that can be added on top.

If its not useful enough in this current form (since it's only in the PDF, 
because tooling is lacking support), feel freel to remove it Markus.

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


Afaik, most browsers support pdf nowadays.

pdf output is more pleasant to read, the html version would need significant 
styling to be comparable (I have played with the CSS, that would already help). 
I hope we get there once we have better doc tooling (sphinx, readthedocs etc)