diff options
Diffstat (limited to 'gnu/usr.bin/texinfo/info-files/texi.info-2')
| -rw-r--r-- | gnu/usr.bin/texinfo/info-files/texi.info-2 | 1289 |
1 files changed, 1289 insertions, 0 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-2 b/gnu/usr.bin/texinfo/info-files/texi.info-2 new file mode 100644 index 0000000..6ad094d --- /dev/null +++ b/gnu/usr.bin/texinfo/info-files/texi.info-2 @@ -0,0 +1,1289 @@ +This is Info file texi.info, produced by Makeinfo-1.55 from the input +file texi.texi. + + This file documents Texinfo, a documentation system that uses a +single source file to produce both on-line information and a printed +manual. + + Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation, +Inc. + + This is the second edition of the Texinfo documentation, +and is consistent with version 2 of `texinfo.tex'. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + + +File: texi.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: texi.info, Node: Texinfo Mode Overview, Next: Emacs Editing, 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: texi.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: +(emacs)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: texi.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 SPC and leave the cursor after the + SPC. + +`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: texi.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 with the `C-x +n' (`narrow-to-region') command and `texinfo-show-structure' will work +on only that region. To see the whole buffer again, use `C-x w' +(`widen'). (*Note Narrowing: (emacs)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: (emacs)Pages, for more +information about the page commands. + + +File: texi.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: texi.info, Node: Updating Commands, Next: Updating Requirements, 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: (emacs)Edit Options.) or with the `M-x set-variable' +command (*note Examining and Setting Variables: (emacs)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: texi.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: texi.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* RET' + 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: texi.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 the Info formatting commands to work, the file *must* include a +line that has `@setfilename' in its header. + + Not all systems support the `makeinfo'-based formatting commands. + + *Note Create an Info File::, for details about Info formatting. + + +File: texi.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. + + 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-r' +`M-x texinfo-tex-region' + Run TeX on the region. + +`C-c C-t C-b' +`M-x texinfo-tex-buffer' + Run TeX on the buffer. + +`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' or `texinfo-tex-buffer'. You must run the + `tex' command a second time after sorting the raw index files. + +`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: texi.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 typing `C-n' for `texinfo-update-node' or typing `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 TeX 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: texi.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: texi.info, Node: Four Parts, Next: Sample Beginning, 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: texi.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), (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: texi.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: texi.info, Node: First Line, Next: Start of 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: texi.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: texi.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header + +`@setfilename' +-------------- + + In order to be made into an Info file, 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 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. The convention is to write a name with a `.info' extension, to +produce an Info file name such as `texinfo.info'. + + 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 actually `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 need to be commented out. The `@setfilename' +line is ignored when you typeset a printed manual. + + +File: texi.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, TeX formats a Texinfo file for double-sided output +so as to print the title in the left-hand (even-numbered) page headings +and the current chapter titles 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: texi.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: texi.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 0, the Info formatting commands delete + existing indentation. + + * If the value of INDENT is greater than 0, 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 `texinfo-format-buffer' and `texinfo-format-region' +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: texi.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: texi.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: texi.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. + |
