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, 0 insertions, 1289 deletions
diff --git a/gnu/usr.bin/texinfo/info-files/texi.info-2 b/gnu/usr.bin/texinfo/info-files/texi.info-2 deleted file mode 100644 index 6ad094d..0000000 --- a/gnu/usr.bin/texinfo/info-files/texi.info-2 +++ /dev/null @@ -1,1289 +0,0 @@ -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. - |
