1 This is ../info/texinfo.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text
38 Indicating Definitions, Commands, etc.
39 ======================================
41 Texinfo has commands for indicating just what kind of object a piece
42 of text refers to. For example, metasyntactic variables are marked by
43 `@var', and code by `@code'. Since the pieces of text are labelled by
44 commands that tell what kind of object they are, it is easy to change
45 the way the Texinfo formatters prepare such text. (Texinfo is an
46 _intentional_ formatting language rather than a _typesetting_
49 For example, in a printed manual, code is usually illustrated in a
50 typewriter font; `@code' tells TeX to typeset this text in this font.
51 But it would be easy to change the way TeX highlights code to use
52 another font, and this change would not effect how keystroke examples
53 are highlighted. If straight typesetting commands were used in the body
54 of the file and you wanted to make a change, you would need to check
55 every single occurrence to make sure that you were changing code and
56 not something else that should not be changed.
60 * Useful Highlighting:: Highlighting provides useful information.
61 * code:: How to indicate code.
62 * kbd:: How to show keyboard input.
63 * key:: How to specify keys.
64 * samp:: How to show a literal sequence of characters.
65 * var:: How to indicate a metasyntactic variable.
66 * file:: How to indicate the name of a file.
67 * dfn:: How to specify a definition.
68 * cite:: How to refer to a book that is not in Info.
69 * url:: How to indicate a world wide web reference.
70 * email:: How to indicate an electronic mail address.
73 File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating
75 Highlighting Commands are Useful
76 --------------------------------
78 The highlighting commands can be used to generate useful information
79 from the file, such as lists of functions or file names. It is
80 possible, for example, to write a program in Emacs Lisp (or a keyboard
81 macro) to insert an index entry after every paragraph that contains
82 words or phrases marked by a specified command. You could do this to
83 construct an index of functions if you had not already made the entries.
85 The commands serve a variety of purposes:
88 Indicate text that is a literal example of a piece of a program.
90 `@kbd{KEYBOARD-CHARACTERS}'
91 Indicate keyboard input.
94 Indicate the conventional name for a key on a keyboard.
97 Indicate text that is a literal example of a sequence of
100 `@var{METASYNTACTIC-VARIABLE}'
101 Indicate a metasyntactic variable.
103 `@url{UNIFORM-RESOURCE-LOCATOR}'
104 Indicate a uniform resource locator for the World Wide Web.
107 Indicate the name of a file.
109 `@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
110 Indicate an electronic mail address.
113 Indicate the introductory or defining use of a term.
116 Indicate the name of a book.
119 File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating
124 Use the `@code' command to indicate text that is a piece of a program
125 and which consists of entire syntactic tokens. Enclose the text in
128 Thus, you should use `@code' for an expression in a program, for the
129 name of a variable or function used in a program, or for a keyword.
130 Also, you should use `@code' for the name of a program, such as `diff',
131 that is a name used in the machine. (You should write the name of a
132 program in the ordinary text font if you regard it as a new English
133 word, such as `Emacs' or `Bison'.)
135 Use `@code' for environment variables such as `TEXINPUTS', and other
138 Use `@code' for command names in command languages that resemble
139 programming languages, such as Texinfo or the shell. For example,
140 `@code' and `@samp' are produced by writing `@code{@@code}' and
141 `@code{@@samp}' in the Texinfo source, respectively.
143 Note, however, that you should not use `@code' for shell options such
144 as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
145 shell command often looks better if written using `@samp' rather than
146 `@code'. In this case, the rule is to choose the more pleasing format.
148 It is incorrect to alter the case of a word inside an `@code' command
149 when it appears at the beginning of a sentence. Most computer
150 languages are case sensitive. In C, for example, `Printf' is different
151 from the identifier `printf', and most likely is a misspelling of it.
152 Even in languages which are not case sensitive, it is confusing to a
153 human reader to see identifiers spelled in different ways. Pick one
154 spelling and always use that. If you do not want to start a sentence
155 with a command written all in lower case, you should rearrange the
158 Do not use the `@code' command for a string of characters shorter
159 than a syntactic token. If you are writing about `TEXINPU', which is
160 just a part of the name for the `TEXINPUTS' environment variable, you
163 In particular, you should not use the `@code' command when writing
164 about the characters used in a token; do not, for example, use `@code'
165 when you are explaining what letters or printable symbols can be used
166 in the names of functions. (Use `@samp'.) Also, you should not use
167 `@code' to mark text that is considered input to programs unless the
168 input is written in a language that is like a programming language.
169 For example, you should not use `@code' for the keystroke commands of
170 GNU Emacs (use `@kbd' instead) although you may use `@code' for the
171 names of the Emacs Lisp functions that the keystroke commands invoke.
173 In the printed manual, `@code' causes TeX to typeset the argument in
174 a typewriter face. In the Info file, it causes the Info formatting
175 commands to use single quotation marks around the text.
179 Use @code{diff} to compare two files.
181 produces this in the printed manual:
183 Use `diff' to compare two files.
186 File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating
188 `@kbd'{KEYBOARD-CHARACTERS}
189 ---------------------------
191 Use the `@kbd' command for characters of input to be typed by users.
192 For example, to refer to the characters `M-a', write
196 and to refer to the characters `M-x shell', write
200 The `@kbd' command has the same effect as `@code' in Info, but by
201 default produces a different font (slanted typewriter instead of normal
202 typewriter) in the printed manual, so users can distinguish the
203 characters they are supposed to type from those the computer outputs.
205 Since the usage of `@kbd' varies from manual to manual, you can
206 control the font switching with the `@kbdinputstyle' command. This
207 command has no effect on Info output. Write this command at the
208 beginning of a line with a single word as an argument, one of the
211 Always use the same font for `@kbd' as `@code'.
214 Use the distinguishing font for `@kbd' only in `@example' and
215 similar environments.
218 (the default) Always use the distinguishing font for `@kbd'.
220 You can embed another @-command inside the braces of an `@kbd'
221 command. Here, for example, is the way to describe a command that
222 would be described more verbosely as "press an `r' and then press the
227 This produces: `r <RET>'
229 You also use the `@kbd' command if you are spelling out the letters
230 you type; for example:
232 To give the @code{logout} command,
233 type the characters @kbd{l o g o u t @key{RET}}.
237 To give the `logout' command, type the characters `l o g o u t
240 (Also, this example shows that you can add spaces for clarity. If you
241 really want to mention a space character as one of the characters of
242 input, write `@key{SPC}' for it.)
245 File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating
250 Use the `@key' command for the conventional name for a key on a
255 You can use the `@key' command within the argument of an `@kbd'
256 command when the sequence of characters to be typed includes one or
257 more keys that are described by name.
259 For example, to produce `C-x <ESC>' you would type:
263 Here is a list of the recommended names for keys:
272 Linefeed (however, since most keyboards nowadays do not have
273 a Linefeed key, it might be better to call this character
297 There are subtleties to handling words like `meta' or `ctrl' that are
298 names of modifier keys. When mentioning a character in which the
299 modifier key is used, such as `Meta-a', use the `@kbd' command alone;
300 do not use the `@key' command; but when you are referring to the
301 modifier key in isolation, use the `@key' command. For example, write
302 `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
305 File: texinfo.info, Node: samp, Next: var, Prev: key, Up: Indicating
310 Use the `@samp' command to indicate text that is a literal example or
311 `sample' of a sequence of characters in a file, string, pattern, etc.
312 Enclose the text in braces. The argument appears within single
313 quotation marks in both the Info file and the printed manual; in
314 addition, it is printed in a fixed-width font.
316 To match @samp{foo} at the end of the line,
317 use the regexp @samp{foo$}.
321 To match `foo' at the end of the line, use the regexp `foo$'.
323 Any time you are referring to single characters, you should use
324 `@samp' unless `@kbd' or `@key' is more appropriate. Use `@samp' for
325 the names of command-line options (except in an `@table', where `@code'
326 seems to read more easily). Also, you may use `@samp' for entire
327 statements in C and for entire shell commands--in this case, `@samp'
328 often looks better than `@code'. Basically, `@samp' is a catchall for
329 whatever is not covered by `@code', `@kbd', or `@key'.
331 Only include punctuation marks within braces if they are part of the
332 string you are specifying. Write punctuation marks outside the braces
333 if those punctuation marks are part of the English text that surrounds
334 the string. In the following sentence, for example, the commas and
335 period are outside of the braces:
337 In English, the vowels are @samp{a}, @samp{e},
338 @samp{i}, @samp{o}, @samp{u}, and sometimes
343 In English, the vowels are `a', `e', `i', `o', `u', and sometimes
347 File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating
349 `@var'{METASYNTACTIC-VARIABLE}
350 ------------------------------
352 Use the `@var' command to indicate metasyntactic variables. A
353 "metasyntactic variable" is something that stands for another piece of
354 text. For example, you should use a metasyntactic variable in the
355 documentation of a function to describe the arguments that are passed
358 Do not use `@var' for the names of particular variables in
359 programming languages. These are specific names from a program, so
360 `@code' is correct for them. For example, the Emacs Lisp variable
361 `texinfo-tex-command' is not a metasyntactic variable; it is properly
362 formatted using `@code'.
364 The effect of `@var' in the Info file is to change the case of the
365 argument to all upper case; in the printed manual, to italicize it.
369 To delete file @var{filename},
370 type @code{rm @var{filename}}.
374 To delete file FILENAME, type `rm FILENAME'.
376 (Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
378 Write a metasyntactic variable all in lower case without spaces, and
379 use hyphens to make it more readable. Thus, the Texinfo source for the
380 illustration of how to begin a Texinfo manual looks like this:
383 @@setfilename @var{info-file-name}
384 @@settitle @var{name-of-manual}
389 @setfilename INFO-FILE-NAME
390 @settitle NAME-OF-MANUAL
392 In some documentation styles, metasyntactic variables are shown with
393 angle brackets, for example:
395 ..., type rm <filename>
397 However, that is not the style that Texinfo uses. (You can, of course,
398 modify the sources to TeX and the Info formatting commands to output
399 the `<...>' format if you wish.)
402 File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating
407 Use the `@file' command to indicate text that is the name of a file,
408 buffer, or directory, or is the name of a node in Info. You can also
409 use the command for file name suffixes. Do not use `@file' for symbols
410 in a programming language; use `@code'.
412 Currently, `@file' is equivalent to `@samp' in its effects. For
415 The @file{.el} files are in
416 the @file{/usr/local/emacs/lisp} directory.
420 The `.el' files are in the `/usr/local/emacs/lisp' directory.
423 File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating
428 Use the `@dfn' command to identify the introductory or defining use
429 of a technical term. Use the command only in passages whose purpose is
430 to introduce a term which will be used again or which the reader ought
431 to know. Mere passing mention of a term for the first time does not
432 deserve `@dfn'. The command generates italics in the printed manual,
433 and double quotation marks in the Info file. For example:
435 Getting rid of a file is called @dfn{deleting} it.
439 Getting rid of a file is called "deleting" it.
441 As a general rule, a sentence containing the defining occurrence of a
442 term should be a definition of the term. The sentence does not need to
443 say explicitly that it is a definition, but it should contain the
444 information of a definition--it should make the meaning clear.
447 File: texinfo.info, Node: cite, Next: url, Prev: dfn, Up: Indicating
452 Use the `@cite' command for the name of a book that lacks a companion
453 Info file. The command produces italics in the printed manual, and
454 quotation marks in the Info file.
456 (If a book is written in Texinfo, it is better to use a cross
457 reference command since a reader can easily follow such a reference in
458 Info. *Note `@xref': xref.)
461 File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating
463 `@url'{UNIFORM-RESOURCE-LOCATOR}
464 --------------------------------
466 Use the `@url' to indicate a uniform resource locator on the World
467 Wide Web. This is analogous to `@file', `@var', etc., and is purely
468 for markup purposes. It does not produce a link you can follow in HTML
469 output (the `@uref' command does, *note `@uref': uref.). It is useful
470 for example URL's which do not actually exist. For example:
472 For example, the url might be
473 @url{http://host.domain.org/path}.
476 File: texinfo.info, Node: email, Prev: url, Up: Indicating
478 `@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
479 -----------------------------------------
481 Use the `@email' command to indicate an electronic mail address. It
482 takes one mandatory argument, the address, and one optional argument,
483 the text to display (the default is the address itself).
485 In Info and TeX, the address is shown in angle brackets, preceded by
486 the text to display if any. In HTML output, `@email' produces a
487 `mailto' link that usually brings up a mail composition window. For
490 Send bug reports to @email{bug-texinfo@@gnu.org}.
491 Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
494 Send bug reports to <bug-texinfo@gnu.org>.
495 Send suggestions to the same place <bug-texinfo@gnu.org>.
498 File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text
503 Usually, Texinfo changes the font to mark words in the text according
504 to what category the words belong to; an example is the `@code' command.
505 Most often, this is the best way to mark words. However, sometimes you
506 will want to emphasize text without indicating a category. Texinfo has
507 two commands to do this. Also, Texinfo has several commands that
508 specify the font in which TeX will typeset text. These commands have
509 no affect on Info and only one of them, the `@r' command, has any
514 * emph & strong:: How to emphasize text in Texinfo.
515 * Smallcaps:: How to use the small caps font.
516 * Fonts:: Various font commands for printed output.
517 * Customized Highlighting:: How to define highlighting commands.
520 File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis
522 `@emph'{TEXT} and `@strong'{TEXT}
523 ---------------------------------
525 The `@emph' and `@strong' commands are for emphasis; `@strong' is
526 stronger. In printed output, `@emph' produces _italics_ and `@strong'
532 @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
533 files in the directory.
538 *Caution*: `rm * .[^.]*' removes *all*
539 files in the directory.
541 The `@strong' command is seldom used except to mark what is, in
542 effect, a typographical element, such as the word `Caution' in the
545 In the Info file, both `@emph' and `@strong' put asterisks around the
548 *Caution:* Do not use `@emph' or `@strong' with the word `Note';
549 Info will mistake the combination for a cross reference. Use a
550 phrase such as *Please note* or *Caution* instead.
553 File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis
555 `@sc'{TEXT}: The Small Caps Font
556 --------------------------------
558 Use the `@sc' command to set text in the printed output in a small
559 caps font and set text in the Info file in upper case letters.
561 Write the text between braces in lower case, like this:
563 The @sc{acm} and @sc{ieee} are technical societies.
567 The ACM and IEEE are technical societies.
569 TeX typesets the small caps font in a manner that prevents the
570 letters from `jumping out at you on the page'. This makes small caps
571 text easier to read than text in all upper case. The Info formatting
572 commands set all small caps text in upper case.
574 If the text between the braces of an `@sc' command is upper case, TeX
575 typesets in full-size capitals. Use full-size capitals sparingly.
577 You may also use the small caps font for a jargon word such as ATO (a
578 NASA word meaning `abort to orbit').
580 There are subtleties to using the small caps font with a jargon word
581 such as CDR, a word used in Lisp programming. In this case, you should
582 use the small caps font when the word refers to the second and
583 subsequent elements of a list (the CDR of the list), but you should use
584 `@code' when the word refers to the Lisp function of the same spelling.
587 File: texinfo.info, Node: Fonts, Next: Customized Highlighting, Prev: Smallcaps, Up: Emphasis
589 Fonts for Printing, Not Info
590 ----------------------------
592 Texinfo provides four font commands that specify font changes in the
593 printed manual but have no effect in the Info file. `@i' requests
594 italic font (in some versions of TeX, a slanted font is used), `@b'
595 requests bold face, `@t' requests the fixed-width, typewriter-style
596 font used by `@code', and `@r' requests a roman font, which is the
597 usual font in which text is printed. All four commands apply to an
598 argument that follows, surrounded by braces.
600 Only the `@r' command has much use: in example programs, you can use
601 the `@r' command to convert code comments from the fixed-width font to
602 a roman font. This looks better in printed output.
607 (+ 2 2) ; @r{Add two plus two.}
612 (+ 2 2) ; Add two plus two.
614 If possible, you should avoid using the other three font commands. If
615 you need to use one, it probably indicates a gap in the Texinfo
619 File: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis
621 Customized Highlighting
622 -----------------------
624 You can use regular TeX commands inside of `@iftex' ... `@end iftex'
625 to create your own customized highlighting commands for Texinfo. The
626 easiest way to do this is to equate your customized commands with
627 pre-existing commands, such as those for italics. Such new commands
630 You can use the `@definfoenclose' command inside of `@ifinfo' ...
631 `@end ifinfo' to define commands for Info with the same names as new
632 commands for TeX. `@definfoenclose' creates new commands for Info that
633 mark text by enclosing it in strings that precede and follow the text.
634 (1) (*note Customized Highlighting-Footnote-1::)
636 Here is how to create a new @-command called `@phoo' that causes TeX
637 to typeset its argument in italics and causes Info to display the
638 argument between `//' and `\\'.
640 For TeX, write the following to equate the `@phoo' command with the
641 existing `@i' italics command:
647 This defines `@phoo' as a command that causes TeX to typeset the
648 argument to `@phoo' in italics. `@global@let' tells TeX to equate the
649 next argument with the argument that follows the equals sign.
651 For Info, write the following to tell the Info formatters to enclose
652 the argument between `//' and `\\':
655 @definfoenclose phoo, //, \\
658 Write the `@definfoenclose' command on a line and follow it with three
659 arguments separated by commas (commas are used as separators in an
660 `@node' line in the same way).
662 * The first argument to `@definfoenclose' is the @-command name
665 * the second argument is the Info start delimiter string; and,
667 * the third argument is the Info end delimiter string.
669 The latter two arguments enclose the highlighted text in the Info file.
670 A delimiter string may contain spaces. Neither the start nor end
671 delimiter is required. However, if you do not provide a start
672 delimiter, you must follow the command name with two commas in a row;
673 otherwise, the Info formatting commands will misinterpret the end
674 delimiter string as a start delimiter string.
676 After you have defined `@phoo' both for TeX and for Info, you can
677 then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
678 italics in printed output.
680 Note that each definition applies to its own formatter: one for TeX,
683 Here is another example:
686 @definfoenclose headword, , :
689 @global@let@headword=@b
692 This defines `@headword' as an Info formatting command that inserts
693 nothing before and a colon after the argument and as a TeX formatting
694 command to typeset its argument in bold.
697 File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting
699 (1) Currently, `@definfoenclose' works only with
700 `texinfo-format-buffer' and `texinfo-format-region', not with
704 File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top
706 Quotations and Examples
707 ***********************
709 Quotations and examples are blocks of text consisting of one or more
710 whole paragraphs that are set off from the bulk of the text and treated
711 differently. They are usually indented.
713 In Texinfo, you always begin a quotation or example by writing an
714 @-command at the beginning of a line by itself, and end it by writing
715 an `@end' command that is also at the beginning of a line by itself.
716 For instance, you begin an example by writing `@example' by itself at
717 the beginning of a line and end the example by writing `@end example'
718 on a line by itself, at the beginning of that line.
722 * Block Enclosing Commands:: Use different constructs for
724 * quotation:: How to write a quotation.
725 * example:: How to write an example in a fixed-width font.
726 * noindent:: How to prevent paragraph indentation.
727 * Lisp Example:: How to illustrate Lisp code.
728 * smallexample & smalllisp:: Forms for the `@smallbook' option.
729 * display:: How to write an example in the current font.
730 * format:: How to write an example that does not narrow
732 * exdent:: How to undo the indentation of a line.
733 * flushleft & flushright:: How to push text flushleft or flushright.
734 * cartouche:: How to draw cartouches around examples.
737 File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples
739 The Block Enclosing Commands
740 ============================
742 Here are commands for quotations and examples:
745 Indicate text that is quoted. The text is filled, indented, and
746 printed in a roman font by default.
749 Illustrate code, commands, and the like. The text is printed in a
750 fixed-width font, and indented but not filled.
753 Illustrate Lisp code. The text is printed in a fixed-width font,
754 and indented but not filled.
757 Illustrate code, commands, and the like. Similar to `@example',
758 except that in TeX this command typesets text in a smaller font
759 for the smaller `@smallbook' format than for the 8.5 by 11 inch
763 Illustrate Lisp code. Similar to `@lisp', except that in TeX this
764 command typesets text in a smaller font for the smaller
765 `@smallbook' format than for the 8.5 by 11 inch format.
768 Display illustrative text. The text is indented but not filled,
769 and no font is specified (so, by default, the font is roman).
772 Print illustrative text. The text is not indented and not filled
773 and no font is specified (so, by default, the font is roman).
775 The `@exdent' command is used within the above constructs to undo the
776 indentation of a line.
778 The `@flushleft' and `@flushright' commands are used to line up the
779 left or right margins of unfilled text.
781 The `@noindent' command may be used after one of the above constructs
782 to prevent the following text from being indented as a new paragraph.
784 You can use the `@cartouche' command within one of the above
785 constructs to highlight the example or quotation by drawing a box with
786 rounded corners around it. (The `@cartouche' command affects only the
787 printed manual; it has no effect in the Info file; see *Note Drawing
788 Cartouches Around Examples: cartouche.)
791 File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples
796 The text of a quotation is processed normally except that:
798 * the margins are closer to the center of the page, so the whole of
799 the quotation is indented;
801 * the first lines of paragraphs are indented no more than other
804 * in the printed output, interparagraph spacing is reduced.
806 This is an example of text written between an `@quotation' command
807 and an `@end quotation' command. An `@quotation' command is most
808 often used to indicate text that is excerpted from another (real
809 or hypothetical) printed work.
811 Write an `@quotation' command as text on a line by itself. This line
812 will disappear from the output. Mark the end of the quotation with a
813 line beginning with and containing only `@end quotation'. The `@end
814 quotation' line will likewise disappear from the output. Thus, the
827 File: texinfo.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples
832 The `@example' command is used to indicate an example that is not
833 part of the running text, such as computer input or output.
835 This is an example of text written between an
837 and an `@end example' command.
838 The text is indented but not filled.
840 In the printed manual, the text is typeset in a
841 fixed-width font, and extra spaces and blank lines are
842 significant. In the Info file, an analogous result is
843 obtained by indenting each line with five spaces.
845 Write an `@example' command at the beginning of a line by itself.
846 This line will disappear from the output. Mark the end of the example
847 with an `@end example' command, also written at the beginning of a line
848 by itself. The `@end example' will disappear from the output.
860 Since the lines containing `@example' and `@end example' will
861 disappear, you should put a blank line before the `@example' and
862 another blank line after the `@end example'. (Remember that blank
863 lines between the beginning `@example' and the ending `@end example'
864 will appear in the output.)
866 *Caution:* Do not use tabs in the lines of an example (or anywhere
867 else in Texinfo, for that matter)! TeX treats tabs as single
868 spaces, and that is not what they look like. This is a problem
869 with TeX. (If necessary, in Emacs, you can use `M-x untabify' to
870 convert tabs in a region to multiple spaces.)
872 Examples are often, logically speaking, "in the middle" of a
873 paragraph, and the text continues after an example should not be
874 indented. The `@noindent' command prevents a piece of text from being
875 indented as if it were a new paragraph. (*Note noindent::.)
877 (The `@code' command is used for examples of code that are embedded
878 within sentences, not set off from preceding and following text. *Note
882 File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples
887 An example or other inclusion can break a paragraph into segments.
888 Ordinarily, the formatters indent text that follows an example as a new
889 paragraph. However, you can prevent this by writing `@noindent' at the
890 beginning of a line by itself preceding the continuation text.
899 This line is not indented. As you can see, the
900 beginning of the line is fully flush left with the line
901 that follows after it. (This whole example is between
902 @code{@@display} and @code{@@end display}.)
909 This line is not indented. As you can see, the
910 beginning of the line is fully flush left with the line
911 that follows after it. (This whole example is between
912 `@display' and `@end display'.)
914 To adjust the number of blank lines properly in the Info file output,
915 remember that the line containing `@noindent' does not generate a blank
916 line, and neither does the `@end example' line.
918 In the Texinfo source file for this manual, each line that says
919 `produces' is preceded by a line containing `@noindent'.
921 Do not put braces after an `@noindent' command; they are not
922 necessary, since `@noindent' is a command used outside of paragraphs
923 (*note Command Syntax::).
926 File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples
931 The `@lisp' command is used for Lisp code. It is synonymous with the
934 This is an example of text written between an
935 `@lisp' command and an `@end lisp' command.
937 Use `@lisp' instead of `@example' to preserve information regarding
938 the nature of the example. This is useful, for example, if you write a
939 function that evaluates only and all the Lisp code in a Texinfo file.
940 Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
941 Example-Footnote-1::)
943 Mark the end of `@lisp' with `@end lisp' on a line by itself.
946 File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example
948 (1) It would be straightforward to extend Texinfo to work in a
949 similar fashion for C, Fortran, or other languages.
952 File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples
954 `@smallexample' and `@smalllisp'
955 ================================
957 In addition to the regular `@example' and `@lisp' commands, Texinfo
958 has two other "example-style" commands. These are the `@smallexample'
959 and `@smalllisp' commands. Both these commands are designed for use
960 with the `@smallbook' command that causes TeX to produce a printed
961 manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
964 In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
965 a smaller font for the smaller `@smallbook' format than for the 8.5 by
966 11 inch format. Consequently, many examples containing long lines fit
967 in a narrower, `@smallbook' page without needing to be shortened. Both
968 commands typeset in the normal font size when you format for the 8.5 by
969 11 inch size; indeed, in this situation, the `@smallexample' and
970 `@smalllisp' commands are defined to be the `@example' and `@lisp'
973 In Info, the `@smallexample' and `@smalllisp' commands are equivalent
974 to the `@example' and `@lisp' commands, and work exactly the same.
976 Mark the end of `@smallexample' or `@smalllisp' with `@end
977 smallexample' or `@end smalllisp', respectively.
979 This is an example of text written between `@smallexample' and
980 `@end smallexample'. In Info and in an 8.5 by 11 inch manual,
981 this text appears in its normal size; but in a 7 by 9.25 inch manual,
982 this text appears in a smaller font.
984 The `@smallexample' and `@smalllisp' commands make it easier to
985 prepare smaller format manuals without forcing you to edit examples by
986 hand to fit them onto narrower pages.
988 As a general rule, a printed document looks better if you write all
989 the examples in a chapter consistently in `@example' or in
990 `@smallexample'. Only occasionally should you mix the two formats.
992 *Note Printing "Small" Books: smallbook, for more information about
993 the `@smallbook' command.
996 File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples
1001 The `@display' command begins a kind of example. It is like the
1002 `@example' command except that, in a printed manual, `@display' does
1003 not select the fixed-width font. In fact, it does not specify the font
1004 at all, so that the text appears in the same font it would have
1005 appeared in without the `@display' command.
1007 This is an example of text written between an `@display' command
1008 and an `@end display' command. The `@display' command
1009 indents the text, but does not fill it.
1012 File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples
1017 The `@format' command is similar to `@example' except that, in the
1018 printed manual, `@format' does not select the fixed-width font and does
1019 not narrow the margins.
1021 This is an example of text written between an `@format' command
1022 and an `@end format' command. As you can see
1024 the `@format' command does not fill the text.
1027 File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples
1029 `@exdent': Undoing a Line's Indentation
1030 =======================================
1032 The `@exdent' command removes any indentation a line might have. The
1033 command is written at the beginning of a line and applies only to the
1034 text that follows the command that is on the same line. Do not use
1035 braces around the text. In a printed manual, the text on an `@exdent'
1036 line is printed in the roman font.
1038 `@exdent' is usually used within examples. Thus,
1041 This line follows an @@example command.
1042 @exdent This line is exdented.
1043 This line follows the exdented line.
1044 The @@end example comes on the next line.
1049 This line follows an @example command.
1050 This line is exdented.
1051 This line follows the exdented line.
1052 The @end example comes on the next line.
1054 In practice, the `@exdent' command is rarely used. Usually, you
1055 un-indent text by ending the example and returning the page to its
1059 File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples
1061 `@flushleft' and `@flushright'
1062 ==============================
1064 The `@flushleft' and `@flushright' commands line up the ends of lines
1065 on the left and right margins of a page, but do not fill the text. The
1066 commands are written on lines of their own, without braces. The
1067 `@flushleft' and `@flushright' commands are ended by `@end flushleft'
1068 and `@end flushright' commands on lines of their own.
1082 `@flushright' produces the type of indentation often used in the
1083 return address of letters. For example,
1086 Here is an example of text written
1087 flushright. The @code{@flushright} command
1088 right justifies every line but leaves the
1094 Here is an example of text written
1095 flushright. The `@flushright' command
1096 right justifies every line but leaves the
1100 File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
1102 Drawing Cartouches Around Examples
1103 ==================================
1105 In a printed manual, the `@cartouche' command draws a box with
1106 rounded corners around its contents. You can use this command to
1107 further highlight an example or quotation. For instance, you could
1108 write a manual in which one type of example is surrounded by a cartouche
1111 The `@cartouche' command affects only the printed manual; it has no
1112 effect in the Info file.
1119 /usr/local/share/emacs
1123 surrounds the two-line example with a box with rounded corners, in the
1127 File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
1132 Texinfo has several ways of making lists and tables. Lists can be
1133 bulleted or numbered; two-column tables can highlight the items in the
1134 first column; multi-column tables are also supported.
1138 * Introducing Lists:: Texinfo formats lists for you.
1139 * itemize:: How to construct a simple list.
1140 * enumerate:: How to construct a numbered list.
1141 * Two-column Tables:: How to construct a two-column table.
1142 * Multi-column Tables:: How to construct generalized tables.
1145 File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
1150 Texinfo automatically indents the text in lists or tables, and numbers
1151 an enumerated list. This last feature is useful if you modify the
1152 list, since you do not need to renumber it yourself.
1154 Numbered lists and tables begin with the appropriate @-command at the
1155 beginning of a line, and end with the corresponding `@end' command on a
1156 line by itself. The table and itemized-list commands also require that
1157 you write formatting information on the same line as the beginning
1160 Begin an enumerated list, for example, with an `@enumerate' command
1161 and end the list with an `@end enumerate' command. Begin an itemized
1162 list with an `@itemize' command, followed on the same line by a
1163 formatting command such as `@bullet', and end the list with an `@end
1166 Precede each element of a list with an `@item' or `@itemx' command.
1169 Here is an itemized list of the different kinds of table and lists:
1171 * Itemized lists with and without bullets.
1173 * Enumerated lists, using numbers or letters.
1175 * Two-column tables with highlighting.
1178 Here is an enumerated list with the same items:
1180 1. Itemized lists with and without bullets.
1182 2. Enumerated lists, using numbers or letters.
1184 3. Two-column tables with highlighting.
1187 And here is a two-column table with the same items and their @-commands:
1190 Itemized lists with and without bullets.
1193 Enumerated lists, using numbers or letters.
1198 Two-column tables with indexing.
1201 File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
1203 Making an Itemized List
1204 =======================
1206 The `@itemize' command produces sequences of indented paragraphs,
1207 with a bullet or other mark inside the left margin at the beginning of
1208 each paragraph for which such a mark is desired.
1210 Begin an itemized list by writing `@itemize' at the beginning of a
1211 line. Follow the command, on the same line, with a character or a
1212 Texinfo command that generates a mark. Usually, you will write
1213 `@bullet' after `@itemize', but you can use `@minus', or any character
1214 or any special symbol that results in a single character in the Info
1215 file. (When you write `@bullet' or `@minus' after an `@itemize'
1216 command, you may omit the `{}'.)
1218 Write the text of the indented paragraphs themselves after the
1219 `@itemize', up to another line that says `@end itemize'.
1221 Before each paragraph for which a mark in the margin is desired, write
1222 a line that says just `@item'. Do not write any other text on this
1225 Usually, you should put a blank line before an `@item'. This puts a
1226 blank line in the Info file. (TeX inserts the proper interline
1227 whitespace in either case.) Except when the entries are very brief,
1228 these blank lines make the list look better.
1230 Here is an example of the use of `@itemize', followed by the output
1231 it produces. Note that `@bullet' produces an `*' in Info and a round
1245 * Some text for foo.
1247 * Some text for bar.
1249 Itemized lists may be embedded within other itemized lists. Here is a
1250 list marked with dashes embedded in a list marked with bullets:
1274 - Second inner item.
1276 * Second outer item.
1279 File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
1281 Making a Numbered or Lettered List
1282 ==================================
1284 `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
1285 that the labels on the items are successive integers or letters instead
1288 Write the `@enumerate' command at the beginning of a line. The
1289 command does not require an argument, but accepts either a number or a
1290 letter as an option. Without an argument, `@enumerate' starts the list
1291 with the number `1'. With a numeric argument, such as `3', the command
1292 starts the list with that number. With an upper or lower case letter,
1293 such as `a' or `A', the command starts the list with that letter.
1295 Write the text of the enumerated list in the same way you write an
1296 itemized list: put `@item' on a line of its own before the start of
1297 each paragraph that you want enumerated. Do not write any other text
1298 on the line beginning with `@item'.
1300 You should put a blank line between entries in the list. This
1301 generally makes it easier to read the Info file.
1303 Here is an example of `@enumerate' without an argument:
1315 1. Underlying causes.
1317 2. Proximate causes.
1321 Here is an example with an argument of `3':
1326 Predisposing causes.
1329 Precipitating causes.
1332 Perpetuating causes.
1337 3. Predisposing causes.
1339 4. Precipitating causes.
1341 5. Perpetuating causes.
1345 Here is a brief summary of the alternatives. The summary is
1346 constructed using `@enumerate' with an argument of `a'.
1351 Without an argument, produce a numbered list, starting with the
1354 b. `@enumerate POSITIVE-INTEGER'
1356 With a (positive) numeric argument, start a numbered list with that
1357 number. You can use this to continue a list that you interrupted
1360 c. `@enumerate UPPER-CASE-LETTER'
1362 With an upper case letter as argument, start a list in which each
1363 item is marked by a letter, beginning with that upper case letter.
1365 d. `@enumerate LOWER-CASE-LETTER'
1367 With a lower case letter as argument, start a list in which each
1368 item is marked by a letter, beginning with that lower case letter.
1370 You can also nest enumerated lists, as in an outline.
1373 File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
1375 Making a Two-column Table
1376 =========================
1378 `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
1379 allows you to specify a name or heading line for each item. The
1380 `@table' command is used to produce two-column tables, and is
1381 especially useful for glossaries, explanatory exhibits, and
1382 command-line option summaries.
1386 * table:: How to construct a two-column table.
1387 * ftable vtable:: Automatic indexing for two-column tables.
1388 * itemx:: How to put more entries in the first column.
1391 File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
1393 Using the `@table' Command
1394 --------------------------
1396 Use the `@table' command to produce two-column tables.
1398 Write the `@table' command at the beginning of a line and follow it
1399 on the same line with an argument that is a Texinfo "indicating"
1400 command such as `@code', `@samp', `@var', or `@kbd' (*note
1401 Indicating::). Although these commands are usually followed by
1402 arguments in braces, in this case you use the command name without an
1403 argument because `@item' will supply the argument. This command will
1404 be applied to the text that goes into the first column of each item and
1405 determines how it will be highlighted. For example, `@code' will cause
1406 the text in the first column to be highlighted with an `@code' command.
1407 (We recommend `@code' for `@table''s of command-line options.)
1409 You may also choose to use the `@asis' command as an argument to
1410 `@table'. `@asis' is a command that does nothing; if you use this
1411 command after `@table', TeX and the Info formatting commands output the
1412 first column entries without added highlighting ("as is").
1414 (The `@table' command may work with other commands besides those
1415 listed here. However, you can only use commands that normally take
1416 arguments in braces.)
1418 Begin each table entry with an `@item' command at the beginning of a
1419 line. Write the first column text on the same line as the `@item'
1420 command. Write the second column text on the line following the
1421 `@item' line and on subsequent lines. (You do not need to type
1422 anything for an empty second column entry.) You may write as many
1423 lines of supporting text as you wish, even several paragraphs. But
1424 only text on the same line as the `@item' will be placed in the first
1427 Normally, you should put a blank line before an `@item' line. This
1428 puts a blank like in the Info file. Except when the entries are very
1429 brief, a blank line looks better.
1431 The following table, for example, highlights the text in the first
1432 column with an `@samp' command:
1436 This is the text for
1440 Text for @samp{bar}.
1446 This is the text for `foo'.
1451 If you want to list two or more named items with a single block of
1452 text, use the `@itemx' command. (*Note `@itemx': itemx.)