Go to the first, previous, next, last section, table of contents.


Special Insertions

Texinfo provides several commands for inserting characters that have special meaning in Texinfo, such as braces, and for other graphic elements that do not correspond to simple characters you can type.

These are:

Inserting @ and Braces

`@' and curly braces are special characters in Texinfo. To insert these characters so they appear in text, you must put an `@' in front of these characters to prevent Texinfo from misinterpreting them.

Do not put braces after any of these commands; they are not necessary.

Inserting `@' with @@

@@ stands for a single `@' in either printed or Info output.

Do not put braces after an @@ command.

Inserting `{' and `}'with @{ and @}

@{ stands for a single `{' in either printed or Info output.

@} stands for a single `}' in either printed or Info output.

Do not put braces after either an @{ or an @} command.

Inserting Space

The following sections describe commands that control spacing of various kinds within and after sentences.

Not Ending a Sentence

Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after a period in a typeset manual. Since it is not always possible for Texinfo to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. (Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period, question mark, or exclamation mark that ends a sentence.)

Use the @: command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use @: after periods that end abbreviations which are not at the ends of sentences.

For example,

The s.o.p.@: has three parts ...
The s.o.p. has three parts ...

produces the following. If you look carefully at this printed output, you will see a little more whitespace after `s.o.p.' in the second line.

The s.o.p. has three parts ...
The s.o.p. has three parts ...

(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating Procedure".)

@: has no effect on the Info output. Do not put braces after @:.

Ending a Sentence

Use @. instead of a period, @! instead of an exclamation point, and @? instead of a question mark at the end of a sentence that ends with a single capital letter. Otherwise, TeX will think the letter is an abbreviation and will not insert the correct end-of-sentence spacing. Here is an example:

Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces the following. If you look carefully at this printed output, you will see a little more whitespace after the `W' in the first line.

Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.

In the Info file output, @. is equivalent to a simple `.'; likewise for @! and @?.

The meanings of @: and @. in Texinfo are designed to work well with the Emacs sentence motion commands (see section `Sentences' in The GNU Emacs Manual). This made it necessary for them to be incompatible with some other formatting systems that use @-commands.

Do not put braces after any of these commands.

Multiple Spaces

Ordinarily, TeX collapses multiple whitespace characters (space, tab, and newline) into a single space. Info output, on the other hand, preserves whitespace as you type it, except for changing a newline into a space; this is why it is important to put two spaces at the end of sentences in Texinfo documents.

Occasionally, you may want to actually insert several consecutive spaces, either for purposes of example (what your program does with multiple spaces as input), or merely for purposes of appearance in headings or lists. Texinfo supports three commands: @SPACE, @TAB, and @NL, all of which insert a single space into the output. (Here, @SPACE represents an `@' character followed by a space, i.e., `@ ', and TAB and NL represent the tab character and end-of-line, i.e., when `@' is the last character on a line.)

For example,

Spacey@ @ @ @
example.

produces

Spacey   
example.

Other possible uses of @SPACE have been subsumed by @multitable (see section Multi-column Tables).

Do not follow any of these commands with braces.

@dmn{dimension}: Format a Dimension

At times, you may want to write `12pt' or `8.5in' with little or no space between the number and the abbreviation for the dimension. You can use the @dmn command to do this. On seeing the command, TeX inserts just enough space for proper typesetting; the Info formatting commands insert no space at all, since the Info file does not require it.

To use the @dmn command, write the number and then follow it immediately, with no intervening space, by @dmn, and then by the dimension within braces. For example,

A4 paper is 8.27@dmn{in} wide.

produces

A4 paper is 8.27in wide.

