10.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.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.

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 (see @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; see @- @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.