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 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.
@smallbook.
Here are commands for quotations and examples, explained further in the following sections:
@quotation
@example
@smallexample
@example, except that in TeX this command typesets
text in a smaller font for the @smallbook format than for the
default 8.5 by 11 inch format.
@lisp
@example, but specifically for illustrating Lisp code. The
text is printed in a fixed-width font, and indented but not filled.
@smalllisp
@lisp as @smallexample is to @example.
@display
@smalldisplay
@display as @smallexample is to @example.
@format
@display (the text is not filled and no font is selected),
but the text is not indented.
@smallformat
@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 command within one of the above
constructs to highlight the example or quotation by drawing a box with
rounded corners around it. See section 10.11 Drawing Cartouches Around Examples.
@quotationThe text of a quotation is processed normally except that:
This is an example of text written between an
@quotationcommand and an@end quotationcommand. An@quotationcommand 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. Thus, the following,
@quotation This is a foo. @end quotation
produces
This is a foo.
@example
The @example command is used to indicate an example that is
not part of the running text, such as computer input or output.
This is an example of text written between an@examplecommand and an@end examplecommand. The text is indented but not filled. In the printed manual, the text is typeset in a fixed-width font, and extra spaces and blank lines are significant. In the Info file, an analogous result is obtained by indenting each line with five spaces.
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.
For example,
@example mv foo bar @end example
produces
mv foo bar
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.
Note that blank lines inside the beginning
@example and the ending @end example will appear in
the output.
Caution: Do not use tabs in the lines of an example (or anywhere else in Texinfo, for that matter)! TeX treats tabs as single spaces, and that is not what they look like. This is a problem with TeX. (If necessary, in Emacs, 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 after an example should not be
indented. The @noindent command prevents a piece of text from
being indented as if it were a new paragraph.
(See section 10.4 @noindent.)
(The @code command is used for examples of code that are
embedded within sentences, not set off from preceding and following
text. See section 9.1.2 @code{sample-code}.)
@noindent
An example or other inclusion can break a paragraph into segments.
Ordinarily, the formatters indent text that follows an example as a new
paragraph. However, you can prevent this by writing @noindent
at the beginning of a line by itself preceding the continuation
text.
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 exampleThis 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@displayand@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 a line containing @noindent.
Do not put braces after an @noindent command; they are not
necessary, since @noindent is a command used outside of
paragraphs (see section I. @-Command Syntax).
@lisp
The @lisp command is used for Lisp code. It is synonymous
with the @example command.
This is an example of text written between an@lispcommand and an@end lispcommand.
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.(7)
Mark the end of @lisp with @end lisp on a line by
itself.
@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. All of these commands are designed for use with the
@smallbook command (which causes TeX to format a printed book for
a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size).
In TeX, the @small... commands typeset text in a smaller
font for the smaller @smallbook format than for the 8.5 by 11
inch format. Consequently, many examples containing long lines fit in a
narrower, @smallbook page without needing to be shortened. Both
commands typeset in the normal font size when you format for the 8.5 by
11 inch size. Indeed, in this situation, the @small...
commands are equivalent to their non-small versions.
In Info, the @small... commands are also equivalent to their
non-small companion commands.
Mark the end of an @small... block with a corresponding
@end small.... For example, pair @smallexample with
@end smallexample.
This is an example of text written between@smallexampleand@end smallexample. In Info and in an 8.5 by 11 inch manual, this text appears in its normal size; but in a 7 by 9.25 inch manual, this text appears in a smaller font.
The @small... commands make it easier to prepare smaller
format manuals without forcing you to edit examples by hand to fit them
onto narrower pages.
As a general rule, a printed document looks better if you use only one
of (for example) @example or in @smallexample
consistently within a chapter. Only occasionally should you mix the two
formats.
See section 19.11 Printing "Small" Books, for more information
about the @smallbook command.
@display and @smalldisplay
The @display command begins a kind of example. It is 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@displaycommand and an@end displaycommand. The@displaycommand 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 10.6 @small... Block Commands.
@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@formatcommand and an@end formatcommand. As you can see from this example, the@formatcommand 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 10.6 @small... Block Commands.
@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 group
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.
@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.
In a printed manual, the @cartouche command draws a box with
rounded corners around its contents. 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.
@cartouche affects only the printed manual; it has no effect in
other output files.
For example,
@example @cartouche % pwd /usr/local/share/emacs @end cartouche @end example
surrounds the two-line example with a box with rounded corners, in the printed manual.
Go to the first, previous, next, last section, table of contents.