Not everyone uses this style. Some people prefer `8.27 in.@:' or `8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases, however, the formatters may insert a line break between the number and the dimension, so use @w (see section @w{text}: Prevent Line Breaks). Also, if you write a period after an abbreviation within a sentence, you should write `@:' after the period to prevent TeX from inserting extra whitespace, as shown here. See section Inserting Space.

Inserting Accents

Here is a table with the commands Texinfo provides for inserting floating accents. The commands with non-alphabetic names do not take braces around their argument (which is taken to be the next character). (Exception: @, does take braces around its argument.) This is so as to make the source as convenient to type and read as possible, since accented characters are very common in some languages.

Command @"o@'o@,{c}@=o@^o@`o@~o@dotaccent{o}@H{o}@ringaccent{o}@tieaccent{oo}@u{o}@ubaraccent{o}@udotaccent{o}@v{o}
Output What
@"o umlaut accent
'o acute accent
@,{c} cedilla accent
@=o macron/overbar accent
@^o circumflex accent
`o grave accent
@~o tilde accent
@dotaccent{o} overdot accent
@H{o} long Hungarian umlaut
@ringaccent{o} ring accent
@tieaccent{oo} tie-after accent
@u{o} breve accent
@ubaraccent{o} underbar accent
@udotaccent{o} underdot accent
@v{o} hacek or check accent
This table lists the Texinfo commands for inserting other characters commonly used in languages other than English. @exclamdown{}@questiondown{}@aa{},@AA{}@ae{},@AE{}@dotless{i}@dotless{j}@l{},@L{}@o{},@O{}@oe{},@OE{}@ss{}
¡ upside-down !
¿ upside-down ?
å,Å A,a with circle
æ,Æ ae,AE ligatures
@dotless{i} dotless i
@dotless{j} dotless j
l/,L/ suppressed-L,l
ø,Ø O,o with slash
oe,OE OE,oe ligatures
ß es-zet or sharp S

Inserting Ellipsis, Dots, and Bullets

An ellipsis (a line of dots) is not typeset as a string of periods, so a special command is used for ellipsis in Texinfo. The @bullet command is special, too. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces. (You need to use braces with these commands because you can use them next to other text; without the braces, the formatters would be confused. See section @-Command Syntax, for further information.)

@dots{} (...)

Use the @dots{} command to generate an ellipsis, which is three dots in a row, appropriately spaced, like this: `...'. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual.

Similarly, the @enddots{} command generates an end-of-sentence ellipsis (four dots) ....

Here is an ellipsis: ... Here are three periods in a row: ...

In printed output, the three periods in a row are closer together than the dots in the ellipsis.

@bullet{} (*)

Use the @bullet{} command to generate a large round dot, or the closest possible thing to one. In Info, an asterisk is used.

Here is a bullet: *

When you use @bullet in @itemize, you do not need to type the braces, because @itemize supplies them. (See section Making an Itemized List.)

Inserting TeX and the Copyright Symbol

The logo `TeX' is typeset in a special fashion and it needs an @-command. The copyright symbol, `©', is also special. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces.

@TeX{} (TeX)

Use the @TeX{} command to generate `TeX'. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like `TeX'. The @TeX{} command is unique among Texinfo commands in that the T and the X are in upper case.

@copyright{} (©)

Use the @copyright{} command to generate `©'. In a printed manual, this is a `c' inside a circle, and in Info, this is `(C)'.

@pounds{} (£): Pounds Sterling

Use the @pounds{} command to generate `£'. In a printed manual, this is the symbol for the currency pounds sterling. In Info, it is a `#'. Other currency symbols are unfortunately not available.

@minus{} (-): Inserting a Minus Sign

Use the @minus{} command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign--a little longer than a hyphen, shorter than an em-dash:

`-' is a minus sign generated with `@minus{}',

`-' is a hyphen generated with the character `-',

`---' is an em-dash for text.

In the fixed-width font used by Info, @minus{} is the same as a hyphen.

You should not use @minus{} inside @code or @example because the width distinction is not made in the fixed-width font they use.

When you use @minus to specify the mark beginning each entry in an itemized list, you do not need to type the braces (see section Making an Itemized List.)

@math: Inserting Mathematical Expressions

You can write a short mathematical expression with the @math command. Write the mathematical expression between braces, like this:

@math{(a + b)(a + b) = a^2 + 2ab + b^2}

This produces the following in TeX:

(a + b)(a + b) = a^2 + 2ab + b^2

and the following in Info:

(a + b)(a + b) = a^2 + 2ab + b^2

Thus, the @math command has no effect on the Info output.

For complex mathematical expressions, you can also use TeX directly (see section Raw Formatter Commands). When you use TeX directly, remember to write the mathematical expression between one or two `$' (dollar-signs) as appropriate.

