10. Quotations and Examples

Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented in the output.

In Texinfo, you always begin a quotation or example by writing an @-command at the beginning of a line by itself, and end it by writing an @end command that is also at the beginning of a line by itself. For instance, you begin an example by writing @example by itself at the beginning of a line and end the example by writing @end example on a line by itself, at the beginning of that line, and with only one space between the @end and the example.

10.1 Block Enclosing Commands

Here are commands for quotations and examples, explained further in the following sections:

@quotation

Indicate text that is quoted. The text is filled, indented (from both margins), and printed in a roman font by default.

@example

Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.

@verbatim

Mark a piece of text that is to be printed verbatim; no character substitutions are made and all commands are ignored, until the next @end verbatim. The text is printed in a fixed-width font, and not indented or filled. Extra spaces and blank lines are significant, and tabs are expanded.

@smallexample

Same as @example, except that in TeX this command typesets text in a smaller font.

@lisp

Like @example, but specifically for illustrating Lisp code. The text is printed in a fixed-width font, and indented but not filled.

@smalllisp

Is to @lisp as @smallexample is to @example.

@display

Display illustrative text. The text is indented but not filled, and no font is selected (so, by default, the font is roman).

@smalldisplay

Is to @display as @smallexample is to @example.

@format

Like @display (the text is not filled and no font is selected), but the text is not indented.

@smallformat

Is to @format as @smallexample is to @example.

The @exdent command is used within the above constructs to undo the indentation of a line.

The @flushleft and @flushright commands are used to line up the left or right margins of unfilled text.

The @noindent command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph.

You can use the @cartouche environment around one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. See section Drawing Cartouches Around Examples.

10.2 @quotation: Block quotations

The text of a quotation is processed normally (regular font, text is filled) except that:

• the margins are closer to the center of the page, so the whole of the quotation is indented;
• and the first lines of paragraphs are indented no more than other lines.

This is an example of text written between an @quotation command and an @end quotation command. An @quotation command is most often used to indicate text that is excerpted from another (real or hypothetical) printed work.

Write an @quotation command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @end quotation. The @end quotation line will likewise disappear from the output.

@quotation takes one optional argument, given on the remainder of the line. This text, if present, is included at the beginning of the quotation in bold or otherwise emphasized, and followed with a ‘:’. For example:

@quotation Note
This is
a foo.
@end quotation

produces

Note: This is a foo.

If the @quotation argument is exactly one of these words:

Caution  Important  Note  Tip  Warning

then the Docbook output uses corresponding special tags (<note>, etc.) instead of the default <blockquote>. HTML output always uses <blockquote>.

10.3 @example: Example Text

The @example environment is used to indicate an example that is not part of the running text, such as computer input or output. Write an @example command at the beginning of a line by itself. Mark the end of the example with an @end example command, also written at the beginning of a line by itself.

An @example environment has the following characteristics:

• Each line in the input file is a line in the output; that is, the source text is not filled as it normally is.
• Extra spaces and blank lines are significant.
• The output is indented.
• The output uses a fixed-width font.
• Texinfo commands are expanded; if you want the output to be the input verbatim, use the @verbatim environment instead (see section @verbatim).

For example,

@example
cp foo @var{dest1}; \
 cp foo @var{dest2}
@end example

produces

cp foo dest1; \
 cp foo dest2

The lines containing @example and @end example will disappear from the output. To make the output look good, you should put a blank line before the @example and another blank line after the @end example. Blank lines inside the beginning @example and the ending @end example, on the other hand, do appear in the output.

Caution: Do not use tabs in the lines of an example! (Or anywhere else in Texinfo, except in verbatim environments.) TeX treats tabs as single spaces, and that is not what they look like. In XEmacs, you can use M-x untabify to convert tabs in a region to multiple spaces.

