This is Info file texinfo.info, produced by Makeinfo-1.43 from the input file texinfo2.texi. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. This is edition 2.14 of the Texinfo documentation, 14 February 1992, for Texinfo version 2. Copyright (C) 1988, 1990, 1991, 1992 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: texinfo.info, Node: Other Info Files, Next: Invocation, Prev: menu, Up: Nodes & Menus Referring to Other Info Files ============================= You can refer to nodes in other Info files by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu item format, which saves the reader from having to type the file name. If you do not list the node name, but only name the file, then Info presumes that you are referring to the `Top' node. The format looks like this: @menu * FIRST-ITEM:(FILENAME)NODENAME. DESCRIPTION * SECOND-ITEM:(FILENAME)SECOND-NODE. DESCRIPTION @end menu The `dir' top level directory for the Info system has menu entries that take you directly to the `Top' nodes of each Info document. (*Note Installing an Info File::.) For example, ... * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. ... To refer directly to the `Outlining' and `Rebinding' nodes in the `Emacs Manual', you would write a menu similar to the following: @menu * Outlining: (emacs)Outline Mode. The major mode for editing outlines. * Rebinding: (emacs)Rebinding. How to redefine the meaning of a key. @end menu  File: texinfo.info, Node: Invocation, Prev: Other Info Files, Up: Nodes & Menus Describing Command Invocation ============================= Documents that describe programs such as Emacs, GCC, and GAWK that are invoked from a shell each contain a section that describes the command line arguments. Unfortunately, the node names and titles for these sections are all different! This makes it hard to search for the section. We suggest adopting the convention of naming such sections with a phrase beginning with the word `Invoking ...', as in `Invoking Emacs'; this way users can find the section easily.  File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Nodes & Menus, Up: Top Making Cross References *********************** Cross references are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes are the points to which cross references can refer. * Menu: * References:: What cross references are for. * Cross Reference Commands:: A summary of the different commands. * Cross Reference Parts:: A cross reference has several parts. * xref:: Begin a reference with `See' ... * Top Node Naming:: Naming a `Top' Node * ref:: A reference for the last part of a sentence. * pxref:: How to write a parenthetical cross reference. * inforef:: How to refer to an Info-only file.  File: texinfo.info, Node: References, Next: Cross Reference Commands, Prev: Cross References, Up: Cross References What References Are For ======================= Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth to find information that should be presented to them as they need it. However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to provide access to such information. Also, an on-line help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross references to help readers find other information that they may not have read. In a printed manual, a cross reference creates a page reference, unless it is to another manual altogether, in which case it names that manual. In Info, a cross reference creates an entry that you can follow using the Info `f' command. (*note Some advanced Info commands: (info)Help-Adv.) The various cross reference commands use nodes to define cross reference locations. This is evident in Info, in which a cross reference takes you to the specified node. TeX also uses nodes to define cross reference locations, but the action is less obvious. When TeX generates a DVI file, it records nodes' page numbers and uses the page numbers in making references. Thus, if you are writing a manual that will only be printed, and will not be used on-line, you must nonetheless write `@node' lines to name the places to which you make cross references.  File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References Different Cross Reference Commands ================================== There are several different cross reference commands: `@xref' Used to start a sentence in the printed manual saying `See ...' or an entry in the Info file saying `*Note ...'. `@ref' Used within or, more often, at the end of a sentence; produces just the reference in the printed manual without a preceding `See'. `@pxref' Used within parentheses to make a reference that starts with a lower case `see' within the printed manual. (`p' is for `parenthesis'.) `@inforef' Used to make a reference to an Info file for which there is no printed manual. (The `@cite' command is used to make references to books and manuals for which there is no corresponding Info file and, therefore, no node to which to point. *Note `@cite': cite.)  File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References Parts of a Cross Reference ========================== A cross reference command requires only one argument, which is the name of the node to which it refers. But a cross reference command may contain up to four additional arguments. By using these arguments, you can provide a menu item name for Info, a descriptive phrase for the printed output, the name of a different Info file, and the name of a different printed manual. Here is a simple cross reference example: @xref{Node name}. which produces *Note Node name::. and See section NNN [Node name], page PPP. Here, however, is an example of a full five-part cross reference: @xref{Node name, Item name, Topic, info-file-name, A Printed Manual}, for details. which produces *Note Item name: (info-file-name)Node name, for details. and See section Topic of A Printed Manual, for details. The five arguments for a cross reference are: 1. The node name (required). This is the node to which the cross reference takes you. In a printed document, the location of the node provides the page reference (for references within the same document). 2. The item name for the Info reference, if it is to be different from the node name. It is usually omitted. 3. A topic description or section name. Often, this is the title of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used. 4. The name of the Info file in which the reference is located, if it is different from the current file. 5. The name of another printed manual. Cross references with one, two, three, four, and five arguments are described separately following the description of `@xref'. Write a node name in a cross reference in exactly the same way as in the node line, including the same capitalization; otherwise, the formatters may not find the reference. You can write cross reference commands within a paragraph, but note how Info and TeX format the output of each of the various commands: write `@xref' at the beginning of a sentence; write `@pxref' only within parentheses, and so on.  File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References `@xref' ======= The `@xref' command generates a cross reference for the beginning of a sentence. The Info formatting commands convert it into an Info cross reference, which the Info `f' command can use to bring you directly to another node. The TeX typesetting commands convert it into a page reference, or a reference to another book or manual. * Menu: * Reference Syntax:: What a reference looks like and requires. * One Argument:: `@xref' with one argument. * Two Arguments:: `@xref' with two arguments. * Three Arguments:: `@xref' with three arguments. * Four and Five Arguments:: `@xref' with Four and Five Arguments  File: texinfo.info, Node: Reference Syntax, Next: One Argument, Prev: xref, Up: xref What a Reference Looks Like and Requires ---------------------------------------- Most often, an Info cross reference looks like this: *Note NODE-NAME::. or like this *Note ITEM-NAME: NODE-NAME. In TeX, a cross reference looks like this: See section SECTION [NODE-NAME], page PAGE or like this See section SECTION [TOPIC], page PAGE The `@xref' command does not generate a period or comma to end the cross reference in either the Info file or the printed output. You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The `@pxref' command works differently. *Note `@pxref': pxref.) *Please note:* A period or comma *must* follow the closing brace of an `@xref'. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual. `@xref' must refer to an Info node by name. Use `@node' to define the node (*note Writing a Node::.). `@xref' is followed by several arguments inside braces, separated by commas. Whitespace before and after these commas is ignored. A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different.  File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref `@xref' with One Argument ------------------------- The simplest form of `@xref' takes one argument, the name of another node in the same Info file. For example, @xref{Tropical Storms}. produces *Note Tropical Storms::. and See section NNN [Tropical Storms], page PPP. (Note that in the preceding example the closing brace is followed by a period.) You can write a clause after the cross reference, like this: @xref{Tropical Storms}, for more info. which produces: *Note Tropical Storms::, for more info. See section NNN [Tropical Storms], page PPP, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause.)  File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref `@xref' with Two Arguments -------------------------- With two arguments, the second one is used as the name of the Info cross reference, while the first argument is still the node that the cross reference points to: The template is like this: @xref NODE-NAME, ITEM-NAME. For example: @xref{Electrical Effects, Lightning}. which produces: *Note Lightning: Electrical Effects. and See section NNN [Electrical Effects], page PPP. (Note that in the preceding example the closing brace is followed by a period; and that the node name is printed, not the item name.) You can write a clause after the cross reference, like this: @xref{Electrical Effects, Lightning}, for more info. produces *Note Lightning: Electrical Effects, for more info. and See section NNN [Electrical Effects], page PPP, for more info. (Note that in the preceding example the closing brace is followed by a comma, and then by the clause.)  File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref `@xref' with Three Arguments ---------------------------- A third argument replaces the node name in the TeX output. The third argument should state the topic discussed by the section being referenced, or be the name of the section. Often, you will want to use initial upper case letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning. Remember that a comma or period must follow the closing brace of an `@xref' command to terminate the cross reference. In the following examples, a clause follows a terminating comma. The template is like this: @xref NODE-NAME, ITEM-NAME, TOPIC. For example, @xref{Electrical Effects, Lightning, Thunder and Lightning}, for details. which produces *Note Lightning: Electrical Effects, for details. and See section NNN [Thunder and Lightning], page PPP, for details. If a third argument is given and the second one is empty, then the third argument serves both. (Note how two commas, side by side, mark the empty second argument.) @xref{Electrical Effects, , Thunder and Lightning}, for details. produces *Note Thunder and Lightning: Electrical Effects, for details. and See section NNN [Thunder and Lightning], page PPP, for details.  File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref `@xref' with Four and Five Arguments ------------------------------------ In a cross reference, a fourth argument specifies the name of another Info file, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual. Remember that a comma or period must follow the closing brace of an `@xref' command to terminate the cross reference. In the following examples, a clause follows a terminating comma. The template is: @xref{NODE-NAME, ITEM-NAME, TOPIC, INFO-FILE-NAME, PRINTED-TITLE}. For example, @xref{Electrical Effects, Lightning, Thunder and Lightning, weather, An Introduction to Meteorology}, for details. which produces *Note Lightning: (weather)Electrical Effects, for details. The name of the Info file is enclosed in parentheses and precedes the name of the node. In a printed manual, the reference looks like this: See section Thunder and Lightning of An Introduction to Meteorology, for details. The name of the printed manual is typeset in italics; and the reference lacks a page number since TeX cannot know to which page a refer refers when the reference is to another manual. Often, you will leave out the second argument when you use the long version of `@xref'. In this case, the third argument, the topic description, will be used as the item name in Info. The template looks like this: @xref{NODE-NAME, , TOPIC, INFO-FILE-NAME, PRINTED-TITLE}, for details. which produces *Note TOPIC: (INFO-FILE-NAME)NODE-NAME, for details. and See section TOPIC of PRINTED-MANUAL-TITLE, for details. For example: @xref{Electrical Effects, , Thunder and Lightning, weather, An Introduction to Meteorology}, for details. which produces *Note Thunder and Lightning: (weather)Electrical Effects, for details. and See section Thunder and Lightning of An Introduction to Meteorology, for details. On rare occasions, you may want to refer to another Info file that is within a single printed manual--when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth.  File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References Naming a `Top' Node =================== In a cross reference, you must always name a node. This means that in order to refer to a whole manual, you must identify the `Top' node by writing it as the first argument to the `@xref' command. (This is different from the way you write a menu entry. *Note Referring to Other Info Files: Other Info Files.) At the same time, to provide a meaningful section topic or title in the printed cross reference (instead of the word `Top'), you must write an appropriate entry for the third argument to the `@xref' command. Thus, to make a cross reference to `The GNU Make Manual', write: @xref{Top, , Overview, make, The GNU Make Manual}. which produces *Note Overview: (make)Top. and See section Overview of The GNU Make Manual. In this example, `Top' is the name of the node, and `Overview' is the name of the first section of the manual.  File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References `@ref' ====== `@ref' is nearly the same as `@xref' except that it does not generate a `See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence. For example: For more information, see @ref{Orogenesis, , Mountain Building}. produces For more information, see *Note Mountain Building: Orogenesis. and For more information, see section NNN [Mountain Building]. page PPP. The `@ref' command sometimes leads writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience will be using both the printed and the Info format. For example, Sea surges are described in @ref{Hurricanes}. produces Sea surges are described in section NNN [Hurricanes]. in a printed document, but Sea surges are described in *Note Hurricanes::. in Info. *Caution:* You *must* write a period or comma immediately after an `@ref' command with two or more arguments. Otherwise, Info will not find the end of the cross reference entry and attempts to follow the cross reference will fail. As a general rule, you should write a period or comma after every `@ref' command. This looks best in both the printed and the Info output.  File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References `@pxref' ======== The parenthetical reference command, `@pxref', is nearly the same as `@xref', but you use it *only* inside parentheses and you do *not* type a comma or period after the command's closing brace. The command differs from `@xref' in two ways: 1. TeX typesets the reference for the printed manual with a lower case `see' rather than an upper case `See'. 2. The Info formatting commands automatically end the reference with a closing colon or period. Because one type of formatting automatically inserts closing punctuation and the other does not, you should use `@pxref' *only* inside parentheses as part of another sentence. Also, you yourself should not insert punctuation after the reference, as you do with `@xref'. `@pxref' is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. In a printed manual, a closing comma or period should not follow a cross reference within parentheses; such punctuation is wrong. But in an Info file, suitable closing punctuation must follow the cross reference so Info can recognize its end. `@pxref' spares you the need to use complicated methods to put a terminator into one form of the output and not the other. Don't try to use `@pxref' as a clause in a sentence. It will look bad in either the Info file, the printed output, or both. Use it only as a parenthetical reference. With one argument, a parenthetical cross reference looks like this: ... large storms (@pxref{Hurricanes}) may cause flooding ... which produces ... large storms (*Note Hurricanes::) may cause flooding ... and ... large storms (see section NNN [Hurricanes], page PPP) may cause flooding ... With two arguments, a parenthetical cross reference has this template: ... (@pxref{NODE-NAME, ITEM-NAME}) ... which produces ... (*Note ITEM-NAME: NODE-NAME.) ... and ... (see section NNN [NODE-NAME], page PPP) ... `@pxref' can be used with up to five arguments just like `@xref' (*note `@xref': xref.).  File: texinfo.info, Node: inforef, Prev: pxref, Up: Cross References `@inforef' ========== `@inforef' is used for cross references to Info files for which there are no printed manuals. Even in a printed manual, `@inforef' generates a reference directing the user to look in an Info file. The command takes either two or three arguments, in the following order: 1. The node name. 2. The item name (optional). 3. The Info file name. Separate the arguments with commas, as with `@xref'. Also, you must terminate the reference with a comma or period after the `}', as you do with `@xref'. The template is: @inforef{NODE-NAME, ITEM-NAME, INFO-FILE-NAME}, Thus, @inforef{Expert, Advanced Info commands, info}, for more information. produces *Note Advanced Info commands: (info)Expert, for more information. and See Info file `info', node `Expert', for more information. Similarly, @inforef{Expert, , info}, for more information. produces *Note (info)Expert::, for more information. and See Info file `info', node `Expert', for more information. The converse of `@inforef' is `@cite', which is used to refer to printed works for which no Info form exists. *Note `@cite': cite.  File: texinfo.info, Node: Marking Text, Next: Insertions, Prev: Cross References, Up: Top Marking Words and Phrases ************************* In Texinfo, you can mark words and phrases in a variety of ways. These ways specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text. * Menu: * Indicating:: Indicating definitions, files, commands etc. * Emphasis:: How to emphasize text.  File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text Indicating Definitions, Commands, etc. ====================================== Texinfo has commands for indicating just what kind of object a piece of text refers to. Metasyntactic variables, for example, are marked by `@var' and code by `@code'. Texinfo uses this information to determine how to highlight the text. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way Texinfo formats such text. (Texinfo is an "intentional" formatting language rather than a "typesetting" formatting language.) For example, code is usually illustrated in a typewriter font, but it would be easy to change the way Texinfo highlights code to use another font. This change would not effect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would have to check every single occurrence to make sure that you were changing code and not something else that should not be changed. * Menu: * Useful Highlighting:: Highlighting provides useful information. * code:: How to indicate code. * kbd:: How to show keyboard input. * key:: How to specify keys. * samp:: How to show a literal sequence of characters. * var:: How to indicate a metasyntactic variable. * file:: How to indicate the name of a file. * dfn:: How to specify a definition. * cite:: How to refer to a book that is not in Info.  File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating Highlighting Commands are Useful -------------------------------- The highlighting commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries. The commands serve a variety of purposes: `@code{SAMPLE-CODE}' Indicate text that is a literal example of a piece of a program. `@kbd{KEYBOARD-CHARACTERS}' Indicate keyboard input. `@key{KEY-NAME}' Use for the conventional name for a key on a keyboard. `@samp{TEXT}' Indicate text that is a literal example of a sequence of characters. `@var{METASYNTACTIC-VARIABLE}' Indicate a metasyntactic variable. `@file{FILE-NAME}' Indicate the name of a file. `@dfn{TERM}' Use for the introductory or defining use of a term. `@cite{REFERENCE}' Indicate the name of a book.  File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating `@code'{SAMPLE-CODE} -------------------- Use the `@code' command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the text in braces. Thus, you should use `@code' for an expression in a program, for the name of a variable or function used in a program, or for a keyword. Also, you should use `@code' for the name of a program, such as `diff', that is a name used in the machine. (You should write the name of a program in the ordinary text font if you regard it as a new English word, such as `Emacs' or `Bison'.) Use `@code' for the `TEXINPUTS' environment variable and other such variables. Do not use the `@code' command for a string of characters shorter than a syntactic token. In particular, you should not use the `@code' command when writing about the characters used in a token; do not, for example, use `@code' when you are explaining what letters or printable symbols can be used in the names of functions. (Use `@samp'.) Also, you should not use `@code' to mark text that is considered input to programs unless the input is written in a language that is like a programming language. For example, you should not use `@code' for the single character commands of GNU Emacs (use `@kbd' instead) although you may use `@code' for the names of the Emacs Lisp functions that the keyboard commands invoke. Do use `@code' for command names in command languages that resemble programming languages, such as Texinfo or the shell. Note, however, that you should not use `@code' for options such as `-c' when such options stand alone. (Use `@samp'.) Also, an entire shell command often looks better if written using `@samp' rather than `@code'. It is incorrect to alter the case of a word inside an `@code' command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, `Printf' is a misspelling of `printf'. If you do not want to start a sentence with such a command written all in lower case, you should rearrange the sentence. In the printed manual, `@code' causes TeX to typeset the argument in a typewriter face. In the Info file, it causes the Info formatting commands to use `...' quotation. For example: Use @code{diff} to compare two files. produces this in the printed manual: Use `diff' to compare two files.  File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating `@kbd'{KEYBOARD-CHARACTERS} --------------------------- Use the `@kbd' command for characters of input to be typed by users. For example, to refer to the characters `M-a', write @kbd{M-a} and to refer to the characters `M-x shell', write @kbd{M-x shell} The `@kbd' command has the same effect as `@code' in Info, but may produce a different font in a printed manual. You can embed another @-command inside the braces of an `@kbd' command. Here, for example, is the way to describe a command that would be described more verbosely as "press an `r' and then press the RET key": @kbd{r @key{RET}} This produces: `r RET' You also use the `@kbd' command if you are spelling out the letters you type; for example: To give the @code{logout} command, type the characters @kbd{l o g o u t @key{RET}}. This produces To give the `logout' command, type the characters `l o g o u t RET'. (Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write `@key{SPC}' for it.)  File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating `@key'{KEY-NAME} ---------------- Use the `@key' command for the conventional name for a key on a keyboard, as in @key{RET} You can use the `@key' command within the argument of an `@kbd' command when the sequence of characters to be typed includes one or more keys that are described by name. For example, to produce `C-x ESC' you would type: @kbd{C-x @key{ESC}} The recommended names to use for keys are in upper case and are SPC Space RET Return LFD Linefeed TAB Tab BS Backspace ESC Escape DEL Delete SFT Shift CTL Control META Meta There are subtleties to handling words like `meta' or `ctl' that are names of shift keys. When mentioning a character in which the shift key is used, such as `Meta-a', use the `@kbd' command alone without the `@key' command, but when you are referring to the shift key in isolation, use the `@key' command. For example, write `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce META. This is because `Meta-a' refers to keys that you press on a keyboard, but META refers to a key without implying that you press it.  File: texinfo.info, Node: samp, Next: var, Prev: key, Up: Indicating `@samp'{TEXT} ------------- Use the `@samp' command to indicate text that is a literal example of a sequence of characters in a file, string, pattern, etc. Enclose the text in braces. The argument appears within `...' quotation in both the Info file and the printed manual; in addition, it is printed in a fixed-width font. To match @samp{foo} at the end of the line, use the regexp @samp{foo$}. produces To match `foo' at the end of the line, use the regexp `foo$'. Any time you are referring to single characters, you should use `@samp' unless `@kbd' is more appropriate. `@samp' is used for entire statements in C, for entire shell commands, and for names of command-line options. Use it for buffer names in Emacs and for node names in Info or Texinfo. Basically, `@samp' is a catchall for whatever is not covered by `@code', `@kbd', or `@key'. Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces: In English, the vowels are @samp{a}, @samp{e}, @samp{i}, @samp{o}, @samp{u}, and sometimes @samp{y}. This produces: In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.  File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating `@var'{METASYNTACTIC-VARIABLE} ------------------------------ Use the `@var' command to indicate metasyntactic variables. A metasyntactic variable is something that stands for another piece of text. For example, you should use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function. Do not use `@var' for the names of particular variables in programming languages. These are specific names from a program, so `@code' is correct for them. For example, the Lisp variable `texinfo-tex-command' is not a metasyntactic variable; it is properly formatted using `@code'. The effect of `@var' in the Info file is to upcase the argument; in the printed manual, to italicize it. For example: To delete file @var{filename}, type @code{rm @var{filename}}. produces To delete file FILENAME, type `rm FILENAME'. (Note that `@var' may appear inside `@code', `@samp', `@file', etc.) Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the illustration of how to begin a Texinfo manual looks like this: \input texinfo @setfilename INFO-FILE-NAME @settitle NAME-OF-MANUAL In some documentation styles, metasyntactic variables are shown with angle brackets, for example: ..., type rm However, that is not the style we use in Texinfo. (You can, of course, modify the sources to TeX and the Info formatting commands to output the `<...>' format if you wish.)  File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating `@file'{FILE-NAME} ------------------ Use the `@file' command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for filename suffixes. Don't use `@file' for symbols in a programming language; thus, a node name is a name in an Info file but not an identifier in a programming language. Currently, `@file' is equivalent to `@samp' in its effects on the output. For example, The @file{.el} files are in the @file{/usr/local/emacs/lisp} directory. produces The `.el' files are in the `/usr/local/emacs/lisp' directory.  File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating `@dfn'{TERM} ------------ Use the `@dfn' command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time doesn't deserve `@dfn'. The command generates italics in the printed manual, and double quotation marks in the Info file. For example: Getting rid of a file is called @dfn{deleting} it. produces Getting rid of a file is called "deleting" it. As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not have to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.  File: texinfo.info, Node: cite, Prev: dfn, Up: Indicating `@cite'{REFERENCE} ------------------ Use the `@cite' command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file. (If a book is written in Texinfo, it is better to use a cross reference command since you can easily follow such a reference in Info. *Note `@xref': xref.)  File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text Emphasizing Text ================ Usually, Texinfo changes the font to mark words in the text according to what category the words belong to. The `@code' command, for example, does this. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two ways to do this: commands that tell Texinfo to emphasize the text but leave the method to the program, and commands that specify the method to use. The first method is generally the best because it makes it possible to change the style of a document without needing to re-edit it line by line. * Menu: * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output.  File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis `@emph'{TEXT} and `@strong'{TEXT} --------------------------------- The `@emph' and `@strong' commands are for emphasis; `@strong' is stronger. In printed output, `@emph' produces *italics* and `@strong' produces *bold*. For example, @quotation @strong{Caution:} @code{rm * .[^.]*} removes @emph{all} files in the directory. @end quotation produces: *Caution*: `rm * .[^.]*' removes *all* files in the directory. The `@strong' command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example.(1) In the Info file, both `@emph' and `@strong' put asterisks around the text. ---------- Footnotes ---------- (1) Don't try to use `@emph' or `@strong' with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as *Please note* or *Caution* instead.  File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis `@sc'{TEXT}: The Small Caps Font -------------------------------- Use the `@sc' command to set text in the printed output in a small caps font and set text in the Info file in upper case letters. Write the text between braces in lower case, like this: The @sc{acm} and @sc{ieee} are technical societies. This produces: The ACM and IEEE are technical societies. TeX typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps text easier to read than text in all upper case. TeX typesets any upper case letters in the small caps fonts in full-size capitals. Use them sparingly. The Info formatting commands set all small caps text in upper case. You may also use the small caps font for a jargon word such as ATO (a NASA word meaning `abort to orbit'). There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.  File: texinfo.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis Fonts for Printing, Not Info ---------------------------- Texinfo provides four font commands that specify font changes in the printed manual but have no effect in the Info file. `@i' requests italic font (in some versions of TeX, a slanted font is used), `@b' requests bold face, `@t' requests the fixed-width font used by `@code', and `@r' requests a roman font, which is the usual font in which text is printed. All four commands apply to an argument that follows, surrounded by braces. Only the `@r' command has much use: in example programs, you can use the `@r' command to convert code comments from the fixed-width font to a roman font. This looks better in printed output. For example, @lisp (+ 2 2) ; @r{Add two plus two.} @end lisp produces (+ 2 2) ; Add two plus two. If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.  File: texinfo.info, Node: Insertions, Next: Quotations and Examples, Prev: Marking Text, Up: Top Special Insertions ****************** Texinfo provides several commands for formatting dimensions, for inserting single characters that have special meaning in Texinfo, such as braces, and for inserting special graphic symbols that do not correspond to characters, such as dots and bullets. * Menu: * Braces Atsigns Periods:: How to insert braces, `@' and periods. * dmn:: How to format a dimension. * Dots Bullets:: How to insert dots and bullets. * TeX and copyright:: How to insert the TeX logo and the copyright symbol. * minus:: How to insert a minus sign.  File: texinfo.info, Node: Braces Atsigns Periods, Next: dmn, Prev: Insertions, Up: Insertions Inserting `@', Braces, and Periods ================================== `@' and curly braces are special characters in Texinfo. To insert these characters into text, you must put an `@' in front of these characters to prevent Texinfo from misinterpreting them. Periods are also special. Depending on whether the period 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 don't have 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.) Do not put braces after any of these commands; they are not necessary. * Menu: * Inserting An Atsign:: * Inserting Braces:: Inserting `{' and `}'--@{ and @} * Controlling Spacing::  File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns Periods, Up: Braces Atsigns Periods Inserting `@'--@@ ----------------- `@@' stands for a single `@' in either printed or Info output. Do not put braces after an `@@' command.  File: texinfo.info, Node: Inserting Braces, Next: Controlling Spacing, Prev: Inserting An Atsign, Up: Braces Atsigns Periods Inserting `{' and `}'--@{ 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.  File: texinfo.info, Node: Controlling Spacing, Prev: Inserting Braces, Up: Braces Atsigns Periods Spacing After Colons and Periods -------------------------------- 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. `@:' has no effect on the Info file output. For example: The U.S.A.@: is a continental nation. produces The U.S.A. is a continental nation. Use `@.' instead of a period 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 X. and to Y@. Give it to Z@. Give it to X. and to Y. Give it to Z. produces Give it to X. and to Y. Give it to Z. Give it to X. and to Y. Give it to Z. In the Info file output, `@.' is equivalent to a simple `.'. The meanings of `@:' and `@.' in Texinfo are designed to work well with the Emacs sentence motion commands. This made it necessary for them to be incompatible with some other formatting systems that use @-commands. Do not put braces after either an `@:' or an `@.' command.  File: texinfo.info, Node: dmn, Next: Dots Bullets, Prev: Braces Atsigns Periods, Up: Insertions `@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. Instead of `8.27in', you may write `8.27 in.' or `8.27 inches'.  File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: dmn, Up: Insertions Inserting Ellipsis, Dots, and Bullets ===================================== An "ellipsis" (a line of dots) is typeset unlike 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. (For an explanation of why the braces are needed, *note @-Command Syntax: Command Syntax.). * Menu: * dots:: Inserting dots ... * bullet:: Inserting a bullet.  File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets `@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.  File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets `@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.  File: texinfo.info, Node: TeX and copyright, Next: minus, Prev: Dots Bullets, Up: Insertions Inserting TeX and the Copyright Symbol ====================================== The logo TeX is typeset in a special fashion and it needs an @-command, as does the command for inserting the copyright symbol. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces. * Menu: * tex:: Insert the TeX logo. * copyright symbol:: `@copyright'{}  File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright `@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.  File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright `@copyright'{} -------------- Use the `@copyright{}' command to generate `(C)'. In a printed manual, this is a `c' inside a circle, and in Info, this is `(C)'.  File: texinfo.info, Node: minus, Prev: TeX and copyright, Up: Insertions `@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. You can compare the two forms: `-' is a minus sign generated with `@minus{}', `-' is a hyphen generated with the character `-'. 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.  File: texinfo.info, Node: Quotations and Examples, Next: Special Glyphs, Prev: Insertions, Up: Top 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 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 at itself, at the beginning of that line. * Menu: * Block Enclosing Commands:: Use different constructs for different purposes. * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent indentation. * Lisp Example:: How to illustrate a Lisp code. * smallexample & smalllisp:: Forms for the `@smallbook' option. * display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. * exdent:: How to undo the indentation of a line. * flushleft & flushright:: `@flushleft' and `@flushright' * cartouche:: Drawing cartouches around examples.