X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=info%2Ftexinfo.info-1;h=c45b6395f0824100f835774e9675a7633c9eee27;hp=ffb02ba258c53fed653ee4eea2f64fc537281727;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=de1ec4b272dfa3f9ef2c9ae28a9ba67170d24da5;ds=sidebyside diff --git a/info/texinfo.info-1 b/info/texinfo.info-1 index ffb02ba..c45b639 100644 --- a/info/texinfo.info-1 +++ b/info/texinfo.info-1 @@ -1,4 +1,4 @@ -This is ../info/texinfo.info, produced by makeinfo version 4.0 from +This is ../info/texinfo.info, produced by makeinfo version 4.6 from texinfo.texi. INFO-DIR-SECTION Texinfo documentation system @@ -38,7 +38,7 @@ File: texinfo.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) Texinfo ******* - Texinfo is a documentation system that uses a single source file to +Texinfo is a documentation system that uses a single source file to produce both on-line information and printed output. The first part of this master menu lists the major nodes in this Info @@ -516,8 +516,8 @@ File: texinfo.info, Node: Copying, Next: Overview, Prev: Top, Up: Top Texinfo Copying Conditions ************************** - The programs currently being distributed that relate to Texinfo -include portions of GNU Emacs, plus other separate programs (including +The programs currently being distributed that relate to Texinfo include +portions of GNU Emacs, plus other separate programs (including `makeinfo', `info', `texindex', and `texinfo.tex'). These programs are "free"; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo-related programs are @@ -556,7 +556,7 @@ File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: T Overview of Texinfo ******************* - "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system +"Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system that uses a single source file to produce both on-line information and printed output. This means that instead of writing two different documents, one for the on-line help or other on-line information and @@ -648,8 +648,8 @@ File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Using Texinf Info files ========== - An Info file is a Texinfo file formatted so that the Info -documentation reading program can operate on it. (`makeinfo' and +An Info file is a Texinfo file formatted so that the Info documentation +reading program can operate on it. (`makeinfo' and `texinfo-format-buffer' are two commands that convert a Texinfo file into an Info file.) @@ -733,9 +733,9 @@ File: texinfo.info, Node: Printed Books, Next: Formatting Commands, Prev: Inf Printed Books ============= - A Texinfo file can be formatted and typeset as a printed book or -manual. To do this, you need TeX, a powerful, sophisticated typesetting -program written by Donald Knuth.(1) (*note Printed Books-Footnote-1::) +A Texinfo file can be formatted and typeset as a printed book or manual. +To do this, you need TeX, a powerful, sophisticated typesetting program +written by Donald Knuth.(1) (*note Printed Books-Footnote-1::) A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, @@ -795,7 +795,7 @@ File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Print @-commands ========== - In a Texinfo file, the commands that tell TeX how to typeset the +In a Texinfo file, the commands that tell TeX how to typeset the printed manual and tell `makeinfo' and `texinfo-format-buffer' how to create an Info file are preceded by `@'; they are called "@-commands". For example, `@node' is the command to indicate a node and `@chapter' @@ -868,8 +868,8 @@ File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Comma General Syntactic Conventions ============================= - All printable ASCII characters except `@', `{' and `}' can appear in -a Texinfo file and stand for themselves. `@' is the escape character +All printable ASCII characters except `@', `{' and `}' can appear in a +Texinfo file and stand for themselves. `@' is the escape character which introduces commands. `{' and `}' should be used only to surround arguments to certain commands. To put one of these special characters into the document, put an `@' character in front of it, like this: @@ -921,17 +921,17 @@ File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Ov Comments ======== - You can write comments in a Texinfo file that will not appear in -either the Info file or the printed manual by using the `@comment' -command (which may be abbreviated to `@c'). Such comments are for the -person who reads the Texinfo file. All the text on a line that follows -either `@comment' or `@c' is a comment; the rest of the line does not -appear in either the Info file or the printed manual. (Often, you can -write the `@comment' or `@c' in the middle of a line, and only the text -that follows after the `@comment' or `@c' command does not appear; but -some commands, such as `@settitle' and `@setfilename', work on a whole -line. You cannot use `@comment' or `@c' in a line beginning with such -a command.) +You can write comments in a Texinfo file that will not appear in either +the Info file or the printed manual by using the `@comment' command +(which may be abbreviated to `@c'). Such comments are for the person +who reads the Texinfo file. All the text on a line that follows either +`@comment' or `@c' is a comment; the rest of the line does not appear +in either the Info file or the printed manual. (Often, you can write +the `@comment' or `@c' in the middle of a line, and only the text that +follows after the `@comment' or `@c' command does not appear; but some +commands, such as `@settitle' and `@setfilename', work on a whole line. +You cannot use `@comment' or `@c' in a line beginning with such a +command.) You can write long stretches of text that will not appear in either the Info file or the printed manual by using the `@ignore' and `@end @@ -949,7 +949,7 @@ File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Over What a Texinfo File Must Have ============================= - By convention, the names of Texinfo files end with one of the +By convention, the names of Texinfo files end with one of the extensions `.texinfo', `.texi', or `.tex'. The longer extension is preferred since it describes more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that @@ -1006,8 +1006,8 @@ File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Six Parts of a Texinfo File =========================== - Generally, a Texinfo file contains more than the minimal beginning -and end--it usually contains six parts: +Generally, a Texinfo file contains more than the minimal beginning and +end--it usually contains six parts: 1. Header The "Header" names the file, tells TeX which definitions' file to @@ -1040,3 +1040,6875 @@ and end--it usually contains six parts: The "End" contains commands for printing indices and generating the table of contents, and the `@bye' command on a line of its own. + +File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview + +A Short Sample Texinfo File +=========================== + +Here is a complete but very short Texinfo file, in six parts. The first +three parts of the file, from `\input texinfo' through to `@end +titlepage', look more intimidating than they are. Most of the material +is standard boilerplate; when you write a manual, simply insert the +names for your own manual in this segment. (*Note Beginning a File::.) + +In the following, the sample text is _indented_; comments on it are +not. The complete file, without any comments, is shown in *Note Sample +Texinfo File::. + +Part 1: Header +-------------- + +The header does not appear in either the Info file or the printed +output. It sets various parameters, including the name of the Info +file and the title used in the header. + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Document + @c %**end of header + + @setchapternewpage odd + +Part 2: Summary Description and Copyright +----------------------------------------- + +The summary description and copyright segment does not appear in the +printed document. + + @ifinfo + This is a short example of a complete Texinfo file. + + Copyright @copyright{} 1990 Free Software Foundation, Inc. + @end ifinfo + +Part 3: Titlepage and Copyright +------------------------------- + +The titlepage segment does not appear in the Info file. + + @titlepage + @sp 10 + @comment The title is printed in a large font. + @center @titlefont{Sample Title} + + @c The following two commands start the copyright page. + @page + @vskip 0pt plus 1filll + Copyright @copyright{} 1990 Free Software Foundation, Inc. + @end titlepage + +Part 4: `Top' Node and Master Menu +---------------------------------- + +The `Top' node contains the master menu for the Info file. Since a +printed manual uses a table of contents rather than a menu, the master +menu appears only in the Info file. + + @node Top, First Chapter, , (dir) + @comment node-name, next, previous, up + + @menu + * First Chapter:: The first chapter is the + only chapter in this sample. + * Concept Index:: This index has two entries. + @end menu + +Part 5: The Body of the Document +--------------------------------- + +The body segment contains all the text of the document, but not the +indices or table of contents. This example illustrates a node and a +chapter containing an enumerated list. + + @node First Chapter, Concept Index, Top, Top + @comment node-name, next, previous, up + @chapter First Chapter + @cindex Sample index entry + + This is the contents of the first chapter. + @cindex Another sample index entry + + Here is a numbered list. + + @enumerate + @item + This is the first item. + + @item + This is the second item. + @end enumerate + + The @code{makeinfo} and @code{texinfo-format-buffer} + commands transform a Texinfo file such as this into + an Info file; and @TeX{} typesets it for a printed + manual. + +Part 6: The End of the Document +------------------------------- + +The end segment contains commands both for generating an index in a node +and unnumbered chapter of its own and for generating the table of +contents; and it contains the `@bye' command that marks the end of the +document. + + @node Concept Index, , First Chapter, Top + @comment node-name, next, previous, up + @unnumbered Concept Index + + @printindex cp + + @contents + @bye + +The Results +----------- + +Here is what the contents of the first chapter of the sample look like: + + + This is the contents of the first chapter. + + Here is a numbered list. + + 1. This is the first item. + + 2. This is the second item. + + The `makeinfo' and `texinfo-format-buffer' commands transform a + Texinfo file such as this into an Info file; and TeX typesets it + for a printed manual. + + +File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview + +Acknowledgements +================ + +Richard M. Stallman wrote Edition 1.0 of this manual. +Robert J. Chassell revised and extended it, starting with Edition 1.1. +Karl Berry made updates for the Texinfo 3.8 and subsequent releases, +starting with Edition 2.22. + + Our thanks go out to all who helped improve this work, particularly to +Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and +reported mistakes and obscurities; our special thanks go to Melissa +Weisshaus for her frequent and often tedious reviews of nearly similar +editions. Our mistakes are our own. + + Please send suggestions and corrections to: + + Internet address: + bug-texinfo@gnu.org + +Please include the manual's edition number and update date in your +messages. + + +File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top + +Using Texinfo Mode +****************** + +You may edit a Texinfo file with any text editor you choose. A Texinfo +file is no different from any other ASCII file. However, GNU Emacs +comes with a special mode, called Texinfo mode, that provides Emacs +commands and tools to help ease your work. + + This chapter describes features of GNU Emacs' Texinfo mode but not any +features of the Texinfo formatting language. If you are reading this +manual straight through from the beginning, you may want to skim through +this chapter briefly and come back to it after reading succeeding +chapters which describe the Texinfo formatting language in detail. + +* Menu: + +* Texinfo Mode Overview:: How Texinfo mode can help you. +* Emacs Editing:: Texinfo mode adds to GNU Emacs' general + purpose editing features. +* Inserting:: How to insert frequently used @-commands. +* Showing the Structure:: How to show the structure of a file. +* Updating Nodes and Menus:: How to update or create new nodes and menus. +* Info Formatting:: How to format for Info. +* Printing:: How to format and print part or all of a file. +* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. + + +File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode + +Texinfo Mode Overview +===================== + + Texinfo mode provides special features for working with Texinfo files: + + * Insert frequently used @-commands. + + * Automatically create `@node' lines. + + * Show the structure of a Texinfo source file. + + * Automatically create or update the `Next', `Previous', and `Up' + pointers of a node. + + * Automatically create or update menus. + + * Automatically create a master menu. + + * Format a part or all of a file for Info. + + * Typeset and print part or all of a file. + + Perhaps the two most helpful features are those for inserting +frequently used @-commands and for creating node pointers and menus. + + +File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode + +The Usual GNU Emacs Editing Commands +==================================== + +In most cases, the usual Text mode commands work the same in Texinfo +mode as they do in Text mode. Texinfo mode adds new editing commands +and tools to GNU Emacs' general purpose editing features. The major +difference concerns filling. In Texinfo mode, the paragraph separation +variable and syntax table are redefined so that Texinfo commands that +should be on lines of their own are not inadvertently included in +paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a +paragraph but not mix an indexing command on a line adjacent to it into +the paragraph. + + In addition, Texinfo mode sets the `page-delimiter' variable to the +value of `texinfo-chapter-level-regexp'; by default, this is a regular +expression matching the commands for chapters and their equivalents, +such as appendices. With this value for the page delimiter, you can +jump from chapter title to chapter title with the `C-x ]' +(`forward-page') and `C-x [' (`backward-page') commands and narrow to a +chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages: +(xemacs)Pages, for details about the page commands.) + + You may name a Texinfo file however you wish, but the convention is to +end a Texinfo file name with one of the three extensions `.texinfo', +`.texi', or `.tex'. A longer extension is preferred, since it is +explicit, but a shorter extension may be necessary for operating +systems that limit the length of file names. GNU Emacs automatically +enters Texinfo mode when you visit a file with a `.texinfo' or `.texi' +extension. Also, Emacs switches to Texinfo mode when you visit a file +that has `-*-texinfo-*-' in its first line. If ever you are in another +mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'. + + Like all other Emacs features, you can customize or enhance Texinfo +mode as you wish. In particular, the keybindings are very easy to +change. The keybindings described here are the default or standard +ones. + + +File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode + +Inserting Frequently Used Commands +================================== + +Texinfo mode provides commands to insert various frequently used +@-commands into the buffer. You can use these commands to save +keystrokes. + + The insert commands are invoked by typing `C-c' twice and then the +first letter of the @-command: + +`C-c C-c c' +`M-x texinfo-insert-@code' + Insert `@code{}' and put the cursor between the braces. + +`C-c C-c d' +`M-x texinfo-insert-@dfn' + Insert `@dfn{}' and put the cursor between the braces. + +`C-c C-c e' +`M-x texinfo-insert-@end' + Insert `@end' and attempt to insert the correct following word, + such as `example' or `table'. (This command does not handle + nested lists correctly, but inserts the word appropriate to the + immediately preceding list.) + +`C-c C-c i' +`M-x texinfo-insert-@item' + Insert `@item' and put the cursor at the beginning of the next + line. + +`C-c C-c k' +`M-x texinfo-insert-@kbd' + Insert `@kbd{}' and put the cursor between the braces. + +`C-c C-c n' +`M-x texinfo-insert-@node' + Insert `@node' and a comment line listing the sequence for the + `Next', `Previous', and `Up' nodes. Leave point after the `@node'. + +`C-c C-c o' +`M-x texinfo-insert-@noindent' + Insert `@noindent' and put the cursor at the beginning of the next + line. + +`C-c C-c s' +`M-x texinfo-insert-@samp' + Insert `@samp{}' and put the cursor between the braces. + +`C-c C-c t' +`M-x texinfo-insert-@table' + Insert `@table' followed by a and leave the cursor after the + . + +`C-c C-c v' +`M-x texinfo-insert-@var' + Insert `@var{}' and put the cursor between the braces. + +`C-c C-c x' +`M-x texinfo-insert-@example' + Insert `@example' and put the cursor at the beginning of the next + line. + +`C-c C-c {' +`M-x texinfo-insert-braces' + Insert `{}' and put the cursor between the braces. + +`C-c C-c }' +`C-c C-c ]' +`M-x up-list' + Move from between a pair of braces forward past the closing brace. + Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is, + however, more mnemonic; hence the two keybindings. (Also, you can + move out from between braces by typing `C-f'.) + + To put a command such as `@code{...}' around an _existing_ word, +position the cursor in front of the word and type `C-u 1 C-c C-c c'. +This makes it easy to edit existing plain text. The value of the +prefix argument tells Emacs how many words following point to include +between braces--`1' for one word, `2' for two words, and so on. Use a +negative argument to enclose the previous word or words. If you do not +specify a prefix argument, Emacs inserts the @-command string and +positions the cursor between the braces. This feature works only for +those @-commands that operate on a word or words within one line, such +as `@kbd' and `@var'. + + This set of insert commands was created after analyzing the frequency +with which different @-commands are used in the `GNU Emacs Manual' and +the `GDB Manual'. If you wish to add your own insert commands, you can +bind a keyboard macro to a key, use abbreviations, or extend the code +in `texinfo.el'. + + `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command +that works differently from the other insert commands. It inserts a +node's section or chapter title in the space for the description in a +menu entry line. (A menu entry has three parts, the entry name, the +node name, and the description. Only the node name is required, but a +description helps explain what the node is about. *Note The Parts of a +Menu: Menu Parts.) + + To use `texinfo-start-menu-description', position point in a menu +entry line and type `C-c C-c C-d'. The command looks for and copies +the title that goes with the node name, and inserts the title as a +description; it positions point at beginning of the inserted text so you +can edit it. The function does not insert the title if the menu entry +line already contains a description. + + This command is only an aid to writing descriptions; it does not do +the whole job. You must edit the inserted text since a title tends to +use the same words as a node name but a useful description uses +different words. + + +File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode + +Showing the Section Structure of a File +======================================= + +You can show the section structure of a Texinfo file by using the `C-c +C-s' command (`texinfo-show-structure'). This command shows the +section structure of a Texinfo file by listing the lines that begin +with the @-commands for `@chapter', `@section', and the like. It +constructs what amounts to a table of contents. These lines are +displayed in another buffer called the `*Occur*' buffer. In that +buffer, you can position the cursor over one of the lines and use the +`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the +corresponding spot in the Texinfo file. + +`C-c C-s' +`M-x texinfo-show-structure' + Show the `@chapter', `@section', and such lines of a Texinfo file. + +`C-c C-c' +`M-x occur-mode-goto-occurrence' + Go to the line in the Texinfo file corresponding to the line under + the cursor in the `*Occur*' buffer. + + If you call `texinfo-show-structure' with a prefix argument by typing +`C-u C-c C-s', it will list not only those lines with the @-commands +for `@chapter', `@section', and the like, but also the `@node' lines. +(This is how the `texinfo-show-structure' command worked without an +argument in the first version of Texinfo. It was changed because +`@node' lines clutter up the `*Occur*' buffer and are usually not +needed.) You can use `texinfo-show-structure' with a prefix argument +to check whether the `Next', `Previous', and `Up' pointers of an +`@node' line are correct. + + Often, when you are working on a manual, you will be interested only +in the structure of the current chapter. In this case, you can mark +off the region of the buffer that you are interested in by using the +`C-x n n' (`narrow-to-region') command and `texinfo-show-structure' +will work on only that region. To see the whole buffer again, use +`C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more +information about the narrowing commands.) + + In addition to providing the `texinfo-show-structure' command, +Texinfo mode sets the value of the page delimiter variable to match the +chapter-level @-commands. This enables you to use the `C-x ]' +(`forward-page') and `C-x [' (`backward-page') commands to move forward +and backward by chapter, and to use the `C-x p' (`narrow-to-page') +command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more +information about the page commands. + + +File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode + +Updating Nodes and Menus +======================== + +Texinfo mode provides commands for automatically creating or updating +menus and node pointers. The commands are called "update" commands +because their most frequent use is for updating a Texinfo file after +you have worked on it; but you can use them to insert the `Next', +`Previous', and `Up' pointers into an `@node' line that has none and to +create menus in a file that has none. + + If you do not use the updating commands, you need to write menus and +node pointers by hand, which is a tedious task. + +* Menu: + +* Updating Commands:: Five major updating commands. +* Updating Requirements:: How to structure a Texinfo file for + using the updating command. +* Other Updating Commands:: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. + + +File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus + +The Updating Commands +--------------------- + + You can use the updating commands + + * to insert or update the `Next', `Previous', and `Up' pointers of a + node, + + * to insert or update the menu for a section, and + + * to create a master menu for a Texinfo source file. + + You can also use the commands to update all the nodes and menus in a +region or in a whole Texinfo file. + + The updating commands work only with conventional Texinfo files, which +are structured hierarchically like books. In such files, a structuring +command line must follow closely after each `@node' line, except for +the `Top' `@node' line. (A "structuring command line" is a line +beginning with `@chapter', `@section', or other similar command.) + + You can write the structuring command line on the line that follows +immediately after an `@node' line or else on the line that follows +after a single `@comment' line or a single `@ifinfo' line. You cannot +interpose more than one line between the `@node' line and the +structuring command line; and you may interpose only an `@comment' line +or an `@ifinfo' line. + + Commands which work on a whole buffer require that the `Top' node be +followed by a node with an `@chapter' or equivalent-level command. +Note that the menu updating commands will not create a main or master +menu for a Texinfo file that has only `@chapter'-level nodes! The menu +updating commands only create menus _within_ nodes for lower level +nodes. To create a menu of chapters, you must provide a `Top' node. + + The menu updating commands remove menu entries that refer to other +Info files since they do not refer to nodes within the current buffer. +This is a deficiency. Rather than use menu entries, you can use cross +references to refer to other Info files. None of the updating commands +affect cross references. + + Texinfo mode has five updating commands that are used most often: two +are for updating the node pointers or menu of a single node (or a +region); two are for updating every node pointer and menu in a file; +and one, the `texinfo-master-menu' command, is for creating a master +menu for a complete file, and optionally, for updating every node and +menu in the whole Texinfo file. + + The `texinfo-master-menu' command is the primary command: + +`C-c C-u m' +`M-x texinfo-master-menu' + Create or update a master menu that includes all the other menus + (incorporating the descriptions from pre-existing menus, if any). + + With an argument (prefix argument, `C-u,' if interactive), first + create or update all the nodes and all the regular menus in the + buffer before constructing the master menu. (*Note The Top Node + and Master Menu: The Top Node, for more about a master menu.) + + For `texinfo-master-menu' to work, the Texinfo file must have a + `Top' node and at least one subsequent node. + + After extensively editing a Texinfo file, you can type the + following: + + C-u M-x texinfo-master-menu + or + C-u C-c C-u m + + This updates all the nodes and menus completely and all at once. + + The other major updating commands do smaller jobs and are designed for +the person who updates nodes and menus as he or she writes a Texinfo +file. + + The commands are: + +`C-c C-u C-n' +`M-x texinfo-update-node' + Insert the `Next', `Previous', and `Up' pointers for the node that + point is within (i.e., for the `@node' line preceding point). If + the `@node' line has pre-existing `Next', `Previous', or `Up' + pointers in it, the old pointers are removed and new ones inserted. + With an argument (prefix argument, `C-u', if interactive), this + command updates all `@node' lines in the region (which is the text + between point and mark). + +`C-c C-u C-m' +`M-x texinfo-make-menu' + Create or update the menu in the node that point is within. With + an argument (`C-u' as prefix argument, if interactive), the + command makes or updates menus for the nodes which are either + within or a part of the region. + + Whenever `texinfo-make-menu' updates an existing menu, the + descriptions from that menu are incorporated into the new menu. + This is done by copying descriptions from the existing menu to the + entries in the new menu that have the same node names. If the + node names are different, the descriptions are not copied to the + new menu. + +`C-c C-u C-e' +`M-x texinfo-every-node-update' + Insert or update the `Next', `Previous', and `Up' pointers for + every node in the buffer. + +`C-c C-u C-a' +`M-x texinfo-all-menus-update' + Create or update all the menus in the buffer. With an argument + (`C-u' as prefix argument, if interactive), first insert or update + all the node pointers before working on the menus. + + If a master menu exists, the `texinfo-all-menus-update' command + updates it; but the command does not create a new master menu if + none already exists. (Use the `texinfo-master-menu' command for + that.) + + When working on a document that does not merit a master menu, you + can type the following: + + C-u C-c C-u C-a + or + C-u M-x texinfo-all-menus-update + + This updates all the nodes and menus. + + The `texinfo-column-for-description' variable specifies the column to +which menu descriptions are indented. By default, the value is 32 +although it is often useful to reduce it to as low as 24. You can set +the variable with the `M-x edit-options' command (*note Editing +Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable' +command (*note Examining and Setting Variables: (xemacs)Examining.). + + Also, the `texinfo-indent-menu-description' command may be used to +indent existing menu descriptions to a specified column. Finally, if +you wish, you can use the `texinfo-insert-node-lines' command to insert +missing `@node' lines into a file. (*Note Other Updating Commands::, +for more information.) + + +File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus + +Updating Requirements +--------------------- + +To use the updating commands, you must organize the Texinfo file +hierarchically with chapters, sections, subsections, and the like. +When you construct the hierarchy of the manual, do not `jump down' more +than one level at a time: you can follow the `Top' node with a chapter, +but not with a section; you can follow a chapter with a section, but +not with a subsection. However, you may `jump up' any number of levels +at one time--for example, from a subsection to a chapter. + + Each `@node' line, with the exception of the line for the `Top' node, +must be followed by a line with a structuring command such as +`@chapter', `@section', or `@unnumberedsubsec'. + + Each `@node' line/structuring-command line combination must look +either like this: + + @node Comments, Minimum, Conventions, Overview + @comment node-name, next, previous, up + @section Comments + + or like this (without the `@comment' line): + + @node Comments, Minimum, Conventions, Overview + @section Comments + +In this example, `Comments' is the name of both the node and the +section. The next node is called `Minimum' and the previous node is +called `Conventions'. The `Comments' section is within the `Overview' +node, which is specified by the `Up' pointer. (Instead of an +`@comment' line, you can write an `@ifinfo' line.) + + If a file has a `Top' node, it must be called `top' or `Top' and be +the first node in the file. + + The menu updating commands create a menu of sections within a chapter, +a menu of subsections within a section, and so on. This means that you +must have a `Top' node if you want a menu of chapters. + + Incidentally, the `makeinfo' command will create an Info file for a +hierarchically organized Texinfo file that lacks `Next', `Previous' and +`Up' pointers. Thus, if you can be sure that your Texinfo file will be +formatted with `makeinfo', you have no need for the `update node' +commands. (*Note Creating an Info File: Create an Info File, for more +information about `makeinfo'.) However, both `makeinfo' and the +`texinfo-format-...' commands require that you insert menus in the file. + + +File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus + +Other Updating Commands +----------------------- + +In addition to the five major updating commands, Texinfo mode possesses +several less frequently used updating commands: + +`M-x texinfo-insert-node-lines' + Insert `@node' lines before the `@chapter', `@section', and other + sectioning commands wherever they are missing throughout a region + in a Texinfo file. + + With an argument (`C-u' as prefix argument, if interactive), the + `texinfo-insert-node-lines' command not only inserts `@node' lines + but also inserts the chapter or section titles as the names of the + corresponding nodes. In addition, it inserts the titles as node + names in pre-existing `@node' lines that lack names. Since node + names should be more concise than section or chapter titles, you + must manually edit node names so inserted. + + For example, the following marks a whole buffer as a region and + inserts `@node' lines and titles throughout: + + C-x h C-u M-x texinfo-insert-node-lines + + (Note that this command inserts titles as node names in `@node' + lines; the `texinfo-start-menu-description' command (*note + Inserting Frequently Used Commands: Inserting.) inserts titles as + descriptions in menu entries, a different action. However, in both + cases, you need to edit the inserted text.) + +`M-x texinfo-multiple-files-update' + Update nodes and menus in a document built from several separate + files. With `C-u' as a prefix argument, create and insert a + master menu in the outer file. With a numeric prefix argument, + such as `C-u 2', first update all the menus and all the `Next', + `Previous', and `Up' pointers of all the included files before + creating and inserting a master menu in the outer file. The + `texinfo-multiple-files-update' command is described in the + appendix on `@include' files. *Note + texinfo-multiple-files-update::. + +`M-x texinfo-indent-menu-description' + Indent every description in the menu following point to the + specified column. You can use this command to give yourself more + space for descriptions. With an argument (`C-u' as prefix + argument, if interactive), the `texinfo-indent-menu-description' + command indents every description in every menu in the region. + However, this command does not indent the second and subsequent + lines of a multi-line description. + +`M-x texinfo-sequential-node-update' + Insert the names of the nodes immediately following and preceding + the current node as the `Next' or `Previous' pointers regardless + of those nodes' hierarchical level. This means that the `Next' + node of a subsection may well be the next chapter. Sequentially + ordered nodes are useful for novels and other documents that you + read through sequentially. (However, in Info, the `g *' command + lets you look through the file sequentially, so sequentially + ordered nodes are not strictly necessary.) With an argument + (prefix argument, if interactive), the + `texinfo-sequential-node-update' command sequentially updates all + the nodes in the region. + + +File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode + +Formatting for Info +=================== + +Texinfo mode provides several commands for formatting part or all of a +Texinfo file for Info. Often, when you are writing a document, you +want to format only part of a file--that is, a region. + + You can use either the `texinfo-format-region' or the +`makeinfo-region' command to format a region: + +`C-c C-e C-r' +`M-x texinfo-format-region' +`C-c C-m C-r' +`M-x makeinfo-region' + Format the current region for Info. + + You can use either the `texinfo-format-buffer' or the +`makeinfo-buffer' command to format a whole buffer: + +`C-c C-e C-b' +`M-x texinfo-format-buffer' +`C-c C-m C-b' +`M-x makeinfo-buffer' + Format the current buffer for Info. + + For example, after writing a Texinfo file, you can type the following: + + C-u C-c C-u m +or + C-u M-x texinfo-master-menu + +This updates all the nodes and menus. Then type the following to create +an Info file: + + C-c C-m C-b +or + M-x makeinfo-buffer + + For TeX or the Info formatting commands to work, the file _must_ +include a line that has `@setfilename' in its header. + + *Note Create an Info File::, for details about Info formatting. + + +File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode + +Formatting and Printing +======================= + +Typesetting and printing a Texinfo file is a multi-step process in which +you first create a file for printing (called a DVI file), and then +print the file. Optionally, you may also create indices. To do this, +you must run the `texindex' command after first running the `tex' +typesetting command; and then you must run the `tex' command again. Or +else run the `texi2dvi' command which automatically creates indices as +needed (*note Format with texi2dvi::). + + Often, when you are writing a document, you want to typeset and print +only part of a file to see what it will look like. You can use the +`texinfo-tex-region' and related commands for this purpose. Use the +`texinfo-tex-buffer' command to format all of a buffer. + +`C-c C-t C-b' +`M-x texinfo-tex-buffer' + Run `texi2dvi' on the buffer. In addition to running TeX on the + buffer, this command automatically creates or updates indices as + needed. + +`C-c C-t C-r' +`M-x texinfo-tex-region' + Run TeX on the region. + +`C-c C-t C-i' +`M-x texinfo-texindex' + Run `texindex' to sort the indices of a Texinfo file formatted with + `texinfo-tex-region'. The `texinfo-tex-region' command does not + run `texindex' automatically; it only runs the `tex' typesetting + command. You must run the `texinfo-tex-region' command a second + time after sorting the raw index files with the `texindex' + command. (Usually, you do not format an index when you format a + region, only when you format a buffer. Now that the `texi2dvi' + command exists, there is little or no need for this command.) + +`C-c C-t C-p' +`M-x texinfo-tex-print' + Print the file (or the part of the file) previously formatted with + `texinfo-tex-buffer' or `texinfo-tex-region'. + + For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file +_must_ start with a `\input texinfo' line and must include an +`@settitle' line. The file must end with `@bye' on a line by itself. +(When you use `texinfo-tex-region', you must surround the `@settitle' +line with start-of-header and end-of-header lines.) + + *Note Format/Print Hardcopy::, for a description of the other TeX +related commands, such as `tex-show-print-queue'. + + +File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode + +Texinfo Mode Summary +==================== + +In Texinfo mode, each set of commands has default keybindings that +begin with the same keys. All the commands that are custom-created for +Texinfo mode begin with `C-c'. The keys are somewhat mnemonic. + +Insert Commands +--------------- + +The insert commands are invoked by typing `C-c' twice and then the +first letter of the @-command to be inserted. (It might make more +sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c' +is quick to type.) + + C-c C-c c Insert `@code'. + C-c C-c d Insert `@dfn'. + C-c C-c e Insert `@end'. + C-c C-c i Insert `@item'. + C-c C-c n Insert `@node'. + C-c C-c s Insert `@samp'. + C-c C-c v Insert `@var'. + C-c C-c { Insert braces. + C-c C-c ] + C-c C-c } Move out of enclosing braces. + + C-c C-c C-d Insert a node's section title + in the space for the description + in a menu entry line. + +Show Structure +-------------- + +The `texinfo-show-structure' command is often used within a narrowed +region. + + C-c C-s List all the headings. + +The Master Update Command +------------------------- + +The `texinfo-master-menu' command creates a master menu; and can be +used to update every node and menu in a file as well. + + C-c C-u m + M-x texinfo-master-menu + Create or update a master menu. + + C-u C-c C-u m With `C-u' as a prefix argument, first + create or update all nodes and regular + menus, and then create a master menu. + +Update Pointers +--------------- + +The update pointer commands are invoked by typing `C-c C-u' and then +either `C-n' for `texinfo-update-node' or `C-e' for +`texinfo-every-node-update'. + + C-c C-u C-n Update a node. + C-c C-u C-e Update every node in the buffer. + +Update Menus +------------ + +Invoke the update menu commands by typing `C-c C-u' and then either +`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'. +To update both nodes and menus at the same time, precede `C-c C-u C-a' +with `C-u'. + + C-c C-u C-m Make or update a menu. + + C-c C-u C-a Make or update all + menus in a buffer. + + C-u C-c C-u C-a With `C-u' as a prefix argument, + first create or update all nodes and + then create or update all menus. + +Format for Info +--------------- + +The Info formatting commands that are written in Emacs Lisp are invoked +by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the +whole buffer. + + The Info formatting commands that are written in C and based on the +`makeinfo' program are invoked by typing `C-c C-m' and then either +`C-r' for a region or `C-b' for the whole buffer. + +Use the `texinfo-format...' commands: + + C-c C-e C-r Format the region. + C-c C-e C-b Format the buffer. + +Use `makeinfo': + + C-c C-m C-r Format the region. + C-c C-m C-b Format the buffer. + C-c C-m C-l Recenter the `makeinfo' output buffer. + C-c C-m C-k Kill the `makeinfo' formatting job. + +Typeset and Print +----------------- + +The TeX typesetting and printing commands are invoked by typing `C-c +C-t' and then another control command: `C-r' for `texinfo-tex-region', +`C-b' for `texinfo-tex-buffer', and so on. + + C-c C-t C-r Run TeX on the region. + C-c C-t C-b Run `texi2dvi' on the buffer. + C-c C-t C-i Run `texindex'. + C-c C-t C-p Print the DVI file. + C-c C-t C-q Show the print queue. + C-c C-t C-d Delete a job from the print queue. + C-c C-t C-k Kill the current TeX formatting job. + C-c C-t C-x Quit a currently stopped TeX formatting job. + C-c C-t C-l Recenter the output buffer. + +Other Updating Commands +----------------------- + +The `other updating commands' do not have standard keybindings because +they are rarely used. + + M-x texinfo-insert-node-lines + Insert missing `@node' lines in region. + With `C-u' as a prefix argument, + use section titles as node names. + + M-x texinfo-multiple-files-update + Update a multi-file document. + With `C-u 2' as a prefix argument, + create or update all nodes and menus + in all included files first. + + M-x texinfo-indent-menu-description + Indent descriptions. + + M-x texinfo-sequential-node-update + Insert node pointers in strict sequence. + + +File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top + +Beginning a Texinfo File +************************ + +Certain pieces of information must be provided at the beginning of a +Texinfo file, such as the name of the file and the title of the +document. + +* Menu: + +* Four Parts:: Four parts begin a Texinfo file. +* Sample Beginning:: Here is a sample beginning for a Texinfo file. +* Header:: The very beginning of a Texinfo file. +* Info Summary and Permissions:: Summary and copying permissions for Info. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* The Top Node:: Creating the `Top' node and master menu. +* Software Copying Permissions:: Ensure that you and others continue to + have the right to use and share software. + + +File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File + +Four Parts Begin a File +======================= + + Generally, the beginning of a Texinfo file has four parts: + + 1. The header, delimited by special comment lines, that includes the + commands for naming the Texinfo file and telling TeX what + definitions file to use when processing the Texinfo file. + + 2. A short statement of what the file is about, with a copyright + notice and copying permissions. This is enclosed in `@ifinfo' and + `@end ifinfo' commands so that the formatters place it only in the + Info file. + + 3. A title page and copyright page, with a copyright notice and + copying permissions. This is enclosed between `@titlepage' and + `@end titlepage' commands. The title and copyright page appear + only in the printed manual. + + 4. The `Top' node that contains a menu for the whole Info file. The + contents of this node appear only in the Info file. + + Also, optionally, you may include the copying conditions for a program +and a warranty disclaimer. The copying section will be followed by an +introduction or else by the first chapter of the manual. + + Since the copyright notice and copying permissions for the Texinfo +document (in contrast to the copying permissions for a program) are in +parts that appear only in the Info file or only in the printed manual, +this information must be given twice. + + +File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File + +Sample Texinfo File Beginning +============================= + +The following sample shows what is needed. + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename NAME-OF-INFO-FILE + @settitle NAME-OF-MANUAL + @setchapternewpage odd + @c %**end of header + + @ifinfo + This file documents ... + + Copyright YEAR COPYRIGHT-OWNER + + Permission is granted to ... + @end ifinfo + + @c This title page illustrates only one of the + @c two methods of forming a title page. + + @titlepage + @title NAME-OF-MANUAL-WHEN-PRINTED + @subtitle SUBTITLE-IF-ANY + @subtitle SECOND-SUBTITLE + @author AUTHOR + + @c The following two commands + @c start the copyright page. + @page + @vskip 0pt plus 1filll + Copyright @copyright{} YEAR COPYRIGHT-OWNER + + Published by ... + + Permission is granted to ... + @end titlepage + + @node Top, Overview, , (dir) + + @ifinfo + This document describes ... + + This document applies to version ... + of the program named ... + @end ifinfo + + @menu + * Copying:: Your rights and freedoms. + * First Chapter:: Getting started ... + * Second Chapter:: ... + ... + ... + @end menu + + @node First Chapter, Second Chapter, top, top + @comment node-name, next, previous, up + @chapter First Chapter + @cindex Index entry for First Chapter + + +File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File + +The Texinfo File Header +======================= + +Texinfo files start with at least three lines that provide Info and TeX +with necessary information. These are the `\input texinfo' line, the +`@settitle' line, and the `@setfilename' line. If you want to run TeX +on just a part of the Texinfo File, you must write the `@settitle' and +`@setfilename' lines between start-of-header and end-of-header lines. + + Thus, the beginning of a Texinfo file looks like this: + + \input texinfo @c -*-texinfo-*- + @setfilename sample.info + @settitle Sample Document + +or else like this: + + \input texinfo @c -*-texinfo-*- + @c %**start of header + @setfilename sample.info + @settitle Sample Document + @c %**end of header + +* Menu: + +* First Line:: The first line of a Texinfo file. +* Start of Header:: Formatting a region requires this. +* setfilename:: Tell Info the name of the Info file. +* settitle:: Create a title for the printed work. +* setchapternewpage:: Start chapters on right-hand pages. +* paragraphindent:: An option to specify paragraph indentation. +* End of Header:: Formatting a region requires this. + + +File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header + +The First Line of a Texinfo File +-------------------------------- + +Every Texinfo file that is to be the top-level input to TeX must begin +with a line that looks like this: + + \input texinfo @c -*-texinfo-*- + +This line serves two functions: + + 1. When the file is processed by TeX, the `\input texinfo' command + tells TeX to load the macros needed for processing a Texinfo file. + These are in a file called `texinfo.tex', which is usually located + in the `/usr/lib/tex/macros' directory. TeX uses the backslash, + `\', to mark the beginning of a command, just as Texinfo uses `@'. + The `texinfo.tex' file causes the switch from `\' to `@'; before + the switch occurs, TeX requires `\', which is why it appears at + the beginning of the file. + + 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode + specification tells Emacs to use Texinfo mode. + + +File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header + +Start of Header +--------------- + +Write a start-of-header line on the second line of a Texinfo file. +Follow the start-of-header line with `@setfilename' and `@settitle' +lines and, optionally, with other command lines, such as `@smallbook' +or `@footnotestyle'; and then by an end-of-header line (*note End of +Header::). + + With these lines, you can format part of a Texinfo file for Info or +typeset part for printing. + + A start-of-header line looks like this: + + @c %**start of header + + The odd string of characters, `%**', is to ensure that no other +comment is accidentally taken for a start-of-header line. + + +File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header + +`@setfilename' +-------------- + +In order to serve as the primary input file for either `makeinfo' or +TeX, a Texinfo file must contain a line that looks like this: + + @setfilename INFO-FILE-NAME + + Write the `@setfilename' command at the beginning of a line and +follow it on the same line by the Info file name. Do not write anything +else on the line; anything on the line after the command is considered +part of the file name, including what would otherwise be a comment. + + The `@setfilename' line specifies the name of the Info file to be +generated. This name should be different from the name of the Texinfo +file. There are two conventions for choosing the name: you can either +remove the `.texi' extension from the input file name, or replace it +with the `.info' extension. + + Some operating systems cannot handle long file names. You can run +into a problem even when the file name you specify is itself short +enough. This occurs because the Info formatters split a long Info file +into short indirect subfiles, and name them by appending `-1', `-2', +..., `-10', `-11', and so on, to the original file name. (*Note Tag +Files and Split Files: Tag and Split Files.) The subfile name +`texinfo.info-10', for example, is too long for some systems; so the +Info file name for this document is `texinfo' rather than +`texinfo.info'. + + The Info formatting commands ignore everything written before the +`@setfilename' line, which is why the very first line of the file (the +`\input' line) does not show up in the output. + + The `@setfilename' line produces no output when you typeset a manual +with TeX, but it nevertheless is essential: it opens the index, +cross-reference, and other auxiliary files used by Texinfo, and also +reads `texinfo.cnf' if that file is present on your system (*note +Preparing to Use TeX: Preparing for TeX.). + + +File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header + +`@settitle' +----------- + +In order to be made into a printed manual, a Texinfo file must contain +a line that looks like this: + + @settitle TITLE + + Write the `@settitle' command at the beginning of a line and follow +it on the same line by the title. This tells TeX the title to use in a +header or footer. Do not write anything else on the line; anything on +the line after the command is considered part of the title, including a +comment. + + Conventionally, when TeX formats a Texinfo file for double-sided +output, the title is printed in the left-hand (even-numbered) page +headings and the current chapter title is printed in the right-hand +(odd-numbered) page headings. (TeX learns the title of each chapter +from each `@chapter' command.) Page footers are not printed. + + Even if you are printing in a single-sided style, TeX looks for an +`@settitle' command line, in case you include the manual title in the +heading. + + The `@settitle' command should precede everything that generates +actual output in TeX. + + Although the title in the `@settitle' command is usually the same as +the title on the title page, it does not affect the title as it appears +on the title page. Thus, the two do not need not match exactly; and +the title in the `@settitle' command can be a shortened or expanded +version of the title as it appears on the title page. (*Note +`@titlepage': titlepage.) + + TeX prints page headings only for that text that comes after the +`@end titlepage' command in the Texinfo file, or that comes after an +`@headings' command that turns on headings. (*Note The `@headings' +Command: headings on off, for more information.) + + You may, if you wish, create your own, customized headings and +footings. *Note Page Headings: Headings, for a detailed discussion of +this process. + + +File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header + +`@setchapternewpage' +-------------------- + +In a book or a manual, text is usually printed on both sides of the +paper, chapters start on right-hand pages, and right-hand pages have +odd numbers. But in short reports, text often is printed only on one +side of the paper. Also in short reports, chapters sometimes do not +start on new pages, but are printed on the same page as the end of the +preceding chapter, after a small amount of vertical whitespace. + + You can use the `@setchapternewpage' command with various arguments +to specify how TeX should start chapters and whether it should typeset +pages for printing on one or both sides of the paper (single-sided or +double-sided printing). + + Write the `@setchapternewpage' command at the beginning of a line +followed by its argument. + + For example, you would write the following to cause each chapter to +start on a fresh odd-numbered page: + + @setchapternewpage odd + + You can specify one of three alternatives with the +`@setchapternewpage' command: + +`@setchapternewpage off' + Cause TeX to typeset a new chapter on the same page as the last + chapter, after skipping some vertical whitespace. Also, cause TeX + to format page headers for single-sided printing. (You can + override the headers format with the `@headings double' command; + see *Note The `@headings' Command: headings on off.) + +`@setchapternewpage on' + Cause TeX to start new chapters on new pages and to typeset page + headers for single-sided printing. This is the form most often + used for short reports. + + This alternative is the default. + +`@setchapternewpage odd' + Cause TeX to start new chapters on new, odd-numbered pages + (right-handed pages) and to typeset for double-sided printing. + This is the form most often used for books and manuals. + +Texinfo does not have an `@setchapternewpage even' command. + +(You can countermand or modify an `@setchapternewpage' command with an +`@headings' command. *Note The `@headings' Command: headings on off.) + + At the beginning of a manual or book, pages are not numbered--for +example, the title and copyright pages of a book are not numbered. By +convention, table of contents pages are numbered with roman numerals +and not in sequence with the rest of the document. + + Since an Info file does not have pages, the `@setchapternewpage' +command has no effect on it. + + Usually, you do not write an `@setchapternewpage' command for +single-sided printing, but accept the default which is to typeset for +single-sided printing and to start new chapters on new pages. Usually, +you write an `@setchapternewpage odd' command for double-sided printing. + + +File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header + +Paragraph Indenting +------------------- + +The Info formatting commands may insert spaces at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You +can use the `@paragraphindent' command to specify the indentation. +Write an `@paragraphindent' command at the beginning of a line followed +by either `asis' or a number. The template is: + + @paragraphindent INDENT + + The Info formatting commands indent according to the value of INDENT: + + * If the value of INDENT is `asis', the Info formatting commands do + not change the existing indentation. + + * If the value of INDENT is zero, the Info formatting commands delete + existing indentation. + + * If the value of INDENT is greater than zero, the Info formatting + commands indent the paragraph by that number of spaces. + + The default value of INDENT is `asis'. + + Write the `@paragraphindent' command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you write +the command between the start-of-header and end-of-header lines, the +region formatting commands indent paragraphs as specified.) + + A peculiarity of the `texinfo-format-buffer' and +`texinfo-format-region' commands is that they do not indent (nor fill) +paragraphs that contain `@w' or `@*' commands. *Note Refilling +Paragraphs::, for a detailed description of what goes on. + + +File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header + +End of Header +------------- + +Follow the header lines with an end-of-header line. An end-of-header +line looks like this: + + @c %**end of header + + If you include the `@setchapternewpage' command between the +start-of-header and end-of-header lines, TeX will typeset a region as +that command specifies. Similarly, if you include an `@smallbook' +command between the start-of-header and end-of-header lines, TeX will +typeset a region in the "small" book format. + + The reason for the odd string of characters (`%**') is so that the +`texinfo-tex-region' command does not accidentally find something that +it should not when it is looking for the header. + + The start-of-header line and the end-of-header line are Texinfo mode +variables that you can change. + + +File: texinfo.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File + +Summary and Copying Permissions for Info +======================================== + +The title page and the copyright page appear only in the printed copy of +the manual; therefore, the same information must be inserted in a +section that appears only in the Info file. This section usually +contains a brief description of the contents of the Info file, a +copyright notice, and copying permissions. + + The copyright notice should read: + + Copyright YEAR COPYRIGHT-OWNER + +and be put on a line by itself. + + Standard text for the copyright permissions is contained in an +appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo +Permissions, for the complete text. + + The permissions text appears in an Info file _before_ the first node. +This mean that a reader does _not_ see this text when reading the file +using Info, except when using the advanced Info command `g *'. + + +File: texinfo.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File + +The Title and Copyright Pages +============================= + +A manual's name and author are usually printed on a title page. +Sometimes copyright information is printed on the title page as well; +more often, copyright information is printed on the back of the title +page. + + The title and copyright pages appear in the printed manual, but not +in the Info file. Because of this, it is possible to use several +slightly obscure TeX typesetting commands that cannot be used in an +Info file. In addition, this part of the beginning of a Texinfo file +contains the text of the copying permissions that will appear in the +printed manual. + + *Note Titlepage Copying Permissions: Titlepage Permissions, for the +standard text for the copyright permissions. + +* Menu: + +* titlepage:: Create a title for the printed document. +* titlefont center sp:: The `@titlefont', `@center', + and `@sp' commands. +* title subtitle author:: The `@title', `@subtitle', + and `@author' commands. +* Copyright & Permissions:: How to write the copyright notice and + include copying permissions. +* end titlepage:: Turn on page headings after the title and + copyright pages. +* headings on off:: An option for turning headings on and off + and double or single sided printing. + + +File: texinfo.info, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page + +`@titlepage' +------------ + +Start the material for the title page and following copyright page with +`@titlepage' on a line by itself and end it with `@end titlepage' on a +line by itself. + + The `@end titlepage' command starts a new page and turns on page +numbering. (*Note Page Headings: Headings, for details about how to +generate page headings.) All the material that you want to appear on +unnumbered pages should be put between the `@titlepage' and `@end +titlepage' commands. By using the `@page' command you can force a page +break within the region delineated by the `@titlepage' and `@end +titlepage' commands and thereby create more than one unnumbered page. +This is how the copyright page is produced. (The `@titlepage' command +might perhaps have been better named the `@titleandadditionalpages' +command, but that would have been rather long!) + + When you write a manual about a computer program, you should write the +version of the program to which the manual applies on the title page. +If the manual changes more frequently than the program or is +independent of it, you should also include an edition number(1) (*note +titlepage-Footnote-1::) for the manual. This helps readers keep track +of which manual is for which version of the program. (The `Top' node +should also contain this information; see *Note `@top': makeinfo top.) + + Texinfo provides two main methods for creating a title page. One +method uses the `@titlefont', `@sp', and `@center' commands to generate +a title page in which the words on the page are centered. + + The second method uses the `@title', `@subtitle', and `@author' +commands to create a title page with black rules under the title and +author lines and the subtitle text set flush to the right hand side of +the page. With this method, you do not specify any of the actual +formatting of the title page. You specify the text you want, and +Texinfo does the formatting. You may use either method. + + For extremely simple applications, Texinfo also provides a command +`@shorttitlepage' which takes a single argument as the title. The +argument is typeset on a page by itself and followed by a blank page. + + +File: texinfo.info, Node: titlepage-Footnotes, Up: titlepage + + (1) We have found that it is helpful to refer to versions of manuals +as `editions' and versions of programs as `versions'; otherwise, we +find we are liable to confuse each other in conversation by referring +to both the documentation and the software with the same words. + + +File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page + +`@titlefont', `@center', and `@sp' +---------------------------------- + +You can use the `@titlefont', `@sp', and `@center' commands to create a +title page for a printed document. (This is the first of the two +methods for creating a title page in Texinfo.) + + Use the `@titlefont' command to select a large font suitable for the +title itself. + + For example: + + @titlefont{Texinfo} + + Use the `@center' command at the beginning of a line to center the +remaining text on that line. Thus, + + @center @titlefont{Texinfo} + +centers the title, which in this example is "Texinfo" printed in the +title font. + + Use the `@sp' command to insert vertical space. For example: + + @sp 2 + +This inserts two blank lines on the printed page. (*Note `@sp': sp, +for more information about the `@sp' command.) + + A template for this method looks like this: + + @titlepage + @sp 10 + @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} + @sp 2 + @center SUBTITLE-IF-ANY + @sp 2 + @center AUTHOR + ... + @end titlepage + + The spacing of the example fits an 8 1/2 by 11 inch manual. + + +File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page + +`@title', `@subtitle', and `@author' +------------------------------------ + +You can use the `@title', `@subtitle', and `@author' commands to create +a title page in which the vertical and horizontal spacing is done for +you automatically. This contrasts with the method described in the +previous section, in which the `@sp' command is needed to adjust +vertical spacing. + + Write the `@title', `@subtitle', or `@author' commands at the +beginning of a line followed by the title, subtitle, or author. + + The `@title' command produces a line in which the title is set flush +to the left-hand side of the page in a larger than normal font. The +title is underlined with a black rule. + + The `@subtitle' command sets subtitles in a normal-sized font flush +to the right-hand side of the page. + + The `@author' command sets the names of the author or authors in a +middle-sized font flush to the left-hand side of the page on a line +near the bottom of the title page. The names are underlined with a +black rule that is thinner than the rule that underlines the title. +(The black rule only occurs if the `@author' command line is followed +by an `@page' command line.) + + There are two ways to use the `@author' command: you can write the +name or names on the remaining part of the line that starts with an +`@author' command: + + @author by Jane Smith and John Doe + +or you can write the names one above each other by using two (or more) +`@author' commands: + + @author Jane Smith + @author John Doe + +(Only the bottom name is underlined with a black rule.) + + A template for this method looks like this: + + @titlepage + @title NAME-OF-MANUAL-WHEN-PRINTED + @subtitle SUBTITLE-IF-ANY + @subtitle SECOND-SUBTITLE + @author AUTHOR + @page + ... + @end titlepage + +Contrast this form with the form of a title page written using the +`@sp', `@center', and `@titlefont' commands: + + @titlepage + @sp 10 + @center @titlefont{Name of Manual When Printed} + @sp 2 + @center Subtitle, If Any + @sp 1 + @center Second subtitle + @sp 2 + @center Author + @page + ... + @end titlepage + + +File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page + +Copyright Page and Permissions +------------------------------ + +By international treaty, the copyright notice for a book should be +either on the title page or on the back of the title page. The +copyright notice should include the year followed by the name of the +organization or person who owns the copyright. + + When the copyright notice is on the back of the title page, that page +is customarily not numbered. Therefore, in Texinfo, the information on +the copyright page should be within `@titlepage' and `@end titlepage' +commands. + + Use the `@page' command to cause a page break. To push the copyright +notice and the other text on the copyright page towards the bottom of +the page, you can write a somewhat mysterious line after the `@page' +command that reads like this: + + @vskip 0pt plus 1filll + +This is a TeX command that is not supported by the Info formatting +commands. The `@vskip' command inserts whitespace. The `0pt plus +1filll' means to put in zero points of mandatory whitespace, and as +much optional whitespace as needed to push the following text to the +bottom of the page. Note the use of three `l's in the word `filll'; +this is the correct usage in TeX. + + In a printed manual, the `@copyright{}' command generates a `c' +inside a circle. (In Info, it generates `(C)'.) The copyright notice +itself has the following legally defined sequence: + + Copyright (C) YEAR COPYRIGHT-OWNER + + It is customary to put information on how to get a manual after the +copyright notice, followed by the copying permissions for the manual. + + Note that permissions must be given here as well as in the summary +segment within `@ifinfo' and `@end ifinfo' that immediately follows the +header since this text appears only in the printed manual and the +`ifinfo' text appears only in the Info file. + + *Note Sample Permissions::, for the standard text. + + +File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page + +Heading Generation +------------------ + +An `@end titlepage' command on a line by itself not only marks the end +of the title and copyright pages, but also causes TeX to start +generating page headings and page numbers. + + To repeat what is said elsewhere, Texinfo has two standard page +heading formats, one for documents which are printed on one side of +each sheet of paper (single-sided printing), and the other for +documents which are printed on both sides of each sheet (double-sided +printing). (*Note `@setchapternewpage': setchapternewpage.) You can +specify these formats in different ways: + + * The conventional way is to write an `@setchapternewpage' command + before the title page commands, and then have the `@end titlepage' + command start generating page headings in the manner desired. + (*Note `@setchapternewpage': setchapternewpage.) + + * Alternatively, you can use the `@headings' command to prevent page + headings from being generated or to start them for either single or + double-sided printing. (Write an `@headings' command immediately + after the `@end titlepage' command. *Note The `@headings' + Command: headings on off, for more information.) + + * Or, you may specify your own page heading and footing format. + *Note Page Headings: Headings, for detailed information about page + headings and footings. + + Most documents are formatted with the standard single-sided or +double-sided format, using `@setchapternewpage odd' for double-sided +printing and no `@setchapternewpage' command for single-sided printing. + + +File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page + +The `@headings' Command +----------------------- + +The `@headings' command is rarely used. It specifies what kind of page +headings and footings to print on each page. Usually, this is +controlled by the `@setchapternewpage' command. You need the +`@headings' command only if the `@setchapternewpage' command does not +do what you want, or if you want to turn off pre-defined page headings +prior to defining your own. Write an `@headings' command immediately +after the `@end titlepage' command. + + You can use `@headings' as follows: + +`@headings off' + Turn off printing of page headings. + +`@headings single' + Turn on page headings appropriate for single-sided printing. + +`@headings double' + Turn on page headings appropriate for double-sided printing. The + two commands, `@headings on' and `@headings double', are + synonymous. + +`@headings singleafter' +`@headings doubleafter' + Turn on `single' or `double' headings, respectively, after the + current page is output. + +`@headings on' + Turn on page headings: `single' if `@setchapternewpage on', + `double' otherwise. + + For example, suppose you write `@setchapternewpage off' before the +`@titlepage' command to tell TeX to start a new chapter on the same +page as the end of the last chapter. This command also causes TeX to +typeset page headers for single-sided printing. To cause TeX to +typeset for double sided printing, write `@headings double' after the +`@end titlepage' command. + + You can stop TeX from generating any page headings at all by writing +`@headings off' on a line of its own immediately after the line +containing the `@end titlepage' command, like this: + + @end titlepage + @headings off + +The `@headings off' command overrides the `@end titlepage' command, +which would otherwise cause TeX to print page headings. + + You can also specify your own style of page heading and footing. +*Note Page Headings: Headings, for more information. + + +File: texinfo.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File + +The `Top' Node and Master Menu +============================== + +The `Top' node is the node from which you enter an Info file. + + A `Top' node should contain a brief description of the Info file and +an extensive, master menu for the whole Info file. This helps the +reader understand what the Info file is about. Also, you should write +the version number of the program to which the Info file applies; or, +at least, the edition number. + + The contents of the `Top' node should appear only in the Info file; +none of it should appear in printed output, so enclose it between +`@ifinfo' and `@end ifinfo' commands. (TeX does not print either an +`@node' line or a menu; they appear only in Info; strictly speaking, +you are not required to enclose these parts between `@ifinfo' and `@end +ifinfo', but it is simplest to do so. *Note Conditionally Visible +Text: Conditionals.) + +* Menu: + +* Title of Top Node:: Sketch what the file is about. +* Master Menu Parts:: A master menu has three or more parts. + + +File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node + +`Top' Node Title +---------------- + + Sometimes, you will want to place an `@top' sectioning command line +containing the title of the document immediately after the `@node Top' +line (*note The `@top' Sectioning Command: makeinfo top command., for +more information). + + For example, the beginning of the Top node of this manual contains an +`@top' sectioning command, a short description, and edition and version +information. It looks like this: + + ... + @end titlepage + + @ifinfo + @node Top, Copying, , (dir) + @top Texinfo + + Texinfo is a documentation system... + + This is edition... + ... + @end ifinfo + + @menu + * Copying:: Texinfo is freely + redistributable. + * Overview:: What is Texinfo? + ... + @end menu + + In a `Top' node, the `Previous', and `Up' nodes usually refer to the +top level directory of the whole Info system, which is called `(dir)'. +The `Next' node refers to the first node that follows the main or master +menu, which is usually the copying permissions, introduction, or first +chapter. + + +File: texinfo.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node + +Parts of a Master Menu +---------------------- + +A "master menu" is a detailed main menu listing all the nodes in a file. + + A master menu is enclosed in `@menu' and `@end menu' commands and +does not appear in the printed document. + + Generally, a master menu is divided into parts. + + * The first part contains the major nodes in the Texinfo file: the + nodes for the chapters, chapter-like sections, and the appendices. + + * The second part contains nodes for the indices. + + * The third and subsequent parts contain a listing of the other, + lower level nodes, often ordered by chapter. This way, rather + than go through an intermediary menu, an inquirer can go directly + to a particular node when searching for specific information. + These menu items are not required; add them if you think they are a + convenience. If you do use them, put `@detailmenu' before the + first one, and `@end detailmenu' after the last; otherwise, + `makeinfo' will get confused. + + Each section in the menu can be introduced by a descriptive line. So +long as the line does not begin with an asterisk, it will not be +treated as a menu entry. (*Note Writing a Menu::, for more +information.) + + For example, the master menu for this manual looks like the following +(but has many more entries): + + @menu + * Copying:: Texinfo is freely + redistributable. + * Overview:: What is Texinfo? + * Texinfo Mode:: Special features in GNU Emacs. + ... + ... + * Command and Variable Index:: + An entry for each @-command. + * Concept Index:: An entry for each concept. + + @detailmenu + --- The Detailed Node Listing --- + + Overview of Texinfo + + * Info Files:: What is an Info file? + * Printed Manuals:: Characteristics of + a printed manual. + ... + ... + + Using Texinfo Mode + + * Info on a Region:: Formatting part of a file + for Info. + ... + ... + @end detailmenu + @end menu + + +File: texinfo.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File + +Software Copying Permissions +============================ + +If the Texinfo file has a section containing the "General Public +License" and the distribution information and a warranty disclaimer for +the software that is documented, this section usually follows the `Top' +node. The General Public License is very important to Project GNU +software. It ensures that you and others will continue to have a right +to use and share the software. + + The copying and distribution information and the disclaimer are +followed by an introduction or else by the first chapter of the manual. + + Although an introduction is not a required part of a Texinfo file, it +is very helpful. Ideally, it should state clearly and concisely what +the file is about and who would be interested in reading it. In +general, an introduction would follow the licensing and distribution +information, although sometimes people put it earlier in the document. +Usually, an introduction is put in an `@unnumbered' section. (*Note +The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.) + + +File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top + +Ending a Texinfo File +********************* + +The end of a Texinfo file should include the commands that create +indices and generate detailed and summary tables of contents. And it +must include the `@bye' command that marks the last line processed by +TeX. + + For example: + + @node Concept Index, , Variables Index, Top + @c node-name, next, previous, up + @unnumbered Concept Index + + @printindex cp + + @contents + @bye + +* Menu: + +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Contents:: How to create a table of contents. +* File End:: How to mark the end of a file. + + +File: texinfo.info, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File + +Index Menus and Printing an Index +================================= + +To print an index means to include it as part of a manual or Info file. +This does not happen automatically just because you use `@cindex' or +other index-entry generating commands in the Texinfo file; those just +cause the raw data for the index to be accumulated. To generate an +index, you must include the `@printindex' command at the place in the +document where you want the index to appear. Also, as part of the +process of creating a printed manual, you must run a program called +`texindex' (*note Format/Print Hardcopy::) to sort the raw data to +produce a sorted index file. The sorted index file is what is actually +used to print the index. + + Texinfo offers six different types of predefined index: the concept +index, the function index, the variables index, the keystroke index, the +program index, and the data type index (*note Predefined Indices::). +Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', +and `tp'. You may merge indices, or put them into separate sections +(*note Combining Indices::); or you may define your own indices (*note +Defining New Indices: New Indices.). + + The `@printindex' command takes a two-letter index name, reads the +corresponding sorted index file and formats it appropriately into an +index. + + The `@printindex' command does not generate a chapter heading for the +index. Consequently, you should precede the `@printindex' command with +a suitable section or chapter command (usually `@unnumbered') to supply +the chapter heading and put the index into the table of contents. +Precede the `@unnumbered' command with an `@node' line. + + For example: + + @node Variable Index, Concept Index, Function Index, Top + @comment node-name, next, previous, up + @unnumbered Variable Index + + @printindex vr + + @node Concept Index, , Variable Index, Top + @comment node-name, next, previous, up + @unnumbered Concept Index + + @printindex cp + + @summarycontents + @contents + @bye + +(Readers often prefer that the concept index come last in a book, since +that makes it easiest to find.) + + +File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File + +Generating a Table of Contents +============================== + +The `@chapter', `@section', and other structuring commands supply the +information to make up a table of contents, but they do not cause an +actual table to appear in the manual. To do this, you must use the +`@contents' and `@summarycontents' commands: + +`@contents' + Generate a table of contents in a printed manual, including all + chapters, sections, subsections, etc., as well as appendices and + unnumbered chapters. (Headings generated by the `@heading' series + of commands do not appear in the table of contents.) The + `@contents' command should be written on a line by itself. + +`@shortcontents' +`@summarycontents' + (`@summarycontents' is a synonym for `@shortcontents'; the two + commands are exactly the same.) + + Generate a short or summary table of contents that lists only the + chapters (and appendices and unnumbered chapters). Omit sections, + subsections and subsubsections. Only a long manual needs a short + table of contents in addition to the full table of contents. + + Write the `@shortcontents' command on a line by itself right + _before_ the `@contents' command. + + The table of contents commands automatically generate a chapter-like +heading at the top of the first table of contents page. Write the table +of contents commands at the very end of a Texinfo file, just before the +`@bye' command, following any index sections--anything in the Texinfo +file after the table of contents commands will be omitted from the +table of contents. + + When you print a manual with a table of contents, the table of +contents are printed last and numbered with roman numerals. You need +to place those pages in their proper place, after the title page, +yourself. (This is the only collating you need to do for a printed +manual. The table of contents is printed last because it is generated +after the rest of the manual is typeset.) + + Here is an example of where to write table of contents commands: + + INDICES... + @shortcontents + @contents + @bye + + Since an Info file uses menus instead of tables of contents, the Info +formatting commands ignore the `@contents' and `@shortcontents' +commands. + + +File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File + +`@bye' File Ending +================== + +An `@bye' command terminates TeX or Info formatting. None of the +formatting commands see any of the file following `@bye'. The `@bye' +command should be on a line by itself. + + If you wish, you may follow the `@bye' line with notes. These notes +will not be formatted and will not appear in either Info or a printed +manual; it is as if text after `@bye' were within `@ignore' ... `@end +ignore'. Also, you may follow the `@bye' line with a local variables +list. *Note Using Local Variables and the Compile Command: +Compile-Command, for more information. + + +File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top + +Chapter Structuring +******************* + +The "chapter structuring" commands divide a document into a hierarchy of +chapters, sections, subsections, and subsubsections. These commands +generate large headings; they also provide information for the table of +contents of a printed manual (*note Generating a Table of Contents: +Contents.). + + The chapter structuring commands do not create an Info node structure, +so normally you should put an `@node' command immediately before each +chapter structuring command (*note Nodes::). The only time you are +likely to use the chapter structuring commands without using the node +structuring commands is if you are writing a document that contains no +cross references and will never be transformed into Info format. + + It is unlikely that you will ever write a Texinfo file that is +intended only as an Info file and not as a printable document. If you +do, you might still use chapter structuring commands to create a +heading at the top of each node--but you don't need to. + +* Menu: + +* Tree Structuring:: A manual is like an upside down tree ... +* Structuring Command Types:: How to divide a manual into parts. +* makeinfo top:: The `@top' command, part of the `Top' node. +* chapter:: +* unnumbered & appendix:: +* majorheading & chapheading:: +* section:: +* unnumberedsec appendixsec heading:: +* subsection:: +* unnumberedsubsec appendixsubsec subheading:: +* subsubsection:: Commands for the lowest level sections. +* Raise/lower sections:: How to change commands' hierarchical level. + + +File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring + +Tree Structure of Sections +========================== + +A Texinfo file is usually structured like a book with chapters, +sections, subsections, and the like. This structure can be visualized +as a tree (or rather as an upside-down tree) with the root at the top +and the levels corresponding to chapters, sections, subsection, and +subsubsections. + + Here is a diagram that shows a Texinfo file with three chapters, each +of which has two sections. + + Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | + Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 + + In a Texinfo file that has this structure, the beginning of Chapter 2 +looks like this: + + @node Chapter 2, Chapter 3, Chapter 1, top + @chapter Chapter 2 + + The chapter structuring commands are described in the sections that +follow; the `@node' and `@menu' commands are described in following +chapters. (*Note Nodes::, and see *Note Menus::.) + + +File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring + +Types of Structuring Commands +============================= + +The chapter structuring commands fall into four groups or series, each +of which contains structuring commands corresponding to the +hierarchical levels of chapters, sections, subsections, and +subsubsections. + + The four groups are the `@chapter' series, the `@unnumbered' series, +the `@appendix' series, and the `@heading' series. + + Each command produces titles that have a different appearance on the +printed page or Info file; only some of the commands produce titles +that are listed in the table of contents of a printed book or manual. + + * The `@chapter' and `@appendix' series of commands produce numbered + or lettered entries both in the body of a printed work and in its + table of contents. + + * The `@unnumbered' series of commands produce unnumbered entries + both in the body of a printed work and in its table of contents. + The `@top' command, which has a special use, is a member of this + series (*note `@top': makeinfo top.). + + * The `@heading' series of commands produce unnumbered headings that + do not appear in a table of contents. The heading commands never + start a new page. + + * The `@majorheading' command produces results similar to using the + `@chapheading' command but generates a larger vertical whitespace + before the heading. + + * When an `@setchapternewpage' command says to do so, the + `@chapter', `@unnumbered', and `@appendix' commands start new + pages in the printed manual; the `@heading' commands do not. + + Here are the four groups of chapter structuring commands: + + + No new pages + Numbered Unnumbered Lettered and numbered Unnumbered + In contents In contents In contents Not in contents + + @top @majorheading + @chapter @unnumbered @appendix @chapheading + @section @unnumberedsec @appendixsec @heading + @subsection @unnumberedsubsec @appendixsubsec @subheading + @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading + + +File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring + +`@top' +====== + +The `@top' command is a special sectioning command that you use only +after an `@node Top' line at the beginning of a Texinfo file. The +`@top' command tells the `makeinfo' formatter which node is the `Top' +node. It has the same typesetting effect as `@unnumbered' (*note +`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed +information, see *Note The `@top' Command: makeinfo top command. + + +File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring + +`@chapter' +========== + +`@chapter' identifies a chapter in the document. Write the command at +the beginning of a line and follow it on the same line by the title of +the chapter. + + For example, this chapter in this manual is entitled "Chapter +Structuring"; the `@chapter' line looks like this: + + @chapter Chapter Structuring + + In TeX, the `@chapter' command creates a chapter in the document, +specifying the chapter title. The chapter is numbered automatically. + + In Info, the `@chapter' command causes the title to appear on a line +by itself, with a line of asterisks inserted underneath. Thus, in +Info, the above example produces the following output: + + Chapter Structuring + ******************* + + Texinfo also provides a command `@centerchap', which is analogous to +`@unnumbered', but centers its argument in the printed output. This +kind of stylistic choice is not usually offered by Texinfo. + + +File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring + +`@unnumbered', `@appendix' +========================== + +Use the `@unnumbered' command to create a chapter that appears in a +printed manual without chapter numbers of any kind. Use the +`@appendix' command to create an appendix in a printed manual that is +labelled by letter instead of by number. + + For Info file output, the `@unnumbered' and `@appendix' commands are +equivalent to `@chapter': the title is printed on a line by itself with +a line of asterisks underneath. (*Note `@chapter': chapter.) + + To create an appendix or an unnumbered chapter, write an `@appendix' +or `@unnumbered' command at the beginning of a line and follow it on +the same line by the title, as you would if you were creating a chapter. + + +File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring + +`@majorheading', `@chapheading' +=============================== + +The `@majorheading' and `@chapheading' commands put chapter-like +headings in the body of a document. + + However, neither command causes TeX to produce a numbered heading or +an entry in the table of contents; and neither command causes TeX to +start a new page in a printed manual. + + In TeX, an `@majorheading' command generates a larger vertical +whitespace before the heading than an `@chapheading' command but is +otherwise the same. + + In Info, the `@majorheading' and `@chapheading' commands are +equivalent to `@chapter': the title is printed on a line by itself with +a line of asterisks underneath. (*Note `@chapter': chapter.) + + +File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring + +`@section' +========== + +In a printed manual, an `@section' command identifies a numbered +section within a chapter. The section title appears in the table of +contents. In Info, an `@section' command provides a title for a +segment of text, underlined with `='. + + This section is headed with an `@section' command and looks like this +in the Texinfo file: + + @section @code{@@section} + + To create a section, write the `@section' command at the beginning of +a line and follow it on the same line by the section title. + + Thus, + + @section This is a section + +produces + + This is a section + ================= + +in Info. + + +File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring + +`@unnumberedsec', `@appendixsec', `@heading' +============================================ + +The `@unnumberedsec', `@appendixsec', and `@heading' commands are, +respectively, the unnumbered, appendix-like, and heading-like +equivalents of the `@section' command. (*Note `@section': section.) + +`@unnumberedsec' + The `@unnumberedsec' command may be used within an unnumbered + chapter or within a regular chapter or appendix to provide an + unnumbered section. + +`@appendixsec' +`@appendixsection' + `@appendixsection' is a longer spelling of the `@appendixsec' + command; the two are synonymous. + + Conventionally, the `@appendixsec' or `@appendixsection' command + is used only within appendices. + +`@heading' + You may use the `@heading' command anywhere you wish for a + section-style heading that will not appear in the table of + contents. + + +File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring + +The `@subsection' Command +========================= + +Subsections are to sections as sections are to chapters. (*Note +`@section': section.) In Info, subsection titles are underlined with +`-'. For example, + + @subsection This is a subsection + +produces + + This is a subsection + -------------------- + + In a printed manual, subsections are listed in the table of contents +and are numbered three levels deep. + + +File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring + +The `@subsection'-like Commands +=============================== + +The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' commands +are, respectively, the unnumbered, appendix-like, and heading-like +equivalents of the `@subsection' command. (*Note `@subsection': +subsection.) + + In Info, the `@subsection'-like commands generate a title underlined +with hyphens. In a printed manual, an `@subheading' command produces a +heading like that of a subsection except that it is not numbered and +does not appear in the table of contents. Similarly, an +`@unnumberedsubsec' command produces an unnumbered heading like that of +a subsection and an `@appendixsubsec' command produces a +subsection-like heading labelled with a letter and numbers; both of +these commands produce headings that appear in the table of contents. + + +File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring + +The `subsub' Commands +===================== + +The fourth and lowest level sectioning commands in Texinfo are the +`subsub' commands. They are: + +`@subsubsection' + Subsubsections are to subsections as subsections are to sections. + (*Note `@subsection': subsection.) In a printed manual, + subsubsection titles appear in the table of contents and are + numbered four levels deep. + +`@unnumberedsubsubsec' + Unnumbered subsubsection titles appear in the table of contents of + a printed manual, but lack numbers. Otherwise, unnumbered + subsubsections are the same as subsubsections. In Info, unnumbered + subsubsections look exactly like ordinary subsubsections. + +`@appendixsubsubsec' + Conventionally, appendix commands are used only for appendices and + are lettered and numbered appropriately in a printed manual. They + also appear in the table of contents. In Info, appendix + subsubsections look exactly like ordinary subsubsections. + +`@subsubheading' + The `@subsubheading' command may be used anywhere that you need a + small heading that will not appear in the table of contents. In + Info, subsubheadings look exactly like ordinary subsubsection + headings. + + In Info, `subsub' titles are underlined with periods. For example, + + @subsubsection This is a subsubsection + +produces + + This is a subsubsection + ....................... + + +File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring + +`@raisesections' and `@lowersections' +===================================== + +The `@raisesections' and `@lowersections' commands raise and lower the +hierarchical level of chapters, sections, subsections and the like. +The `@raisesections' command changes sections to chapters, subsections +to sections, and so on. The `@lowersections' command changes chapters +to sections, sections to subsections, and so on. + + An `@lowersections' command is useful if you wish to include text +that is written as an outer or standalone Texinfo file in another +Texinfo file as an inner, included file. If you write the command at +the beginning of the file, all your `@chapter' commands are formatted +as if they were `@section' commands, all your `@section' command are +formatted as if they were `@subsection' commands, and so on. + + `@raisesections' raises a command one level in the chapter +structuring hierarchy: + + Change To + + @subsection @section, + @section @chapter, + @heading @chapheading, + etc. + + `@lowersections' lowers a command one level in the chapter +structuring hierarchy: + + Change To + + @chapter @section, + @subsection @subsubsection, + @heading @subheading, + etc. + + An `@raisesections' or `@lowersections' command changes only those +structuring commands that follow the command in the Texinfo file. +Write an `@raisesections' or `@lowersections' command on a line of its +own. + + An `@lowersections' command cancels an `@raisesections' command, and +vice versa. Typically, the commands are used like this: + + @lowersections + @include somefile.texi + @raisesections + + Without the `@raisesections', all the subsequent sections in your +document will be lowered. + + Repeated use of the commands continue to raise or lower the +hierarchical level a step at a time. + + An attempt to raise above `chapters' reproduces chapter commands; an +attempt to lower below `subsubsections' reproduces subsubsection +commands. + + +File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top + +Nodes +***** + +"Nodes" are the primary segments of a Texinfo file. They do not +themselves impose a hierarchic or any other kind of structure on a file. +Nodes contain "node pointers" that name other nodes, and can contain +"menus" which are lists of nodes. In Info, the movement commands can +carry you to a pointed-to node or to a node listed in a menu. Node +pointers and menus provide structure for Info files just as chapters, +sections, subsections, and the like, provide structure for printed +books. + +* Menu: + +* Two Paths:: Different commands to structure + Info output and printed output. +* Node Menu Illustration:: A diagram, and sample nodes and menus. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'. + + +File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes + +Two Paths +========= + + The node and menu commands and the chapter structuring commands are +independent of each other: + + * In Info, node and menu commands provide structure. The chapter + structuring commands generate headings with different kinds of + underlining--asterisks for chapters, hyphens for sections, and so + on; they do nothing else. + + * In TeX, the chapter structuring commands generate chapter and + section numbers and tables of contents. The node and menu + commands provide information for cross references; they do nothing + else. + + You can use node pointers and menus to structure an Info file any way +you want; and you can write a Texinfo file so that its Info output has a +different structure than its printed output. However, most Texinfo +files are written such that the structure for the Info output +corresponds to the structure for the printed output. It is not +convenient to do otherwise. + + Generally, printed output is structured in a tree-like hierarchy in +which the chapters are the major limbs from which the sections branch +out. Similarly, node pointers and menus are organized to create a +matching structure in the Info output. + + +File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes + +Node and Menu Illustration +========================== + +Here is a copy of the diagram shown earlier that illustrates a Texinfo +file with three chapters, each of which contains two sections. + + Note that the "root" is at the top of the diagram and the "leaves" +are at the bottom. This is how such a diagram is drawn conventionally; +it illustrates an upside-down tree. For this reason, the root node is +called the `Top' node, and `Up' node pointers carry you closer to the +root. + + Top + | + ------------------------------------- + | | | + Chapter 1 Chapter 2 Chapter 3 + | | | + -------- -------- -------- + | | | | | | + Section Section Section Section Section Section + 1.1 1.2 2.1 2.2 3.1 3.2 + + Write the beginning of the node for Chapter 2 like this: + + @node Chapter 2, Chapter 3, Chapter 1, top + @comment node-name, next, previous, up + +This `@node' line says that the name of this node is "Chapter 2", the +name of the `Next' node is "Chapter 3", the name of the `Previous' node +is "Chapter 1", and the name of the `Up' node is "Top". + + *Please Note:* `Next' refers to the next node at the same + hierarchical level in the manual, not necessarily to the next node + within the Texinfo file. In the Texinfo file, the subsequent node + may be at a lower level--a section-level node may follow a + chapter-level node, and a subsection-level node may follow a + section-level node. `Next' and `Previous' refer to nodes at the + _same_ hierarchical level. (The `Top' node contains the exception + to this rule. Since the `Top' node is the only node at that + level, `Next' refers to the first following node, which is almost + always a chapter or chapter-level node.) + + To go to Sections 2.1 and 2.2 using Info, you need a menu inside +Chapter 2. (*Note Menus::.) You would write the menu just before the +beginning of Section 2.1, like this: + + @menu + * Sect. 2.1:: Description of this section. + * Sect. 2.2:: + @end menu + + Write the node for Sect. 2.1 like this: + + @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 + @comment node-name, next, previous, up + + In Info format, the `Next' and `Previous' pointers of a node usually +lead to other nodes at the same level--from chapter to chapter or from +section to section (sometimes, as shown, the `Previous' pointer points +up); an `Up' pointer usually leads to a node at the level above (closer +to the `Top' node); and a `Menu' leads to nodes at a level below (closer +to `leaves'). (A cross reference can point to a node at any level; see +*Note Cross References::.) + + Usually, an `@node' command and a chapter structuring command are +used in sequence, along with indexing commands. (You may follow the +`@node' line with a comment line that reminds you which pointer is +which.) + + Here is the beginning of the chapter in this manual called "Ending a +Texinfo File". This shows an `@node' line followed by a comment line, +an `@chapter' line, and then by indexing lines. + + @node Ending a File, Structuring, Beginning a File, Top + @comment node-name, next, previous, up + @chapter Ending a Texinfo File + @cindex Ending a Texinfo file + @cindex Texinfo file ending + @cindex File ending + + +File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes + +The `@node' Command +=================== + +A "node" is a segment of text that begins at an `@node' command and +continues until the next `@node' command. The definition of node is +different from that for chapter or section. A chapter may contain +sections and a section may contain subsections; but a node cannot +contain subnodes; the text of a node continues only until the next +`@node' command in the file. A node usually contains only one chapter +structuring command, the one that follows the `@node' line. On the +other hand, in printed output nodes are used only for cross references, +so a chapter or section may contain any number of nodes. Indeed, a +chapter usually contains several nodes, one for each section, +subsection, and subsubsection. + + To create a node, write an `@node' command at the beginning of a +line, and follow it with four arguments, separated by commas, on the +rest of the same line. These arguments are the name of the node, and +the names of the `Next', `Previous', and `Up' pointers, in that order. +You may insert spaces before each pointer if you wish; the spaces are +ignored. You must write the name of the node, and the names of the +`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, +the formatters fail. (*note info: (info)Top, for more information +about nodes in Info.) + + Usually, you write one of the chapter-structuring command lines +immediately after an `@node' line--for example, an `@section' or +`@subsection' line. (*Note Types of Structuring Commands: Structuring +Command Types.) + + *Please note:* The GNU Emacs Texinfo mode updating commands work + only with Texinfo files in which `@node' lines are followed by + chapter structuring lines. *Note Updating Requirements::. + + TeX uses `@node' lines to identify the names to use for cross +references. For this reason, you must write `@node' lines in a Texinfo +file that you intend to format for printing, even if you do not intend +to format it for Info. (Cross references, such as the one at the end +of this sentence, are made with `@xref' and its related commands; see +*Note Cross References::.) + +* Menu: + +* Node Names:: How to choose node and pointer names. +* Writing a Node:: How to write an `@node' line. +* Node Line Tips:: Keep names short. +* Node Line Requirements:: Keep names unique, without @-commands. +* First Node:: How to write a `Top' node. +* makeinfo top command:: How to use the `@top' command. +* Top Node Summary:: Write a brief description for readers. + + +File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node + +Choosing Node and Pointer Names +------------------------------- + + The name of a node identifies the node. The pointers enable you to +reach other nodes and consist of the names of those nodes. + + Normally, a node's `Up' pointer contains the name of the node whose +menu mentions that node. The node's `Next' pointer contains the name +of the node that follows that node in that menu and its `Previous' +pointer contains the name of the node that precedes it in that menu. +When a node's `Previous' node is the same as its `Up' node, both node +pointers name the same node. + + Usually, the first node of a Texinfo file is the `Top' node, and its +`Up' and `Previous' pointers point to the `dir' file, which contains +the main menu for all of Info. + + The `Top' node itself contains the main or master menu for the manual. +Also, it is helpful to include a brief description of the manual in the +`Top' node. *Note First Node::, for information on how to write the +first node of a Texinfo file. + + +File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node + +How to Write an `@node' Line +---------------------------- + +The easiest way to write an `@node' line is to write `@node' at the +beginning of a line and then the name of the node, like this: + + @node NODE-NAME + + If you are using GNU Emacs, you can use the update node commands +provided by Texinfo mode to insert the names of the pointers; or you +can leave the pointers out of the Texinfo file and let `makeinfo' +insert node pointers into the Info file it creates. (*Note Texinfo +Mode::, and *Note makeinfo Pointer Creation::.) + + Alternatively, you can insert the `Next', `Previous', and `Up' +pointers yourself. If you do this, you may find it helpful to use the +Texinfo mode keyboard command `C-c C-c n'. This command inserts +`@node' and a comment line listing the names of the pointers in their +proper order. The comment line helps you keep track of which arguments +are for which pointers. This comment line is especially useful if you +are not familiar with Texinfo. + + The template for a node line with `Next', `Previous', and `Up' +pointers looks like this: + + @node NODE-NAME, NEXT, PREVIOUS, UP + + If you wish, you can ignore `@node' lines altogether in your first +draft and then use the `texinfo-insert-node-lines' command to create +`@node' lines for you. However, we do not recommend this practice. It +is better to name the node itself at the same time that you write a +segment so you can easily make cross references. A large number of +cross references are an especially important feature of a good Info +file. + + After you have inserted an `@node' line, you should immediately write +an @-command for the chapter or section and insert its name. Next (and +this is important!), put in several index entries. Usually, you will +find at least two and often as many as four or five ways of referring +to the node in the index. Use them all. This will make it much easier +for people to find the node. + + +File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node + +`@node' Line Tips +----------------- + +Here are three suggestions: + + * Try to pick node names that are informative but short. + + In the Info file, the file name, node name, and pointer names are + all inserted on one line, which may run into the right edge of the + window. (This does not cause a problem with Info, but is ugly.) + + * Try to pick node names that differ from each other near the + beginnings of their names. This way, it is easy to use automatic + name completion in Info. + + * By convention, node names are capitalized just as they would be for + section or chapter titles--initial and significant words are + capitalized; others are not. + + +File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node + +`@node' Line Requirements +------------------------- + +Here are several requirements for `@node' lines: + + * All the node names for a single Info file must be unique. + + Duplicates confuse the Info movement commands. This means, for + example, that if you end every chapter with a summary, you must + name each summary node differently. You cannot just call each one + "Summary". You may, however, duplicate the titles of chapters, + sections, and the like. Thus you can end each chapter in a book + with a section called "Summary", so long as the node names for + those sections are all different. + + * A pointer name must be the name of a node. + + The node to which a pointer points may come before or after the + node containing the pointer. + + * You cannot use any of the Texinfo @-commands in a node name; + @-commands confuse Info. + + Thus, the beginning of the section called `@chapter' looks like + this: + + @node chapter, unnumbered & appendix, makeinfo top, Structuring + @comment node-name, next, previous, up + @section @code{@@chapter} + @findex chapter + + * You cannot use commas or apostrophes within a node name; these + confuse TeX or the Info formatters. + + For example, the following is a section title: + + @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} + + The corresponding node name is: + + unnumberedsec appendixsec heading + + * Case is significant. + + +File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node + +The First Node +-------------- + +The first node of a Texinfo file is the "Top" node, except in an +included file (*note Include Files::). The Top node contains the main +or master menu for the document, and a short summary of the document +(*note Top Node Summary::). + + The Top node (which must be named `top' or `Top') should have as its +`Up' node the name of a node in another file, where there is a menu +that leads to this file. Specify the file name in parentheses. If the +file is to be installed directly in the Info directory file, use +`(dir)' as the parent of the Top node; this is short for `(dir)top', +and specifies the Top node in the `dir' file, which contains the main +menu for the Info system as a whole. For example, the `@node Top' line +of this manual looks like this: + + @node Top, Copying, , (dir) + +(You can use the Texinfo updating commands or the `makeinfo' utility to +insert these pointers automatically.) + + Do not define the `Previous' node of the Top node to be `(dir)', as +it causes confusing behavior for users: if you are in the Top node and +hit to go backwards, you wind up in the middle of some other +entry in the `dir' file, which has nothing to do with what you were +reading. + + *Note Install an Info File::, for more information about installing +an Info file in the `info' directory. + + +File: texinfo.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node + +The `@top' Sectioning Command +----------------------------- + +A special sectioning command, `@top', has been created for use with the +`@node Top' line. The `@top' sectioning command tells `makeinfo' that +it marks the `Top' node in the file. It provides the information that +`makeinfo' needs to insert node pointers automatically. Write the +`@top' command at the beginning of the line immediately following the +`@node Top' line. Write the title on the remaining part of the same +line as the `@top' command. + + In Info, the `@top' sectioning command causes the title to appear on a +line by itself, with a line of asterisks inserted underneath. + + In TeX and `texinfo-format-buffer', the `@top' sectioning command is +merely a synonym for `@unnumbered'. Neither of these formatters +require an `@top' command, and do nothing special with it. You can use +`@chapter' or `@unnumbered' after the `@node Top' line when you use +these formatters. Also, you can use `@chapter' or `@unnumbered' when +you use the Texinfo updating commands to create or update pointers and +menus. + + +File: texinfo.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node + +The `Top' Node Summary +---------------------- + +You can help readers by writing a summary in the `Top' node, after the +`@top' line, before the main or master menu. The summary should +briefly describe the document. In Info, this summary will appear just +before the master menu. In a printed manual, this summary will appear +on a page of its own. + + If you do not want the summary to appear on a page of its own in a +printed manual, you can enclose the whole of the `Top' node, including +the `@node Top' line and the `@top' sectioning command line or other +sectioning command line between `@ifinfo' and `@end ifinfo'. This +prevents any of the text from appearing in the printed output. (*note +Conditionally Visible Text: Conditionals.). You can repeat the brief +description from the `Top' node within `@iftex' ... `@end iftex' at the +beginning of the first chapter, for those who read the printed manual. +This saves paper and may look neater. + + You should write the version number of the program to which the manual +applies in the summary. This helps the reader keep track of which +manual is for which version of the program. If the manual changes more +frequently than the program or is independent of it, you should also +include an edition number for the manual. (The title page should also +contain this information: see *Note `@titlepage': titlepage.) + + +File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes + +Creating Pointers with `makeinfo' +================================= + +The `makeinfo' program has a feature for automatically creating node +pointers for a hierarchically organized file that lacks them. + + When you take advantage of this feature, you do not need to write the +`Next', `Previous', and `Up' pointers after the name of a node. +However, you must write a sectioning command, such as `@chapter' or +`@section', on the line immediately following each truncated `@node' +line. You cannot write a comment line after a node line; the section +line must follow it immediately. + + In addition, you must follow the `Top' `@node' line with a line +beginning with `@top' to mark the `Top' node in the file. *Note `@top': +makeinfo top. + + Finally, you must write the name of each node (except for the `Top' +node) in a menu that is one or more hierarchical levels above the +node's hierarchical level. + + This node pointer insertion feature in `makeinfo' is an alternative +to the menu and pointer creation and update commands in Texinfo mode. +(*Note Updating Nodes and Menus::.) It is especially helpful to people +who do not use GNU Emacs for writing Texinfo documents. + + +File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top + +Menus +***** + +"Menus" contain pointers to subordinate nodes.(1) (*note +Menus-Footnote-1::) In Info, you use menus to go to such nodes. Menus +have no effect in printed manuals and do not appear in them. + + By convention, a menu is put at the end of a node since a reader who +uses the menu may not see text that follows it. + + A node that has a menu should _not_ contain much text. If you have a +lot of text and a menu, move most of the text into a new subnode--all +but a few lines. + +* Menu: + +* Menu Location:: Put a menu in a short node. +* Writing a Menu:: What is a menu? +* Menu Parts:: A menu entry has three parts. +* Less Cluttered Menu Entry:: Two part menu entry. +* Menu Example:: Two and three part menu entries. +* Other Info Files:: How to refer to a different Info file. + + +File: texinfo.info, Node: Menus-Footnotes, Up: Menus + + (1) Menus can carry you to any node, regardless of the hierarchical +structure; even to nodes in a different Info file. However, the GNU +Emacs Texinfo mode updating commands work only to create menus of +subordinate nodes. Conventionally, cross references are used to refer +to other nodes. + + +File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, Up: Menus + +Menus Need Short Nodes +====================== + + A reader can easily see a menu that is close to the beginning of the +node. The node should be short. As a practical matter, you should +locate a menu within 20 lines of the beginning of the node. Otherwise, +a reader with a terminal that displays only a few lines may miss the +menu and its associated text. + + The short text before a menu may look awkward in a printed manual. To +avoid this, you can write a menu near the beginning of its node and +follow the menu by an `@node' line, and then an `@heading' line located +within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line, +and title appear only in the Info file, not the printed document. + + For example, the preceding two paragraphs follow an Info-only menu, +`@node' line, and heading, and look like this: + + @menu + * Menu Location:: Put a menu in a short node. + * Writing a Menu:: What is a menu? + * Menu Parts:: A menu entry has three parts. + * Less Cluttered Menu Entry:: Two part menu entry. + * Menu Example:: Two and three part entries. + * Other Info Files:: How to refer to a different + Info file. + @end menu + + @node Menu Location, Writing a Menu, , Menus + @ifinfo + @heading Menus Need Short Nodes + @end ifinfo + + The Texinfo file for this document contains more than a dozen +examples of this procedure. One is at the beginning of this chapter; +another is at the beginning of the "Cross References" chapter. + + +File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus + +Writing a Menu +============== + +A menu consists of an `@menu' command on a line by itself followed by +menu entry lines or menu comment lines and then by an `@end menu' +command on a line by itself. + + A menu looks like this: + + @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu + + In a menu, every line that begins with an `* ' is a "menu entry". +(Note the space after the asterisk.) A line that does not start with +an `* ' may also appear in a menu. Such a line is not a menu entry but +is a menu comment line that appears in the Info file. In the example +above, the line `Larger Units of Text' is a menu comment line; the two +lines starting with `* ' are menu entries. + + +File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus + +The Parts of a Menu +=================== + +A menu entry has three parts, only the second of which is required: + + 1. The menu entry name (optional). + + 2. The name of the node (required). + + 3. A description of the item (optional). + + The template for a menu entry looks like this: + + * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION + + Follow the menu entry name with a single colon and follow the node +name with tab, comma, period, or newline. + + In Info, a user selects a node with the `m' (`Info-menu') command. +The menu entry name is what the user types after the `m' command. + + The third part of a menu entry is a descriptive phrase or sentence. +Menu entry names and node names are often short; the description +explains to the reader what the node is about. A useful description +complements the node name rather than repeats it. The description, +which is optional, can spread over two or more lines; if it does, some +authors prefer to indent the second line while others prefer to align it +with the first (and all others). It's up to you. + + +File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus + +Less Cluttered Menu Entry +========================= + +When the menu entry name and node name are the same, you can write the +name immediately after the asterisk and space at the beginning of the +line and follow the name with two colons. + + For example, write + + * Name:: DESCRIPTION + +instead of + + * Name: Name. DESCRIPTION + + You should use the node name for the menu entry name whenever +possible, since it reduces visual clutter in the menu. + + +File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus + +A Menu Example +============== + +A menu looks like this in Texinfo: + + @menu + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. + @end menu + +This produces: + + * menu: + + * menu entry name: Node name. A short description. + * Node name:: This form is preferred. + + Here is an example as you might see it in a Texinfo file: + + @menu + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + @end menu + +This produces: + + * menu: + Larger Units of Text + + * Files:: All about handling files. + * Multiples: Buffers. Multiple buffers; editing + several files at once. + + In this example, the menu has two entries. `Files' is both a menu +entry name and the name of the node referred to by that name. +`Multiples' is the menu entry name; it refers to the node named +`Buffers'. The line `Larger Units of Text' is a comment; it appears in +the menu, but is not an entry. + + Since no file name is specified with either `Files' or `Buffers', +they must be the names of nodes in the same Info file (*note Referring +to Other Info Files: Other Info Files.). + + +File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus + +Referring to Other Info Files +============================= + +You can create a menu entry that enables a reader in Info to go to a +node in another Info file by writing the file name in parentheses just +before the node name. In this case, you should use the three-part menu +entry format, which saves the reader from having to type the file name. + + The format looks like this: + + @menu + * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION + * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION + @end menu + + For example, to refer directly to the `Outlining' and `Rebinding' +nodes in the `XEmacs User's Manual', you would write a menu like this: + + @menu + * Outlining: (xemacs)Outline Mode. The major mode for + editing outlines. + * Rebinding: (xemacs)Rebinding. How to redefine the + meaning of a key. + @end menu + + 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 `dir' file that contains the main menu for Info has menu entries +that list only file names. These take you directly to the `Top' nodes +of each Info document. (*Note Install an Info File::.) + + For example: + + * Info: (info). Documentation browsing system. + * Emacs: (emacs). The extensible, self-documenting + text editor. + +(The `dir' top level directory for the Info system is an Info file, not +a Texinfo file, but a menu entry looks the same in both types of file.) + + Note that the GNU Emacs Texinfo mode menu updating commands only work +with nodes within the current buffer, so you cannot use them to create +menus that refer to other files. You must write such menus by hand. + + +File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top + +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 places 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:: How to refer to the beginning of another file. +* 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. +* uref:: How to refer to a uniform resource locator. + + +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 results in a page reference, +unless it is to another manual altogether, in which case the cross +reference names that manual. + + In Info, a cross reference results in 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 four different cross reference commands: + +`@xref' + Used to start a sentence in the printed manual saying `See ...' + or an Info cross-reference saying `*Note NAME: NODE.'. + +`@ref' + Used within or, more often, at the end of a sentence; same as + `@xref' for Info; produces just the reference in the printed + manual without a preceding `See'. + +`@pxref' + Used within parentheses to make a reference that suits both an Info + file and a printed book. 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 cross reference name for Info, a topic description or +section title 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 is an example of a full five-part cross reference: + + @xref{Node name, Cross Reference Name, Particular Topic, + info-file-name, A Printed Manual}, for details. + +which produces + + *Note Cross Reference Name: (info-file-name)Node name, + for details. + +in Info and + + See section "Particular Topic" in A Printed Manual, for details. + +in a printed book. + + The five possible 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 only for references within the + same document. + + 2. The cross reference name for the Info reference, if it is to be + different from the node name. If you include this argument, it + becomes the first part of the cross reference. 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. You need not include any + `.info' suffix on the file name, since Info readers try appending + it automatically. + + 5. The name of a printed manual from a different Texinfo file. + + The template for a full five argument cross reference looks like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, + INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. + + 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 CROSS-REFERENCE-NAME: NODE-NAME. + +In TeX, a cross reference looks like this: + + See Section SECTION-NUMBER [NODE-NAME], page PAGE. + +or like this + + See Section SECTION-NUMBER [TITLE-OR-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. + + *Please note:* Commas separate arguments in a cross reference; + avoid including them in the title or other part lest the formatters + mistake them for separators. + + +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. The Info formatters produce output that +the Info readers can use to jump to the reference; TeX produces output +that specifies the page and section number for you. + +For example, + + @xref{Tropical Storms}. + +produces + + *Note Tropical Storms::. + +and + + See Section 3.1 [Tropical Storms], page 24. + +(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 3.1 [Tropical Storms], page 24, for more info. + +(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + + +File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref + +`@xref' with Two Arguments +-------------------------- + +With two arguments, the second is used as the name of the Info cross +reference, while the first is still the name of the node to which the +cross reference points. + +The template is like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME}. + +For example, + + @xref{Electrical Effects, Lightning}. + +produces: + + *Note Lightning: Electrical Effects. + +and + + See Section 5.2 [Electrical Effects], page 57. + +(Note that in the preceding example the closing brace is followed by a +period; and that the node name is printed, not the cross reference +name.) + + You can write a clause after the cross reference, like this: + + @xref{Electrical Effects, Lightning}, for more info. + +which produces + *Note Lightning: Electrical Effects, for more info. + +and + + See Section 5.2 [Electrical Effects], page 57, for more info. + +(Note that in the preceding example the closing brace is followed by a +comma, and then by the clause, which is followed by a period.) + + +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 be the name of the section in the printed output, or +else state the topic discussed by that 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 to avoid placing a comma within the title or topic section of +a cross reference, or within any other section. The formatters divide +cross references into arguments according to the commas; a comma within +a title or other section will divide it into two arguments. In a +reference, you need to write a title such as "Clouds, Mist, and Fog" +without the commas. + + Also, remember to write a comma or period after the closing brace of a +`@xref' to terminate the cross reference. In the following examples, a +clause follows a terminating comma. + +The template is like this: + + @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}. + +For example, + + @xref{Electrical Effects, Lightning, Thunder and Lightning}, + for details. + +produces + + *Note Lightning: Electrical Effects, for details. + +and + + See Section 5.2 [Thunder and Lightning], page 57, 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 5.2 [Thunder and Lightning], page 57, for details. + + As a practical matter, it is often best to write cross references with +just the first argument if the node name and the section title are the +same, and with the first and third arguments if the node name and title +are different. + + Here are several examples from `The GNU Awk User's Guide': + + @xref{Sample Program}. + @xref{Glossary}. + @xref{Case-sensitivity, ,Case-sensitivity in Matching}. + @xref{Close Output, , Closing Output Files and Pipes}, + for more information. + @xref{Regexp, , Regular Expressions as Patterns}. + + +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, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC, + INFO-FILE-NAME, PRINTED-MANUAL-TITLE}. + +For example, + + @xref{Electrical Effects, Lightning, Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. + +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" in An Introduction to + Meteorology, for details. + +The title of the printed manual is typeset in italics; and the +reference lacks a page number since TeX cannot know to which page a +reference refers when that 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 cross reference name in Info. + +The template looks like this: + + @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME, + PRINTED-MANUAL-TITLE}, for details. + +which produces + + *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details. + +and + + See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details. + +For example, + + @xref{Electrical Effects, , Thunder and Lightning, + weather, An Introduction to Meteorology}, for details. + +produces + + *Note Thunder and Lightning: (weather)Electrical Effects, + for details. + +and + + See section "Thunder and Lightning" in 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; see *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" in The GNU Make Manual. + +In this example, `Top' is the name of the first 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{Hurricanes}. + +produces + + For more information, see *Note Hurricanes::. + +and + + For more information, see Section 8.2 [Hurricanes], page 123. + + 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 6.7 [Hurricanes], page 72. + +in a printed document, and the following in Info: + + Sea surges are described in *Note Hurricanes::. + + *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 its attempt 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. + +With one argument, a parenthetical cross reference looks like this: + + ... storms cause flooding (@pxref{Hurricanes}) ... + +which produces + + ... storms cause flooding (*Note Hurricanes::) ... + +and + + ... storms cause flooding (see Section 6.7 [Hurricanes], page 72) + ... + + With two arguments, a parenthetical cross reference has this template: + + ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ... + +which produces + + ... (*Note CROSS-REFERENCE-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.). + + *Please note:* Use `@pxref' only as a parenthetical reference. Do + not try to use `@pxref' as a clause in a sentence. It will look + bad in either the Info file, the printed output, or both. + + Also, parenthetical cross references look best at the ends of + sentences. Although you may write them in the middle of a + sentence, that location breaks up the flow of text. + + +File: texinfo.info, Node: inforef, Next: uref, 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 cross reference 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, CROSS-REFERENCE-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: uref, Prev: inforef, Up: Cross References + +`@uref{URL[, DISPLAYED-TEXT]}' +============================== + +`@uref' produces a reference to a uniform resource locator (URL). It +takes one mandatory argument, the URL, and one optional argument, the +text to display (the default is the URL itself). In HTML output, +`@uref' produces a link you can follow. For example: + + The official GNU ftp site is + @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu} + +produces (in text): + The official GNU ftp site is + `ftp://ftp.gnu.ai.mit.edu/pub/gnu' + +whereas + The official + @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, + GNU ftp site} holds programs and texts. + +produces (in text): + The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds + programs and texts. + +and (in HTML): + The official GNU ftp + site holds programs and texts. + + To merely indicate a URL, use `@url' (*note `@url': url.). + + +File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top + +Marking Words and Phrases +************************* + +In Texinfo, you can mark words and phrases in a variety of ways. The +Texinfo formatters use this information to determine how to highlight +the text. You can 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:: How to indicate definitions, files, 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. For example, metasyntactic variables are marked by +`@var', and code by `@code'. Since the pieces of text are labelled by +commands that tell what kind of object they are, it is easy to change +the way the Texinfo formatters prepare such text. (Texinfo is an +_intentional_ formatting language rather than a _typesetting_ +formatting language.) + + For example, in a printed manual, code is usually illustrated in a +typewriter font; `@code' tells TeX to typeset this text in this font. +But it would be easy to change the way TeX highlights code to use +another font, and 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 need 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. +* url:: How to indicate a world wide web reference. +* email:: How to indicate an electronic mail address. + + +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}' + Indicate 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. + +`@url{UNIFORM-RESOURCE-LOCATOR}' + Indicate a uniform resource locator for the World Wide Web. + +`@file{FILE-NAME}' + Indicate the name of a file. + +`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}' + Indicate an electronic mail address. + +`@dfn{TERM}' + Indicate 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 environment variables such as `TEXINPUTS', and other +variables. + + Use `@code' for command names in command languages that resemble +programming languages, such as Texinfo or the shell. For example, +`@code' and `@samp' are produced by writing `@code{@@code}' and +`@code{@@samp}' in the Texinfo source, respectively. + + Note, however, that you should not use `@code' for shell 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'. In this case, the rule is to choose the more pleasing format. + + 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 different +from the identifier `printf', and most likely is a misspelling of it. +Even in languages which are not case sensitive, it is confusing to a +human reader to see identifiers spelled in different ways. Pick one +spelling and always use that. If you do not want to start a sentence +with a command written all in lower case, you should rearrange the +sentence. + + Do not use the `@code' command for a string of characters shorter +than a syntactic token. If you are writing about `TEXINPU', which is +just a part of the name for the `TEXINPUTS' environment variable, you +should use `@samp'. + + 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 keystroke commands of +GNU Emacs (use `@kbd' instead) although you may use `@code' for the +names of the Emacs Lisp functions that the keystroke commands invoke. + + 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 single quotation marks around the text. + + 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 by +default produces a different font (slanted typewriter instead of normal +typewriter) in the printed manual, so users can distinguish the +characters they are supposed to type from those the computer outputs. + + Since the usage of `@kbd' varies from manual to manual, you can +control the font switching with the `@kbdinputstyle' command. This +command has no effect on Info output. Write this command at the +beginning of a line with a single word as an argument, one of the +following: +`code' + Always use the same font for `@kbd' as `@code'. + +`example' + Use the distinguishing font for `@kbd' only in `@example' and + similar environments. + +`example' + (the default) Always use the distinguishing font for `@kbd'. + + 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 + key": + + @kbd{r @key{RET}} + +This produces: `r ' + + 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 + '. + + (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 ' you would type: + + @kbd{C-x @key{ESC}} + + Here is a list of the recommended names for keys: + + SPC + Space + + RET + Return + + LFD + Linefeed (however, since most keyboards nowadays do not have + a Linefeed key, it might be better to call this character + `C-j'. + + TAB + Tab + + BS + Backspace + + ESC + Escape + + DEL + Delete + + SHIFT + Shift + + CTRL + Control + + META + Meta + + There are subtleties to handling words like `meta' or `ctrl' that are +names of modifier keys. When mentioning a character in which the +modifier key is used, such as `Meta-a', use the `@kbd' command alone; +do not use the `@key' command; but when you are referring to the +modifier key in isolation, use the `@key' command. For example, write +`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce . + + +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 or +`sample' of a sequence of characters in a file, string, pattern, etc. +Enclose the text in braces. The argument appears within single +quotation marks 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' or `@key' is more appropriate. Use `@samp' for +the names of command-line options (except in an `@table', where `@code' +seems to read more easily). Also, you may use `@samp' for entire +statements in C and for entire shell commands--in this case, `@samp' +often looks better than `@code'. 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 Emacs 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 change the case of the +argument to all upper case; 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 Texinfo source for the +illustration of how to begin a Texinfo manual looks like this: + + \input texinfo + @@setfilename @var{info-file-name} + @@settitle @var{name-of-manual} + +This produces: + + \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 that Texinfo uses. (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 file name suffixes. Do not use `@file' for symbols +in a programming language; use `@code'. + + Currently, `@file' is equivalent to `@samp' in its effects. 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 does not +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 need 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, Next: url, 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 a reader can easily follow such a reference in +Info. *Note `@xref': xref.) + + +File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating + +`@url'{UNIFORM-RESOURCE-LOCATOR} +-------------------------------- + +Use the `@url' to indicate a uniform resource locator on the World Wide +Web. This is analogous to `@file', `@var', etc., and is purely for +markup purposes. It does not produce a link you can follow in HTML +output (the `@uref' command does, *note `@uref': uref.). It is useful +for example URL's which do not actually exist. For example: + + For example, the url might be + @url{http://host.domain.org/path}. + + +File: texinfo.info, Node: email, Prev: url, Up: Indicating + +`@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]} +----------------------------------------- + +Use the `@email' command to indicate an electronic mail address. It +takes one mandatory argument, the address, and one optional argument, +the text to display (the default is the address itself). + + In Info and TeX, the address is shown in angle brackets, preceded by +the text to display if any. In HTML output, `@email' produces a +`mailto' link that usually brings up a mail composition window. For +example: + + Send bug reports to @email{bug-texinfo@@gnu.org}. + Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. + +produces + Send bug reports to . + Send suggestions to the same place . + + +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; an example is the `@code' command. +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 commands to do this. Also, Texinfo has several commands that +specify the font in which TeX will typeset text. These commands have +no affect on Info and only one of them, the `@r' command, has any +regular use. + +* Menu: + +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. + + +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:} @samp{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. + + In the Info file, both `@emph' and `@strong' put asterisks around the +text. + + *Caution:* Do not 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. The Info formatting +commands set all small caps text in upper case. + + If the text between the braces of an `@sc' command is upper case, TeX +typesets in full-size capitals. Use full-size capitals sparingly. + + 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, Next: Customized Highlighting, 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, typewriter-style +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: Customized Highlighting, Prev: Fonts, Up: Emphasis + +Customized Highlighting +----------------------- + +You can use regular TeX commands inside of `@iftex' ... `@end iftex' +to create your own customized highlighting commands for Texinfo. The +easiest way to do this is to equate your customized commands with +pre-existing commands, such as those for italics. Such new commands +work only with TeX. + + You can use the `@definfoenclose' command inside of `@ifinfo' ... +`@end ifinfo' to define commands for Info with the same names as new +commands for TeX. `@definfoenclose' creates new commands for Info that +mark text by enclosing it in strings that precede and follow the text. +(1) (*note Customized Highlighting-Footnote-1::) + + Here is how to create a new @-command called `@phoo' that causes TeX +to typeset its argument in italics and causes Info to display the +argument between `//' and `\\'. + + For TeX, write the following to equate the `@phoo' command with the +existing `@i' italics command: + + @iftex + @global@let@phoo=@i + @end iftex + +This defines `@phoo' as a command that causes TeX to typeset the +argument to `@phoo' in italics. `@global@let' tells TeX to equate the +next argument with the argument that follows the equals sign. + + For Info, write the following to tell the Info formatters to enclose +the argument between `//' and `\\': + + @ifinfo + @definfoenclose phoo, //, \\ + @end ifinfo + +Write the `@definfoenclose' command on a line and follow it with three +arguments separated by commas (commas are used as separators in an +`@node' line in the same way). + + * The first argument to `@definfoenclose' is the @-command name + *without* the `@'; + + * the second argument is the Info start delimiter string; and, + + * the third argument is the Info end delimiter string. + +The latter two arguments enclose the highlighted text in the Info file. +A delimiter string may contain spaces. Neither the start nor end +delimiter is required. However, if you do not provide a start +delimiter, you must follow the command name with two commas in a row; +otherwise, the Info formatting commands will misinterpret the end +delimiter string as a start delimiter string. + + After you have defined `@phoo' both for TeX and for Info, you can +then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in +italics in printed output. + + Note that each definition applies to its own formatter: one for TeX, +the other for Info. + + Here is another example: + + @ifinfo + @definfoenclose headword, , : + @end ifinfo + @iftex + @global@let@headword=@b + @end iftex + +This defines `@headword' as an Info formatting command that inserts +nothing before and a colon after the argument and as a TeX formatting +command to typeset its argument in bold. + + +File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting + + (1) Currently, `@definfoenclose' works only with +`texinfo-format-buffer' and `texinfo-format-region', not with +`makeinfo'. + + +File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, 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 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 paragraph indentation. +* Lisp Example:: How to illustrate 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:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. + + +File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples + +The Block Enclosing Commands +============================ + +Here are commands for quotations and examples: + +`@quotation' + Indicate text that is quoted. The text is filled, indented, and + printed in a roman font by default. + +`@example' + Illustrate code, commands, and the like. The text is printed in a + fixed-width font, and indented but not filled. + +`@lisp' + Illustrate Lisp code. The text is printed in a fixed-width font, + and indented but not filled. + +`@smallexample' + Illustrate code, commands, and the like. Similar to `@example', + except that in TeX this command typesets text in a smaller font + for the smaller `@smallbook' format than for the 8.5 by 11 inch + format. + +`@smalllisp' + Illustrate Lisp code. Similar to `@lisp', except that in TeX this + command typesets text in a smaller font for the smaller + `@smallbook' format than for the 8.5 by 11 inch format. + +`@display' + Display illustrative text. The text is indented but not filled, + and no font is specified (so, by default, the font is roman). + +`@format' + Print illustrative text. The text is not indented and not filled + and no font is specified (so, by default, the font is roman). + + The `@exdent' command is used within the above constructs to undo the +indentation of a line. + + The `@flushleft' and `@flushright' commands are used to line up the +left or right margins of unfilled text. + + The `@noindent' command may be used after one of the above constructs +to prevent the following text from being indented as a new paragraph. + + You can use the `@cartouche' command within one of the above +constructs to highlight the example or quotation by drawing a box with +rounded corners around it. (The `@cartouche' command affects only the +printed manual; it has no effect in the Info file; see *Note Drawing +Cartouches Around Examples: cartouche.) + + +File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples + +`@quotation' +============ + +The text of a quotation is processed normally except that: + + * the margins are closer to the center of the page, so the whole of + the quotation is indented; + + * the first lines of paragraphs are indented no more than other + lines; + + * in the printed output, interparagraph spacing is reduced. + + This is an example of text written between an `@quotation' command + and an `@end quotation' command. An `@quotation' command is most + often used to indicate text that is excerpted from another (real + or hypothetical) printed work. + + Write an `@quotation' command as text on a line by itself. This line +will disappear from the output. Mark the end of the quotation with a +line beginning with and containing only `@end quotation'. The `@end +quotation' line will likewise disappear from the output. Thus, the +following, + + @quotation + This is + a foo. + @end quotation + +produces + + This is a foo. + + +File: texinfo.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples + +`@example' +========== + +The `@example' command is used to indicate an example that is not part +of the running text, such as computer input or output. + + This is an example of text written between an + `@example' command + and an `@end example' command. + The text is indented but not filled. + + In the printed manual, the text is typeset in a + fixed-width font, and extra spaces and blank lines are + significant. In the Info file, an analogous result is + obtained by indenting each line with five spaces. + + Write an `@example' command at the beginning of a line by itself. +This line will disappear from the output. Mark the end of the example +with an `@end example' command, also written at the beginning of a line +by itself. The `@end example' will disappear from the output. + + For example, + + @example + mv foo bar + @end example + +produces + + mv foo bar + + Since the lines containing `@example' and `@end example' will +disappear, you should put a blank line before the `@example' and +another blank line after the `@end example'. (Remember that blank +lines between the beginning `@example' and the ending `@end example' +will appear in the output.) + + *Caution:* Do not use tabs in the lines of an example (or anywhere + else in Texinfo, for that matter)! TeX treats tabs as single + spaces, and that is not what they look like. This is a problem + with TeX. (If necessary, in Emacs, you can use `M-x untabify' to + convert tabs in a region to multiple spaces.) + + Examples are often, logically speaking, "in the middle" of a +paragraph, and the text continues after an example should not be +indented. The `@noindent' command prevents a piece of text from being +indented as if it were a new paragraph. (*Note noindent::.) + + (The `@code' command is used for examples of code that are embedded +within sentences, not set off from preceding and following text. *Note +`@code': code.) + + +File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples + +`@noindent' +=========== + +An example or other inclusion can break a paragraph into segments. +Ordinarily, the formatters indent text that follows an example as a new +paragraph. However, you can prevent this by writing `@noindent' at the +beginning of a line by itself preceding the continuation text. + + For example: + + @example + This is an example + @end example + + @noindent + This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + @code{@@display} and @code{@@end display}.) + +produces + + This is an example + + + This line is not indented. As you can see, the + beginning of the line is fully flush left with the line + that follows after it. (This whole example is between + `@display' and `@end display'.) + + To adjust the number of blank lines properly in the Info file output, +remember that the line containing `@noindent' does not generate a blank +line, and neither does the `@end example' line. + + In the Texinfo source file for this manual, each line that says +`produces' is preceded by a line containing `@noindent'. + + Do not put braces after an `@noindent' command; they are not +necessary, since `@noindent' is a command used outside of paragraphs +(*note Command Syntax::). + + +File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples + +`@lisp' +======= + +The `@lisp' command is used for Lisp code. It is synonymous with the +`@example' command. + + This is an example of text written between an + `@lisp' command and an `@end lisp' command. + + Use `@lisp' instead of `@example' to preserve information regarding +the nature of the example. This is useful, for example, if you write a +function that evaluates only and all the Lisp code in a Texinfo file. +Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp +Example-Footnote-1::) + + Mark the end of `@lisp' with `@end lisp' on a line by itself. + + +File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example + + (1) It would be straightforward to extend Texinfo to work in a +similar fashion for C, Fortran, or other languages. + + +File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples + +`@smallexample' and `@smalllisp' +================================ + +In addition to the regular `@example' and `@lisp' commands, Texinfo has +two other "example-style" commands. These are the `@smallexample' and +`@smalllisp' commands. Both these commands are designed for use with +the `@smallbook' command that causes TeX to produce a printed manual in +a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. + + In TeX, the `@smallexample' and `@smalllisp' commands typeset text in +a smaller font for the smaller `@smallbook' format than for the 8.5 by +11 inch format. Consequently, many examples containing long lines fit +in a narrower, `@smallbook' page without needing to be shortened. Both +commands typeset in the normal font size when you format for the 8.5 by +11 inch size; indeed, in this situation, the `@smallexample' and +`@smalllisp' commands are defined to be the `@example' and `@lisp' +commands. + + In Info, the `@smallexample' and `@smalllisp' commands are equivalent +to the `@example' and `@lisp' commands, and work exactly the same. + + Mark the end of `@smallexample' or `@smalllisp' with `@end +smallexample' or `@end smalllisp', respectively. + + This is an example of text written between `@smallexample' and + `@end smallexample'. In Info and in an 8.5 by 11 inch manual, + this text appears in its normal size; but in a 7 by 9.25 inch manual, + this text appears in a smaller font. + + The `@smallexample' and `@smalllisp' commands make it easier to +prepare smaller format manuals without forcing you to edit examples by +hand to fit them onto narrower pages. + + As a general rule, a printed document looks better if you write all +the examples in a chapter consistently in `@example' or in +`@smallexample'. Only occasionally should you mix the two formats. + + *Note Printing "Small" Books: smallbook, for more information about +the `@smallbook' command. + + +File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples + +`@display' +========== + +The `@display' command begins a kind of example. It is like the +`@example' command except that, in a printed manual, `@display' does +not select the fixed-width font. In fact, it does not specify the font +at all, so that the text appears in the same font it would have +appeared in without the `@display' command. + + This is an example of text written between an `@display' command + and an `@end display' command. The `@display' command + indents the text, but does not fill it. + + +File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples + +`@format' +========= + +The `@format' command is similar to `@example' except that, in the +printed manual, `@format' does not select the fixed-width font and does +not narrow the margins. + +This is an example of text written between an `@format' command +and an `@end format' command. As you can see +from this example, +the `@format' command does not fill the text. + + +File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples + +`@exdent': Undoing a Line's Indentation +======================================= + +The `@exdent' command removes any indentation a line might have. The +command is written at the beginning of a line and applies only to the +text that follows the command that is on the same line. Do not use +braces around the text. In a printed manual, the text on an `@exdent' +line is printed in the roman font. + + `@exdent' is usually used within examples. Thus, + + @example + This line follows an @@example command. + @exdent This line is exdented. + This line follows the exdented line. + The @@end example comes on the next line. + @end group + +produces + + This line follows an @example command. +This line is exdented. + This line follows the exdented line. + The @end example comes on the next line. + + In practice, the `@exdent' command is rarely used. Usually, you +un-indent text by ending the example and returning the page to its +normal width. + + +File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples + +`@flushleft' and `@flushright' +============================== + +The `@flushleft' and `@flushright' commands line up the ends of lines +on the left and right margins of a page, but do not fill the text. The +commands are written on lines of their own, without braces. The +`@flushleft' and `@flushright' commands are ended by `@end flushleft' +and `@end flushright' commands on lines of their own. + + For example, + + @flushleft + This text is + written flushleft. + @end flushleft + +produces + + This text is + written flushleft. + + `@flushright' produces the type of indentation often used in the +return address of letters. For example, + + @flushright + Here is an example of text written + flushright. The @code{@flushright} command + right justifies every line but leaves the + left end ragged. + @end flushright + +produces + + Here is an example of text written + flushright. The `@flushright' command + right justifies every line but leaves the + left end ragged. + + +File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples + +Drawing Cartouches Around Examples +================================== + +In a printed manual, the `@cartouche' command draws a box with rounded +corners around its contents. You can use this command to further +highlight an example or quotation. For instance, you could write a +manual in which one type of example is surrounded by a cartouche for +emphasis. + + The `@cartouche' command affects only the printed manual; it has no +effect in the Info file. + + For example, + + @example + @cartouche + % pwd + /usr/local/share/emacs + @end cartouche + @end example + +surrounds the two-line example with a box with rounded corners, in the +printed manual. + + +File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top + +Lists and Tables +**************** + +Texinfo has several ways of making lists and tables. Lists can be +bulleted or numbered; two-column tables can highlight the items in the +first column; multi-column tables are also supported. + +* Menu: + +* Introducing Lists:: Texinfo formats lists for you. +* itemize:: How to construct a simple list. +* enumerate:: How to construct a numbered list. +* Two-column Tables:: How to construct a two-column table. +* Multi-column Tables:: How to construct generalized tables. + + +File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables + +Introducing Lists +================= + + Texinfo automatically indents the text in lists or tables, and numbers +an enumerated list. This last feature is useful if you modify the +list, since you do not need to renumber it yourself. + + Numbered lists and tables begin with the appropriate @-command at the +beginning of a line, and end with the corresponding `@end' command on a +line by itself. The table and itemized-list commands also require that +you write formatting information on the same line as the beginning +@-command. + + Begin an enumerated list, for example, with an `@enumerate' command +and end the list with an `@end enumerate' command. Begin an itemized +list with an `@itemize' command, followed on the same line by a +formatting command such as `@bullet', and end the list with an `@end +itemize' command. + + Precede each element of a list with an `@item' or `@itemx' command. + + +Here is an itemized list of the different kinds of table and lists: + + * Itemized lists with and without bullets. + + * Enumerated lists, using numbers or letters. + + * Two-column tables with highlighting. + + +Here is an enumerated list with the same items: + + 1. Itemized lists with and without bullets. + + 2. Enumerated lists, using numbers or letters. + + 3. Two-column tables with highlighting. + + +And here is a two-column table with the same items and their @-commands: + +`@itemize' + Itemized lists with and without bullets. + +`@enumerate' + Enumerated lists, using numbers or letters. + +`@table' +`@ftable' +`@vtable' + Two-column tables with indexing. + + +File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables + +Making an Itemized List +======================= + +The `@itemize' command produces sequences of indented paragraphs, with +a bullet or other mark inside the left margin at the beginning of each +paragraph for which such a mark is desired. + + Begin an itemized list by writing `@itemize' at the beginning of a +line. Follow the command, on the same line, with a character or a +Texinfo command that generates a mark. Usually, you will write +`@bullet' after `@itemize', but you can use `@minus', or any character +or any special symbol that results in a single character in the Info +file. (When you write `@bullet' or `@minus' after an `@itemize' +command, you may omit the `{}'.) + + Write the text of the indented paragraphs themselves after the +`@itemize', up to another line that says `@end itemize'. + + Before each paragraph for which a mark in the margin is desired, write +a line that says just `@item'. Do not write any other text on this +line. + + Usually, you should put a blank line before an `@item'. This puts a +blank line in the Info file. (TeX inserts the proper interline +whitespace in either case.) Except when the entries are very brief, +these blank lines make the list look better. + + Here is an example of the use of `@itemize', followed by the output +it produces. Note that `@bullet' produces a `*' in Info and a round +dot in TeX. + + @itemize @bullet + @item + Some text for foo. + + @item + Some text + for bar. + @end itemize + +This produces: + + * Some text for foo. + + * Some text for bar. + + Itemized lists may be embedded within other itemized lists. Here is a +list marked with dashes embedded in a list marked with bullets: + + @itemize @bullet + @item + First item. + + @itemize @minus + @item + Inner item. + + @item + Second inner item. + @end itemize + + @item + Second outer item. + @end itemize + +This produces: + + * First item. + + - Inner item. + + - Second inner item. + + * Second outer item. + + +File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables + +Making a Numbered or Lettered List +================================== + +`@enumerate' is like `@itemize' (*note `@itemize': itemize.), except +that the labels on the items are successive integers or letters instead +of bullets. + + Write the `@enumerate' command at the beginning of a line. The +command does not require an argument, but accepts either a number or a +letter as an option. Without an argument, `@enumerate' starts the list +with the number `1'. With a numeric argument, such as `3', the command +starts the list with that number. With an upper or lower case letter, +such as `a' or `A', the command starts the list with that letter. + + Write the text of the enumerated list in the same way you write an +itemized list: put `@item' on a line of its own before the start of +each paragraph that you want enumerated. Do not write any other text +on the line beginning with `@item'. + + You should put a blank line between entries in the list. This +generally makes it easier to read the Info file. + + Here is an example of `@enumerate' without an argument: + + @enumerate + @item + Underlying causes. + + @item + Proximate causes. + @end enumerate + +This produces: + + 1. Underlying causes. + + 2. Proximate causes. + + + Here is an example with an argument of `3': + + @enumerate 3 + @item + Predisposing causes. + + @item + Precipitating causes. + + @item + Perpetuating causes. + @end enumerate + +This produces: + + 3. Predisposing causes. + + 4. Precipitating causes. + + 5. Perpetuating causes. + + + Here is a brief summary of the alternatives. The summary is +constructed using `@enumerate' with an argument of `a'. + + a. `@enumerate' + + Without an argument, produce a numbered list, starting with the + number 1. + + b. `@enumerate POSITIVE-INTEGER' + + With a (positive) numeric argument, start a numbered list with that + number. You can use this to continue a list that you interrupted + with other text. + + c. `@enumerate UPPER-CASE-LETTER' + + With an upper case letter as argument, start a list in which each + item is marked by a letter, beginning with that upper case letter. + + d. `@enumerate LOWER-CASE-LETTER' + + With a lower case letter as argument, start a list in which each + item is marked by a letter, beginning with that lower case letter. + + You can also nest enumerated lists, as in an outline. + + +File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables + +Making a Two-column Table +========================= + +`@table' is similar to `@itemize' (*note `@itemize': itemize.), but +allows you to specify a name or heading line for each item. The +`@table' command is used to produce two-column tables, and is +especially useful for glossaries, explanatory exhibits, and +command-line option summaries. + +* Menu: + +* table:: How to construct a two-column table. +* ftable vtable:: Automatic indexing for two-column tables. +* itemx:: How to put more entries in the first column. + + +File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables + +Using the `@table' Command +-------------------------- + +Use the `@table' command to produce two-column tables. + + Write the `@table' command at the beginning of a line and follow it +on the same line with an argument that is a Texinfo "indicating" +command such as `@code', `@samp', `@var', or `@kbd' (*note +Indicating::). Although these commands are usually followed by +arguments in braces, in this case you use the command name without an +argument because `@item' will supply the argument. This command will +be applied to the text that goes into the first column of each item and +determines how it will be highlighted. For example, `@code' will cause +the text in the first column to be highlighted with an `@code' command. +(We recommend `@code' for `@table''s of command-line options.) + + You may also choose to use the `@asis' command as an argument to +`@table'. `@asis' is a command that does nothing; if you use this +command after `@table', TeX and the Info formatting commands output the +first column entries without added highlighting ("as is"). + + (The `@table' command may work with other commands besides those +listed here. However, you can only use commands that normally take +arguments in braces.) + + Begin each table entry with an `@item' command at the beginning of a +line. Write the first column text on the same line as the `@item' +command. Write the second column text on the line following the +`@item' line and on subsequent lines. (You do not need to type +anything for an empty second column entry.) You may write as many +lines of supporting text as you wish, even several paragraphs. But +only text on the same line as the `@item' will be placed in the first +column. + + Normally, you should put a blank line before an `@item' line. This +puts a blank like in the Info file. Except when the entries are very +brief, a blank line looks better. + + The following table, for example, highlights the text in the first +column with an `@samp' command: + + @table @samp + @item foo + This is the text for + @samp{foo}. + + @item bar + Text for @samp{bar}. + @end table + +This produces: + +`foo' + This is the text for `foo'. + +`bar' + Text for `bar'. + + If you want to list two or more named items with a single block of +text, use the `@itemx' command. (*Note `@itemx': itemx.) + + +File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables + +`@ftable' and `@vtable' +----------------------- + +The `@ftable' and `@vtable' commands are the same as the `@table' +command except that `@ftable' automatically enters each of the items in +the first column of the table into the index of functions and `@vtable' +automatically enters each of the items in the first column of the table +into the index of variables. This simplifies the task of creating +indices. Only the items on the same line as the `@item' commands are +indexed, and they are indexed in exactly the form that they appear on +that line. *Note Creating Indices: Indices, for more information about +indices. + + Begin a two-column table using `@ftable' or `@vtable' by writing the +@-command at the beginning of a line, followed on the same line by an +argument that is a Texinfo command such as `@code', exactly as you +would for an `@table' command; and end the table with an `@end ftable' +or `@end vtable' command on a line by itself. + + See the example for `@table' in the previous section. + + +File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables + +`@itemx' +-------- + +Use the `@itemx' command inside a table when you have two or more first +column entries for the same item, each of which should appear on a line +of its own. Use `@itemx' for all but the first entry; `@itemx' should +always follow an `@item' command. The `@itemx' command works exactly +like `@item' except that it does not generate extra vertical space +above the first column text. + + For example, + + @table @code + @item upcase + @itemx downcase + These two functions accept a character or a string as + argument, and return the corresponding upper case (lower + case) character or string. + @end table + +This produces: + +`upcase' +`downcase' + These two functions accept a character or a string as argument, + and return the corresponding upper case (lower case) character or + string. + +(Note also that this example illustrates multi-line supporting text in +a two-column table.) + + +File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables + +Multi-column Tables +=================== + +`@multitable' allows you to construct tables with any number of +columns, with each column having any width you like. + + You define the column widths on the `@multitable' line itself, and +write each row of the actual table following an `@item' command, with +columns separated by an `@tab' command. Finally, `@end multitable' +completes the table. Details in the sections below. + +* Menu: + +* Multitable Column Widths:: Defining multitable column widths. +* Multitable Rows:: Defining multitable rows, with examples. + + +File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables + +Multitable Column Widths +------------------------ + +You can define the column widths for a multitable in two ways: as +fractions of the line length; or with a prototype row. Mixing the two +methods is not supported. In either case, the widths are defined +entirely on the same line as the `@multitable' command. + + 1. To specify column widths as fractions of the line length, write + `@columnfractions' and the decimal numbers (presumably less than + 1) after the `@multitable' command, as in: + + @multitable @columnfractions .33 .33 .33 + + The fractions need not add up exactly to 1.0, as these do not. + This allows you to produce tables that do not need the full line + length. + + 2. To specify a prototype row, write the longest entry for each column + enclosed in braces after the `@multitable' command. For example: + + @multitable {some text for column one} {for column two} + + The first column will then have the width of the typeset `some + text for column one', and the second column the width of `for + column two'. + + The prototype entries need not appear in the table itself. + + Although we used simple text in this example, the prototype + entries can contain Texinfo commands; markup commands such as + `@code' are particularly likely to be useful. + + + +File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables + +Multitable Rows +--------------- + +After the `@multitable' command defining the column widths (see the +previous section), you begin each row in the body of a multitable with +`@item', and separate the column entries with `@tab'. Line breaks are +not special within the table body, and you may break input lines in +your source file as necessary. + + Here is a complete example of a multi-column table (the text is from +`The XEmacs Users' Manual', *note Splitting Windows: (xemacs)Split +Window.): + + @multitable @columnfractions .15 .45 .4 + @item Key @tab Command @tab Description + @item C-x 2 + @tab @code{split-window-vertically} + @tab Split the selected window into two windows, + with one above the other. + @item C-x 3 + @tab @code{split-window-horizontally} + @tab Split the selected window into two windows + positioned side by side. + @item C-Mouse-2 + @tab + @tab In the mode line or scroll bar of a window, + split that window. + @end multitable + +produces: + +Key Command Description +C-x 2 `split-window-vertically' Split the selected window + into two windows, with one + above the other. +C-x 3 `split-window-horizontally' Split the selected window + into two windows positioned + side by side. +C-Mouse-2 In the mode line or scroll + bar of a window, split that + window. + + +File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top + +Creating Indices +**************** + +Using Texinfo, you can generate indices without having to sort and +collate entries manually. In an index, the entries are listed in +alphabetical order, together with information on how to find the +discussion of each entry. In a printed manual, this information +consists of page numbers. In an Info file, this information is a menu +entry leading to the first node referenced. + + Texinfo provides several predefined kinds of index: an index for +functions, an index for variables, an index for concepts, and so on. +You can combine indices or use them for other than their canonical +purpose. If you wish, you can define your own indices. + +* Menu: + +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entry. +* Indexing Commands:: How to make an index entry. +* Combining Indices:: How to combine indices. +* New Indices:: How to define your own indices. + + +File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices + +Making Index Entries +==================== + +When you are making index entries, it is good practice to think of the +different ways people may look for something. Different people _do +not_ think of the same words when they look something up. A helpful +index will have items indexed under all the different words that people +may use. For example, one reader may think it obvious that the +two-letter names for indices should be listed under "Indices, +two-letter names", since the word "Index" is the general concept. But +another reader may remember the specific concept of two-letter names +and search for the entry listed as "Two letter names for indices". A +good index will have both entries and will help both readers. + + Like typesetting, the construction of an index is a highly skilled, +professional art, the subtleties of which are not appreciated until you +need to do it yourself. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices + +Predefined Indices +================== + +Texinfo provides six predefined indices: + + * A "concept index" listing concepts that are discussed. + + * A "function index" listing functions (such as entry points of + libraries). + + * A "variables index" listing variables (such as global variables of + libraries). + + * A "keystroke index" listing keyboard commands. + + * A "program index" listing names of programs. + + * A "data type index" listing data types (such as structures defined + in header files). + +Not every manual needs all of these, and most manuals use two or three +of them. This manual has two indices: a concept index and an @-command +index (that is actually the function index but is called a command +index in the chapter heading). Two or more indices can be combined +into one using the `@synindex' or `@syncodeindex' commands. *Note +Combining Indices::. + + +File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices + +Defining the Entries of an Index +================================ + +The data to make an index come from many individual indexing commands +scattered throughout the Texinfo source file. Each command says to add +one entry to a particular index; after formatting, the index will give +the current page number or node name as the reference. + + An index entry consists of an indexing command at the beginning of a +line followed, on the rest of the line, by the entry. + + For example, this section begins with the following five entries for +the concept index: + + @cindex Defining indexing entries + @cindex Index entries + @cindex Entries for an index + @cindex Specifying index entries + @cindex Creating index entries + + Each predefined index has its own indexing command--`@cindex' for the +concept index, `@findex' for the function index, and so on. + + Concept index entries consist of text. The best way to write an index +is to choose entries that are terse yet clear. If you can do this, the +index often looks better if the entries are not capitalized, but +written just as they would appear in the middle of a sentence. +(Capitalize proper names and acronyms that always call for upper case +letters.) This is the case convention we use in most GNU manuals' +indices. + + If you don't see how to make an entry terse yet clear, make it longer +and clear--not terse and confusing. If many of the entries are several +words long, the index may look better if you use a different convention: +to capitalize the first word of each entry. But do not capitalize a +case-sensitive name such as a C or Lisp function name or a shell +command; that would be a spelling error. + + Whichever case convention you use, please use it consistently! + + Entries in indices other than the concept index are symbol names in +programming languages, or program names; these names are usually +case-sensitive, so use upper and lower case as required for them. + + By default, entries for a concept index are printed in a small roman +font and entries for the other indices are printed in a small `@code' +font. You may change the way part of an entry is printed with the +usual Texinfo commands, such as `@file' for file names and `@emph' for +emphasis (*note Marking Text::). + + The six indexing commands for predefined indices are: + +`@cindex CONCEPT' + Make an entry in the concept index for CONCEPT. + +`@findex FUNCTION' + Make an entry in the function index for FUNCTION. + +`@vindex VARIABLE' + Make an entry in the variable index for VARIABLE. + +`@kindex KEYSTROKE' + Make an entry in the key index for KEYSTROKE. + +`@pindex PROGRAM' + Make an entry in the program index for PROGRAM. + +`@tindex DATA TYPE' + Make an entry in the data type index for DATA TYPE. + + *Caution:* Do not use a colon in an index entry. In Info, a colon + separates the menu entry name from the node name. An extra colon + confuses Info. *Note The Parts of a Menu: Menu Parts, for more + information about the structure of a menu entry. + + If you write several identical index entries in different places in a +Texinfo file, the index in the printed manual will list all the pages to +which those entries refer. However, the index in the Info file will +list *only* the node that references the *first* of those index +entries. Therefore, it is best to write indices in which each entry +refers to only one place in the Texinfo file. Fortunately, this +constraint is a feature rather than a loss since it means that the index +will be easy to use. Otherwise, you could create an index that lists +several pages for one entry and your reader would not know to which page +to turn. If you have two identical entries for one topic, change the +topics slightly, or qualify them to indicate the difference. + + You are not actually required to use the predefined indices for their +canonical purposes. For example, suppose you wish to index some C +preprocessor macros. You could put them in the function index along +with actual functions, just by writing `@findex' commands for them; +then, when you print the "Function Index" as an unnumbered chapter, you +could give it the title `Function and Macro Index' and all will be +consistent for the reader. Or you could put the macros in with the +data types by writing `@tindex' commands for them, and give that index +a suitable title so the reader will understand. (*Note Printing +Indices & Menus::.) + + +File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices + +Combining Indices +================= + +Sometimes you will want to combine two disparate indices such as +functions and concepts, perhaps because you have few enough of one of +them that a separate index for them would look silly. + + You could put functions into the concept index by writing `@cindex' +commands for them instead of `@findex' commands, and produce a +consistent manual by printing the concept index with the title +`Function and Concept Index' and not printing the `Function Index' at +all; but this is not a robust procedure. It works only if your +document is never included as part of another document that is designed +to have a separate function index; if your document were to be included +with such a document, the functions from your document and those from +the other would not end up together. Also, to make your function names +appear in the right font in the concept index, you would need to +enclose every one of them between the braces of `@code'. + +* Menu: + +* syncodeindex:: How to merge two indices, using `@code' + font for the merged-from index. +* synindex:: How to merge two indices, using the + default font of the merged-to index. + + +File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices + +`@syncodeindex' +--------------- + +When you want to combine functions and concepts into one index, you +should index the functions with `@findex' and index the concepts with +`@cindex', and use the `@syncodeindex' command to redirect the function +index entries into the concept index. + + The `@syncodeindex' command takes two arguments; they are the name of +the index to redirect, and the name of the index to redirect it to. +The template looks like this: + + @syncodeindex FROM TO + + For this purpose, the indices are given two-letter names: + +`cp' + concept index + +`fn' + function index + +`vr' + variable index + +`ky' + key index + +`pg' + program index + +`tp' + data type index + + Write an `@syncodeindex' command before or shortly after the +end-of-header line at the beginning of a Texinfo file. For example, to +merge a function index with a concept index, write the following: + + @syncodeindex fn cp + +This will cause all entries designated for the function index to merge +in with the concept index instead. + + To merge both a variables index and a function index into a concept +index, write the following: + + @syncodeindex vr cp + @syncodeindex fn cp + + The `@syncodeindex' command puts all the entries from the `from' +index (the redirected index) into the `@code' font, overriding whatever +default font is used by the index to which the entries are now +directed. This way, if you direct function names from a function index +into a concept index, all the function names are printed in the `@code' +font as you would expect. + + +File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices + +`@synindex' +----------- + +The `@synindex' command is nearly the same as the `@syncodeindex' +command, except that it does not put the `from' index entries into the +`@code' font; rather it puts them in the roman font. Thus, you use +`@synindex' when you merge a concept index into a function index. + + *Note Printing Indices & Menus::, for information about printing an +index at the end of a book or creating an index menu in an Info file. + + +File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices + +Defining New Indices +==================== + +In addition to the predefined indices, you may use the `@defindex' and +`@defcodeindex' commands to define new indices. These commands create +new indexing @-commands with which you mark index entries. The +`@defindex 'command is used like this: + + @defindex NAME + + The name of an index should be a two letter word, such as `au'. For +example: + + @defindex au + + This defines a new index, called the `au' index. At the same time, +it creates a new indexing command, `@auindex', that you can use to make +index entries. Use the new indexing command just as you would use a +predefined indexing command. + + For example, here is a section heading followed by a concept index +entry and two `au' index entries. + + @section Cognitive Semantics + @cindex kinesthetic image schemas + @auindex Johnson, Mark + @auindex Lakoff, George + +(Evidently, `au' serves here as an abbreviation for "author".) Texinfo +constructs the new indexing command by concatenating the name of the +index with `index'; thus, defining an `au' index leads to the automatic +creation of an `@auindex' command. + + Use the `@printindex' command to print the index, as you do with the +predefined indices. For example: + + @node Author Index, Subject Index, , Top + @unnumbered Author Index + + @printindex au + + The `@defcodeindex' is like the `@defindex' command, except that, in +the printed output, it prints entries in an `@code' font instead of a +roman font. Thus, it parallels the `@findex' command rather than the +`@cindex' command. + + You should define new indices within or right after the end-of-header +line of a Texinfo file, before any `@synindex' or `@syncodeindex' +commands (*note Header::). + + +File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top + +Special Insertions +****************** + +Texinfo provides several commands for inserting characters that have +special meaning in Texinfo, such as braces, and for other graphic +elements that do not correspond to simple characters you can type. + +* Menu: + +* Braces Atsigns:: How to insert braces, `@'. +* Inserting Space:: How to insert the right amount of space + within a sentence. +* Inserting Accents:: How to insert accents and special characters. +* Dots Bullets:: How to insert dots and bullets. +* TeX and copyright:: How to insert the TeX logo + and the copyright symbol. +* pounds:: How to insert the pounds currency symbol. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. +* Glyphs:: How to indicate results of evaluation, + expansion of macros, errors, etc. +* Images:: How to include graphics. + + +File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions + +Inserting @ and Braces +====================== + +`@' and curly braces are special characters in Texinfo. To insert +these characters so they appear in text, you must put an `@' in front +of these characters to prevent Texinfo from misinterpreting them. + + Do not put braces after any of these commands; they are not necessary. + +* Menu: + +* Inserting An Atsign:: How to insert `@'. +* Inserting Braces:: How to insert `{' and `}'. + + +File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns + +Inserting `@' with @@ +--------------------- + +`@@' stands for a single `@' in either printed or Info output. + + Do not put braces after an `@@' command. + + +File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns + +Inserting `{' and `}'with @{ and @} +----------------------------------- + +`@{' stands for a single `{' in either printed or Info output. + + `@}' stands for a single `}' in either printed or Info output. + + Do not put braces after either an `@{' or an `@}' command. + + +File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions + +Inserting Space +=============== + +The following sections describe commands that control spacing of various +kinds within and after sentences. + +* Menu: + +* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. +* Ending a Sentence:: Sometimes it does. +* Multiple Spaces:: Inserting multiple spaces. +* dmn:: How to format a dimension. + + +File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space + +Not Ending a Sentence +--------------------- + +Depending on whether a period or exclamation point or question mark is +inside or at the end of a sentence, less or more space is inserted after +a period in a typeset manual. Since it is not always possible for +Texinfo to determine when a period ends a sentence and when it is used +in an abbreviation, special commands are needed in some circumstances. +(Usually, Texinfo can guess how to handle periods, so you do not need to +use the special commands; you just enter a period as you would if you +were using a typewriter, which means you put two spaces after the +period, question mark, or exclamation mark that ends a sentence.) + + Use the `@:' command after a period, question mark, exclamation mark, +or colon that should not be followed by extra space. For example, use +`@:' after periods that end abbreviations which are not at the ends of +sentences. + + For example, + + The s.o.p.@: has three parts ... + The s.o.p. has three parts ... + +produces + + The s.o.p. has three parts ... + The s.o.p. has three parts ... + +(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating +Procedure".) + + `@:' has no effect on the Info output. Do not put braces after `@:'. + + +File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space + +Ending a Sentence +----------------- + +Use `@.' instead of a period, `@!' instead of an exclamation point, and +`@?' instead of a question mark at the end of a sentence that ends with +a single capital letter. Otherwise, TeX will think the letter is an +abbreviation and will not insert the correct end-of-sentence spacing. +Here is an example: + + Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@. + Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. + +produces + + Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. + Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. + + In the Info file output, `@.' is equivalent to a simple `.'; likewise +for `@!' and `@?'. + + The meanings of `@:' and `@.' in Texinfo are designed to work well +with the Emacs sentence motion commands (*note Sentences: +(xemacs)Sentences.). This made it necessary for them to be +incompatible with some other formatting systems that use @-commands. + + Do not put braces after any of these commands. + + +File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space + +Multiple Spaces +--------------- + +Ordinarily, TeX collapses multiple whitespace characters (space, tab, +and newline) into a single space. Info output, on the other hand, +preserves whitespace as you type it, except for changing a newline into +a space; this is why it is important to put two spaces at the end of +sentences in Texinfo documents. + + Occasionally, you may want to actually insert several consecutive +spaces, either for purposes of example (what your program does with +multiple spaces as input), or merely for purposes of appearance in +headings or lists. Texinfo supports three commands: `@SPACE', `@TAB', +and `@NL', all of which insert a single space into the output. (Here, +`@SPACE' represents an `@' character followed by a space, i.e., `@ ', +and `TAB' and `NL' represent the tab character and end-of-line, i.e., +when `@' is the last character on a line.) + + For example, + Spacey@ @ @ @ + example. + +produces + + Spacey example. + + Other possible uses of `@SPACE' have been subsumed by `@multitable' +(*note Multi-column Tables::). + + Do not follow any of these commands with braces. + + +File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space + +`@dmn'{DIMENSION}: Format a Dimension +------------------------------------- + +At times, you may want to write `12pt' or `8.5in' with little or no +space between the number and the abbreviation for the dimension. You +can use the `@dmn' command to do this. On seeing the command, TeX +inserts just enough space for proper typesetting; the Info formatting +commands insert no space at all, since the Info file does not require +it. + + To use the `@dmn' command, write the number and then follow it +immediately, with no intervening space, by `@dmn', and then by the +dimension within braces. For example, + + A4 paper is 8.27@dmn{in} wide. + +produces + + A4 paper is 8.27in wide. + + Not everyone uses this style. Some people prefer `8.27 in.@:' or +`8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases, +however, the formatters may insert a line break between the number and +the dimension, so use `@w' (*note w::). Also, if you write a period +after an abbreviation within a sentence, you should write `@:' after +the period to prevent TeX from inserting extra whitespace, as shown +here. *Note Inserting Space::. + + +File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions + +Inserting Accents +================= + +Here is a table with the commands Texinfo provides for inserting +floating accents. The commands with non-alphabetic names do not take +braces around their argument (which is taken to be the next character). +(Exception: `@,' _does_ take braces around its argument.) This is so +as to make the source as convenient to type and read as possible, since +accented characters are very common in some languages. + +Command Output What +@"o o" umlaut accent +@'o o' acute accent +@,{c} c, cedilla accent +@=o o= macron/overbar accent +@^o o^ circumflex accent +@`o o` grave accent +@~o o~ tilde accent +@dotaccent{o} o. overdot accent +@H{o} o'' long Hungarian umlaut +@ringaccent{o} o* ring accent +@tieaccent{oo} oo[ tie-after accent +@u{o} o( breve accent +@ubaraccent{o} o_ underbar accent +@udotaccent{o} .o underdot accent +@v{o} o< hacek or check accent + + This table lists the Texinfo commands for inserting other characters +commonly used in languages other than English. + +@exclamdown{} ! upside-down ! +@questiondown{} ? upside-down ? +@aa{},@AA{} aa,AA A,a with circle +@ae{},@AE{} ae,AE ae,AE ligatures +@dotless{i} i dotless i +@dotless{j} j dotless j +@l{},@L{} /l,/L suppressed-L,l +@o{},@O{} /o,/O O,o with slash +@oe{},@OE{} oe,OE OE,oe ligatures +@ss{} ss es-zet or sharp S + + +File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions + +Inserting Ellipsis, Dots, and Bullets +===================================== + +An "ellipsis" (a line of dots) is not typeset as a string of periods, +so a special command is used for ellipsis in Texinfo. The `@bullet' +command is special, too. Each of these commands is followed by a pair +of braces, `{}', without any whitespace between the name of the command +and the braces. (You need to use braces with these commands because +you can use them next to other text; without the braces, the formatters +would be confused. *Note @-Command Syntax: Command Syntax, for further +information.) + +* Menu: + +* dots:: How to insert dots ... +* bullet:: How to insert 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. + + Similarly, the `@enddots{}' command generates an end-of-sentence +ellipsis (four dots) .... + + +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. (*Note `@itemize': itemize.) + + +File: texinfo.info, Node: TeX and copyright, Next: pounds, 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. The copyright symbol, `(C)', is also special. Each of +these commands is followed by a pair of braces, `{}', without any +whitespace between the name of the command and the braces. + +* Menu: + +* tex:: How to insert the TeX logo. +* copyright symbol:: How to use `@copyright'{}. + + +File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright + +`@TeX'{} (TeX) +-------------- + +Use the `@TeX{}' command to generate `TeX'. In a printed manual, this +is a special logo that is different from three ordinary letters. In +Info, it just looks like `TeX'. The `@TeX{}' command is unique among +Texinfo commands in that the `T' and the `X' are in upper case. + + +File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright + +`@copyright'{} ((C)) +-------------------- + +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: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions + +`@pounds{}' (#): Pounds Sterling +================================ + +Use the `@pounds{}' command to generate `#'. In a printed manual, this +is the symbol for the currency pounds sterling. In Info, it is a `#'. +Other currency symbols are unfortunately not available. + + +File: texinfo.info, Node: minus, Next: math, Prev: pounds, 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, shorter than an em-dash: + + `-' is a minus sign generated with `@minus{}', + + `-' is a hyphen generated with the character `-', + + `---' is an em-dash for text. + +In the fixed-width font used by Info, `@minus{}' is the same as a +hyphen. + + You should not use `@minus{}' inside `@code' or `@example' because +the width distinction is not made in the fixed-width font they use. + + When you use `@minus' to specify the mark beginning each entry in an +itemized list, you do not need to type the braces (*note `@itemize': +itemize..) + + +File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions + +`@math' - Inserting Mathematical Expressions +============================================ + +You can write a short mathematical expression with the `@math' command. +Write the mathematical expression between braces, like this: + + @math{(a + b)(a + b) = a^2 + 2ab + b^2} + +This produces the following in Info: + + (a + b)(a + b) = a^2 + 2ab + b^2 + + Thus, the `@math' command has no effect on the Info output. + + For complex mathematical expressions, you can also use TeX directly +(*note Raw Formatter Commands::). When you use TeX directly, remember +to write the mathematical expression between one or two `$' +(dollar-signs) as appropriate. + + +File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions + +Glyphs for Examples +=================== + +In Texinfo, code is often illustrated in examples that are delimited by +`@example' and `@end example', or by `@lisp' and `@end lisp'. In such +examples, you can indicate the results of evaluation or an expansion +using `=>' or `==>'. Likewise, there are commands to insert glyphs to +indicate printed output, error messages, equivalence of expressions, +and the location of point. + + The glyph-insertion commands do not need to be used within an +example, but most often they are. Every glyph-insertion command is +followed by a pair of left- and right-hand braces. + +* Menu: + +* Glyphs Summary:: +* result:: How to show the result of expression. +* expansion:: How to indicate an expansion. +* Print Glyph:: How to indicate printed output. +* Error Glyph:: How to indicate an error message. +* Equivalence:: How to indicate equivalence. +* Point Glyph:: How to indicate the location of point. + + +File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs + +Glyphs Summary +-------------- + +Here are the different glyph commands: + +=> + `@result{}' points to the result of an expression. + +==> + `@expansion{}' shows the results of a macro expansion. + +-| + `@print{}' indicates printed output. + +error--> + `@error{}' indicates that the following text is an error message. + +== + `@equiv{}' indicates the exact equivalence of two forms. + +-!- + `@point{}' shows the location of point. + +* Menu: + +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: + + +File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs + +`@result{}' (=>): Indicating Evaluation +--------------------------------------- + +Use the `@result{}' command to indicate the result of evaluating an +expression. + + The `@result{}' command is displayed as `=>' in Info and as a double +stemmed arrow in the printed output. + + Thus, the following, + + (cdr '(1 2 3)) + => (2 3) + +may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'". + + +File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs + +`@expansion{}' (==>): Indicating an Expansion +--------------------------------------------- + +When an expression is a macro call, it expands into a new expression. +You can indicate the result of the expansion with the `@expansion{}' +command. + + The `@expansion{}' command is displayed as `==>' in Info and as a +long arrow with a flat base in the printed output. + + For example, the following + + @lisp + (third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c + @end lisp + +produces + + (third '(a b c)) + ==> (car (cdr (cdr '(a b c)))) + => c + +which may be read as: + + `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the + result of evaluating the expression is `c'. + +Often, as in this case, an example looks better if the `@expansion{}' +and `@result{}' commands are indented five spaces. + + +File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs + +`@print{}' (-|): Indicating Printed Output +------------------------------------------ + +Sometimes an expression will print output during its execution. You +can indicate the printed output with the `@print{}' command. + + The `@print{}' command is displayed as `-|' in Info and similarly, as +a horizontal dash butting against a vertical bar, in the printed output. + + In the following example, the printed text is indicated with `-|', +and the value of the expression follows on the last line. + + (progn (print 'foo) (print 'bar)) + -| foo + -| bar + => bar + +In a Texinfo source file, this example is written as follows: + + @lisp + (progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar + @end lisp + + +File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs + +`@error{}' (error-->): Indicating an Error Message +-------------------------------------------------- + +A piece of code may cause an error when you evaluate it. You can +designate the error message with the `@error{}' command. + + The `@error{}' command is displayed as `error-->' in Info and as the +word `error' in a box in the printed output. + + Thus, + + @lisp + (+ 23 'x) + @error{} Wrong type argument: integer-or-marker-p, x + @end lisp + +produces + + (+ 23 'x) + error--> Wrong type argument: integer-or-marker-p, x + +This indicates that the following error message is printed when you +evaluate the expression: + + Wrong type argument: integer-or-marker-p, x + + `error-->' itself is not part of the error message. + + +File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs + +`@equiv{}' (==): Indicating Equivalence +--------------------------------------- + +Sometimes two expressions produce identical results. You can indicate +the exact equivalence of two forms with the `@equiv{}' command. + + The `@equiv{}' command is displayed as `==' in Info and as a three +parallel horizontal lines in the printed output. + + Thus, + + @lisp + (make-sparse-keymap) @equiv{} (list 'keymap) + @end lisp + +produces + + (make-sparse-keymap) == (list 'keymap) + +This indicates that evaluating `(make-sparse-keymap)' produces +identical results to evaluating `(list 'keymap)'. + + +File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs + +`@point{}' (-!-): Indicating Point in a Buffer +---------------------------------------------- + +Sometimes you need to show an example of text in an Emacs buffer. In +such examples, the convention is to include the entire contents of the +buffer in question between two lines of dashes containing the buffer +name. + + You can use the `@point{}' command to show the location of point in +the text in the buffer. (The symbol for point, of course, is not part +of the text in the buffer; it indicates the place _between_ two +characters where point is located.) + + The `@point{}' command is displayed as `-!-' in Info and as a small +five pointed star in the printed output. + + The following example shows the contents of buffer `foo' before and +after evaluating a Lisp command to insert the word `changed'. + + ---------- Buffer: foo ---------- + This is the -!-contents of foo. + ---------- Buffer: foo ---------- + + (insert "changed ") + => nil + ---------- Buffer: foo ---------- + This is the changed -!-contents of foo. + ---------- Buffer: foo ---------- + + In a Texinfo source file, the example is written like this: + + @example + ---------- Buffer: foo ---------- + This is the @point{}contents of foo. + ---------- Buffer: foo ---------- + + (insert "changed ") + @result{} nil + ---------- Buffer: foo ---------- + This is the changed @point{}contents of foo. + ---------- Buffer: foo ---------- + @end example + + +File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions + +Inserting Images +================ + +You can insert an image in an external file with the `@image' command: + + @image{FILENAME, [WIDTH], [HEIGHT]} + + The FILENAME argument is mandatory, and must not have an extension, +because the different processors support different formats: TeX reads +the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo' +uses `FILENAME.txt' verbatim for Info output (more or less as if it was +an `@example'). HTML output requires `FILENAME.jpg'. + + The optional WIDTH and HEIGHT arguments specify the size to scale the +image to (they are ignored for Info output). If they are both +specified, the image is presented in its natural size (given in the +file); if only one is specified, the other is scaled proportionately; +and if both are specified, both are respected, thus possibly distorting +the original image by changing its aspect ratio. + + The WIDTH and HEIGHT may be specified using any valid TeX dimension, +namely: + +pt + point (72.27pt = 1in) + +pc + pica (1pc = 12pt) + +bp + big point (72bp = 1in) + +in + inch + +cm + centimeter (2.54cm = 1in) + +mm + millimeter (10mm = 1cm) + +dd + dido^t point (1157dd = 1238pt) + +cc + cicero (1cc = 12dd) + +sp + scaled point (65536sp = 1pt) + + For example, the following will scale a file `ridt.eps' to one inch +vertically, with the width scaled proportionately: + + @image{ridt,,1in} + + For `@image' to work with TeX, the file `epsf.tex' must be installed +somewhere that TeX can find it. This file is included in the Texinfo +distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'. + + +File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top + +Making and Preventing Breaks +**************************** + +Usually, a Texinfo file is processed both by TeX and by one of the Info +formatting commands. Line, paragraph, or page breaks sometimes occur +in the `wrong' place in one or other form of output. You must ensure +that text looks right both in the printed manual and in the Info file. + + For example, in a printed manual, page breaks may occur awkwardly in +the middle of an example; to prevent this, you can hold text together +using a grouping command that keeps the text from being split across +two pages. Conversely, you may want to force a page break where none +would occur normally. Fortunately, problems like these do not often +arise. When they do, use the break, break prevention, or pagination +commands. + +* Menu: + +* Break Commands:: Cause and prevent splits. +* Line Breaks:: How to force a single line to use two lines. +* - and hyphenation:: How to tell TeX about hyphenation points. +* w:: How to prevent unwanted line breaks. +* sp:: How to insert blank lines. +* page:: How to force the start of a new page. +* group:: How to prevent unwanted page breaks. +* need:: Another way to prevent unwanted page breaks. + + +File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks + +The Break Commands +================== + + The break commands create or allow line and paragraph breaks: + +`@*' + Force a line break. + +`@sp N' + Skip N blank lines. + +`@-' + Insert a discretionary hyphen. + +`@hyphenation{HY-PHEN-A-TED WORDS}' + Define hyphen points in HY-PHEN-A-TED WORDS. + + The line-break-prevention command holds text together all on one line: + +`@w{TEXT}' + Prevent TEXT from being split and hyphenated across two lines. + + The pagination commands apply only to printed output, since Info +files do not have pages. + +`@page' + Start a new page in the printed manual. + +`@group' + Hold text together that must appear on one printed page. + +`@need MILS' + Start a new printed page if not enough space on this one. + + +File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks + +`@*': Generate Line Breaks +========================== + +The `@*' command forces a line break in both the printed manual and in +Info. + + For example, + + This line @* is broken @*in two places. + +produces + + This line + is broken + in two places. + +(Note that the space after the first `@*' command is faithfully carried +down to the next line.) + + The `@*' command is often used in a file's copyright page: + + This is edition 2.0 of the Texinfo documentation,@* + and is for ... + +In this case, the `@*' command keeps TeX from stretching the line +across the whole page in an ugly manner. + + *Please note:* Do not write braces after an `@*' command; they are + not needed. + + Do not write an `@refill' command at the end of a paragraph + containing an `@*' command; it will cause the paragraph to be + refilled after the line break occurs, negating the effect of the + line break. + + +File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks + +`@-' and `@hyphenation': Helping TeX hyphenate +============================================== + +Although TeX's hyphenation algorithm is generally pretty good, it does +miss useful hyphenation points from time to time. (Or, far more +rarely, insert an incorrect hyphenation.) So, for documents with an +unusual vocabulary or when fine-tuning for a printed edition, you may +wish to help TeX out. Texinfo supports two commands for this: + +`@-' + Insert a discretionary hyphen, i.e., a place where TeX can (but + does not have to) hyphenate. This is especially useful when you + notice an overfull hbox is due to TeX missing a hyphenation (*note + Overfull hboxes::). TeX will not insert any hyphenation points in + a word containing `@-'. + +`@hyphenation{HY-PHEN-A-TED WORDS}' + Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put + a `-' at each hyphenation point. For example: + @hyphenation{man-u-script man-u-scripts} + + TeX only uses the specified hyphenation points when the words + match exactly, so give all necessary variants. + + Info output is not hyphenated, so these commands have no effect there. + + +File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks + +`@w'{TEXT}: Prevent Line Breaks +=============================== + +`@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT. + + You can use the `@w' command to prevent TeX from automatically +hyphenating a long name or phrase that happens to fall near the end of a +line. + + You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}. + +produces + + You can copy GNU software from `ftp.gnu.ai.mit.edu'. + + *Caution:* Do not write an `@refill' command at the end of a + paragraph containing an `@w' command; it will cause the paragraph + to be refilled and may thereby negate the effect of the `@w' + command. + + +File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks + +`@sp' N: Insert Blank Lines +=========================== + +A line beginning with and containing only `@sp N' generates N blank +lines of space in both the printed manual and the Info file. `@sp' +also forces a paragraph break. For example, + + @sp 2 + +generates two blank lines. + + The `@sp' command is most often used in the title page. + + +File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks + +`@page': Start a New Page +========================= + +A line containing only `@page' starts a new page in a printed manual. +The command has no effect on Info files since they are not paginated. +An `@page' command is often used in the `@titlepage' section of a +Texinfo file to start the copyright page. + + +File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks + +`@group': Prevent Page Breaks +============================= + +The `@group' command (on a line by itself) is used inside an `@example' +or similar construct to begin an unsplittable vertical group, which +will appear entirely on one page in the printed output. The group is +terminated by a line containing only `@end group'. These two lines +produce no output of their own, and in the Info file output they have +no effect at all. + + Although `@group' would make sense conceptually in a wide variety of +contexts, its current implementation works reliably only within +`@example' and variants, and within `@display', `@format', `@flushleft' +and `@flushright'. *Note Quotations and Examples::. (What all these +commands have in common is that each line of input produces a line of +output.) In other contexts, `@group' can cause anomalous vertical +spacing. + + This formatting requirement means that you should write: + + @example + @group + ... + @end group + @end example + +with the `@group' and `@end group' commands inside the `@example' and +`@end example' commands. + + The `@group' command is most often used to hold an example together +on one page. In this Texinfo manual, more than 100 examples contain +text that is enclosed between `@group' and `@end group'. + + If you forget to end a group, you may get strange and unfathomable +error messages when you run TeX. This is because TeX keeps trying to +put the rest of the Texinfo file onto the one page and does not start +to generate error messages until it has processed considerable text. +It is a good rule of thumb to look for a missing `@end group' if you +get incomprehensible error messages in TeX. + + +File: texinfo.info, Node: need, Prev: group, Up: Breaks + +`@need MILS': Prevent Page Breaks +================================= + +A line containing only `@need N' starts a new page in a printed manual +if fewer than N mils (thousandths of an inch) remain on the current +page. Do not use braces around the argument N. The `@need' command +has no effect on Info files since they are not paginated. + + This paragraph is preceded by an `@need' command that tells TeX to +start a new page if fewer than 800 mils (eight-tenths inch) remain on +the page. It looks like this: + + @need 800 + This paragraph is preceded by ... + + The `@need' command is useful for preventing orphans (single lines at +the bottoms of printed pages). + + +File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top + +Definition Commands +******************* + +The `@deffn' command and the other "definition commands" enable you to +describe functions, variables, macros, commands, user options, special +forms and other such artifacts in a uniform format. + + In the Info file, a definition causes the entity +category--`Function', `Variable', or whatever--to appear at the +beginning of the first line of the definition, followed by the entity's +name and arguments. In the printed manual, the command causes TeX to +print the entity's name and its arguments on the left margin and print +the category next to the right margin. In both output formats, the +body of the definition is indented. Also, the name of the entity is +entered into the appropriate index: `@deffn' enters the name into the +index of functions, `@defvr' enters it into the index of variables, and +so on. + + A manual need not and should not contain more than one definition for +a given name. An appendix containing a summary should use `@table' +rather than the definition commands. + +* Menu: + +* Def Cmd Template:: How to structure a description using a + definition command. +* Optional Arguments:: How to handle optional and repeated arguments. +* deffnx:: How to group two or more `first' lines. +* Def Cmds in Detail:: All the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: + + +File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands + +The Template for a Definition +============================= + +The `@deffn' command is used for definitions of entities that resemble +functions. To write a definition using the `@deffn' command, write the +`@deffn' command at the beginning of a line and follow it on the same +line by the category of the entity, the name of the entity itself, and +its arguments (if any). Then write the body of the definition on +succeeding lines. (You may embed examples in the body.) Finally, end +the definition with an `@end deffn' command written on a line of its +own. (The other definition commands follow the same format.) + + The template for a definition looks like this: + + @deffn CATEGORY NAME ARGUMENTS... + BODY-OF-DEFINITION + @end deffn + +For example, + + @deffn Command forward-word count + This command moves point forward @var{count} words + (or backward if @var{count} is negative). ... + @end deffn + +produces + + - Command: forward-word count + This function moves point forward COUNT words (or backward if + COUNT is negative). ... + + Capitalize the category name like a title. If the name of the +category contains spaces, as in the phrase `Interactive Command', write +braces around it. For example: + + @deffn {Interactive Command} isearch-forward + ... + @end deffn + +Otherwise, the second word will be mistaken for the name of the entity. + + Some of the definition commands are more general than others. The +`@deffn' command, for example, is the general definition command for +functions and the like--for entities that may take arguments. When you +use this command, you specify the category to which the entity belongs. +The `@deffn' command possesses three predefined, specialized +variations, `@defun', `@defmac', and `@defspec', that specify the +category for you: "Function", "Macro", and "Special Form" respectively. +(In Lisp, a special form is an entity much like a function.) The +`@defvr' command also is accompanied by several predefined, specialized +variations for describing particular kinds of variables. + + The template for a specialized definition, such as `@defun', is +similar to the template for a generalized definition, except that you +do not need to specify the category: + + @defun NAME ARGUMENTS... + BODY-OF-DEFINITION + @end defun + +Thus, + + @defun buffer-end flag + This function returns @code{(point-min)} if @var{flag} + is less than 1, @code{(point-max)} otherwise. + ... + @end defun + +produces + + - Function: buffer-end flag + This function returns `(point-min)' if FLAG is less than 1, + `(point-max)' otherwise. ... + +*Note Sample Function Definition: Sample Function Definition, for a +more detailed example of a function definition, including the use of +`@example' inside the definition. + + The other specialized commands work like `@defun'. +