This is texinfo, produced by makeinfo version 4.3 from texinfo.txi.
This manual is for GNU Texinfo (version 4.3, 14 November 2002), a
documentation system that can produce both online information and a
printed manual from a single source.
Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
END-INFO-DIR-ENTRY
File: texinfo, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview
What a Texinfo File Must Have
=============================
By convention, the namea of a Texinfo file ends with (in order of
preference) one of the extensions `.texinfo', `.texi', `.txi', or
`.tex'. The longer extensions are preferred since they describe more
clearly to a human reader the nature of the file. The shorter
extensions are for operating systems that cannot handle long file names.
In order to be made into a printed manual and an Info file, a Texinfo
file *must* begin with lines like this:
\input texinfo
@setfilename INFO-FILE-NAME
@settitle NAME-OF-MANUAL
The contents of the file follow this beginning, and then you *must* end
a Texinfo file with a line like this:
@bye
Here's an explanation:
* The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
which tells TeX how to translate the Texinfo @-commands into TeX
typesetting commands. (Note the use of the backslash, `\'; this
is correct for TeX.)
* The `@setfilename' line provides a name for the Info file and
tells TeX to open auxiliary files. *All text before
`@setfilename' is ignored!*
* The `@settitle' line specifies a title for the page headers (or
footers) of the printed manual, and the default document
description for the `
' in HTML format. Strictly speaking,
`@settitle' is optional--if you don't mind your document being
titled `Untitled'.
* The `@bye' line at the end of the file on a line of its own tells
the formatters that the file is ended and to stop formatting.
Typically, you will not use quite such a spare format, but will
include mode setting and start-of-header and end-of-header lines at the
beginning of a Texinfo file, like this:
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename INFO-FILE-NAME
@settitle NAME-OF-MANUAL
@c %**end of header
In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
mode when you edit the file.
The `@c' lines which surround the `@setfilename' and `@settitle'
lines are optional, but you need them in order to run TeX or Info on
just part of the file. (*Note Start of Header::.)
Furthermore, you will usually provide a Texinfo file with a title
page, indices, and the like, all of which are explained in this manual.
But the minimum, which can be useful for short documents, is just the
three lines at the beginning and the one line at the end.
File: texinfo, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview
Six Parts of a Texinfo File
===========================
Generally, a Texinfo file contains more than the minimal beginning and
end described in the previous section--it usually contains the six
parts listed below. These are described fully in the following
sections.
1. Header
The "Header" names the file, tells TeX which definitions file to
use, and other such housekeeping tasks.
2. Summary and Copyright
The "Summary and Copyright" segment describes the document and
contains the copyright notice and copying permissions. This is
done with the `@copying' command.
3. Title and Copyright
The "Title and Copyright" segment contains the title and copyright
pages for the printed manual. The segment must be enclosed between
`@titlepage' and `@end titlepage' commands. The title and
copyright page appear only in the printed manual.
4. `Top' Node and Master Menu
The `Top' node starts off the online output; it does not appear in
the printed manual. We recommend including the copying
permissions here as well as the segments above. And it contains
at least a top-level menu listing the chapters, and possibly a
"Master Menu" listing all the nodes in the entire document.
5. Body
The "Body" of the document is typically structured like a
traditional book or encyclopedia, but it may be free form.
6. End
The "End" segment contains commands for printing indices and
generating the table of contents, and the `@bye' command on a line
of its own.
File: texinfo, Node: Short Sample, Next: History, Prev: Six Parts, Up: Overview
A Short Sample Texinfo File
===========================
Here is a very short but complete Texinfo file, in the six
conventional parts enumerated in the previous section, so you can see
how Texinfo source appears in practice. 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 writing a manual, you simply change the names as
appropriate.
*Note Beginning a File::, for full documentation on the commands
listed here. *Note GNU Sample Texts::, for the full texts to be used
in GNU manuals.
In the following, the sample text is _indented_; comments on it are
not. The complete file, without interspersed comments, is shown in
*Note Short 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 Manual 1.0
@c %**end of header
Part 2: Summary Description and Copyright
-----------------------------------------
A real manual includes more text here, according to the license under
which it is distributed. *Note GNU Sample Texts::.
@copying
This is a short example of a complete Texinfo file, version 1.0.
Copyright @copyright{} 2002 Free Software Foundation, Inc.
@end copying
Part 3: Titlepage, Contents, Copyright
--------------------------------------
The titlepage segment does not appear in the online output, only in the
printed manual. We use the `@insertcopying' command to include the
permission text from the previous section, instead of writing it out
again; it is output on the back of the title page. The `@contents'
command generates a table of contents.
@titlepage
@title Sample Title
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@c Output the table of contents at the beginning.
@contents
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 online output. We also include the copying text
again for the benefit of online readers. And since the copying text
begins with a brief description of the manual, no other text is needed.
@ifnottex
@node Top
@end ifnottex
@insertcopying
@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
* Index:: Complete index.
@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
@chapter First Chapter
@cindex chapter, first
This is the first chapter.
@cindex index entry, another
Here is a numbered list.
@enumerate
@item
This is the first item.
@item
This is the second item.
@end enumerate
Part 6: The End of the Document
-------------------------------
The end segment contains commands for generating an index in a node and
unnumbered chapter of its own, and the `@bye' command that marks the
end of the document.
@node Index
@unnumbered Index
@printindex cp
@bye
Some Results
------------
Here is what the contents of the first chapter of the sample look
like:
This is the first chapter.
Here is a numbered list.
1. This is the first item.
2. This is the second item.
File: texinfo, Node: History, Prev: Short Sample, Up: Overview
History
=======
Richard M. Stallman invented the Texinfo format, wrote the initial
processors, and created Edition 1.0 of this manual. Robert J.
Chassell greatly revised and extended the manual, starting with Edition
1.1. Brian Fox was responsible for the standalone Texinfo distribution
until version 3.8, and wrote the standalone `makeinfo' and `info'
programs. Karl Berry has continued maintenance since Texinfo 3.8
(manual edition 2.22).
Our thanks go out to all who helped improve this work, particularly
the indefatigable Eli Zaretskii and Andreas Schwab, who have provided
patches beyond counting. Franc,ois Pinard and David D. Zuhn,
tirelessly recorded and reported mistakes and obscurities. Zack
Weinberg did the impossible by implementing the macro syntax in
`texinfo.tex'. Special thanks go to Melissa Weisshaus for her frequent
reviews of nearly similar editions. Dozens of others have contributed
patches and suggestions, they are gratefully acknowledged in the
`ChangeLog' file. Our mistakes are our own.
A bit of history: in the 1970's at CMU, Brian Reid developed a program
and format named Scribe to mark up documents for printing. It used the
`@' character to introduce commands, as Texinfo does. Much more
consequentially, it strived to describe document contents rather than
formatting, an idea wholeheartedly adopted by Texinfo.
Meanwhile, people at MIT developed another, not too dissimilar format
called Bolio. This then was converted to using TeX as its typesetting
language: BoTeX. The earliest BoTeX version seems to have been 0.02 on
October 31, 1984.
BoTeX could only be used as a markup language for documents to be
printed, not for online documents. Richard Stallman (RMS) worked on
both Bolio and BoTeX. He also developed a nifty on-line help format
called Info, and then combined BoTeX and Info to create Texinfo, a mark
up language for text that is intended to be read both online and as
printed hard copy.
File: texinfo, 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. So if you are reading this
manual straight through from the beginning, you may want to skim through
this chapter briefly and come back to it after reading succeeding
chapters which describe the Texinfo formatting language in detail.
* Menu:
* Texinfo Mode Overview:: How Texinfo mode can help you.
* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
purpose editing features.
* Inserting:: How to insert frequently used @-commands.
* Showing the Structure:: How to show the structure of a file.
* Updating Nodes and Menus:: How to update or create new nodes and menus.
* Info Formatting:: How to format for Info.
* Printing:: How to format and print part or all of a file.
* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
File: texinfo, 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.
You can:
* 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 extensions `.texinfo', `.texi',
`.txi', 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', `.texi' or
`.txi' 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 and leave the cursor after the
.
`C-c C-c v'
`M-x texinfo-insert-@var'
Insert `@var{}' and put the cursor between the braces.
`C-c C-c x'
`M-x texinfo-insert-@example'
Insert `@example' and put the cursor at the beginning of the next
line.
`C-c C-c {'
`M-x texinfo-insert-braces'
Insert `{}' and put the cursor between the braces.
`C-c C-c }'
`C-c C-c ]'
`M-x up-list'
Move from between a pair of braces forward past the closing brace.
Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
however, more mnemonic; hence the two keybindings. (Also, you can
move out from between braces by typing `C-f'.)
To put a command such as `@code{...}' around an _existing_ word,
position the cursor in front of the word and type `C-u 1 C-c C-c c'.
This makes it easy to edit existing plain text. The value of the
prefix argument tells Emacs how many words following point to include
between braces--`1' for one word, `2' for two words, and so on. Use a
negative argument to enclose the previous word or words. If you do not
specify a prefix argument, Emacs inserts the @-command string and
positions the cursor between the braces. This feature works only for
those @-commands that operate on a word or words within one line, such
as `@kbd' and `@var'.
This set of insert commands was created after analyzing the frequency
with which different @-commands are used in the `GNU Emacs Manual' and
the `GDB Manual'. If you wish to add your own insert commands, you can
bind a keyboard macro to a key, use abbreviations, or extend the code
in `texinfo.el'.
`C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
that works differently from the other insert commands. It inserts a
node's section or chapter title in the space for the description in a
menu entry line. (A menu entry has three parts, the entry name, the
node name, and the description. Only the node name is required, but a
description helps explain what the node is about. *Note The Parts of a
Menu: Menu Parts.)
To use `texinfo-start-menu-description', position point in a menu
entry line and type `C-c C-c C-d'. The command looks for and copies
the title that goes with the node name, and inserts the title as a
description; it positions point at beginning of the inserted text so you
can edit it. The function does not insert the title if the menu entry
line already contains a description.
This command is only an aid to writing descriptions; it does not do
the whole job. You must edit the inserted text since a title tends to
use the same words as a node name but a useful description uses
different words.
File: texinfo, 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.
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: (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, 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,
* insert or update the menu for a section, and
* 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. 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
or like this (without the explicit node pointers):
@node Comments
@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 may also 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::, 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
This command inserts titles as node names in `@node' lines; the
`texinfo-start-menu-description' command (*note Inserting
Frequently Used Commands: Inserting.) inserts titles as
descriptions in menu entries, a different action. However, in
both cases, you need to edit the inserted text.
`M-x texinfo-multiple-files-update'
Update nodes and menus in a document built from several separate
files. With `C-u' as a prefix argument, create and insert a
master menu in the outer file. With a numeric prefix argument,
such as `C-u 2', first update all the menus and all the `Next',
`Previous', and `Up' pointers of all the included files before
creating and inserting a master menu in the outer file. The
`texinfo-multiple-files-update' command is described in the
appendix on `@include' files. *Note
texinfo-multiple-files-update::.
`M-x texinfo-indent-menu-description'
Indent every description in the menu following point to the
specified column. You can use this command to give yourself more
space for descriptions. With an argument (`C-u' as prefix
argument, if interactive), the `texinfo-indent-menu-description'
command indents every description in every menu in the region.
However, this command does not indent the second and subsequent
lines of a multi-line description.
`M-x texinfo-sequential-node-update'
Insert the names of the nodes immediately following and preceding
the current node as the `Next' or `Previous' pointers regardless
of those nodes' hierarchical level. This means that the `Next'
node of a subsection may well be the next chapter. Sequentially
ordered nodes are useful for novels and other documents that you
read through sequentially. (However, in Info, the `g *' command
lets you look through the file sequentially, so sequentially
ordered nodes are not strictly necessary.) With an argument
(prefix argument, if interactive), the
`texinfo-sequential-node-update' command sequentially updates all
the nodes in the region.
File: texinfo, 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 Creating 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'
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 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 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 remaining 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 for the output file(s), the title of the
document, and the Top node.
This chapter expands on the minimal complete Texinfo source file
previously given (*note Six Parts::).
* Menu:
* Sample Beginning:: A sample beginning for a Texinfo file.
* Texinfo File Header:: The first lines.
* Document Permissions:: Ensuring your manual is free.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* The Top Node:: Creating the `Top' node and master menu.
* Global Document Commands:: Affecting formatting throughout.
* Software Copying Permissions:: Ensure that you and others continue to
have the right to use and share software.
File: texinfo, Node: Sample Beginning, Next: Texinfo File Header, Up: Beginning a File
Sample Texinfo File Beginning
=============================
The following sample shows what is needed. The elements given here
are explained in more detail in the following sections. Other commands
are often included at the beginning of Texinfo files, but the ones here
are the most critical.
*Note GNU Sample Texts::, for the full texts to be used in GNU
manuals.
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename INFONAME.info
@settitle NAME-OF-MANUAL VERSION
@c %**end of header
@copying
This manual is for PROGRAM, version VERSION.
Copyright @copyright{} YEARS COPYRIGHT-OWNER.
@quotation
Permission is granted to ...
@end quotation
@end copying
@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
@insertcopying
Published by ...
@end titlepage
@c So the toc is printed in the right place.
@contents
@ifnottex
@node Top
@top TITLE
@insertcopying
@end ifnottex
@menu
* First Chapter:: Getting started ...
* Second Chapter:: ...
...
* Copying:: Your rights and freedoms.
@end menu
@node First Chapter
@chapter First Chapter
@cindex first chapter
@cindex chapter, first
...
File: texinfo, Node: Texinfo File Header, Next: Document Permissions, Prev: Sample Beginning, Up: Beginning a File
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.
Also, if you want to format just part of the Texinfo file, you must
write the `@settitle' and `@setfilename' lines between start-of-header
and end-of-header lines. The start- and end-of-header lines are
optional, but they do no harm, so you might as well always include them.
Any command that affects document formatting as a whole makes sense to
include in the header. `@synindex' (*note synindex::), for instance,
is another command often included in the header. *Note GNU Sample
Texts::, for complete sample texts.
Thus, the beginning of a Texinfo file generally looks like this:
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Manual 1.0
@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.
* End of Header:: Formatting a region requires this.
File: texinfo, Node: First Line, Next: Start of Header, Up: Texinfo File 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 should have been
installed on your system along with either the TeX or Texinfo
software. TeX uses the backslash, `\', to mark the beginning of a
command, exactly 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: Texinfo File Header
Start of Header
---------------
A start-of-header line is a Texinfo comment that looks like this:
@c %**start of header
Write the 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 commands that globally affect the
document formatting, such as `@synindex' or `@footnotestyle'; and then
by an end-of-header line (*note End of Header::).
The start- and end-of-header lines allow you to format only part of a
Texinfo file for Info or printing. *Note texinfo-format commands::.
The odd string of characters, `%**', is to ensure that no other
comment is accidentally taken for a start-of-header line. You can
change it if you wish by setting the `tex-start-of-header' and/or
`tex-end-of-header' Emacs variables. *Note Texinfo Mode Printing::.