12. Special Displays

The commands in this chapter allow you to write text that is specially displayed (output format permitting), outside of the normal document flow.

One set of such commands is for creating “floats”, that is, figures, tables, and the like, set off from the main text, possibly numbered, captioned, and/or referred to from elsewhere in the document. Images are often included in these displays.

Another group of commands is for creating footnotes in Texinfo.

12.1 Floats

A float is a display which is set off from the main text. It is typically labelled as being a “Figure”, “Table”, “Example”, or some similar type.

A float is so-named because, in principle, it can be moved to the bottom or top of the current page, or to a following page, in the printed output. (Floating does not make sense in other output formats.) In the present version of Texinfo, however, this floating is unfortunately not yet implemented. Instead, the floating material is simply output at the current location, more or less as if it were an @group (see section @group).

12.1.1 @float [type][,label]: Floating Material

To produce floating material, enclose the material you want to be displayed separate between @float and @end float commands, on lines by themselves.

Floating material uses @image to display an already-existing graphic (see section Inserting Images), or @multitable to display a table (see section @multitable: Multi-column Tables). However, the contents of the float can be anything. Here’s an example with simple text:

@float Figure,fig:ex1
This is an example float.
@end float

And the output:

Figure 12.1

As shown in the example, @float takes two arguments (separated by a comma), type and label. Both are optional.

type

Specifies the sort of float this is; typically a word such as “Figure”, “Table”, etc. If not given, and label is, any cross-referencing will simply use a bare number.

label

Specifies a cross-reference label for this float. If given, this float is automatically given a number, and will appear in any @listoffloats output (see section @listoffloats: Tables of Contents for Floats). Cross-references to label are allowed.

On the other hand, if label is not given, then the float will not be numbered and consequently will not appear in the @listoffloats output or be cross-referenceable.

Normally, you specify both type and label, to get a labeled and numbered float.

In Texinfo, all floats are numbered the same way: with the chapter number (or appendix letter), a period, and the float number, which simply counts 1, 2, 3, …, and is reset at each chapter. Each float type is counted independently.

Floats within an @unnumbered are numbered, or outside of any chapter, are simply numbered consecutively from 1.

These numbering conventions are not, at present, changeable.

12.1.2 @caption & @shortcaption

You may write an @caption anywhere within a @float environment, to define a caption for the float. It is not allowed in any other context. @caption takes a single argument, enclosed in braces. Here’s an example:

@float
An example float, with caption.
@caption{Caption for example float.}
@end float

The output is:

Caption for example float.

@caption can appear anywhere within the float; it is not processed until the @end float. The caption text is usually a sentence or two, but may consist of several paragraphs if necessary.

In the output, the caption always appears below the float; this is not currently changeable. It is preceded by the float type and/or number, as specified to the @float command (see the previous section).

The @shortcaption command likewise may be used only within @float, and takes a single argument in braces. The short caption text is used instead of the caption text in a list of floats (see the next section). Thus, you can write a long caption for the main document, and a short title to appear in the list of floats. For example:

@float
... as above ...
@shortcaption{Text for list of floats.}
@end float

The text for @caption and @shortcaption may not contain comments (@c), verbatim text (@verb), environments such as @example, or other complex constructs.

12.1.3 @listoffloats: Tables of Contents for Floats

You can write a @listoffloats command to generate a list of floats for a given float type (see section @float [type][,label]: Floating Material), analogous to the document’s overall table of contents. Typically, it is written in its own @unnumbered node to provide a heading and structure, rather like @printindex (see section Printing Indices and Menus).

@listoffloats takes one optional argument, the float type. Here’s an example:

@node List of Figures
@unnumbered List of Figures
@listoffloats Figure

And the output from @listoffloats:

Without any argument, @listoffloats generates a list of floats for which no float type was specified, i.e., no first argument to the @float command (see section @float [type][,label]: Floating Material).

Each line in the list of floats contains the float type (if any), the float number, and the caption, if any—the @shortcaption argument, if it was specified, else the @caption argument. In Info, the result is a menu where each float can be selected. In HTML, each line is a link to the float. In printed output, the page number is included.

Unnumbered floats (those without cross-reference labels) are omitted from the list of floats.

12.2 Inserting Images

You can insert an image given in an external file with the @image command. Although images can be used anywhere, including the middle of a paragraph, we describe them in this chapter since they are most often part of a displayed figure or example.

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 reads the file ‘filename.eps’ (Encapsulated PostScript format).
• pdfTeX reads ‘filename.png’, ‘filename.jpg’, ‘filename.jpeg’, or ‘filename.pdf’ (in that order). It also tries uppercase versions of the extensions. The PDF format cannot support EPS images, so they must be converted first.
• makeinfo includes ‘filename.txt’ verbatim for Info output (more or less as if it was an @example).
• makeinfo uses the optional fifth argument extension to @image for the filename extension, if it is specified. For example:

  @image{foo,,,,.xpm}

  will cause makeinfo to look for ‘foo.xpm’ before any others.

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 section @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 taken as Texinfo text, so special characters such as ‘"’ and ‘<’ and ‘&’ are escaped in the HTML and XML output; also, you can get an empty alt string with @- (a command that produces no output; see section @- and @hyphenation: Helping TeX Hyphenate).

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.

