texinfo - Online Manual Page Of Unix/Linux

Our Recommended Sites:

File: texinfo, Node: Top, Next: Copying Conditions, Up: (dir)

Texinfo
*******

This manual is for GNU Texinfo (version 4.7, 9 April 2004), 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, 2003, 2004 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."

The first part of this master menu lists the major nodes in this Info
document, including the @-command and concept indices. The rest of the
menu lists all the lower level nodes in the document.

* Menu:

* Copying Conditions:: Your rights.
* Overview:: Texinfo in brief.
* Texinfo Mode:: Using the GNU Emacs Texinfo mode.
* Beginning a File:: What is at the beginning of a Texinfo file?
* Ending a File:: What is at the end of a Texinfo file?
* Structuring:: Creating chapters, sections, appendices, etc.
* Nodes:: Writing nodes, the basic unit of Texinfo.
* Menus:: Writing menus.
* Cross References:: Writing cross references.
* Marking Text:: Marking words and phrases as code,
keyboard input, meta-syntactic
variables, and the like.
* Quotations and Examples:: Block quotations, examples, etc.
* Lists and Tables:: Itemized or numbered lists, and tables.
* Special Displays:: Floating figures and footnotes.
* Indices:: Creating indices.
* Insertions:: Inserting @-signs, braces, etc.
* Breaks:: Forcing or preventing line and page breaks.
* Definition Commands:: Describing functions and the like uniformly.
* Conditionals:: Specifying text for only some output cases.
* Internationalization:: Supporting languages other than English.
* Defining New Texinfo Commands:: User-defined macros and aliases.
* Hardcopy:: Output for paper, with TeX.
* Creating and Installing Info Files:: Details on Info output.
* Generating HTML:: Details on HTML output.

* Command List:: All the Texinfo @-commands.
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo Files:: Complete examples, including full texts.
* Include Files:: How to incorporate other Texinfo files.
* Headings:: How to write page headings and footings.
* Catching Mistakes:: How to find formatting mistakes.
* Copying This Manual:: The GNU Free Documentation License.
* Command and Variable Index:: A menu containing commands and variables.
* Concept Index:: A menu covering many topics.

--- The Detailed Node Listing ---

Overview of Texinfo

* Reporting Bugs:: Submitting effective bug reports.
* Using Texinfo:: Create printed or online output.
* Output Formats:: Overview of the supported output formats.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
* Formatting Commands:: @-commands are used for formatting.
* Conventions:: General rules for writing a Texinfo file.
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
* History:: Acknowledgements, contributors and genesis.

Using Texinfo Mode

* 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.

Updating Nodes and Menus

* 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.

Beginning a Texinfo File

* 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.
* Contents:: How to create a table of contents.
* 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.

Texinfo File Header

* 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.

Document Permissions

* copying:: Declare the document's copying permissions.
* insertcopying:: Where to insert the permissions.

Title and Copyright Pages

* 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:: 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.

The `Top' Node and Master Menu

* Top Node Example::
* Master Menu Parts::

Global Document Commands

* documentdescription:: Document summary for the HTML output.
* setchapternewpage:: Start chapters on right-hand pages.
* paragraphindent:: Specify paragraph indentation.
* firstparagraphindent:: Suppress indentation of the first paragraph.
* exampleindent:: Specify environment indentation.

Ending a Texinfo File

* Printing Indices & Menus:: How to print an index in hardcopy and
generate index menus in Info.
* File End:: How to mark the end of a file.

Chapter Structuring

* Tree Structuring:: A manual is like an upside down tree ...
* Structuring Command Types:: How to divide a manual into parts.
* makeinfo top:: The `@top' command, part of the `Top' node.
* chapter::
* unnumbered & appendix::
* majorheading & chapheading::
* section::
* unnumberedsec appendixsec heading::
* subsection::
* unnumberedsubsec appendixsubsec subheading::
* subsubsection:: Commands for the lowest level sections.
* Raise/lower sections:: How to change commands' hierarchical level.

Nodes

* Two Paths:: Different commands to structure
Info output and printed output.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* node:: Creating nodes, in detail.
* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
* anchor:: Defining arbitrary cross-reference targets.

The `@node' Command

* Node Names:: How to choose node and pointer names.
* Writing a Node:: How to write an `@node' line.
* Node Line Tips:: Keep names short.
* Node Line Requirements:: Keep names unique, without @-commands.
* First Node:: How to write a `Top' node.
* makeinfo top command:: How to use the `@top' command.

Menus

* Menu Location:: Menus go at the ends of short nodes.
* Writing a Menu:: What is a menu?
* Menu Parts:: A menu entry has three parts.
* Less Cluttered Menu Entry:: Two part menu entry.
* Menu Example:: Two and three part menu entries.
* Other Info Files:: How to refer to a different Info file.

Cross References

* References:: What cross references are for.
* Cross Reference Commands:: A summary of the different commands.
* Cross Reference Parts:: A cross reference has several parts.
* xref:: Begin a reference with `See' ...
* Top Node Naming:: How to refer to the beginning of another file.
* ref:: A reference for the last part of a sentence.
* pxref:: How to write a parenthetical cross reference.
* inforef:: How to refer to an Info-only file.
* uref:: How to refer to a uniform resource locator.

`@xref'

* Reference Syntax:: What a reference looks like and requires.
* One Argument:: `@xref' with one argument.
* Two Arguments:: `@xref' with two arguments.
* Three Arguments:: `@xref' with three arguments.
* Four and Five Arguments:: `@xref' with four and five arguments.

Marking Words and Phrases

* Indicating:: How to indicate definitions, files, etc.
* Emphasis:: How to emphasize text.

Indicating Definitions, Commands, etc.

* Useful Highlighting:: Highlighting provides useful information.
* code:: Indicating program code.
* kbd:: Showing keyboard input.
* key:: Specifying keys.
* samp:: A literal sequence of characters.
* verb:: A verbatim sequence of characters.
* var:: Indicating metasyntactic variables.
* env:: Indicating environment variables.
* file:: Indicating file names.
* command:: Indicating command names.
* option:: Indicating option names.
* dfn:: Specifying definitions.
* cite:: Referring to books not in the Info system.
* acronym:: Indicating acronyms.
* indicateurl:: Indicating a World Wide Web reference.
* email:: Indicating an electronic mail address.

Emphasizing Text

* emph & strong:: How to emphasize text in Texinfo.
* Smallcaps:: How to use the small caps font.
* Fonts:: Various font commands for printed output.

Quotations and Examples

