texinfo: Image Syntax

Images

Image Scaling

Back to Software Index

12.2.1 Image Syntax
-------------------

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.jpg', 'FILENAME.pdf', 'FILENAME.png' and
     'FILENAME.svg', for every file found.  Als, 'FILENAME.txt' is
     included verbatim, if present.

   * 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'.

  The WIDTH and HEIGHT arguments are described in the next section.

  For TeX output, if an image is the only thing in a paragraph it will
ordinarily be displayed on a line by itself, respecting the current
environment indentation, but without the normal paragraph indentation.
If you want it centered, use '@center' (Note: @titlefont @center @sp).

  For HTML output, 'makeinfo' sets the "alt attribute" for inline images
to the optional ALTTEXT (fourth) argument to '@image', if supplied.  If
not supplied, 'makeinfo' uses the full file name of the image being
displayed.  The ALTTEXT is processed as Texinfo text, so special
characters such as '"' and '<' and '&' are escaped in the HTML output;
also, you can get an empty 'alt' string with '@-' (a command that
produces no output; Note: @- @hyphenation).

  For Info output, the 'alt' string is also processed as Texinfo text
and output.  In this case, '\' is escaped as '\\' and '"' as '\"'; no
other escapes are done.

  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.

  The implementation of this is to put the following construct into the
Info output:

     ^@^H[image src="BINARYFILE" text="TXTFILE"
                alt="ALTTEXT ... ^@^H]

where '^@' and '^H' stand for the actual null and backspace control
characters.  If one of the files is not present, the corresponding
argument is omitted.

  The reason for mentioning this here is that older Info browsers (this
feature was introduced in Texinfo version 4.6) will display the above
literally, which, although not pretty, should not be harmful.