OS/2 Professional/OS2PRO194.ISO/os2/prgramer/unix/info/texinfo.i02

GNU Info File | 1993-06-12 | 50.4 KB | 1,280 lines

This is Info file texinfo, produced by Makeinfo-1.47 from the input
file texinfo2.tex.

   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 Free Software Foundation, Inc.

   This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: texinfo,  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: texinfo,  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: texinfo,  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 operates 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'.


File: texinfo,  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.  The
command 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: texinfo,  Node: Updating Nodes and Menus,  Next: Info Formatting,  Prev: Showing the Structure,  Up: Texinfo Mode

Updating Nodes and Menus
========================

   Texinfo mode provides commands for automatically creating or updating
menus and node pointers.  The commands are called "update" commands
because their most frequent use is for updating a Texinfo file after
you have worked on it; but you can use them to insert the `Next',
`Previous', and `Up' pointers into an `@node' line that has none and to
create menus in a file that has none.

   If you do not use the updating commands, you need to write menus and
node pointers by hand, which is a tedious task.

* Menu:

* Updating Commands::           Five major updating commands.
* Updating Requirements::       How to structure a Texinfo file for
                                  using the updating command.
* Other Updating Commands::     How to indent descriptions, insert
                                  missing nodes lines, and update
                                  nodes in sequence.


File: texinfo,  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: texinfo,  Node: Updating Requirements,  Next: Other Updating Commands,  Prev: Updating Commands,  Up: Updating Nodes and Menus

Updating Requirements
---------------------

   To use the updating commands, you must organize the Texinfo file
hierarchically with chapters, sections, subsections, and the like. When
you construct the hierarchy of the manual, do not `jump down' more than
one level at a time: you can follow the `Top' node with a chapter, but
not with a section; you can follow a chapter with a section, but not
with a subsection.  However, you may `jump up' any number of levels at
one time--for example, from a subsection to a chapter.

   Each `@node' line, with the exception of the line for the `Top'
node, must be followed by a line with a structuring command such as
`@chapter', `@section', or `@unnumberedsubsec'.

   Each `@node' line/structuring-command line combination must look
either like this:

     @node     Comments,  Minimum, Conventions, Overview
     @comment  node-name, next,    previous,    up
     @section Comments

   or like this (without the `@comment' line):

     @node Comments, Minimum, Conventions, Overview
     @section Comments

In this example, `Comments' is the name of both the node and the
section.  The next node is called `Minimum' and the previous node is
called `Conventions'.  The `Comments' section is within the `Overview'
node, which is specified by the `Up' pointer.  (Instead of an
`@comment' line, you can write an `@ifinfo' line.)

   If a file has a `Top' node, it must be called `top' or `Top' and be
the first node in the file.

   The menu updating commands create a menu of sections within a
chapter, a menu of subsections within a section, and so on.  This means
that you must have a `Top' node if you want a menu of chapters.

   Incidentally, the `makeinfo' command will create an Info file for a