* Block Enclosing Commands:: Different constructs for different purposes.
* quotation:: Writing a quotation.
* example:: Writing an example in a fixed-width font.
* verbatim:: Writing a verbatim example.
* verbatiminclude:: Including a file verbatim.
* lisp:: Illustrating Lisp code.
* small:: Examples in a smaller font.
* display:: Writing an example in the current font.
* format:: Writing an example without narrowed margins.
* exdent:: Undo indentation on a line.
* flushleft & flushright:: Pushing text flush left or flush right.
* noindent:: Preventing paragraph indentation.
* indent:: Forcing paragraph indentation.
* cartouche:: Drawing rounded rectangles around examples.

Lists and Tables

* Introducing Lists:: Texinfo formats lists for you.
* itemize:: How to construct a simple list.
* enumerate:: How to construct a numbered list.
* Two-column Tables:: How to construct a two-column table.
* Multi-column Tables:: How to construct generalized tables.

Making a Two-column Table

* table:: How to construct a two-column table.
* ftable vtable:: Automatic indexing for two-column tables.
* itemx:: How to put more entries in the first column.

`@multitable': Multi-column Tables

* Multitable Column Widths:: Defining multitable column widths.
* Multitable Rows:: Defining multitable rows, with examples.

Special Displays

* Floats:: Figures, tables, and the like.
* Images:: Including graphics and images.
* Footnotes:: Writing footnotes.

Floats

* float:: Producing floating material.
* caption shortcaption:: Specifying descriptions for floats.
* listoffloats:: A table of contents for floats.

Inserting Images

* Image Syntax::
* Image Scaling::

Footnotes

* Footnote Commands:: How to write a footnote in Texinfo.
* Footnote Styles:: Controlling how footnotes appear in Info.

Indices

* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
of entries.
* Indexing Commands:: How to make an index entry.
* Combining Indices:: How to combine indices.
* New Indices:: How to define your own indices.

Combining Indices

* syncodeindex:: How to merge two indices, using `@code'
font for the merged-from index.
* synindex:: How to merge two indices, using the
default font of the merged-to index.

Special Insertions

* Atsign Braces Comma:: Inserting @ and {} and ,.
* Inserting Space:: How to insert the right amount of space
within a sentence.
* Inserting Accents:: How to insert accents and special characters.
* Dots Bullets:: How to insert dots and bullets.
* TeX and copyright:: How to insert the TeX logo
and the copyright symbol.
* pounds:: How to insert the pounds currency symbol.
* minus:: How to insert a minus sign.
* math:: How to format a mathematical expression.
* Glyphs:: How to indicate results of evaluation,
expansion of macros, errors, etc.

Inserting @ and {} and ,

* Inserting an Atsign::
* Inserting Braces::
* Inserting a Comma::

Inserting Space

* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
* Ending a Sentence:: Sometimes it does.
* Multiple Spaces:: Inserting multiple spaces.
* dmn:: How to format a dimension.

Inserting Ellipsis and Bullets

* dots:: How to insert dots ...
* bullet:: How to insert a bullet.

Inserting TeX and Legal Symbols: (C), (R)

* tex:: The TeX logos.
* copyright symbol:: The copyright symbol (c in a circle).
* registered symbol:: The registered symbol (R in a circle).

Glyphs for Examples

* Glyphs Summary::
* result:: How to show the result of expression.
* expansion:: How to indicate an expansion.
* Print Glyph:: How to indicate printed output.
* Error Glyph:: How to indicate an error message.
* Equivalence:: How to indicate equivalence.
* Point Glyph:: How to indicate the location of point.

Glyphs Summary

* result::
* expansion::
* Print Glyph::
* Error Glyph::
* Equivalence::
* Point Glyph::

Forcing and Preventing Breaks

* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* - and hyphenation:: Helping TeX with hyphenation points.
* w:: Preventing unwanted line breaks in text.
* tie:: Inserting an unbreakable but varying space.
* sp:: Inserting blank lines.
* page:: Forcing the start of a new page.
* group:: Preventing unwanted page breaks.
* need:: Another way to prevent unwanted page breaks.

Definition Commands

* Def Cmd Template:: Writing descriptions using definition commands.
* Def Cmd Continuation Lines:: Continuing the heading over source lines.
* Optional Arguments:: Handling optional and repeated arguments.
* deffnx:: Group two or more `first' lines.
* Def Cmds in Detail:: Reference for all the definition commands.
* Def Cmd Conventions:: Conventions for writing definitions.
* Sample Function Definition:: An example.

The Definition Commands

* Functions Commands:: Commands for functions and similar entities.
* Variables Commands:: Commands for variables and similar entities.
* Typed Functions:: Commands for functions in typed languages.
* Typed Variables:: Commands for variables in typed languages.
* Data Types:: The definition command for data types.
* Abstract Objects:: Commands for object-oriented programming.

Object-Oriented Programming

* Variables: Object-Oriented Variables.
* Methods: Object-Oriented Methods.

Conditionally Visible Text

* Conditional Commands:: Text for a given format.
* Conditional Not Commands:: Text for any format other than a given one.
* Raw Formatter Commands:: Using raw formatter commands.
* set clear value:: Variable tests and substitutions.
* Conditional Nesting:: Using conditionals inside conditionals.

`@set', `@clear', and `@value'

* set value:: Expand a flag variable to a string.
* ifset ifclear:: Format a region if a flag is set.
* value Example:: An easy way to update edition information.

Internationalization

* documentlanguage:: Declaring the current language.
* documentencoding:: Declaring the input encoding.

Defining New Texinfo Commands

* Defining Macros:: Defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
* Macro Details:: Limitations of Texinfo macros.
* alias:: Command aliases.
* definfoenclose:: Customized highlighting.

Formatting and Printing Hardcopy

* Use TeX:: Use TeX to format for hardcopy.
* Format with tex/texindex:: How to format with explicit shell commands.
* Format with texi2dvi:: A simpler way to format.
* Print with lpr:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: TeX formatting requirements summary.
* Preparing for TeX:: What to do before you use TeX.
* Overfull hboxes:: What are and what to do with overfull hboxes.
* smallbook:: How to print small format books and manuals.
* A4 Paper:: How to print on A4 or A5 paper.
* pagesizes:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
* PDF Output:: Portable Document Format output.
* Obtaining TeX:: How to Obtain TeX.

Creating and Installing Info Files

* Creating an Info File::
* Installing an Info File::

Creating an Info File

* makeinfo advantages:: `makeinfo' provides better error checking.
* Invoking makeinfo:: How to run `makeinfo' from a shell.
* makeinfo options:: Specify fill-column and other options.
* Pointer Validation:: How to check that pointers point somewhere.
* makeinfo in Emacs:: How to run `makeinfo' from Emacs.
* texinfo-format commands:: Two Info formatting commands written
in Emacs Lisp are an alternative
to `makeinfo'.
* Batch Formatting:: How to format for Info in Emacs Batch mode.
* Tag and Split Files:: How tagged and split files help Info
to run better.

Installing an Info File

* Directory File:: The top level menu for all Info files.
* New Info File:: Listing a new Info file.
* Other Info Directories:: How to specify Info files that are
located in other directories.
* Installing Dir Entries:: How to specify what menu entry to add
to the Info directory.
* Invoking install-info:: `install-info' options.