Examples are often, logically speaking, “in the middle” of a paragraph, and the text that continues afterwards should not be indented, as in the example above. The @noindent command prevents a piece of text from being indented as if it were a new paragraph (see section @noindent.

If you want to embed code fragments within sentences, instead of displaying them, use the @code command or its relatives (see section @code).

If you wish to write a “comment” on a line of an example in the normal roman font, you can use the @r command (see section Fonts for Printing, Not Info).

10.4 @verbatim: Literal Text

Use the @verbatim environment for printing of text that may contain special characters or commands that should not be interpreted, such as computer input or output (@example interprets its text as regular Texinfo commands). This is especially useful for including automatically generated files in a Texinfo manual.

In general, the output will be just the same as the input. No character substitutions are made, e.g., all spaces and blank lines are significant, including tabs. In the printed manual, the text is typeset in a fixed-width font, and not indented or filled.

Write a @verbatim command at the beginning of a line by itself. This line will disappear from the output. Mark the end of the verbatim block with a @end verbatim command, also written at the beginning of a line by itself. The @end verbatim will also disappear from the output.

For example:

@verbatim
{
<TAB>@command with strange characters: @'e
expand<TAB>me
}
@end verbatim

This produces:

{
        @command with strange characters: @'e
expand	me
}

Since the lines containing @verbatim and @end verbatim produce no output, typically you should put a blank line before the @verbatim and another blank line after the @end verbatim. Blank lines between the beginning @verbatim and the ending @end verbatim will appear in the output.

You can get a “small” verbatim by enclosing the @verbatim in an @smallformat environment, as shown here:

@smallformat
@verbatim
... still verbatim, but in a smaller font ...
@end verbatim
@end smallformat

Finally, a word of warning: it is not reliable to use @verbatim inside other Texinfo constructs.

10.5 @verbatiminclude file: Include a File Verbatim

You can include the exact contents of a file in the document with the @verbatiminclude command:

@verbatiminclude filename

The contents of filename is printed in a verbatim environment (see section @verbatim). Generally, the file is printed exactly as it is, with all special characters and white space retained. No indentation is added; if you want indentation, enclose the @verbatiminclude within @example (see section @example).

The name of the file is taken literally, with a single exception: @value{var} references are expanded. This makes it possible to include files in other directories within a distribution, for instance:

@verbatiminclude @value{top_srcdir}/NEWS

(You still have to get top_srcdir defined in the first place.)

For a method on printing the file contents in a smaller font size, see the end of the previous section on @verbatim.

10.6 @lisp: Marking a Lisp Example

The @lisp command is used for Lisp code. It is synonymous with the @example command.

This is an example of text written between an
@lisp command and an @end lisp command.

Use @lisp instead of @example to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.(6)

Mark the end of @lisp with @end lisp on a line by itself.

10.7 @small… Block Commands

In addition to the regular @example and @lisp commands, Texinfo has “small” example-style commands. These are @smalldisplay, @smallexample, @smallformat, and @smalllisp.

In Info, the @small… commands are equivalent to their non-small companion commands.

In TeX, however, the @small… commands typeset text in a smaller font than the non-small example commands. Consequently, many examples containing long lines fit on a page without needing to be shortened.

Mark the end of an @small… block with a corresponding @end small…. For example, pair @smallexample with @end smallexample.

Here is an example of the font used by the @small… commands (in Info, the output will be the same as usual):

… to make sure that you have the freedom to
distribute copies of free software (and charge for
this service if you wish), that you receive source
code or can get it if you want it, that you can
change the software or use pieces of it in new free
programs; and that you know you can do these things.

The @small… commands make it easier to prepare manuals without forcing you to edit examples by hand to fit them onto narrower pages.

As a general rule, a printed document looks much better if you use only one of (for instance) @example or @smallexample consistently within a chapter.

10.8 @display and @smalldisplay

The @display command begins a kind of example, where each line of input produces a line of output, and the output is indented. It is thus like the @example command except that, in a printed manual, @display does not select the fixed-width font. In fact, it does not specify the font at all, so that the text appears in the same font it would have appeared in without the @display command.

This is an example of text written between an @display command
and an @end display command.  The @display command
indents the text, but does not fill it.

Texinfo also provides a command @smalldisplay, which is like @display but uses a smaller font in @smallbook format. See section @small… Block Commands.

The @table command (see section Using the @table Command) does not work inside @display. Since @display is line-oriented, it doesn’t make sense to use them together. If you want to indent a table, try @quotation (see section @quotation: Block quotations).

10.9 @format and @smallformat

The @format command is similar to @example except that, in the printed manual, @format does not select the fixed-width font and does not narrow the margins.

This is an example of text written between an @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

Texinfo also provides a command @smallformat, which is like @format but uses a smaller font in @smallbook format. See section @small… Block Commands.

10.10 @exdent: Undoing a Line’s Indentation

The @exdent command removes any indentation a line might have. The command is written at the beginning of a line and applies only to the text that follows the command that is on the same line. Do not use braces around the text. In a printed manual, the text on an @exdent line is printed in the roman font.

@exdent is usually used within examples. Thus,

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end example

produces

This line follows an @example command.
This line is exdented.
This line follows the exdented line.
The @end example comes on the next line.

In practice, the @exdent command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width.

10.11 @flushleft and @flushright

The @flushleft and @flushright commands line up the ends of lines on the left and right margins of a page, but do not fill the text. The commands are written on lines of their own, without braces. The @flushleft and @flushright commands are ended by @end flushleft and @end flushright commands on lines of their own.

For example,

@flushleft
This text is
written flushleft.
@end flushleft

produces

This text is written flushleft.

@flushright produces the type of indentation often used in the return address of letters. For example,

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

produces

Here is an example of text written flushright. The @flushright command right justifies every line but leaves the left end ragged.

10.12 @noindent: Omitting Indentation

An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. You can prevent this on a case-by-case basis by writing @noindent at the beginning of a line, preceding the continuation text. You can also disable indentation for all paragraphs globally with @paragraphindent (see section Paragraph Indenting).

It is best to write @noindent on a line by itself, since in most environments, spaces following the command will not be ignored. It’s ok to use it at the beginning of a line, with text following, outside of any environment.

For example:

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@code{@@display} and @code{@@end display}.)