hierarchically organized Texinfo file that lacks `Next', `Previous' and
`Up' pointers.  Thus, if you can be sure that your Texinfo file will be
formatted with `makeinfo', you have no need for the `update node'
commands.  (*Note Creating an Info File: Create an Info File, for more
information about `makeinfo'.)  However, both `makeinfo' and the
`texinfo-format-...' commands require that you insert menus in the file.


File: texinfo,  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

`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 `C-u 2' as a numeric prefix
     argument, 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': 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: texinfo,  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: texinfo,  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'
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: texinfo,  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 that follow are arranged
mnemonically.

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.

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 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: texinfo,  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 Conditions::  Ensure that you and others continue to
                                  have the right to use and share software.


File: texinfo,  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: texinfo,  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 @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: texinfo,  Node: Header,  Next: Info Summary and Permissions,  Prev: Sample Beginning,  Up: Beginning a File

The Texinfo File Header
=======================

   Texinfo files start with at least three lines that provide Info and
TeX with necessary information.  These are the `\input texinfo' line,
the `@settitle' line, and the `@setfilename' line.  If you want to run
TeX on just a part of the Texinfo File, you must write the `@settitle'
and `@setfilename' lines between start-of-header and end-of-header
lines.

   Thus, the beginning of a Texinfo file looks like this:

     \input texinfo   @c -*-texinfo-*-
     @setfilename sample.info
     @settitle Sample Document

or else like this:

     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Document
     @c %**end of header

* Menu:

* First Line::                  The first line of a Texinfo file.
* Start of Header::             Formatting a region requires this.
* setfilename::                 Tell Info the name of the Info file.
* settitle::                    Create a title for the printed work.
* setchapternewpage::           Start chapters on right-hand pages.
* paragraphindent::             An option to specify paragraph indentation.
* End of Header::               Formatting a region requires this.


File: texinfo,  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: texinfo,  Node: Start of Header,  Next: setfilename,  Prev: First Line,  Up: Header

Start of Header
---------------

   You should write a start-of-header line on the second line of a
Texinfo file.  Follow the start-of-header line with `@setfilename' and
`@settitle' lines and, optionally, with other command lines, such as
`@smallbook' or `@footnotestyle'; and then by an end-of-header line
(*note End of Header::.).

   With these lines, you can format part of a Texinfo file for Info or
typeset part for printing.

   A start-of-header line looks like this:

     @c %**start of header

   The odd string of characters, `%**', is to ensure that no other
comment is accidentally taken for a start-of-header line.


File: texinfo,  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: texinfo,  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: texinfo,  Node: setchapternewpage,  Next: paragraphindent,  Prev: settitle,  Up: Header

`@setchapternewpage'
--------------------

   In a book or a manual, text is usually printed on both sides of the
paper, chapters start on right-hand pages, and right-hand pages have
odd numbers.  But in short reports, text often is printed only on one
side of the paper.  Also in short reports, chapters sometimes do not
start on new pages, but are printed on the same page as the end of the
preceding chapter, after a small amount of vertical whitespace.

   You can use the `@setchapternewpage' command with various arguments
to specify how TeX should start chapters and whether it should typeset
pages for printing on one or both sides of the paper (single-sided or
double-sided printing).

   Write the `@setchapternewpage' command at the beginning of a line
followed by its argument.

   For example, you would write the following to cause each chapter to
start on a fresh odd-numbered page:

     @setchapternewpage odd

   You can specify one of three alternatives with the
`@setchapternewpage' command:

`@setchapternewpage off'
     Cause TeX to typeset a new chapter on the same page as the last
     chapter, after skipping some vertical whitespace.  Also, cause TeX
     to format page headers for single-sided printing. (You can
     override the headers format with the `@headings double' command;
     see *Note The `@headings' Command: headings on off.)

`@setchapternewpage on'
     Cause TeX to start new chapters on new pages and to typeset page
     headers for single-sided printing.  This is the form most often
     used for short reports.

     This alternative is the default.

`@setchapternewpage odd'
     Cause TeX to start new chapters on new, odd-numbered pages
     (right-handed pages) and to typeset for double-sided printing.
     This is the form most often used for books and manuals.

Texinfo does not have an `@setchapternewpage even' command.

(You can countermand or modify an `@setchapternewpage' command with an
`@headings' command.  *Note The `@headings' Command: headings on off.)

   At the beginning of a manual or book, pages are not numbered--for
example, the title and copyright pages of a book are not numbered. By
convention, table of contents pages are numbered with roman numerals
and not in sequence with the rest of the document.

   Since an Info file does not have pages, the `@setchapternewpage'
command has no effect on it.

   Usually, you do not write an `@setchapternewpage' command for
single-sided printing, but accept the default which is to typeset for
single-sided printing and to start new chapters on new pages.  Usually,
you write an `@setchapternewpage odd' command for double-sided printing.


File: texinfo,  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 the `texinfo-format-buffer' and
`texinfo-format-region' commands is that they do not indent (nor fill)
paragraphs that contain `@w' or `@*' commands. *Note Refilling
Paragraphs::, for a detailed description of what goes on.


File: texinfo,  Node: End of Header,  Prev: paragraphindent,  Up: Header

End of Header
-------------

   Follow the header lines with an end-of-header line. An end-of-header
line looks like this:

     @c %**end of header

   If you include the `@setchapternewpage' command between the
start-of-header and end-of-header lines, TeX will typeset a region as
that command specifies.  Similarly, if you include an `@smallbook'
command between the start-of-header and end-of-header lines, TeX will
typeset a region in the "small" book format.

   The reason for the odd string of characters (`%**') is so that the
`texinfo-tex-region' command does not accidentally find something that
it should not when it is looking for the header.

   The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.


File: texinfo,  Node: Info Summary and Permissions,  Next: Titlepage & Copyright Page,  Prev: Header,  Up: Beginning a File

Summary and Copying Permissions for Info
========================================

   The title page and the copyright page appear only in the printed
copy of the manual; therefore, the same information must be inserted in
a section that appears only in the Info file.  This section usually
contains a brief description of the contents of the Info file, a
copyright notice, and copying permissions.

   The copyright notice should read:

     Copyright YEAR COPYRIGHT-OWNER

and be put on a line by itself.

   Standard text for the copyright permissions is contained in an
appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
Permissions, for the complete text.

   The permissions text appears in an Info file *before* the first
node.  This mean that a reader does *not* see this text when reading
the file using Info, except when using the advanced Info command `g *'.


File: texinfo,  Node: Titlepage & Copyright Page,  Next: The Top Node,  Prev: Info Summary and Permissions,  Up: Beginning a File

The Title and Copyright Pages
=============================

   A manual's name and author are usually printed on a title page.
Sometimes copyright information is printed on the title page as well;
more often, copyright information is printed on the back of the title
page.

   The title and copyright pages appear in the printed manual, but not
in the Info file.  Because of this, it is possible to use several
slightly obscure TeX typesetting commands that cannot be used in an
Info file. In addition, this part of the beginning of a Texinfo file
contains the text of the copying permissions that will appear in the
printed manual.

   *Note Titlepage Copying Permissions: Titlepage Permissions, for the
standard text for the copyright permissions.

* Menu:

* titlepage::                   Create a title for the printed document.
* titlefont center sp::         The `@titlefont', `@center',
                                  and `@sp' commands.
* title subtitle author::       The `@title', `@subtitle',
                                  and `@author' commands.
* Copyright & Permissions::     How to write the copyright notice and
                                  include copying permissions.
* end titlepage::               Turn on page headings after the title and
                                  copyright pages.
* headings on off::             An option for turning headings on and off
                                  and double or single sided printing.


File: texinfo,  Node: titlepage,  Next: titlefont center sp,  Up: Titlepage & Copyright Page

`@titlepage'
------------

   Start the material for the title page and following copyright page
with `@titlepage' on a line by itself and end it with `@end titlepage'
on a line by itself.

   The `@end titlepage' command starts a new page and turns on page
numbering. (*Note Page Headings: Headings, for details about how to
generate of page headings.)  All the material that you want to appear
on unnumbered pages should be put between the `@titlepage' and `@end
titlepage' commands.  By using the `@page' command you can force a page
break within the region delineated by the `@titlepage' and `@end
titlepage' commands and thereby create more than one unnumbered page.
This is how the copyright page is produced.  (The `@titlepage' command
might perhaps have been better named the `@titleandadditionalpages'
command, but that would have been rather long!)

   When you write a manual about a computer program, you should write
the version of the program to which the manual applies on the title
page.  If the manual changes more frequently than the program or is
independent of it, you should also include an edition number(1) for the
manual.  This helps readers keep track of which manual is for which
version of the program.  (The `Top' node should also contain this
information; see *Note  `@top': makeinfo top.)

   Texinfo provides two methods for creating a title page.  One method
uses the `@titlefont', `@sp', and `@center' commands to generate a
title page in which the words on the page are centered.

   The second method uses the `@title', `@subtitle', and `@author'
commands to create a title page with black rules under the title and
author lines and the subtitle text set flush to the right hand side of
the page.  With this method, you do not specify any of the actual
formatting of the title page.  You specify the text you want, and
Texinfo does the formatting.  You may use either method.

   ---------- Footnotes ----------

   (1)  We have found that it is helpful to refer to versions of
manuals as `editions' and versions of programs as `versions';
otherwise, we find we are liable to confuse each other in conversation
by referring to both the documentation and the software with the same
words.