If you do not supply the optional extension (fifth) argument, makeinfo first tries ‘filename.png’; if that does not exist, it tries ‘filename.jpg’. If that does not exist either, it complains.

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

12.2.2 Image Scaling

The optional width and height arguments to the @image command (see the previous section) specify the size to scale the image to. They are ignored for Info output. If neither is specified, the image is presented in its natural size (given in the file); if only one is specified, the other is scaled proportionately; and if both are specified, both are respected, thus possibly distorting the original image by changing its aspect ratio.

The width and height may be specified using any valid TeX dimension, namely:

pt

point (72.27pt = 1in)

pc

pica (1pc = 12pt)

bp

big point (72bp = 1in)

in

inch

cm

centimeter (2.54cm = 1in)

mm

millimeter (10mm = 1cm)

dd

didôt point (1157dd = 1238pt)

cc

cicero (1cc = 12dd)

sp

scaled point (65536sp = 1pt)

For example, the following will scale a file ‘ridt.eps’ to one inch vertically, with the width scaled proportionately:

@image{ridt,,1in}

For @image to work with TeX, the file ‘epsf.tex’ must be installed somewhere that TeX can find it. (The standard location is ‘texmf/tex/generic/dvips/epsf.tex’, where texmf is a root of your TeX directory tree.) This file is included in the Texinfo distribution and is also available from ftp://tug.org/tex/epsf.tex, among other places.

@image can be used within a line as well as for displayed figures. Therefore, if you intend it to be displayed, be sure to leave a blank line before the command, or the output will run into the preceding text.

Image scaling is presently implemented only in TeX, not in HTML or any other sort of output.

12.3 Footnotes

A footnote is for a reference that documents or elucidates the primary text.(7) Footnotes are distracting; use them sparingly, if at all. Standard bibliographical references are better placed in a bibliography at the end of a document than in footnotes throughout.

12.3.1 Footnote Commands

In Texinfo, footnotes are created with the @footnote command. This command is followed immediately by a left brace, then by the text of the footnote, and then by a terminating right brace. Footnotes may be of any length (they will be broken across pages if necessary), but are usually short. The template is:

ordinary text@footnote{text of footnote}

As shown here, the @footnote command should come right after the text being footnoted, with no intervening space; otherwise, the footnote marker might end up starting a line.

For example, this clause is followed by a sample footnote(8); in the Texinfo source, it looks like this:

…a sample footnote@footnote{Here is the sample
footnote.}; in the Texinfo source…

As you can see, the source includes two punctuation marks next to each other; in this case, ‘.};’ is the sequence. This is normal (the first ends the footnote and the second belongs to the sentence being footnoted), so don’t worry that it looks odd.

In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the bottom of the page, below a horizontal line.

In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: ‘(1)’. The reference mark is followed by a cross-reference link to the footnote’s text.

In the HTML output, footnote references are marked with a small, superscripted number which is rendered as a hypertext link to the footnote text.

By the way, footnotes in the argument of an @item command for a @table must be on the same line as the @item (as usual). See section Making a Two-column Table.

12.3.2 Footnote Styles

Info has two footnote styles, which determine where the text of the footnote is located:

• In the ‘End’ node style, all the footnotes for a single node are placed at the end of that node. The footnotes are separated from the rest of the node by a line of dashes with the word ‘Footnotes’ within it. Each footnote begins with an ‘(n)’ reference mark.

  Here is an example of a single footnote in the end of node style:

  --------- Footnotes --------- (1) Here is a sample footnote.

• In the ‘Separate’ node style, all the footnotes for a single node are placed in an automatically constructed node of their own. In this style, a “footnote reference” follows each ‘(n)’ reference mark in the body of the node. The footnote reference is actually a cross reference which you use to reach the footnote node.

  The name of the node with the footnotes is constructed by appending ‘-Footnotes’ to the name of the node that contains the footnotes. (Consequently, the footnotes’ node for the ‘Footnotes’ node is ‘Footnotes-Footnotes’!) The footnotes’ node has an ‘Up’ node pointer that leads back to its parent node.

  Here is how the first footnote in this manual looks after being formatted for Info in the separate node style:

  File: texinfo.info Node: Overview-Footnotes, Up: Overview (1) The first syllable of "Texinfo" is pronounced like "speck", not "hex". …

Unless your document has long and important footnotes (as in, say, Gibbon’s Decline and Fall …), we recommend the ‘end’ style, as it is simpler for readers to follow.

Use the @footnotestyle command to specify an Info file’s footnote style. Write this command at the beginning of a line followed by an argument, either ‘end’ for the end node style or ‘separate’ for the separate node style.

For example,

@footnotestyle end

or

@footnotestyle separate

Write an @footnotestyle command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you include the @footnotestyle command between the start-of-header and end-of-header lines, the region formatting commands will format footnotes as specified.)

If you do not specify a footnote style, the formatting commands use their default style. Currently, texinfo-format-buffer and texinfo-format-region use the ‘separate’ style and makeinfo uses the ‘end’ style.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.