Re: [Qemu-devel] [PATCH v5 16/17] docs: add qemu logo

[Markus Armbruster]

Marc-André Lureau <address@hidden> writes:

> Hi
>
> On Fri, Nov 18, 2016 at 4:53 PM Markus Armbruster <address@hidden> wrote:
>
>> Marc-André Lureau <address@hidden> writes:
>>
>> > The pdf (needed by texi2pdf for vectorized images) was generated thanks
>> > to inkscape, from the pc-bios/qemu_logo.svg file.
>>
>> Since we don't want to build-depend on inkscape, we need to commit the
>> .pdf.  Not that bad, as the .svg is unlikely to change.  But let's
>> explain that in the commit message.  Recommend to throw in the inkscape
>> command line.
>>
>
> ok
>
>
>>
>> >
>> > Signed-off-by: Marc-André Lureau <address@hidden>
>>
>> I'm afraid this fails when build tree != source tree.  I get
>>
>>     $ make pdf
>>       GEN     docs/qemu-qmp-ref.pdf
>>     /usr/bin/texi2dvi: pdfetex exited with bad status, quitting.
>>     Makefile:558: recipe for target 'docs/qemu-qmp-ref.pdf' failed
>>     make: *** [docs/qemu-qmp-ref.pdf] Error 1
>>     $ tail qemu-qmp-ref.log
>>                                                       @let @centersub
>> @relax
>>     l.12 @center @image{docs/qemu_logo}
>>
>>     @Texinfo supports .png, .jpg, .jpeg, and .pdf images with PDF output,
>> and none
>>     of those formats could be found. (.eps cannot be supported due to the
>> design of
>>      the PDF format; use regular TeX (DVI output) for that.)
>>
>>
>>     !pdfTeX error: pdfetex (file docs/qemu_logo.): cannot find image file
>>      ==> Fatal error occurred, no output PDF file produced!
>>
>>
> Adding -I $(SRC_PATH) solves it
>
> make dvi fails for me, too.
>>
>
> I propose we drop dvi format rules (pdf is generally better supported)

I figure DVI doesn't provide all that much value anymore, so dropping it
could be justified if keeping it is a burden.  Separate patch, of
course.

>> > ---
>> >  docs/qemu-ga-ref.texi  |   4 ++++
>> >  docs/qemu-qmp-ref.texi |   4 ++++
>> >  docs/qemu_logo.pdf     | Bin 0 -> 9117 bytes
>> >  3 files changed, 8 insertions(+)
>> >  create mode 100644 docs/qemu_logo.pdf
>> >
>> > diff --git a/docs/qemu-ga-ref.texi b/docs/qemu-ga-ref.texi
>> > index 02ecdb7..f7ed73e 100644
>> > --- a/docs/qemu-ga-ref.texi
>> > +++ b/docs/qemu-ga-ref.texi
>> > @@ -6,6 +6,10 @@
>> >
>> >  @settitle QEMU Guest Agent Protocol Reference
>> >
>> > address@hidden
>> > address@hidden @image{docs/qemu_logo}
>> > address@hidden iftex
>> > +
>> >  @copying
>> >  This is the QEMU Guest Agent Protocol reference manual.
>> >
>> > diff --git a/docs/qemu-qmp-ref.texi b/docs/qemu-qmp-ref.texi
>> > index ccc03cb..0f7e9e4 100644
>> > --- a/docs/qemu-qmp-ref.texi
>> > +++ b/docs/qemu-qmp-ref.texi
>> > @@ -6,6 +6,10 @@
>> >
>> >  @settitle QEMU QMP Reference Manual
>> >
>> > address@hidden
>> > address@hidden @image{docs/qemu_logo}
>> > address@hidden iftex
>> > +
>>
>> Quoting the Texinfo manual:
>>
>> Here is the synopsis of the '@image' command:
>>
>>      @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
>>
>>   The FILENAME argument is mandatory, and must not have an extension,
>> because the different processors support different formats:
>>
>>    * TeX (DVI output) reads the file 'FILENAME.eps' (Encapsulated
>>      PostScript format).
>>
>>    * pdfTeX reads 'FILENAME.pdf', 'FILENAME.png', 'FILENAME.jpg', or
>>      'FILENAME.jpeg' (in that order).  It also tries uppercase versions
>>      of the extensions.  The PDF format does not support EPS images, so
>>      such must be converted first.
>>
>>    * For Info, 'makeinfo' includes 'FILENAME.txt' verbatim (more or less
>>      as if it were in '@verbatim').  The Info output may also include a
>>      reference to 'FILENAME.png' or 'FILENAME.jpg'.  (See below.)
>>
>>    * For HTML, 'makeinfo' outputs a reference to 'FILENAME.png',
>>      'FILENAME.jpg', 'FILENAME.jpeg' or 'FILENAME.gif' (in that order).
>>      If none of those exist, it gives an error, and outputs a reference
>>      to 'FILENAME.jpg' anyway.
>>
>>    * For Docbook, 'makeinfo' outputs references to 'FILENAME.eps',
>>      'FILENAME.gif' 'FILENAME.jpeg', 'FILENAME.jpg', 'FILENAME.pdf',
>>      'FILENAME.png' and 'FILENAME.svg', for every file found.  Also,
>>      'FILENAME.txt' is included verbatim, if present.  (The subsequent
>>      Docbook processor is supposed to choose the appropriate one.)
>>
>>    * For Info and HTML output, 'makeinfo' uses the optional fifth
>>      argument EXTENSION to '@image' for the filename extension, if it is
>>      specified and the file is found.  Any leading period should be
>>      included in EXTENSION.  For example:
>>
>>           @image{foo,,,,.xpm}
>>
>>   If you want to install image files for use by Info readers too, we
>> recommend putting them in a subdirectory like 'FOO-figures' for a
>> package FOO.  Copying the files into '$(infodir)/FOO-figures/' should be
>> done in your 'Makefile'.
>>
>> End quote.
>>
>> You provide qemu_logo.pdf, which satisfies pdfTeX (our make target pdf)
>> and Docbook (we don't care).  Should we provide files to satisfy Info
>> and HTML?
>>
>
> The logo is only included @iftex.
>
> I don't see much point in having the logo in info file.

Same point as for PDF: it looks pretty.  At least in sufficiently
capable Info readers:

      In Info output, 'makeinfo' writes a reference to the binary image file
    (trying FILENAME suffixed with 'EXTENSION', '.EXTENSION', '.png', or
    '.jpg', in that order) if one exists.  It also literally includes the
    '.txt' file if one exists.  This way, Info readers which can display
    images (such as the Emacs Info browser, running under X) can do so,
    whereas Info readers which can only use text (such as the standalone
    Info reader) can display the textual version.

Not implementing the logo for Info isn't a deal-breaker, of course.

> We can add eventually add it to html, I guess it depends how the html will
> be published, I'd rather fix that when we improve our doc toolchain in the
> next release (I suppose the pdf will still be generated with texi2pdf, but
> the html with sphinx with Paolo texi/docbook integration)

Not a deal-breaker, either.

Limitations should be mentioned in the commit message, and perhaps in
comments.

>> My version of texinfo seems to ignore the @image when it can't file any
>> file in some cases.  That's why make info and make html still work.
>>
>> >  @copying
>> >  This is the QEMU QMP reference manual.
>> >
>> > diff --git a/docs/qemu_logo.pdf b/docs/qemu_logo.pdf
>> > new file mode 100644
>> > index
>> 0000000000000000000000000000000000000000..294cb7dec50de73c786925671300fb0abdf9d641
>> > GIT binary patch
>> [...]
>>
>> --
> Marc-André Lureau