produces:

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@display and @end display.)

To adjust the number of blank lines properly in the Info file output, remember that the line containing @noindent does not generate a blank line, and neither does the @end example line.

In the Texinfo source file for this manual, each line that says ‘produces’ is preceded by @noindent.

Do not put braces after an @noindent command; they are not necessary, since @noindent is a command used outside of paragraphs (see section @-Command Syntax).

10.13 @indent: Forcing Indentation

To complement the @noindent command (see the previous section), Texinfo provides the @indent command that forces a paragraph to be indented. This paragraph, for instance, is indented using an @indent command. The first paragraph of a section is the most likely place to use @indent, to override the normal behavior of no indentation there (see section @paragraphindent: Paragraph Indenting).

It is best to write @indent on a line by itself, since in most environments, spaces following the command will not be ignored. The @indent line will not generate a blank line in the Info output within an environment.

However, it is ok to use it at the beginning of a line, with text following, outside of any environment.

Do not put braces after an @indent command; they are not necessary, since @indent is a command used outside of paragraphs (see section @-Command Syntax).

10.14 @cartouche: Rounded Rectangles Around Examples

In a printed manual, the @cartouche command draws a box with rounded corners around its contents. In HTML, a normal rectangle is drawn (that’s the best HTML can do). @cartouche has no effect in Info output.

You can use this command to further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis.

For example,

@cartouche
@example
% pwd
/usr/local/share/xemacs
@end example
@end cartouche

surrounds the two-line example with a box with rounded corners, in the printed manual.

The output from the example looks like this (if you’re reading this in Info, you’ll see the @cartouche had no effect):

% pwd
/usr/local/info

For proper output in HTML, it’s necessary to put the @cartouche around the @example, and not the other way around. This limitation of makeinfo may be removed one day.

@cartouche also implies @group (see section @group: Prevent Page Breaks).

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