Glyphs for Examples

In Texinfo, code is often illustrated in examples that are delimited by @example and @end example, or by @lisp and @end lisp. In such examples, you can indicate the results of evaluation or an expansion using `=>' or `==>'. Likewise, there are commands to insert glyphs to indicate printed output, error messages, equivalence of expressions, and the location of point.

The glyph-insertion commands do not need to be used within an example, but most often they are. Every glyph-insertion command is followed by a pair of left- and right-hand braces.

=>
@result{} points to the result of an expression.
==>
@expansion{} shows the results of a macro expansion.
-|
@print{} indicates printed output.
error-->
@error{} indicates that the following text is an error message.
==
@equiv{} indicates the exact equivalence of two forms.
-!-
@point{} shows the location of point.

@result{} (=>): Indicating Evaluation

Use the @result{} command to indicate the result of evaluating an expression.

The @result{} command is displayed as `=>' in Info and as `=>' in the printed output.

Thus, the following,

(cdr '(1 2 3))
     => (2 3)

may be read as "(cdr '(1 2 3)) evaluates to (2 3)".

@expansion{} (==>): Indicating an Expansion

When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the @expansion{} command.

The @expansion{} command is displayed as `==>' in Info and as `==>' in the printed output.

For example, the following

@lisp
(third '(a b c))
     @expansion{} (car (cdr (cdr '(a b c))))
     @result{} c
@end lisp

produces

(third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c

which may be read as:

(third '(a b c)) expands to (car (cdr (cdr '(a b c)))); the result of evaluating the expression is c.

Often, as in this case, an example looks better if the @expansion{} and @result{} commands are indented five spaces.

@print{} (-|): Indicating Printed Output

Sometimes an expression will print output during its execution. You can indicate the printed output with the @print{} command.

The @print{} command is displayed as `-|' in Info and as `-|' in the printed output.

In the following example, the printed text is indicated with `-|', and the value of the expression follows on the last line.

(progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar

In a Texinfo source file, this example is written as follows:

@lisp
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end lisp

@error{} (error-->): Indicating an Error Message

A piece of code may cause an error when you evaluate it. You can designate the error message with the @error{} command.

The @error{} command is displayed as `error-->' in Info and as `error-->' in the printed output.

Thus,

@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp

produces

(+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed when you evaluate the expression:

Wrong type argument: integer-or-marker-p, x

`error-->' itself is not part of the error message.

@equiv{} (==): Indicating Equivalence

Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the @equiv{} command.

The @equiv{} command is displayed as `==' in Info and as `==' in the printed output.

Thus,

@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp

produces

(make-sparse-keymap) == (list 'keymap)

This indicates that evaluating (make-sparse-keymap) produces identical results to evaluating (list 'keymap).

@point{} (-!-): Indicating Point in a Buffer

Sometimes you need to show an example of text in an Emacs buffer. In such examples, the convention is to include the entire contents of the buffer in question between two lines of dashes containing the buffer name.

You can use the `@point{}' command to show the location of point in the text in the buffer. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is located.)

The @point{} command is displayed as `-!-' in Info and as `-!-' in the printed output.

The following example shows the contents of buffer `foo' before and after evaluating a Lisp command to insert the word changed.

---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------

In a Texinfo source file, the example is written like this:

@example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example

Inserting Images

You can insert an image in an external file with the @image command:

@image{filename, [width], [height]}

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); makeinfo uses `filename.txt' verbatim for Info output (more or less as if it was an @example). HTML output requires `filename.jpg'.

The optional width and height arguments specify the size to scale the image to (they are ignored for Info output). If they are both 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@^ot 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. This file is included in the Texinfo distribution and is available from ftp://ftp.tug.org/tex/epsf.tex.


Go to the first, previous, next, last section, table of contents.