Generating HTML

* HTML Translation:: Details of the HTML output.
* HTML Splitting:: How HTML output is split.
* HTML CSS:: Influencing HTML output with Cascading Style Sheets.
* HTML Xref:: Cross-references in HTML output.

HTML Cross-references

* Link Basics: HTML Xref Link Basics.
* Node Expansion: HTML Xref Node Name Expansion.
* Command Expansion: HTML Xref Command Expansion.
* 8-bit Expansion: HTML Xref 8-bit Character Expansion.
* Mismatch: HTML Xref Mismatch.

@-Command List

* Command Syntax:: General syntax for varieties of @-commands.

Sample Texinfo Files

* Short Sample Texinfo File::
* GNU Sample Texts::
* Verbatim Copying License::
* All-permissive Copying License::

Copying This Manual

* GNU Free Documentation License:: License for copying this manual.

Include Files

* Using Include Files:: How to use the `@include' command.
* texinfo-multiple-files-update:: How to create and update nodes and
menus when using included files.
* Include Files Requirements:: `texinfo-multiple-files-update' needs.
* Sample Include File:: A sample outer file with included files
within it; and a sample included file.
* Include Files Evolution:: How use of the `@include' command
has changed over time.

Page Headings

* Headings Introduced:: Conventions for using page headings.
* Heading Format:: Standard page heading formats.
* Heading Choice:: How to specify the type of page heading.
* Custom Headings:: How to create your own headings and footings.

Formatting Mistakes

* makeinfo Preferred:: `makeinfo' finds errors.
* Debugging with Info:: How to catch errors with Info formatting.
* Debugging with TeX:: How to catch errors with TeX formatting.
* Using texinfo-show-structure:: How to use `texinfo-show-structure'.
* Using occur:: How to list all lines containing a pattern.
* Running Info-Validate:: How to find badly referenced nodes.

Finding Badly Referenced Nodes

* Using Info-validate:: How to run `Info-validate'.
* Unsplit:: How to create an unsplit file.
* Tagifying:: How to tagify a file.
* Splitting:: How to split a file manually.

Copying This Manual

* GNU Free Documentation License:: License for copying this manual.

Documentation is like sex: when it is good, it is very, very good;
and when it is bad, it is better than nothing. --Dick Brandon

File: texinfo, Node: Copying Conditions, Next: Overview, Prev: Top, Up: Top

Texinfo Copying Conditions
**************************

The programs currently being distributed that relate to Texinfo include
`makeinfo', `info', `texindex', and `texinfo.tex'. These programs are
"free"; this means that everyone is free to use them and free to
redistribute them on a free basis. The Texinfo-related programs are
not in the public domain; they are copyrighted and there are
restrictions on their distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to Texinfo, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of the Texinfo related programs, you must give the recipients all
the rights that you have. You must make sure that they, too, receive or
can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to Texinfo.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
Licenses that accompany them. This manual specifically is covered by
the GNU Free Documentation License (*note GNU Free Documentation
License::).

File: texinfo, Node: Overview, Next: Texinfo Mode, Prev: Copying Conditions, Up: Top

1 Overview of Texinfo
*********************

"Texinfo"(1) is a documentation system that uses a single source file
to produce both online information and printed output. This means that
instead of writing two different documents, one for the online
information and the other for a printed work, you need write only one
document. Therefore, when the work is revised, you need revise only
that one document.

* Menu:

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

(1) The first syllable of "Texinfo" is pronounced like "speck", not
"hex". This odd pronunciation is derived from, but is not the same as,
the pronunciation of TeX. In the word TeX, the `X' is actually the
Greek letter "chi" rather than the English letter "ex". Pronounce TeX
as if the `X' were the last sound in the name `Bach'; but pronounce
Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T"
and the other letters in lower case.

File: texinfo, Node: Reporting Bugs, Next: Using Texinfo, Up: Overview

1.1 Reporting Bugs
==================

We welcome bug reports and suggestions for any aspect of the Texinfo
system, programs, documentation, installation, anything. Please email
them to <>. You can get the latest version of
Texinfo from `ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide.

For bug reports, please include enough information for the maintainers
to reproduce the problem. Generally speaking, that means:

* the version number of Texinfo and the program(s) or manual(s)
involved.

* hardware and operating system names and versions.

* the contents of any input files necessary to reproduce the bug.

* a description of the problem and samples of any erroneous output.

* any unusual options you gave to `configure'.

* anything else that you think would be helpful.

When in doubt whether something is needed or not, include it. It's
better to include too much than to leave out something important.

Patches are most welcome; if possible, please make them with
`diff -c' (*note Overview: (diff)Top.) and include `ChangeLog' entries
(*note Change Log: (emacs)Change Log.).

