+++ /dev/null
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
-
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
-* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
-END-INFO-DIR-ENTRY
-
- This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
-
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
-Foundation, Inc.
-
- This edition is for Texinfo version 3.12.
-
- 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.
-
-\1f
-File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
-
-A Short Sample Texinfo File
-===========================
-
- Here is a complete but very short Texinfo file, in six parts. The
-first three parts of the file, from `\input texinfo' through to `@end
-titlepage', look more intimidating than they are. Most of the material
-is standard boilerplate; when you write a manual, simply insert the
-names for your own manual in this segment. (*Note Beginning a File::.)
-
-In the following, the sample text is *indented*; comments on it are
-not. The complete file, without any comments, is shown in *Note Sample
-Texinfo File::.
-
-Part 1: Header
---------------
-
-The header does not appear in either the Info file or the printed
-output. It sets various parameters, including the name of the Info
-file and the title used in the header.
-
- \input texinfo @c -*-texinfo-*-
- @c %**start of header
- @setfilename sample.info
- @settitle Sample Document
- @c %**end of header
-
- @setchapternewpage odd
-
-Part 2: Summary Description and Copyright
------------------------------------------
-
-The summary description and copyright segment does not appear in the
-printed document.
-
- @ifinfo
- This is a short example of a complete Texinfo file.
-
- Copyright @copyright{} 1990 Free Software Foundation, Inc.
- @end ifinfo
-
-Part 3: Titlepage and Copyright
--------------------------------
-
-The titlepage segment does not appear in the Info file.
-
- @titlepage
- @sp 10
- @comment The title is printed in a large font.
- @center @titlefont{Sample Title}
-
- @c The following two commands start the copyright page.
- @page
- @vskip 0pt plus 1filll
- Copyright @copyright{} 1990 Free Software Foundation, Inc.
- @end titlepage
-
-Part 4: `Top' Node and Master Menu
-----------------------------------
-
-The `Top' node contains the master menu for the Info file. Since a
-printed manual uses a table of contents rather than a menu, the master
-menu appears only in the Info file.
-
- @node Top, First Chapter, , (dir)
- @comment node-name, next, previous, up
-
- @menu
- * First Chapter:: The first chapter is the
- only chapter in this sample.
- * Concept Index:: This index has two entries.
- @end menu
-
-Part 5: The Body of the Document
----------------------------------
-
-The body segment contains all the text of the document, but not the
-indices or table of contents. This example illustrates a node and a
-chapter containing an enumerated list.
-
- @node First Chapter, Concept Index, Top, Top
- @comment node-name, next, previous, up
- @chapter First Chapter
- @cindex Sample index entry
-
- This is the contents of the first chapter.
- @cindex Another sample index entry
-
- Here is a numbered list.
-
- @enumerate
- @item
- This is the first item.
-
- @item
- This is the second item.
- @end enumerate
-
- The @code{makeinfo} and @code{texinfo-format-buffer}
- commands transform a Texinfo file such as this into
- an Info file; and @TeX{} typesets it for a printed
- manual.
-
-Part 6: The End of the Document
--------------------------------
-
-The end segment contains commands both for generating an index in a node
-and unnumbered chapter of its own and for generating the table of
-contents; and it contains the `@bye' command that marks the end of the
-document.
-
- @node Concept Index, , First Chapter, Top
- @comment node-name, next, previous, up
- @unnumbered Concept Index
-
- @printindex cp
-
- @contents
- @bye
-
-The Results
------------
-
- Here is what the contents of the first chapter of the sample look
-like:
-
- This is the contents of the first chapter.
-
- Here is a numbered list.
-
- 1. This is the first item.
-
- 2. This is the second item.
-
- The `makeinfo' and `texinfo-format-buffer' commands transform a
- Texinfo file such as this into an Info file; and TeX typesets it
- for a printed manual.
-
-\1f
-File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
-
-Acknowledgements
-================
-
- Richard M. Stallman wrote Edition 1.0 of this manual.
-Robert J. Chassell revised and extended it, starting with Edition 1.1.
-Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
-starting with Edition 2.22.
-
- Our thanks go out to all who helped improve this work, particularly to
-Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
-reported mistakes and obscurities; our special thanks go to Melissa
-Weisshaus for her frequent and often tedious reviews of nearly similar
-editions. Our mistakes are our own.
-
- Please send suggestions and corrections to:
-
- Internet address:
- bug-texinfo@gnu.org
-
-Please include the manual's edition number and update date in your
-messages.
-
-\1f
-File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
-
-Using Texinfo Mode
-******************
-
- You may edit a Texinfo file with any text editor you choose. A
-Texinfo file is no different from any other ASCII file. However, GNU
-Emacs comes with a special mode, called Texinfo mode, that provides
-Emacs commands and tools to help ease your work.
-
- This chapter describes features of GNU Emacs' Texinfo mode but not any
-features of the Texinfo formatting language. If you are reading this
-manual straight through from the beginning, you may want to skim through
-this chapter briefly and come back to it after reading succeeding
-chapters which describe the Texinfo formatting language in detail.
-
-* Menu:
-
-* Texinfo Mode Overview:: How Texinfo mode can help you.
-* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
- purpose editing features.
-* Inserting:: How to insert frequently used @-commands.
-* Showing the Structure:: How to show the structure of a file.
-* Updating Nodes and Menus:: How to update or create new nodes and menus.
-* Info Formatting:: How to format for Info.
-* Printing:: How to format and print part or all of a file.
-* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
-
-\1f
-File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
-
-Texinfo Mode Overview
-=====================
-
- Texinfo mode provides special features for working with Texinfo files:
-
- * Insert frequently used @-commands.
-
- * Automatically create `@node' lines.
-
- * Show the structure of a Texinfo source file.
-
- * Automatically create or update the `Next', `Previous', and `Up'
- pointers of a node.
-
- * Automatically create or update menus.
-
- * Automatically create a master menu.
-
- * Format a part or all of a file for Info.
-
- * Typeset and print part or all of a file.
-
- Perhaps the two most helpful features are those for inserting
-frequently used @-commands and for creating node pointers and menus.
-
-\1f
-File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
-
-The Usual GNU Emacs Editing Commands
-====================================
-
- In most cases, the usual Text mode commands work the same in Texinfo
-mode as they do in Text mode. Texinfo mode adds new editing commands
-and tools to GNU Emacs' general purpose editing features. The major
-difference concerns filling. In Texinfo mode, the paragraph separation
-variable and syntax table are redefined so that Texinfo commands that
-should be on lines of their own are not inadvertently included in
-paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
-paragraph but not mix an indexing command on a line adjacent to it into
-the paragraph.
-
- In addition, Texinfo mode sets the `page-delimiter' variable to the
-value of `texinfo-chapter-level-regexp'; by default, this is a regular
-expression matching the commands for chapters and their equivalents,
-such as appendices. With this value for the page delimiter, you can
-jump from chapter title to chapter title with the `C-x ]'
-(`forward-page') and `C-x [' (`backward-page') commands and narrow to a
-chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
-(xemacs)Pages, for details about the page commands.)
-
- You may name a Texinfo file however you wish, but the convention is to
-end a Texinfo file name with one of the three extensions `.texinfo',
-`.texi', or `.tex'. A longer extension is preferred, since it is
-explicit, but a shorter extension may be necessary for operating
-systems that limit the length of file names. GNU Emacs automatically
-enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
-extension. Also, Emacs switches to Texinfo mode when you visit a file
-that has `-*-texinfo-*-' in its first line. If ever you are in another
-mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
-
- Like all other Emacs features, you can customize or enhance Texinfo
-mode as you wish. In particular, the keybindings are very easy to
-change. The keybindings described here are the default or standard
-ones.
-
-\1f
-File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
-
-Inserting Frequently Used Commands
-==================================
-
- Texinfo mode provides commands to insert various frequently used
-@-commands into the buffer. You can use these commands to save
-keystrokes.
-
- The insert commands are invoked by typing `C-c' twice and then the
-first letter of the @-command:
-
-`C-c C-c c'
-`M-x texinfo-insert-@code'
- Insert `@code{}' and put the cursor between the braces.
-
-`C-c C-c d'
-`M-x texinfo-insert-@dfn'
- Insert `@dfn{}' and put the cursor between the braces.
-
-`C-c C-c e'
-`M-x texinfo-insert-@end'
- Insert `@end' and attempt to insert the correct following word,
- such as `example' or `table'. (This command does not handle
- nested lists correctly, but inserts the word appropriate to the
- immediately preceding list.)
-
-`C-c C-c i'
-`M-x texinfo-insert-@item'
- Insert `@item' and put the cursor at the beginning of the next
- line.
-
-`C-c C-c k'
-`M-x texinfo-insert-@kbd'
- Insert `@kbd{}' and put the cursor between the braces.
-
-`C-c C-c n'
-`M-x texinfo-insert-@node'
- Insert `@node' and a comment line listing the sequence for the
- `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
-
-`C-c C-c o'
-`M-x texinfo-insert-@noindent'
- Insert `@noindent' and put the cursor at the beginning of the next
- line.
-
-`C-c C-c s'
-`M-x texinfo-insert-@samp'
- Insert `@samp{}' and put the cursor between the braces.
-
-`C-c C-c t'
-`M-x texinfo-insert-@table'
- Insert `@table' followed by a <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.
-
-\1f
-File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
-
-Showing the Section Structure of a File
-=======================================
-
- You can show the section structure of a Texinfo file by using the
-`C-c C-s' command (`texinfo-show-structure'). This command shows the
-section structure of a Texinfo file by listing the lines that begin
-with the @-commands for `@chapter', `@section', and the like. It
-constructs what amounts to a table of contents. These lines are
-displayed in another buffer called the `*Occur*' buffer. In that
-buffer, you can position the cursor over one of the lines and use the
-`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
-corresponding spot in the Texinfo file.
-
-`C-c C-s'
-`M-x texinfo-show-structure'
- Show the `@chapter', `@section', and such lines of a Texinfo file.
-
-`C-c C-c'
-`M-x occur-mode-goto-occurrence'
- Go to the line in the Texinfo file corresponding to the line under
- the cursor in the `*Occur*' buffer.
-
- If you call `texinfo-show-structure' with a prefix argument by typing
-`C-u C-c C-s', it will list not only those lines with the @-commands
-for `@chapter', `@section', and the like, but also the `@node' lines.
-(This is how the `texinfo-show-structure' command worked without an
-argument in the first version of Texinfo. It was changed because
-`@node' lines clutter up the `*Occur*' buffer and are usually not
-needed.) You can use `texinfo-show-structure' with a prefix argument
-to check whether the `Next', `Previous', and `Up' pointers of an
-`@node' line are correct.
-
- Often, when you are working on a manual, you will be interested only
-in the structure of the current chapter. In this case, you can mark
-off the region of the buffer that you are interested in by using the
-`C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
-will work on only that region. To see the whole buffer again, use
-`C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
-information about the narrowing commands.)
-
- In addition to providing the `texinfo-show-structure' command,
-Texinfo mode sets the value of the page delimiter variable to match the
-chapter-level @-commands. This enables you to use the `C-x ]'
-(`forward-page') and `C-x [' (`backward-page') commands to move forward
-and backward by chapter, and to use the `C-x p' (`narrow-to-page')
-command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
-information about the page commands.
-
-\1f
-File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
-
-Updating Nodes and Menus
-========================
-
- Texinfo mode provides commands for automatically creating or updating
-menus and node pointers. The commands are called "update" commands
-because their most frequent use is for updating a Texinfo file after
-you have worked on it; but you can use them to insert the `Next',
-`Previous', and `Up' pointers into an `@node' line that has none and to
-create menus in a file that has none.
-
- If you do not use the updating commands, you need to write menus and
-node pointers by hand, which is a tedious task.
-
-* Menu:
-
-* Updating Commands:: Five major updating commands.
-* Updating Requirements:: How to structure a Texinfo file for
- using the updating command.
-* Other Updating Commands:: How to indent descriptions, insert
- missing nodes lines, and update
- nodes in sequence.
-
-\1f
-File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
-
-The Updating Commands
----------------------
-
- You can use the updating commands
-
- * to insert or update the `Next', `Previous', and `Up' pointers of a
- node,
-
- * to insert or update the menu for a section, and
-
- * to create a master menu for a Texinfo source file.
-
- You can also use the commands to update all the nodes and menus in a
-region or in a whole Texinfo file.
-
- The updating commands work only with conventional Texinfo files, which
-are structured hierarchically like books. In such files, a structuring
-command line must follow closely after each `@node' line, except for
-the `Top' `@node' line. (A "structuring command line" is a line
-beginning with `@chapter', `@section', or other similar command.)
-
- You can write the structuring command line on the line that follows
-immediately after an `@node' line or else on the line that follows
-after a single `@comment' line or a single `@ifinfo' line. You cannot
-interpose more than one line between the `@node' line and the
-structuring command line; and you may interpose only an `@comment' line
-or an `@ifinfo' line.
-
- Commands which work on a whole buffer require that the `Top' node be
-followed by a node with an `@chapter' or equivalent-level command.
-Note that the menu updating commands will not create a main or master
-menu for a Texinfo file that has only `@chapter'-level nodes! The menu
-updating commands only create menus *within* nodes for lower level
-nodes. To create a menu of chapters, you must provide a `Top' node.
-
- The menu updating commands remove menu entries that refer to other
-Info files since they do not refer to nodes within the current buffer.
-This is a deficiency. Rather than use menu entries, you can use cross
-references to refer to other Info files. None of the updating commands
-affect cross references.
-
- Texinfo mode has five updating commands that are used most often: two
-are for updating the node pointers or menu of a single node (or a
-region); two are for updating every node pointer and menu in a file;
-and one, the `texinfo-master-menu' command, is for creating a master
-menu for a complete file, and optionally, for updating every node and
-menu in the whole Texinfo file.
-
- The `texinfo-master-menu' command is the primary command:
-
-`C-c C-u m'
-`M-x texinfo-master-menu'
- Create or update a master menu that includes all the other menus
- (incorporating the descriptions from pre-existing menus, if any).
-
- With an argument (prefix argument, `C-u,' if interactive), first
- create or update all the nodes and all the regular menus in the
- buffer before constructing the master menu. (*Note The Top Node
- and Master Menu: The Top Node, for more about a master menu.)
-
- For `texinfo-master-menu' to work, the Texinfo file must have a
- `Top' node and at least one subsequent node.
-
- After extensively editing a Texinfo file, you can type the
- following:
-
- C-u M-x texinfo-master-menu
- or
- C-u C-c C-u m
-
- This updates all the nodes and menus completely and all at once.
-
- The other major updating commands do smaller jobs and are designed for
-the person who updates nodes and menus as he or she writes a Texinfo
-file.
-
- The commands are:
-
-`C-c C-u C-n'
-`M-x texinfo-update-node'
- Insert the `Next', `Previous', and `Up' pointers for the node that
- point is within (i.e., for the `@node' line preceding point). If
- the `@node' line has pre-existing `Next', `Previous', or `Up'
- pointers in it, the old pointers are removed and new ones inserted.
- With an argument (prefix argument, `C-u', if interactive), this
- command updates all `@node' lines in the region (which is the text
- between point and mark).
-
-`C-c C-u C-m'
-`M-x texinfo-make-menu'
- Create or update the menu in the node that point is within. With
- an argument (`C-u' as prefix argument, if interactive), the
- command makes or updates menus for the nodes which are either
- within or a part of the region.
-
- Whenever `texinfo-make-menu' updates an existing menu, the
- descriptions from that menu are incorporated into the new menu.
- This is done by copying descriptions from the existing menu to the
- entries in the new menu that have the same node names. If the
- node names are different, the descriptions are not copied to the
- new menu.
-
-`C-c C-u C-e'
-`M-x texinfo-every-node-update'
- Insert or update the `Next', `Previous', and `Up' pointers for
- every node in the buffer.
-
-`C-c C-u C-a'
-`M-x texinfo-all-menus-update'
- Create or update all the menus in the buffer. With an argument
- (`C-u' as prefix argument, if interactive), first insert or update
- all the node pointers before working on the menus.
-
- If a master menu exists, the `texinfo-all-menus-update' command
- updates it; but the command does not create a new master menu if
- none already exists. (Use the `texinfo-master-menu' command for
- that.)
-
- When working on a document that does not merit a master menu, you
- can type the following:
-
- C-u C-c C-u C-a
- or
- C-u M-x texinfo-all-menus-update
-
- This updates all the nodes and menus.
-
- The `texinfo-column-for-description' variable specifies the column to
-which menu descriptions are indented. By default, the value is 32
-although it is often useful to reduce it to as low as 24. You can set
-the variable with the `M-x edit-options' command (*note Editing
-Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
-command (*note Examining and Setting Variables: (xemacs)Examining.).
-
- Also, the `texinfo-indent-menu-description' command may be used to
-indent existing menu descriptions to a specified column. Finally, if
-you wish, you can use the `texinfo-insert-node-lines' command to insert
-missing `@node' lines into a file. (*Note Other Updating Commands::,
-for more information.)
-
-\1f
-File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
-
-Updating Requirements
----------------------
-
- To use the updating commands, you must organize the Texinfo file
-hierarchically with chapters, sections, subsections, and the like.
-When you construct the hierarchy of the manual, do not `jump down' more
-than one level at a time: you can follow the `Top' node with a chapter,
-but not with a section; you can follow a chapter with a section, but
-not with a subsection. However, you may `jump up' any number of levels
-at one time--for example, from a subsection to a chapter.
-
- Each `@node' line, with the exception of the line for the `Top' node,
-must be followed by a line with a structuring command such as
-`@chapter', `@section', or `@unnumberedsubsec'.
-
- Each `@node' line/structuring-command line combination must look
-either like this:
-
- @node Comments, Minimum, Conventions, Overview
- @comment node-name, next, previous, up
- @section Comments
-
- or like this (without the `@comment' line):
-
- @node Comments, Minimum, Conventions, Overview
- @section Comments
-
-In this example, `Comments' is the name of both the node and the
-section. The next node is called `Minimum' and the previous node is
-called `Conventions'. The `Comments' section is within the `Overview'
-node, which is specified by the `Up' pointer. (Instead of an
-`@comment' line, you can write an `@ifinfo' line.)
-
- If a file has a `Top' node, it must be called `top' or `Top' and be
-the first node in the file.
-
- The menu updating commands create a menu of sections within a chapter,
-a menu of subsections within a section, and so on. This means that you
-must have a `Top' node if you want a menu of chapters.
-
- Incidentally, the `makeinfo' command will create an Info file for a
-hierarchically organized Texinfo file that lacks `Next', `Previous' and
-`Up' pointers. Thus, if you can be sure that your Texinfo file will be
-formatted with `makeinfo', you have no need for the `update node'
-commands. (*Note Creating an Info File: Create an Info File, for more
-information about `makeinfo'.) However, both `makeinfo' and the
-`texinfo-format-...' commands require that you insert menus in the file.
-
-\1f
-File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
-
-Other Updating Commands
------------------------
-
- In addition to the five major updating commands, Texinfo mode
-possesses several less frequently used updating commands:
-
-`M-x texinfo-insert-node-lines'
- Insert `@node' lines before the `@chapter', `@section', and other
- sectioning commands wherever they are missing throughout a region
- in a Texinfo file.
-
- With an argument (`C-u' as prefix argument, if interactive), the
- `texinfo-insert-node-lines' command not only inserts `@node' lines
- but also inserts the chapter or section titles as the names of the
- corresponding nodes. In addition, it inserts the titles as node
- names in pre-existing `@node' lines that lack names. Since node
- names should be more concise than section or chapter titles, you
- must manually edit node names so inserted.
-
- For example, the following marks a whole buffer as a region and
- inserts `@node' lines and titles throughout:
-
- C-x h C-u M-x texinfo-insert-node-lines
-
- (Note that this command inserts titles as node names in `@node'
- lines; the `texinfo-start-menu-description' command (*note
- Inserting Frequently Used Commands: Inserting.) inserts titles as
- descriptions in menu entries, a different action. However, in both
- cases, you need to edit the inserted text.)
-
-`M-x texinfo-multiple-files-update'
- Update nodes and menus in a document built from several separate
- files. With `C-u' as a prefix argument, create and insert a
- master menu in the outer file. With a numeric prefix argument,
- such as `C-u 2', first update all the menus and all the `Next',
- `Previous', and `Up' pointers of all the included files before
- creating and inserting a master menu in the outer file. The
- `texinfo-multiple-files-update' command is described in the
- appendix on `@include' files. *Note
- texinfo-multiple-files-update::.
-
-`M-x texinfo-indent-menu-description'
- Indent every description in the menu following point to the
- specified column. You can use this command to give yourself more
- space for descriptions. With an argument (`C-u' as prefix
- argument, if interactive), the `texinfo-indent-menu-description'
- command indents every description in every menu in the region.
- However, this command does not indent the second and subsequent
- lines of a multi-line description.
-
-`M-x texinfo-sequential-node-update'
- Insert the names of the nodes immediately following and preceding
- the current node as the `Next' or `Previous' pointers regardless
- of those nodes' hierarchical level. This means that the `Next'
- node of a subsection may well be the next chapter. Sequentially
- ordered nodes are useful for novels and other documents that you
- read through sequentially. (However, in Info, the `g *' command
- lets you look through the file sequentially, so sequentially
- ordered nodes are not strictly necessary.) With an argument
- (prefix argument, if interactive), the
- `texinfo-sequential-node-update' command sequentially updates all
- the nodes in the region.
-
-\1f
-File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
-
-Formatting for Info
-===================
-
- Texinfo mode provides several commands for formatting part or all of a
-Texinfo file for Info. Often, when you are writing a document, you
-want to format only part of a file--that is, a region.
-
- You can use either the `texinfo-format-region' or the
-`makeinfo-region' command to format a region:
-
-`C-c C-e C-r'
-`M-x texinfo-format-region'
-`C-c C-m C-r'
-`M-x makeinfo-region'
- Format the current region for Info.
-
- You can use either the `texinfo-format-buffer' or the
-`makeinfo-buffer' command to format a whole buffer:
-
-`C-c C-e C-b'
-`M-x texinfo-format-buffer'
-`C-c C-m C-b'
-`M-x makeinfo-buffer'
- Format the current buffer for Info.
-
- For example, after writing a Texinfo file, you can type the following:
-
- C-u C-c C-u m
-or
- C-u M-x texinfo-master-menu
-
-This updates all the nodes and menus. Then type the following to create
-an Info file:
-
- C-c C-m C-b
-or
- M-x makeinfo-buffer
-
- For TeX or the Info formatting commands to work, the file *must*
-include a line that has `@setfilename' in its header.
-
- *Note Create an Info File::, for details about Info formatting.
-
-\1f
-File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
-
-Formatting and Printing
-=======================
-
- Typesetting and printing a Texinfo file is a multi-step process in
-which you first create a file for printing (called a DVI file), and then
-print the file. Optionally, you may also create indices. To do this,
-you must run the `texindex' command after first running the `tex'
-typesetting command; and then you must run the `tex' command again. Or
-else run the `texi2dvi' command which automatically creates indices as
-needed (*note Format with texi2dvi::.).
-
- Often, when you are writing a document, you want to typeset and print
-only part of a file to see what it will look like. You can use the
-`texinfo-tex-region' and related commands for this purpose. Use the
-`texinfo-tex-buffer' command to format all of a buffer.
-
-`C-c C-t C-b'
-`M-x texinfo-tex-buffer'
- Run `texi2dvi' on the buffer. In addition to running TeX on the
- buffer, this command automatically creates or updates indices as
- needed.
-
-`C-c C-t C-r'
-`M-x texinfo-tex-region'
- Run TeX on the region.
-
-`C-c C-t C-i'
-`M-x texinfo-texindex'
- Run `texindex' to sort the indices of a Texinfo file formatted with
- `texinfo-tex-region'. The `texinfo-tex-region' command does not
- run `texindex' automatically; it only runs the `tex' typesetting
- command. You must run the `texinfo-tex-region' command a second
- time after sorting the raw index files with the `texindex'
- command. (Usually, you do not format an index when you format a
- region, only when you format a buffer. Now that the `texi2dvi'
- command exists, there is little or no need for this command.)
-
-`C-c C-t C-p'
-`M-x texinfo-tex-print'
- Print the file (or the part of the file) previously formatted with
- `texinfo-tex-buffer' or `texinfo-tex-region'.
-
- For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
-*must* start with a `\input texinfo' line and must include an
-`@settitle' line. The file must end with `@bye' on a line by itself.
-(When you use `texinfo-tex-region', you must surround the `@settitle'
-line with start-of-header and end-of-header lines.)
-
- *Note Format/Print Hardcopy::, for a description of the other TeX
-related commands, such as `tex-show-print-queue'.
-
-\1f
-File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
-
-Texinfo Mode Summary
-====================
-
- In Texinfo mode, each set of commands has default keybindings that
-begin with the same keys. All the commands that are custom-created for
-Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
-
-Insert Commands
----------------
-
- The insert commands are invoked by typing `C-c' twice and then the
-first letter of the @-command to be inserted. (It might make more
-sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
-is quick to type.)
-
- C-c C-c c Insert `@code'.
- C-c C-c d Insert `@dfn'.
- C-c C-c e Insert `@end'.
- C-c C-c i Insert `@item'.
- C-c C-c n Insert `@node'.
- C-c C-c s Insert `@samp'.
- C-c C-c v Insert `@var'.
- C-c C-c { Insert braces.
- C-c C-c ]
- C-c C-c } Move out of enclosing braces.
-
- C-c C-c C-d Insert a node's section title
- in the space for the description
- in a menu entry line.
-
-Show Structure
---------------
-
- The `texinfo-show-structure' command is often used within a narrowed
-region.
-
- C-c C-s List all the headings.
-
-The Master Update Command
--------------------------
-
- The `texinfo-master-menu' command creates a master menu; and can be
-used to update every node and menu in a file as well.
-
- C-c C-u m
- M-x texinfo-master-menu
- Create or update a master menu.
-
- C-u C-c C-u m With `C-u' as a prefix argument, first
- create or update all nodes and regular
- menus, and then create a master menu.
-
-Update Pointers
----------------
-
- The update pointer commands are invoked by typing `C-c C-u' and then
-either `C-n' for `texinfo-update-node' or `C-e' for
-`texinfo-every-node-update'.
-
- C-c C-u C-n Update a node.
- C-c C-u C-e Update every node in the buffer.
-
-Update Menus
-------------
-
- Invoke the update menu commands by typing `C-c C-u' and then either
-`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
-To update both nodes and menus at the same time, precede `C-c C-u C-a'
-with `C-u'.
-
- C-c C-u C-m Make or update a menu.
-
- C-c C-u C-a Make or update all
- menus in a buffer.
-
- C-u C-c C-u C-a With `C-u' as a prefix argument,
- first create or update all nodes and
- then create or update all menus.
-
-Format for Info
----------------
-
- The Info formatting commands that are written in Emacs Lisp are
-invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
-for the whole buffer.
-
- The Info formatting commands that are written in C and based on the
-`makeinfo' program are invoked by typing `C-c C-m' and then either
-`C-r' for a region or `C-b' for the whole buffer.
-
-Use the `texinfo-format...' commands:
-
- C-c C-e C-r Format the region.
- C-c C-e C-b Format the buffer.
-
-Use `makeinfo':
-
- C-c C-m C-r Format the region.
- C-c C-m C-b Format the buffer.
- C-c C-m C-l Recenter the `makeinfo' output buffer.
- C-c C-m C-k Kill the `makeinfo' formatting job.
-
-Typeset and Print
------------------
-
- The TeX typesetting and printing commands are invoked by typing `C-c
-C-t' and then another control command: `C-r' for `texinfo-tex-region',
-`C-b' for `texinfo-tex-buffer', and so on.
-
- C-c C-t C-r Run TeX on the region.
- C-c C-t C-b Run `texi2dvi' on the buffer.
- C-c C-t C-i Run `texindex'.
- C-c C-t C-p Print the DVI file.
- C-c C-t C-q Show the print queue.
- C-c C-t C-d Delete a job from the print queue.
- C-c C-t C-k Kill the current TeX formatting job.
- C-c C-t C-x Quit a currently stopped TeX formatting job.
- C-c C-t C-l Recenter the output buffer.
-
-Other Updating Commands
------------------------
-
- The `other updating commands' do not have standard keybindings because
-they are rarely used.
-
- M-x texinfo-insert-node-lines
- Insert missing `@node' lines in region.
- With `C-u' as a prefix argument,
- use section titles as node names.
-
- M-x texinfo-multiple-files-update
- Update a multi-file document.
- With `C-u 2' as a prefix argument,
- create or update all nodes and menus
- in all included files first.
-
- M-x texinfo-indent-menu-description
- Indent descriptions.
-
- M-x texinfo-sequential-node-update
- Insert node pointers in strict sequence.
-
-\1f
-File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
-
-Beginning a Texinfo File
-************************
-
- Certain pieces of information must be provided at the beginning of a
-Texinfo file, such as the name of the file and the title of the
-document.
-
-* Menu:
-
-* Four Parts:: Four parts begin a Texinfo file.
-* Sample Beginning:: Here is a sample beginning for a Texinfo file.
-* Header:: The very beginning of a Texinfo file.
-* Info Summary and Permissions:: Summary and copying permissions for Info.
-* Titlepage & Copyright Page:: Creating the title and copyright pages.
-* The Top Node:: Creating the `Top' node and master menu.
-* Software Copying Permissions:: Ensure that you and others continue to
- have the right to use and share software.
-
-\1f
-File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
-
-Four Parts Begin a File
-=======================
-
- Generally, the beginning of a Texinfo file has four parts:
-
- 1. The header, delimited by special comment lines, that includes the
- commands for naming the Texinfo file and telling TeX what
- definitions file to use when processing the Texinfo file.
-
- 2. A short statement of what the file is about, with a copyright
- notice and copying permissions. This is enclosed in `@ifinfo' and
- `@end ifinfo' commands so that the formatters place it only in the
- Info file.
-
- 3. A title page and copyright page, with a copyright notice and
- copying permissions. This is enclosed between `@titlepage' and
- `@end titlepage' commands. The title and copyright page appear
- only in the printed manual.
-
- 4. The `Top' node that contains a menu for the whole Info file. The
- contents of this node appear only in the Info file.
-
- Also, optionally, you may include the copying conditions for a program
-and a warranty disclaimer. The copying section will be followed by an
-introduction or else by the first chapter of the manual.
-
- Since the copyright notice and copying permissions for the Texinfo
-document (in contrast to the copying permissions for a program) are in
-parts that appear only in the Info file or only in the printed manual,
-this information must be given twice.
-
-\1f
-File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
-
-Sample Texinfo File Beginning
-=============================
-
- The following sample shows what is needed.
-
- \input texinfo @c -*-texinfo-*-
- @c %**start of header
- @setfilename NAME-OF-INFO-FILE
- @settitle NAME-OF-MANUAL
- @setchapternewpage odd
- @c %**end of header
-
- @ifinfo
- This file documents ...
-
- Copyright YEAR COPYRIGHT-OWNER
-
- Permission is granted to ...
- @end ifinfo
-
- @c This title page illustrates only one of the
- @c two methods of forming a title page.
-
- @titlepage
- @title NAME-OF-MANUAL-WHEN-PRINTED
- @subtitle SUBTITLE-IF-ANY
- @subtitle SECOND-SUBTITLE
- @author AUTHOR
-
- @c The following two commands
- @c start the copyright page.
- @page
- @vskip 0pt plus 1filll
- Copyright @copyright{} YEAR COPYRIGHT-OWNER
-
- Published by ...
-
- Permission is granted to ...
- @end titlepage
-
- @node Top, Overview, , (dir)
-
- @ifinfo
- This document describes ...
-
- This document applies to version ...
- of the program named ...
- @end ifinfo
-
- @menu
- * Copying:: Your rights and freedoms.
- * First Chapter:: Getting started ...
- * Second Chapter:: ...
- ...
- ...
- @end menu
-
- @node First Chapter, Second Chapter, top, top
- @comment node-name, next, previous, up
- @chapter First Chapter
- @cindex Index entry for First Chapter
-
-\1f
-File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
-
-The Texinfo File Header
-=======================
-
- Texinfo files start with at least three lines that provide Info and
-TeX with necessary information. These are the `\input texinfo' line,
-the `@settitle' line, and the `@setfilename' line. If you want to run
-TeX on just a part of the Texinfo File, you must write the `@settitle'
-and `@setfilename' lines between start-of-header and end-of-header
-lines.
-
- Thus, the beginning of a Texinfo file looks like this:
-
- \input texinfo @c -*-texinfo-*-
- @setfilename sample.info
- @settitle Sample Document
-
-or else like this:
-
- \input texinfo @c -*-texinfo-*-
- @c %**start of header
- @setfilename sample.info
- @settitle Sample Document
- @c %**end of header
-
-* Menu:
-
-* First Line:: The first line of a Texinfo file.
-* Start of Header:: Formatting a region requires this.
-* setfilename:: Tell Info the name of the Info file.
-* settitle:: Create a title for the printed work.
-* setchapternewpage:: Start chapters on right-hand pages.
-* paragraphindent:: An option to specify paragraph indentation.
-* End of Header:: Formatting a region requires this.
-
-\1f
-File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
-
-The First Line of a Texinfo File
---------------------------------
-
- Every Texinfo file that is to be the top-level input to TeX must begin
-with a line that looks like this:
-
- \input texinfo @c -*-texinfo-*-
-
-This line serves two functions:
-
- 1. When the file is processed by TeX, the `\input texinfo' command
- tells TeX to load the macros needed for processing a Texinfo file.
- These are in a file called `texinfo.tex', which is usually located
- in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
- `\', to mark the beginning of a command, just as Texinfo uses `@'.
- The `texinfo.tex' file causes the switch from `\' to `@'; before
- the switch occurs, TeX requires `\', which is why it appears at
- the beginning of the file.
-
- 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
- specification tells Emacs to use Texinfo mode.
-
-\1f
-File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
-
-Start of Header
----------------
-
- Write a start-of-header line on the second line of a Texinfo file.
-Follow the start-of-header line with `@setfilename' and `@settitle'
-lines and, optionally, with other command lines, such as `@smallbook'
-or `@footnotestyle'; and then by an end-of-header line (*note End of
-Header::.).
-
- With these lines, you can format part of a Texinfo file for Info or
-typeset part for printing.
-
- A start-of-header line looks like this:
-
- @c %**start of header
-
- The odd string of characters, `%**', is to ensure that no other
-comment is accidentally taken for a start-of-header line.
-
-\1f
-File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
-
-`@setfilename'
---------------
-
- In order to serve as the primary input file for either `makeinfo' or
-TeX, a Texinfo file must contain a line that looks like this:
-
- @setfilename INFO-FILE-NAME
-
- Write the `@setfilename' command at the beginning of a line and
-follow it on the same line by the Info file name. Do not write anything
-else on the line; anything on the line after the command is considered
-part of the file name, including what would otherwise be a comment.
-
- The `@setfilename' line specifies the name of the Info file to be
-generated. This name should be different from the name of the Texinfo
-file. There are two conventions for choosing the name: you can either
-remove the `.texi' extension from the input file name, or replace it
-with the `.info' extension.
-
- Some operating systems cannot handle long file names. You can run
-into a problem even when the file name you specify is itself short
-enough. This occurs because the Info formatters split a long Info file
-into short indirect subfiles, and name them by appending `-1', `-2',
-..., `-10', `-11', and so on, to the original file name. (*Note Tag
-Files and Split Files: Tag and Split Files.) The subfile name
-`texinfo.info-10', for example, is too long for some systems; so the
-Info file name for this document is `texinfo' rather than
-`texinfo.info'.
-
- The Info formatting commands ignore everything written before the
-`@setfilename' line, which is why the very first line of the file (the
-`\input' line) does not show up in the output.
-
- The `@setfilename' line produces no output when you typeset a manual
-with TeX, but it nevertheless is essential: it opens the index,
-cross-reference, and other auxiliary files used by Texinfo, and also
-reads `texinfo.cnf' if that file is present on your system (*note
-Preparing to Use TeX: Preparing for TeX.).
-
-\1f
-File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
-
-`@settitle'
------------
-
- In order to be made into a printed manual, a Texinfo file must contain
-a line that looks like this:
-
- @settitle TITLE
-
- Write the `@settitle' command at the beginning of a line and follow
-it on the same line by the title. This tells TeX the title to use in a
-header or footer. Do not write anything else on the line; anything on
-the line after the command is considered part of the title, including a
-comment.
-
- Conventionally, when TeX formats a Texinfo file for double-sided
-output, the title is printed in the left-hand (even-numbered) page
-headings and the current chapter title is printed in the right-hand
-(odd-numbered) page headings. (TeX learns the title of each chapter
-from each `@chapter' command.) Page footers are not printed.
-
- Even if you are printing in a single-sided style, TeX looks for an
-`@settitle' command line, in case you include the manual title in the
-heading.
-
- The `@settitle' command should precede everything that generates
-actual output in TeX.
-
- Although the title in the `@settitle' command is usually the same as
-the title on the title page, it does not affect the title as it appears
-on the title page. Thus, the two do not need not match exactly; and
-the title in the `@settitle' command can be a shortened or expanded
-version of the title as it appears on the title page. (*Note
-`@titlepage': titlepage.)
-
- TeX prints page headings only for that text that comes after the
-`@end titlepage' command in the Texinfo file, or that comes after an
-`@headings' command that turns on headings. (*Note The `@headings'
-Command: headings on off, for more information.)
-
- You may, if you wish, create your own, customized headings and
-footings. *Note Page Headings: Headings, for a detailed discussion of
-this process.
-