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

[Markus Armbruster <armbru@redhat.com>]

Marc-André Lureau <marcandre.lureau@redhat.com> 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.

>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>

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!

make dvi fails for me, too.

> ---
>  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
>  
> +@iftex
> +@center @image{docs/qemu_logo}
> +@end 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
>  
> +@iftex
> +@center @image{docs/qemu_logo}
> +@end 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?

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