When sending patches, if possible please do not encode or split them
in any way; it's much easier to deal with one plain text message,
however large, than many small ones. GNU shar
(ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging
multiple and/or binary files for email.

File: texinfo, Node: Using Texinfo, Next: Output Formats, Prev: Reporting Bugs, Up: Overview

1.2 Using Texinfo
=================

Using Texinfo, you can create a printed document (via the TeX
typesetting system) the normal features of a book, including chapters,
sections, cross references, and indices. From the same Texinfo source
file, you can create an Info file with special features to make
documentation browsing easy. You can also create from that same source
file an HTML output file suitable for use with a web browser, or an XML
file. See the next section (*note Output Formats::) for details and
the exact commands to generate output from the source.

TeX works with virtually all printers; Info works with virtually all
computer terminals; the HTML output works with virtually all web
browsers. Thus Texinfo can be used by almost any computer user.

A Texinfo source file is a plain ASCII file containing text
interspersed with "@-commands" (words preceded by an `@') that tell the
typesetting and formatting programs what to do. You can edit a Texinfo
file with any text editor, but it is especially convenient to use GNU
Emacs since that editor has a special mode, called Texinfo mode, that
provides various Texinfo-related features. (*Note Texinfo Mode::.)

You can use Texinfo to create both online help and printed manuals;
moreover, Texinfo is freely redistributable. For these reasons, Texinfo
is the official documentation format of the GNU project. More
information is available at the GNU documentation web page
(http://www.gnu.org/doc/).

File: texinfo, Node: Output Formats, Next: Info Files, Prev: Using Texinfo, Up: Overview

1.3 Output Formats
==================

Here is a brief overview of the output formats currently supported by
Texinfo.

Info
(Generated via `makeinfo'.) This format is essentially a plain
text transliteration of the Texinfo source. It adds a few control
characters to separate nodes and provide navigational information
for menus, cross-references, indices, and so on. See the next
section (*note Info Files::) for more details on this format. The
Emacs Info subsystem (*note Getting Started: (info)Top.), and the
standalone `info' program (*note Info Standalone:
(info-stnd)Top.), among others, can read these files. *Note
Creating and Installing Info Files::.

Plain text
(Generated via `makeinfo --no-headers'.) This is almost the same
as Info output, except the navigational control characters are
omitted.

HTML
(Generated via `makeinfo --html'.) This is the Hyper Text Markup
Language that has become the most commonly used language for
writing documents on the World Wide Web. Web browsers, such as
Mozilla, Lynx, and Emacs-W3, can render this language online.
There are many versions of HTML; `makeinfo' tries to use a subset
of the language that can be interpreted by any common browser. For
details of the HTML language and much related information, see
`http://www.w3.org/MarkUp/'. *Note Generating HTML::.

DVI
(Generated via `texi2dvi'.) This DeVice Independent binary format
is output by the TeX typesetting program (`http://tug.org'). This
is then read by a DVI `driver', which writes the actual
device-specific commands that can be viewed or printed, notably
Dvips for translation to PostScript (*note Invoking Dvips:
(dvips)Invoking Dvips.) and Xdvi for viewing on an X display
(`http://sourceforge.net/projects/xdvi/'). *Note Hardcopy::.

Be aware that the Texinfo language is very different from and much
stricter than TeX's usual languages, plain TeX and LaTeX. For
more information on TeX in general, please see the book `TeX for
the Impatient', available from
`http://savannah.gnu.org/projects/teximpatient'.

PDF
(Generated via `texi2dvi --pdf'.) This format, based on
PostScript, was developed by Adobe Systems for document
interchange. It is intended to be platform-independent and easily
viewable, among other design goals; for a discussion, see
`http://tug.org/tugboat/Articles/tb22-3/tb72beebeI.pdf'. Texinfo
uses the `pdftex' program, a variant of TeX, to output pdf; see
`http://tug.org/applications/pdftex'. *Note PDF Output::.

XML
(Generated via `makeinfo --xml'.) XML is a generic syntax
specification usable for any sort of content (see, for example,
`http://www.w3.org/XML/'). The `makeinfo' xml output, unlike all
the formats above, interprets very little of the Texinfo source.
Rather, it merely translates the Texinfo markup commands into XML
syntax, for processing by further XML tools. The particular
syntax output is defined in the file `texinfo.dtd' included in the
Texinfo source distribution.

Docbook
(Generated via `makeinfo --docbook'.) This is an XML-based format
developed some years ago, primarily for technical documentation.
It therefore bears some resemblance, in broad outlines, to
Texinfo. See `http://www.docbook.org'. If you want to convert
from Docbook _to_ Texinfo, please see
`http://docbook2X.sourceforge.net'.

From time to time, proposals are made to generate traditional Unix man
pages from Texinfo source. However, because man pages have a very
strict conventional format, generating a good man page requires a
completely different source than the typical Texinfo applications of
writing a good user tutorial and/or a good reference manual. This
makes generating man pages incompatible with the Texinfo design goal of
not having to document the same information in different ways for
different output formats. You might as well just write the man page
directly.

Man pages still have their place, and if you wish to support them, you
may find the program `help2man' to be useful; it generates a
traditional man page from the `--help' output of a program. In fact,
this is currently used to generate man pages for the programs in the
Texinfo distribution. It is GNU software written by Brendan O'Dea,
available from `ftp://ftp.gnu.org/gnu/help2man/'.

If you are a programmer and would like to contribute to the GNU
project by implementing additional output formats for Texinfo, that
would be excellent. But please do not write a separate translator
texi2foo for your favorite format foo! That is the hard way to do the
job, and makes extra work in subsequent maintenance, since the Texinfo
language is continually being enhanced and updated. Instead, the best
approach is modify `makeinfo' to generate the new format.

File: texinfo, Node: Info Files, Next: Printed Books, Prev: Output Formats, Up: Overview

1.4 Info Files
==============

An Info file is a Texinfo file formatted so that the Info documentation
reading program can operate on it. (`makeinfo' and
`texinfo-format-buffer' are two commands that convert a Texinfo file
into an Info file.)

Info files are divided into pieces called "nodes", each of which
contains the discussion of one topic. Each node has a name, and
contains both text for the user to read and pointers to other nodes,
which are identified by their names. The Info program displays one node
at a time, and provides commands with which the user can move to other
related nodes.

*Note Top: (info)Top, for more information about using Info.

Each node of an Info file may have any number of child nodes that
describe subtopics of the node's topic. The names of child nodes are
listed in a "menu" within the parent node; this allows you to use
certain Info commands to move to one of the child nodes. Generally, an
Info file is organized like a book. If a node is at the logical level
of a chapter, its child nodes are at the level of sections; likewise,
the child nodes of sections are at the level of subsections.

All the children of any one parent are linked together in a
bidirectional chain of `Next' and `Previous' pointers. The `Next'
pointer provides a link to the next section, and the `Previous' pointer
provides a link to the previous section. This means that all the nodes
that are at the level of sections within a chapter are linked together.
Normally the order in this chain is the same as the order of the
children in the parent's menu. Each child node records the parent node
name as its `Up' pointer. The last child has no `Next' pointer, and the
first child has the parent both as its `Previous' and as its `Up'
pointer.(1)

The book-like structuring of an Info file into nodes that correspond
to chapters, sections, and the like is a matter of convention, not a
requirement. The `Up', `Previous', and `Next' pointers of a node can
point to any other nodes, and a menu can contain any other nodes.
Thus, the node structure can be any directed graph. But it is usually
more comprehensible to follow a structure that corresponds to the
structure of chapters and sections in a printed book or report.

In addition to menus and to `Next', `Previous', and `Up' pointers,
Info provides pointers of another kind, called references, that can be
sprinkled throughout the text. This is usually the best way to
represent links that do not fit a hierarchical structure.

Usually, you will design a document so that its nodes match the
structure of chapters and sections in the printed output. But
occasionally there are times when this is not right for the material
being discussed. Therefore, Texinfo uses separate commands to specify
the node structure for the Info file and the section structure for the
printed output.

Generally, you enter an Info file through a node that by convention is
named `Top'. This node normally contains just a brief summary of the
file's purpose, and a large menu through which the rest of the file is
reached. From this node, you can either traverse the file
systematically by going from node to node, or you can go to a specific
node listed in the main menu, or you can search the index menus and then
go directly to the node that has the information you want.
Alternatively, with the standalone Info program, you can specify
specific menu items on the command line (*note Top: (info)Top.).

If you want to read through an Info file in sequence, as if it were a
printed manual, you can hit repeatedly, or you get the whole file
with the advanced Info command `g *'. (*note Advanced Info commands:
(info)Advanced.)

The `dir' file in the `info' directory serves as the departure point
for the whole Info system. From it, you can reach the `Top' nodes of
each of the documents in a complete Info system.

If you wish to refer to an Info file in a URI, you can use the
(unofficial) syntax exemplified in the following. This works with
Emacs/W3, for example:
info:///usr/info/emacs#Dissociated%20Press
info:emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press

The `info' program itself does not follow URI's of any kind.

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

(1) In some documents, the first child has no `Previous' pointer.
Occasionally, the last child has the node name of the next following
higher level node as its `Next' pointer.

File: texinfo, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview

1.5 Printed Books
=================

A Texinfo file can be formatted and typeset as a printed book or manual.
To do this, you need TeX, a powerful, sophisticated typesetting program
written by Donald Knuth.(1)

A Texinfo-based book is similar to any other typeset, printed work: it
can have a title page, copyright page, table of contents, and preface,
as well as chapters, numbered or unnumbered sections and subsections,
page headers, cross references, footnotes, and indices.

You can use Texinfo to write a book without ever having the intention
of converting it into online information. You can use Texinfo for
writing a printed novel, and even to write a printed memo, although
this latter application is not recommended since electronic mail is so
much easier.

TeX is a general purpose typesetting program. Texinfo provides a
file `texinfo.tex' that contains information (definitions or "macros")
that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells
TeX how to convert the Texinfo @-commands to TeX commands, which TeX
can then process to create the typeset document.) `texinfo.tex'
contains the specifications for printing a document. You can get the
latest version of `texinfo.tex' from
`ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex'.

In the United States, documents are most often printed on 8.5 inch by
11 inch pages (216mm by 280mm); this is the default size. But you can
also print for 7 inch by 9.25 inch pages (178mm by 235mm, the
`@smallbook' size; or on A4 or A5 size paper (`@afourpaper',
`@afivepaper'). (*Note Printing "Small" Books: smallbook. Also, see
*Note Printing on A4 Paper: A4 Paper.)

By changing the parameters in `texinfo.tex', you can change the size
of the printed document. In addition, you can change the style in
which the printed document is formatted; for example, you can change the
sizes and fonts used, the amount of indentation for each paragraph, the
degree to which words are hyphenated, and the like. By changing the
specifications, you can make a book look dignified, old and serious, or
light-hearted, young and cheery.

TeX is freely distributable. It is written in a superset of Pascal
called WEB and can be compiled either in Pascal or (by using a
conversion program that comes with the TeX distribution) in C. (*Note
TeX Mode: (emacs)TeX Mode, for information about TeX.)

TeX is very powerful and has a great many features. Because a
Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
formatting commands that Texinfo supports are necessarily limited.

To get a copy of TeX, see *Note How to Obtain TeX: Obtaining TeX.

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

(1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz)
program if you do not have TeX; since Texinfo is designed for use with
TeX, `texi2roff' is not described here. `texi2roff' is not part of the
standard GNU distribution and is not maintained or up-to-date with all
the Texinfo features described in this manual.

File: texinfo, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview

1.6 @-commands
==============

In a Texinfo file, the commands that tell TeX how to typeset the
printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
create an Info file are preceded by `@'; they are called "@-commands".
For example, `@node' is the command to indicate a node and `@chapter'
is the command to indicate the start of a chapter.

Note: Almost all @ command names are entirely lower case.

The Texinfo @-commands are a strictly limited set of constructs. The
strict limits make it possible for Texinfo files to be understood both
by TeX and by the code that converts them into Info files. You can
display Info files on any terminal that displays alphabetic and numeric
characters. Similarly, you can print the output generated by TeX on a
wide variety of printers.

Depending on what they do or what arguments(1) they take, you need to
write @-commands on lines of their own or as part of sentences:

* Write a command such as `@quotation' at the beginning of a line as
the only text on the line. (`@quotation' begins an indented
environment.)

* Write a command such as `@chapter' at the beginning of a line
followed by the command's arguments, in this case the chapter
title, on the rest of the line. (`@chapter' creates chapter
titles.)

* Write a command such as `@dots{}' wherever you wish but usually
within a sentence. (`@dots{}' creates dots ...)

* Write a command such as `@code{SAMPLE-CODE}' wherever you wish
(but usually within a sentence) with its argument, SAMPLE-CODE in
this example, between the braces. (`@code' marks text as being
code.)

* Write a command such as `@example' on a line of its own; write the
body-text on following lines; and write the matching `@end'
command, `@end example' in this case, on a line of its own after
the body-text. (`@example' ... `@end example' indents and typesets
body-text as an example.) It's usually ok to indent environment
commands like this, but in complicated and hard-to-define
circumstances the extra spaces cause extra space to appear in the
output, so beware.

As a general rule, a command requires braces if it mingles among other
text; but it does not need braces if it starts a line of its own. The
non-alphabetic commands, such as `@:', are exceptions to the rule; they
do not need braces.

As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands
actually make it easier to write and read Texinfo files than if all
commands followed exactly the same syntax. *Note @-Command Syntax:
Command Syntax, for all the details.

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

(1) The word "argument" comes from the way it is used in mathematics
and does not refer to a dispute between two people; it refers to the
information presented to the command. According to the `Oxford English
Dictionary', the word derives from the Latin for "to make clear,
prove"; thus it came to mean `the evidence offered as proof', which is
to say, `the information offered', which led to its mathematical
meaning. In its other thread of derivation, the word came to mean `to
assert in a manner against which others may make counter assertions',
which led to the meaning of `argument' as a dispute.

File: texinfo, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview

1.7 General Syntactic Conventions
=================================

This section describes the general conventions used in all Texinfo
documents.

* All printable ASCII characters except `@', `{' and `}' can appear
in a Texinfo file and stand for themselves. `@' is the escape
character which introduces commands, while `{' and `}' are used to
surround arguments to certain commands. To put one of these
special characters into the document, put an `@' character in
front of it, like this: `@@', `@{', and `@}'.

* Separate paragraphs with one or more blank lines. Currently
Texinfo only recognizes newline characters as end of line, not the
CRLF sequence used on some systems; so a "blank line" means
exactly two consecutive newlines. Sometimes blank lines are
useful or convenient in other cases as well; you can use the
`@noindent' to inhibit paragraph indentation if required (*note
`@noindent': noindent.).

* Use doubled single-quote characters to begin and end quotations:
``...''. TeX converts two single quotes to left- and right-hand
doubled quotation marks, and Info converts doubled single-quote
characters to ASCII double-quotes: ``...'' becomes "...".

You may occasionally need to produce two consecutive single quotes;
for example, in documenting a computer language such as Maxima
where '' is a valid command. You can do this with the input
'@w{}'; the empty `@w' command stops the combination into the
double-quote characters.

The left quote character (`, ASCII code 96) used in Texinfo is a
grave accent in ANSI and ISO character set standards. We use it
as a quote character because that is how TeX is set up, by
default. We hope to eventually support the various quotation
characters in Unicode.

* Use three hyphens in a row, `---', to produce a long dash--like
this (called an "em dash"), used for punctuation in sentences.
Use two hyphens, `--', to produce a medium dash-like this (called
an "en dash"), used to separate numeric ranges. Use a single
hyphen, `-', to produce a standard hyphen used in compound words.
For display on the screen, Info reduces three hyphens to two and
two hyphens to one (not transitively!). Of course, any number of
hyphens in the source remain as they are in literal contexts, such
as `@code' and `@example'.

* *Caution:* Last and most important, do not use tab characters in a
Texinfo file (except in verbatim modes)! TeX uses variable-width
fonts, which means that it is impractical at best to define a tab
to work in all circumstances. Consequently, TeX treats tabs like
single spaces, and that is not what they look like in the source.
Furthermore, `makeinfo' does nothing special with tabs, and thus a
tab character in your input file will usually appear differently
in the output.

To avoid this problem, Texinfo mode causes GNU Emacs to insert
multiple spaces when you press the key.

Also, you can run `untabify' in Emacs to convert tabs in a region
to multiple spaces, or use the `unexpand' command from the shell.

File: texinfo, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview

1.8 Comments
============

You can write comments in a Texinfo file that will not appear in either
the Info file or the printed manual by using the `@comment' command
(which may be abbreviated to `@c'). Such comments are for the person
who revises the Texinfo file. All the text on a line that follows
either `@comment' or `@c' is a comment; the rest of the line does not
appear in either the Info file or the printed manual.

Often, you can write the `@comment' or `@c' in the middle of a line,
and only the text that follows after the `@comment' or `@c' command
does not appear; but some commands, such as `@settitle' and
`@setfilename', work on a whole line. You cannot use `@comment' or
`@c' in a line beginning with such a command.

You can write long stretches of text that will not appear in either
the Info file or the printed manual by using the `@ignore' and `@end
ignore' commands. Write each of these commands on a line of its own,
starting each command at the beginning of the line. Text between these
two commands does not appear in the processed output. You can use
`@ignore' and `@end ignore' for writing comments.

Text enclosed by `@ignore' or by failing `@ifset' or `@ifclear'
conditions is ignored in the sense that it will not contribute to the
formatted output. However, TeX and makeinfo must still parse the
ignored text, in order to understand when to _stop_ ignoring text from
the source file; that means that you may still get error messages if
you have invalid Texinfo commands within ignored text.

File: texinfo, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview

1.9 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

1.10 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

1.11 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.

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 the
printed manual uses a table of contents rather than a menu, it excludes
the `Top' node. We also include the copying text again for the benefit
of online readers. Since the copying text begins with a brief
description of the manual, no other text is needed in this case. The
`@top' command itself helps `makeinfo' determine the relationships
between nodes.

@ifnottex
@node Top
@top Short Sample

@insertcopying
@end ifnottex

@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

1.12 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

2 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:

File: texinfo, Node: Texinfo Mode Overview, Next: Emacs Editing, Up: Texinfo Mode

2.1 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

2.2 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

2.3 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

2.4 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

2.5 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:

File: texinfo, Node: Updating Commands, Next: Updating Requirements, Up: Updating Nodes and Menus

2.5.1 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 via customization (*note Changing an Option:
(emacs)Changing an Option.) 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

2.5.2 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

2.5.3 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

2.6 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

2.7 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

2.8 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

3 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. A table of contents is also generally
produced here.

This chapter expands on the minimal complete Texinfo source file
previously given (*note Six Parts::). It describes the numerous
commands for handling the traditional frontmatter items in Texinfo.

Straight text outside of any command before the Top node should be
avoided. Such text is treated differently in the different output
formats: visible in TeX and HTML, by default not shown in Info readers,
and so on.

* Menu:

File: texinfo, Node: Sample Beginning, Next: Texinfo File Header, Up: Beginning a File

3.1 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.

@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 at the start.
@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

3.2 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:

File: texinfo, Node: First Line, Next: Start of Header, Up: Texinfo File Header

3.2.1 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

3.2.2 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::.

File: texinfo, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Texinfo File Header

3.2.3 `@setfilename': Set the output file name
----------------------------------------------

In order to serve as the primary input file for either `makeinfo' or
TeX, a Texinfo file must contain a line that looks like this:

@setfilename INFO-FILE-NAME

Write the `@setfilename' command at the beginning of a line and
follow it on the same line by the Info file name. Do not write anything
else on the line; anything on the line after the command is considered
part of the file name, including what would otherwise be a comment.

The Info formatting commands ignore everything written before the
`@setfilename' line, which is why the very first line of the file (the
`\input' line) does not show up in the output.

The `@setfilename' line specifies the name of the output file to be
generated. This name must be different from the name of the Texinfo
file. There are two conventions for choosing the name: you can either
remove the extension (such as `.texi') entirely from the input file
name, or, preferably, replace it with the `.info' extension.

Although an explicit `.info' extension is preferable, 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 and Split Files::.) The
subfile name `texinfo.info-10', for example, is too long for old
systems with a 14-character limit on filenames; so the Info file name
for this document is `texinfo' rather than `texinfo.info'. When
`makeinfo' is running on operating systems such as MS-DOS which impose
severe limits on file names, it may remove some characters from the
original file name to leave enough space for the subfile suffix, thus
producing files named `texin-10', `gcc.i12', etc.

When producing HTML output, `makeinfo' will replace any extension
with `html', or add `.html' if the given name has no extension.

The `@setfilename' line produces no output when you typeset a manual
with TeX, but it is nevertheless essential: it opens the index,
cross-reference, and other auxiliary files used by Texinfo, and also
reads `texinfo.cnf' if that file is present on your system (*note
Preparing for TeX: Preparing for TeX.).

File: texinfo, Node: settitle, Next: End of Header, Prev: setfilename, Up: Texinfo File Header

3.2.4 `@settitle': Set the document title
-----------------------------------------

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
what would otherwise be a comment.

The `@settitle' command should precede everything that generates
actual output. The best place for it is right after the `@setfilename'
command (see the previous section).

In the HTML file produced by `makeinfo', TITLE serves as the document
`'. It also becomes the default document description in the
`<head>' part (*note documentdescription::).

The title in the `@settitle' command does not affect the title as it
appears on the title page. Thus, the two do not need not match
exactly. A practice we recommend is to include the version or edition
number of the manual in the `@settitle' title; on the title page, the
version number generally appears as a `@subtitle' so it would be
omitted from the `@title'. *Note titlepage::.

Conventionally, when TeX formats a Texinfo file for double-sided
output, the title is printed in the left-hand (even-numbered) page
headings and the current chapter title is printed in the right-hand
(odd-numbered) page headings. (TeX learns the title of each chapter
from each `@chapter' command.) By default, no page footer is 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.

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 Headings::, for a detailed discussion of this.

File: texinfo, Node: End of Header, Prev: settitle, Up: Texinfo File Header

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

Follow the header lines with an end-of-header line, which is a Texinfo
comment that looks like this:

@c %**end of header

*Note Start of Header::.

File: texinfo, Node: Document Permissions, Next: Titlepage & Copyright Page, Prev: Texinfo File Header, Up: Beginning a File

3.3 Document Permissions
========================

The copyright notice and copying permissions for a document need to
appear in several places in the various Texinfo output formats.
Therefore, Texinfo provides a command (`@copying') to declare this text
once, and another command (`@insertcopying') to insert the text at
appropriate points.

* Menu:

* copying:: Declare the document's copying permissions.
* insertcopying:: Where to insert the permissions.

File: texinfo, Node: copying, Next: insertcopying, Up: Document Permissions

3.3.1 `@copying': Declare Copying Permissions
---------------------------------------------

The `@copying' command should be given very early in the document; the
recommended location is right after the header material (*note Texinfo
File Header::). It conventionally consists of a sentence or two about
what the program is, identification of the documentation itself, the
legal copyright line, and the copying permissions. Here is a skeletal
example:

@copying
This manual is for PROGRAM (version VERSION, updated
DATE), which ...

@quotation
Permission is granted to ...
@end quotation
@end copying

The `@quotation' has no legal significance; it's there to improve
readability in some contexts.

*Note GNU Sample Texts::, for the full text to be used in GNU manuals.
*Note GNU Free Documentation License::, for the license itself under
which GNU and other free manuals are distributed. You need to include
the license as an appendix to your document.

The text of `@copying' is output as a comment at the beginning of
Info, HTML, and XML output files. It is _not_ output implicitly in
plain text or TeX; it's up to you to use `@insertcopying' to emit the
copying information. See the next section for details.

The `@copyright{}' command generates a `c' inside a circle in output
formats that support this (print and HTML). In the other formats (Info
and plain text), it generates `(C)'. The copyright notice itself has
the following legally defined sequence:

The word `Copyright' must always be written in English, even if the
document is otherwise written in another language. This is due to
international law.

The list of years should include all years in which a version was
completed (even if it was released in a subsequent year). Ranges are
not allowed; each year must be written out individually and in full,
separated by commas.

The copyright owner (or owners) is whoever holds legal copyright on
the work. In the case of works assigned to the FSF, the owner is `Free
Software Foundation, Inc.'.

The copyright `line' may actually be split across multiple lines,
both in the source document and in the output. This often happens for
documents with a long history, having many different years of
publication.

*Note Copyright Notices: (maintain)Copyright Notices, for additional
information.

File: texinfo, Node: insertcopying, Prev: copying, Up: Document Permissions

3.3.2 `@insertcopying': Include Permissions Text
------------------------------------------------

The `@insertcopying' command is simply written on a line by itself,
like this:

@insertcopying

This inserts the text previously defined by `@copying'. To meet
legal requirements, it must be used on the copyright page in the printed
manual (*note Copyright::).

We also strongly recommend using `@insertcopying' in the Top node of
your manual (*note The Top Node::), although it is not required
legally. Here's why:

The `@copying' command itself causes the permissions text to appear
in an Info file _before_ the first node. The text is also copied into
the beginning of each split Info output file, as is legally necessary.
This location implies a human reading the manual using Info does _not_
see this text (except when using the advanced Info command `g *').
Therefore, an explicit `@insertcopying' in the Top node makes it
apparent to readers that the manual is free.

Similarly, the `@copying' text is automatically included at the
beginning of each HTML output file, as an HTML comment. Again, this
text is not visible (unless the reader views the HTML source). And
therefore again, the `@insertcopying' in the Top node is valuable
because it makes the copying permissions visible and thus promotes
freedom.

The permissions text defined by `@copying' also appears automatically
at the beginning of the XML output file.

File: texinfo, Node: Titlepage & Copyright Page, Next: Contents, Prev: Document Permissions, Up: Beginning a File

3.4 Title and Copyright Pages
=============================

In hard copy output, the manual's name and author are usually printed on
a title page. Copyright information is usually 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 appears in the printed manual.

You may wish to include titlepage-like information for plain text
output. Simply place any such leading material between `@ifplaintext'
and `@end ifplaintext'; `makeinfo' includes this when writing plain
text (`--no-headers'), along with an `@insertcopying'.

* Menu:

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

3.4.1 `@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 page headings.) All the material that you want to appear on
unnumbered pages should be put between the `@titlepage' and `@end
titlepage' commands. You can force the table of contents to appear
there with the `@setcontentsaftertitlepage' command (*note Contents::).

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 The Top Node::.)

Texinfo provides two main 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, or you may combine them; see the examples
in the sections below.

For extremely simple documents, and for the bastard title page in
traditional book frontmatter, Texinfo also provides a command
`@shorttitlepage' which takes the rest of the line as the title. The
argument is typeset on a page by itself and followed by a blank page.

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

(1) We have found that it is helpful to refer to versions of
independent 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.

File: texinfo, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page

3.4.2 `@titlefont', `@center', and `@sp'
----------------------------------------

You can use the `@titlefont', `@sp', and `@center' commands to create a
title page for a printed document. (This is the first of the two
methods for creating a title page in Texinfo.)

Use the `@titlefont' command to select a large font suitable for the
title itself. You can use `@titlefont' more than once if you have an
especially long title.

For HTML output, each `@titlefont' command produces an `<h1>'
heading, but the HTML document `<title>' is not affected. For that,
you must put an `@settitle' command before the `@titlefont' command
(*note settitle::).

For example:

@titlefont{Texinfo}

Use the `@center' command at the beginning of a line to center the
remaining text on that line. Thus,

@center @titlefont{Texinfo}

centers the title, which in this example is "Texinfo" printed in the
title font.

Use the `@sp' command to insert vertical space. For example:

@sp 2

This inserts two blank lines on the printed page. (*Note `@sp': sp,
for more information about the `@sp' command.)

A template for this method looks like this:

@titlepage
@sp 10
@center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
@sp 2
@center SUBTITLE-IF-ANY
@sp 2
@center AUTHOR
...
@end titlepage

The spacing of the example fits an 8.5 by 11 inch manual.

You can in fact use these commands anywhere, not just on a title page,
but since they are not logical markup commands, we don't recommend them.

File: texinfo, Node: title subtitle author, Next: Copyright, Prev: titlefont center sp, Up: Titlepage & Copyright Page

3.4.3 `@title', `@subtitle', and `@author'
------------------------------------------

You can use the `@title', `@subtitle', and `@author' commands to create
a title page in which the vertical and horizontal spacing is done for
you automatically. This contrasts with the method described in the
previous section, in which the `@sp' command is needed to adjust
vertical spacing.

Write the `@title', `@subtitle', or `@author' commands at the
beginning of a line followed by the title, subtitle, or author. These
commands are only effective in TeX output; it's an error to use them
anywhere except within `@titlepage'.

The `@title' command produces a line in which the title is set flush
to the left-hand side of the page in a larger than normal font. The
title is underlined with a black rule. Only a single line is allowed;
the `@*' command may not be used to break the title into two lines. To
handle very long titles, you may find it profitable to use both
`@title' and `@titlefont'; see the final example in this section.

The `@subtitle' command sets subtitles in a normal-sized font flush
to the right-hand side of the page.

The `@author' command sets the names of the author or authors in a
middle-sized font flush to the left-hand side of the page on a line
near the bottom of the title page. The names are underlined with a
black rule that is thinner than the rule that underlines the title.
(The black rule only occurs if the `@author' command line is followed
by an `@page' command line.)

There are two ways to use the `@author' command: you can write the
name or names on the remaining part of the line that starts with an
`@author' command:

@author by Jane Smith and John Doe

or you can write the names one above each other by using two (or more)
`@author' commands:

@author Jane Smith
@author John Doe

(Only the bottom name is underlined with a black rule.)

A template for this method looks like this:

@titlepage
@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE-IF-ANY
@subtitle SECOND-SUBTITLE
@author AUTHOR
@page
...
@end titlepage

You may also combine the `@titlefont' method described in the
previous section and `@title' method described in this one. This may
be useful if you have a very long title. Here is a real-life example:

@titlepage
@titlefont{GNU Software}
@sp 1
@title for MS-Windows and MS-DOS
@subtitle Edition @value{e} for Release @value{cde}
@author by Daniel Hagerty, Melissa Weisshaus
@author and Eli Zaretskii

(The use of `@value' here is explained in *Note value Example::.

File: texinfo, Node: Copyright, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page

3.4.4 Copyright Page
--------------------

By international treaty, the copyright notice for a book must be either
on the title page or on the back of the title page. When the copyright
notice is on the back of the title page, that page is customarily not
numbered. Therefore, in Texinfo, the information on the copyright page
should be within `@titlepage' and `@end titlepage' commands.

Use the `@page' command to cause a page break. To push the copyright
notice and the other text on the copyright page towards the bottom of
the page, use the following incantantion after `@page':

@vskip 0pt plus 1filll

This is a TeX command that is not supported by the Info formatting
commands. The `@vskip' command inserts whitespace. The `0pt plus
1filll' means to put in zero points of mandatory whitespace, and as
much optional whitespace as needed to push the following text to the
bottom of the page. Note the use of three `l's in the word `filll';
this is correct.

To insert the copyright text itself, write `@insertcopying' next
(*note Document Permissions::):

@insertcopying

Follow the copying text by the publisher, ISBN numbers, cover art
credits, and other such information.

Here is an example putting all this together:

@titlepage
...
@page
@vskip 0pt plus 1filll
@insertcopying

Published by ...

Cover art by ...
@end titlepage

File: texinfo, Node: end titlepage, Next: headings on off, Prev: Copyright, Up: Titlepage & Copyright Page

3.4.5 Heading Generation
------------------------

The `@end titlepage' command must be written on a line by itself. It
not only marks the end of the title and copyright pages, but also
causes TeX to start generating page headings and page numbers.

To repeat what is said elsewhere, Texinfo has two standard page
heading formats, one for documents which are printed on one side of
each sheet of paper (single-sided printing), and the other for
documents which are printed on both sides of each sheet (double-sided
printing). You can specify these formats in different ways:

* The conventional way is to write an `@setchapternewpage' command
before the title page commands, and then have the `@end titlepage'
command start generating page headings in the manner desired.
(*Note setchapternewpage::.)

* Alternatively, you can use the `@headings' command to prevent page
headings from being generated or to start them for either single or
double-sided printing. (Write an `@headings' command immediately
after the `@end titlepage' command. *Note The `@headings'
Command: headings on off, for more information.)

* Or, you may specify your own page heading and footing format.
*Note Page Headings: Headings, for detailed information about page
headings and footings.

Most documents are formatted with the standard single-sided or
double-sided format, using `@setchapternewpage odd' for double-sided
printing and no `@setchapternewpage' command for single-sided printing.

File: texinfo, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page

3.4.6 The `@headings' Command
-----------------------------

The `@headings' command is rarely used. It specifies what kind of page
headings and footings to print on each page. Usually, this is
controlled by the `@setchapternewpage' command. You need the
`@headings' command only if the `@setchapternewpage' command does not
do what you want, or if you want to turn off pre-defined page headings
prior to defining your own. Write an `@headings' command immediately
after the `@end titlepage' command.

You can use `@headings' as follows:

`@headings off'
Turn off printing of page headings.

`@headings single'
Turn on page headings appropriate for single-sided printing.

`@headings double'
`@headings on'
Turn on page headings appropriate for double-sided printing. The
two commands, `@headings on' and `@headings double', are
synonymous.

`@headings singleafter'
`@headings doubleafter'
Turn on `single' or `double' headings, respectively, after the
current page is output.

`@headings on'
Turn on page headings: `single' if `@setchapternewpage on',
`double' otherwise.

For example, suppose you write `@setchapternewpage off' before the
`@titlepage' command to tell TeX to start a new chapter on the same
pag</pre>
</td>
</tr>
</table>
</body>
</html>