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: How to show the result of expression.
• expansion: How to indicate an expansion.
• Print Glyph: How to indicate printed output.
• Error Glyph: How to indicate an error message.
• Equivalence: How to indicate equivalence.
• Point Glyph: How to indicate the location of point.

=>

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

=>: 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)".

==>: 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.

-|: 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-->: 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

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

==: 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).

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