Google Git
Sign in
gnu / gcc / refs/tags/prereleases/egcs-1.1-prerelease / . / texinfo / doc / texinfo.txi
blob: c0b7a20d3b6eb189a8a5595da91523d3b14af3ad [file] [log] [blame]
\input texinfo.tex @c -*-texinfo-*-
@c $Id: texinfo.txi,v 1.50 1998/02/27 21:21:34 karl Exp $
@c %**start of header
@c All text is ignored before the setfilename.
@setfilename texinfo
@settitle Texinfo @value{edition}
@c Edition number is now the same as the Texinfo distribution version number.
@set edition 3.12
@set update-month February 1998
@set update-date 27 @value{update-month}
@c Define a new index for options.
@defcodeindex op
@c Put everything except function (command, in this case) names in one
@c index (arbitrarily chosen to be the concept index).
@syncodeindex op cp
@syncodeindex vr cp
@syncodeindex pg cp
@footnotestyle separate
@paragraphindent 2
@finalout
@comment %**end of header
@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
@c prefix arg). This updates the node pointers, which texinfmt.el needs.
@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
@end direntry
@c Set smallbook if printing in smallbook format so the example of the
@c smallbook font is actually written using smallbook; in bigbook, a kludge
@c is used for TeX output. Do this through the -t option to texi2dvi,
@c so this same source can be used for other paper sizes as well.
@c smallbook
@c set smallbook
@c @@clear smallbook
@c Currently undocumented command, 5 December 1993:
@c nwnode (Same as node, but no warnings; for `makeinfo'.)
@ifinfo
This file documents Texinfo, a documentation system that can produce
both on-line information and a printed manual from a single source file.
Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98
Free Software Foundation, Inc.
This edition is for Texinfo version @value{edition}.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo
@setchapternewpage odd
@shorttitlepage Texinfo
@titlepage
@c use the new format for titles
@title Texinfo
@subtitle The GNU Documentation Format
@subtitle for Texinfo version @value{edition}
@subtitle @value{update-month}
@author Robert J.@: Chassell
@author Richard M.@: Stallman
@c Include the Distribution inside the titlepage so
@c that headings are turned off.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98
Free Software Foundation, Inc.
Published by the Free Software Foundation @*
59 Temple Place Suite 330 @*
Boston, MA 02111-1307 @*
USA @*
ISBN 1-882114-65-5
@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@ifinfo
@node Top, Copying, (dir), (dir)
@top Texinfo
Texinfo is a documentation system that uses a single source file to
produce both on-line information and printed output.@refill
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.@refill
This is Edition @value{edition} of the Texinfo documentation,
@w{@value{update-date}}.
@end ifinfo
@c Here is a spare copy of the chapter menu entry descriptions,
@c in case they are accidently deleted
@ignore
Your rights.
Texinfo in brief.
How to use Texinfo mode.
What is at the beginning of a Texinfo file?
What is at the end of a Texinfo file?
How to create chapters, sections, subsections,
appendices, and other parts.
How to provide structure for a document.
How to write nodes.
How to write menus.
How to write cross references.
How to mark words and phrases as code,
keyboard input, meta-syntactic
variables, and the like.
How to write quotations, examples, etc.
How to write lists and tables.
How to create indices.
How to insert @@-signs, braces, etc.
How to indicate results of evaluation,
expansion of macros, errors, etc.
How to force and prevent line and page breaks.
How to describe functions and the like in a uniform manner.
How to write footnotes.
How to specify text for either @TeX{} or Info.
How to print hardcopy.
How to create an Info file.
How to install an Info file
A list of all the Texinfo @@-commands.
Hints on how to write a Texinfo document.
A sample Texinfo file to look at.
Tell readers they have the right to copy
and distribute.
How to incorporate other Texinfo files.
How to write page headings and footings.
How to find formatting mistakes.
All about paragraph refilling.
A description of @@-Command syntax.
Texinfo second edition features.
A menu containing commands and variables.
A menu covering many topics.
@end ignore
@menu
* Copying:: Your rights.
* Overview:: Texinfo in brief.
* Texinfo Mode:: How to use 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:: How to create chapters, sections, subsections,
appendices, and other parts.
* Nodes:: How to write nodes.
* Menus:: How to write menus.
* Cross References:: How to write cross references.
* Marking Text:: How to mark words and phrases as code,
keyboard input, meta-syntactic
variables, and the like.
* Quotations and Examples:: How to write quotations, examples, etc.
* Lists and Tables:: How to write lists and tables.
* Indices:: How to create indices.
* Insertions:: How to insert @@-signs, braces, etc.
* Breaks:: How to force and prevent line and page breaks.
* Definition Commands:: How to describe functions and the like
in a uniform manner.
* Footnotes:: How to write footnotes.
* Conditionals:: How to specify text for either @TeX{} or Info.
* Macros:: Defining new Texinfo commands.
* Format/Print Hardcopy:: How to convert a Texinfo file to a file
for printing and how to print that file.
* Create an Info File:: Convert a Texinfo file into an Info file.
* Install an Info File:: Make an Info file accessible to users.
* Command List:: All the Texinfo @@-commands.
* Tips:: Hints on how to write a Texinfo document.
* Sample Texinfo File:: A sample Texinfo file to look at.
* Sample Permissions:: Tell readers they have the right to copy
and distribute.
* Include Files:: How to incorporate other Texinfo files.
* Headings:: How to write page headings and footings.
* Catching Mistakes:: How to find formatting mistakes.
* Refilling Paragraphs:: All about paragraph refilling.
* Command Syntax:: A description of @@-Command syntax.
* Obtaining TeX:: How to Obtain @TeX{}.
* Command and Variable Index:: A menu containing commands and variables.
* Concept Index:: A menu covering many topics.
@detailmenu
--- The Detailed Node Listing ---
Overview of Texinfo
* Using Texinfo:: Create a conventional printed book
or an Info file.
* 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:: How to write comments and mark regions that
the formatting commands will ignore.
* Minimum:: What a Texinfo file must have.
* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
* Acknowledgements::
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
* Four Parts:: Four parts begin a Texinfo file.
* Sample Beginning:: Here is a sample beginning for a Texinfo file.
* Header:: The very beginning of a Texinfo file.
* Info Summary and Permissions:: Summary and copying permissions for Info.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* The Top Node:: Creating the `Top' node and master menu.
* Software Copying Permissions:: Ensure that you and others continue to
have the right to use and share software.
The 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.
* setchapternewpage:: Start chapters on right-hand pages.
* paragraphindent:: An option to specify paragraph indentation.
* End of Header:: Formatting a region requires this.
The Title and Copyright Pages
* titlepage:: Create a title for the printed document.
* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
and @code{@@sp} commands.
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
and @code{@@author} commands.
* Copyright & Permissions:: How to write the copyright notice and
include copying permissions.
* end titlepage:: Turn on page headings after the title and
copyright pages.
* headings on off:: An option for turning headings on and off
and double or single sided printing.
The `Top' Node and Master Menu
* Title of Top Node:: Sketch what the file is about.
* Master Menu Parts:: A master menu has three or more parts.
Ending a Texinfo File
* Printing Indices & Menus:: How to print an index in hardcopy and
generate index menus in Info.
* Contents:: How to create a table of contents.
* File End:: How to mark the end of a file.
Chapter Structuring
* Tree Structuring:: A manual is like an upside down tree @dots{}
* Structuring Command Types:: How to divide a manual into parts.
* makeinfo top:: The @code{@@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:: How to write a node, in detail.
* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}.
The @code{@@node} Command
* Node Names:: How to choose node and pointer names.
* Writing a Node:: How to write an @code{@@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 @code{@@top} command.
* Top Node Summary:: Write a brief description for readers.
Menus
* Menu Location:: Put a menu in a short node.
* 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' @dots{}
* 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.
@code{@@xref}
* Reference Syntax:: What a reference looks like and requires.
* One Argument:: @code{@@xref} with one argument.
* Two Arguments:: @code{@@xref} with two arguments.
* Three Arguments:: @code{@@xref} with three arguments.
* Four and Five Arguments:: @code{@@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:: How to indicate code.
* kbd:: How to show keyboard input.
* key:: How to specify keys.
* samp:: How to show a literal sequence of characters.
* var:: How to indicate a metasyntactic variable.
* file:: How to indicate the name of a file.
* dfn:: How to specify a definition.
* cite:: How to refer to a book that is not in Info.
* url:: How to indicate a world wide web reference.
* email:: How to indicate 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.
* Customized Highlighting:: How to define highlighting commands.
Quotations and Examples
* Block Enclosing Commands:: Use different constructs for
different purposes.
* quotation:: How to write a quotation.
* example:: How to write an example in a fixed-width font.
* noindent:: How to prevent paragraph indentation.
* Lisp Example:: How to illustrate Lisp code.
* smallexample & smalllisp:: Forms for the @code{@@smallbook} option.
* display:: How to write an example in the current font.
* format:: How to write an example that does not narrow
the margins.
* exdent:: How to undo the indentation of a line.
* flushleft & flushright:: How to push text flushleft or flushright.
* cartouche:: How to draw cartouches 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.
Multi-column Tables
* Multitable Column Widths:: Defining multitable column widths.
* Multitable Rows:: Defining multitable rows, with examples.
Creating Indices
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
of entry.
* 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{@@code}
font for the merged-from index.
* synindex:: How to merge two indices, using the
default font of the merged-to index.
Special Insertions
* Braces Atsigns:: How to insert braces, @samp{@@}.
* 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.
* Images:: How to include graphics.
Inserting @@ and Braces
* Inserting An Atsign:: How to insert @samp{@@}.
* Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
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, Dots, and Bullets
* dots:: How to insert dots @dots{}
* bullet:: How to insert a bullet.
Inserting @TeX{} and the Copyright Symbol
* tex:: How to insert the @TeX{} logo.
* copyright symbol:: How to use @code{@@copyright}@{@}.
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::
Making and Preventing Breaks
* Break Commands:: Cause and prevent splits.
* Line Breaks:: How to force a single line to use two lines.
* - and hyphenation:: How to tell TeX about hyphenation points.
* w:: How to prevent unwanted line breaks.
* sp:: How to insert blank lines.
* page:: How to force the start of a new page.
* group:: How to prevent unwanted page breaks.
* need:: Another way to prevent unwanted page breaks.
Definition Commands
* Def Cmd Template:: How to structure a description using a
definition command.
* Optional Arguments:: How to handle optional and repeated arguments.
* deffnx:: How to group two or more `first' lines.
* Def Cmds in Detail:: All the definition commands.
* Def Cmd Conventions:: Conventions for writing definitions.
* Sample Function Definition::
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.
* Abstract Objects:: Commands for object-oriented programming.
* Data Types:: The definition command for data types.
Footnotes
* Footnote Commands:: How to write a footnote in Texinfo.
* Footnote Styles:: Controlling how footnotes appear in Info.
Conditionally Visible Text
* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
* set clear value:: Designating which text to format (for
all output formats); and how to set a
flag to a string that you can insert.
@code{@@set}, @code{@@clear}, and @code{@@value}
* ifset ifclear:: Format a region if a flag is set.
* value:: Replace a flag with a string.
* value Example:: An easy way to update edition information.
Macros: Defining New Texinfo Commands
* Defining Macros:: Both defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
Format and Print Hardcopy
* Use TeX:: Use @TeX{} to format for hardcopy.
* Format with tex/texindex:: How to format in a shell.
* Format with texi2dvi:: A simpler way to use the shell.
* 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 you need to do to 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 European A4 paper.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
Creating an Info File
* makeinfo advantages:: @code{makeinfo} provides better error checking.
* Invoking makeinfo:: How to run @code{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 @code{makeinfo} from Emacs.
* texinfo-format commands:: Two Info formatting commands written
in Emacs Lisp are an alternative
to @code{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:: @code{install-info} options.
Sample Permissions
* Inserting Permissions:: How to put permissions in your document.
* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
* Titlepage Permissions:: Sample Titlepage copying permissions.
Include Files
* Using Include Files:: How to use the @code{@@include} command.
* texinfo-multiple-files-update:: How to create and update nodes and
menus when using included files.
* Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
* Sample Include File:: A sample outer file with included files
within it; and a sample included file.
* Include Files Evolution:: How use of the @code{@@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:: @code{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 @code{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 @code{Info-validate}.
* Unsplit:: How to create an unsplit file.
* Tagifying:: How to tagify a file.
* Splitting:: How to split a file manually.
How to Obtain @TeX{}
* New Texinfo Mode Commands:: The updating commands are especially useful.
* New Commands:: Many newly described @@-commands.
@end detailmenu
@end menu
@node Copying, Overview, Top, Top
@comment node-name, next, previous, up
@unnumbered Texinfo Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying Texinfo
The programs currently being distributed that relate to Texinfo include
portions of GNU Emacs, plus other separate programs (including
@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
These programs are @dfn{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.@refill
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.@refill
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.@refill
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.@refill
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.@refill
@node Overview, Texinfo Mode, Copying, Top
@comment node-name, next, previous, up
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview
@dfn{Texinfo}@footnote{Note that 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 @samp{X} is actually the Greek letter ``chi''
rather than the English letter ``ex''. Pronounce @TeX{} as if the
@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T''
and write the other letters in lower case.}
is a documentation system that uses a single source file to produce both
on-line information and printed output. This means that instead of
writing two different documents, one for the on-line help or other on-line
information and the other for a typeset manual or other printed work, you
need write only one document. When the work is revised, you need revise
only one document. (You can read the on-line information, known as an
@dfn{Info file}, with an Info documentation-reading program.)@refill
@menu
* Using Texinfo:: Create a conventional printed book
or an Info file.
* 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:: How to write comments and mark regions that
the formatting commands will ignore.
* Minimum:: What a Texinfo file must have.
* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
* Acknowledgements::
@end menu
@node Using Texinfo, Info Files, Overview, Overview
@ifinfo
@heading Using Texinfo
@end ifinfo
Using Texinfo, you can create a printed document with the normal
features of a book, including chapters, sections, cross references,
and indices. From the same Texinfo source file, you can create a
menu-driven, on-line Info file with nodes, menus, cross references,
and indices. You can, if you wish, make the chapters and sections of
the printed document correspond to the nodes of the on-line
information; and you use the same cross references and indices for
both the Info file and the printed work. @cite{The GNU
Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill
To make a printed document, you process a Texinfo source file with the
@TeX{} typesetting program. This creates a DVI file that you can
typeset and print as a book or report. (Note that the Texinfo language
is completely different from @TeX{}'s usual language, plain @TeX{}.) If
you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you
can use the @code{texi2roff} program instead.@refill
To make an Info file, you process a Texinfo source file with the
@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command;
this creates an Info file that you can install on-line.@refill
@TeX{} and @code{texi2roff} work with many types of printers; similarly,
Info works with almost every type of computer terminal. This power
makes Texinfo a general purpose system, but brings with it a constraint,
which is that a Texinfo file may contain only the customary
``typewriter'' characters (letters, numbers, spaces, and punctuation
marks) but no special graphics.@refill
A Texinfo file is a plain @sc{ascii} file containing text and
@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
typesetting and formatting programs what to do. You may 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. (@xref{Texinfo
Mode}.)@refill
Before writing a Texinfo source file, you should become familiar with
the Info documentation reading program and learn about nodes,
menus, cross references, and the rest. (@inforef{Top, info, info},
for more information.)@refill
You can use Texinfo to create both on-line help and printed manuals;
moreover, Texinfo is freely redistributable. For these reasons, Texinfo
is the format in which documentation for GNU utilities and libraries is
written.@refill
@node Info Files, Printed Books, Using Texinfo, Overview
@comment node-name, next, previous, up
@section Info files
@cindex Info files
An Info file is a Texinfo file formatted so that the Info documentation
reading program can operate on it. (@code{makeinfo}
and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
into an Info file.)@refill
Info files are divided into pieces called @dfn{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.@refill
@ifinfo
@inforef{Top, info, info}, for more information about using Info.@refill
@end ifinfo
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 @dfn{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.@refill
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.@footnote{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.}@refill
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.@refill
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.@refill
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.@refill
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 (@pxref{Top,,, info, Info}).
If you want to read through an Info file in sequence, as if it were a
printed manual, you can hit @key{SPC} repeatedly, or you get the whole
file with the advanced Info command @kbd{g *}. (@inforef{Expert,
Advanced Info commands, info}.)@refill
@c !!! dir file may be located in one of many places:
@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
@c /usr/local/info
@c /usr/local/lib/info
The @file{dir} file in the @file{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.@refill
@node Printed Books, Formatting Commands, Info Files, Overview
@comment node-name, next, previous, up
@section Printed Books
@cindex Printed book and manual characteristics
@cindex Manual characteristics, printed
@cindex Book characteristics, printed
@cindex Texinfo printed book characteristics
@cindex Characteristics, printed books or manuals
@cindex Knuth, Donald
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.@footnote{You can also use the
@code{texi2roff} program if you do not have @TeX{}; since Texinfo is
designed for use with @TeX{}, @code{texi2roff} is not described here.
@code{texi2roff} is not part of the standard GNU distribution.}
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.@refill
You can use Texinfo to write a book without ever having the intention
of converting it into on-line 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.@refill
@TeX{} is a general purpose typesetting program. Texinfo provides a
file called @file{texinfo.tex} that contains information (definitions or
@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
to @TeX{} commands, which @TeX{} can then process to create the typeset
document.) @file{texinfo.tex} contains the specifications for printing
a document.@refill
Most often, documents are printed on 8.5 inch by 11 inch
pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper
(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}.
Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill
By changing the parameters in @file{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.@refill
@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.
(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
about @TeX{}.)@refill
@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.@refill
@xref{Obtaining TeX, , How to Obtain @TeX{}}.
@node Formatting Commands, Conventions, Printed Books, Overview
@comment node-name, next, previous, up
@section @@-commands
@cindex @@-commands
@cindex Formatting commands
In a Texinfo file, the commands that tell @TeX{} how to typeset the
printed manual and tell @code{makeinfo} and
@code{texinfo-format-buffer} how to create an Info file are preceded
by @samp{@@}; they are called @dfn{@@-commands}. For example,
@code{@@node} is the command to indicate a node and @code{@@chapter}
is the command to indicate the start of a chapter.@refill
@quotation
@strong{Please note:} All the @@-commands, with the exception of the
@code{@@TeX@{@}} command, must be written entirely in lower
case.@refill
@end quotation
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.@refill
Depending on what they do or what arguments@footnote{The word
@dfn{argument} comes from the way it is used in mathematics and does
not refer to a disputation between two people; it refers to the
information presented to the command. According to the @cite{Oxford
English Dictionary}, the word derives from the Latin for @dfn{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
disputation.} they take, you need to write @@-commands on lines of
their own or as part of sentences:@refill
@itemize @bullet
@item
Write a command such as @code{@@noindent} at the beginning of a line as
the only text on the line. (@code{@@noindent} prevents the beginning of
the next line from being indented as the beginning of a
paragraph.)@refill
@item
Write a command such as @code{@@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. (@code{@@chapter} creates chapter titles.)@refill
@item
Write a command such as @code{@@dots@{@}} wherever you wish but usually
within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
@item
Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
wish (but usually within a sentence) with its argument,
@var{sample-code} in this example, between the braces. (@code{@@code}
marks text as being code.)@refill
@item
Write a command such as @code{@@example} at the beginning of a line of
its own; write the body-text on following lines; and write the matching
@code{@@end} command, @code{@@end example} in this case, at the
beginning of a line of its own after the body-text. (@code{@@example}
@dots{} @code{@@end example} indents and typesets body-text as an
example.)@refill
@end itemize
@noindent
@cindex Braces, when to use
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 @code{@@:}, are exceptions to the rule;
they do not need braces.@refill
As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands
make it easier to write and read Texinfo files than if all commands
followed exactly the same syntax. (For details about @@-command
syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
@node Conventions, Comments, Formatting Commands, Overview
@comment node-name, next, previous, up
@section General Syntactic Conventions
@cindex General syntactic conventions
@cindex Syntactic conventions
@cindex Conventions, syntactic
All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
@samp{@}} can appear in a Texinfo file and stand for themselves.
@samp{@@} is the escape character which introduces commands.
@samp{@{} and @samp{@}} should be used only to surround arguments to
certain commands. To put one of these special characters into the
document, put an @samp{@@} character in front of it, like this:
@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
@ifinfo
It is customary in @TeX{} to use doubled single-quote characters to
begin and end quotations: ` ` and ' ' (but without a space between the
two single-quote characters). This convention should be followed in
Texinfo files. @TeX{} converts doubled single-quote characters to
left- and right-hand doubled quotation marks and Info converts doubled
single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
@end ifinfo
@iftex
It is customary in @TeX{} to use doubled single-quote characters to
begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This
convention should be followed in Texinfo files. @TeX{} converts
doubled single-quote characters to left- and right-hand doubled
quotation marks, ``like this'', and Info converts doubled single-quote
characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and
@w{@tt{ '' }} to @w{@tt{ " }}.@refill
@end iftex
Use three hyphens in a row, @samp{---}, for a dash---like this. In
@TeX{}, a single or double hyphen produces a printed dash that is
shorter than the usual typeset dash. Info reduces three hyphens to two
for display on the screen.
To prevent a paragraph from being indented in the printed manual, put
the command @code{@@noindent} on a line by itself before the
paragraph.@refill
If you mark off a region of the Texinfo file with the @code{@@iftex}
and @w{@code{@@end iftex}} commands, that region will appear only in
the printed copy; in that region, you can use certain commands
borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
commands, that region will appear only in the Info file; in that
region, you can use Info commands that you cannot use in @TeX{}.
Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
@code{@@ifnothtml @dots{} @@end ifnothtml},
@code{@@ifnotinfo @dots{} @@end ifnotinfo},
@code{@@ifnottex @dots{} @@end ifnottex},
@xref{Conditionals}.
@cindex Tabs; don't use!
@quotation
@strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses
variable-width fonts, which means that it cannot predefine a tab to work
in all circumstances. Consequently, @TeX{} treats tabs like single
spaces, and that is not what they look like. Furthermore,
@code{makeinfo} does nothing special with tabs, and thus a tab character
in your input file may appear differently in the output.
@noindent
To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
spaces when you press the @key{TAB} key.@refill
@noindent
Also, you can run @code{untabify} in Emacs to convert tabs in a region
to multiple spaces.@refill
@noindent
Don't use tabs.
@end quotation
@node Comments, Minimum, Conventions, Overview
@comment node-name, next, previous, up
@section 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
@code{@@comment} command (which may be abbreviated to @code{@@c}).
Such comments are for the person who reads the Texinfo file. All the
text on a line that follows either @code{@@comment} or @code{@@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 @code{@@comment} or
@code{@@c} in the middle of a line, and only the text that follows after
the @code{@@comment} or @code{@@c} command does not appear; but some
commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
whole line. You cannot use @code{@@comment} or @code{@@c} in a line
beginning with such a command.)@refill
@cindex Comments
@findex comment
@findex c @r{(comment)}
You can write long stretches of text that will not appear in either
the Info file or the printed manual by using the @code{@@ignore} and
@code{@@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 @code{@@ignore} and @code{@@end ignore} for writing
comments. Often, @code{@@ignore} and @code{@@end ignore} is used
to enclose a part of the copying permissions that applies to the
Texinfo source file of a document, but not to the Info or printed
version of the document.@refill
@cindex Ignored text
@cindex Unprocessed text
@findex ignore
@c !!! Perhaps include this comment about ignore and ifset:
@ignore
Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
@code{@@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
@emph{stop} ignoring text from the source file; that means that you
will still get error messages if you have invalid Texinfo markup
within ignored text.
@end ignore
@node Minimum, Six Parts, Comments, Overview
@comment node-name, next, previous, up
@section What a Texinfo File Must Have
@cindex Minimal Texinfo file (requirements)
@cindex Must have in Texinfo file
@cindex Required in Texinfo file
@cindex Texinfo file minimum
By convention, the names of Texinfo files end with one of the
extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer
extension is preferred since it describes more clearly to a human
reader the nature of the file. The shorter extensions are for
operating systems that cannot handle long file names.@refill
In order to be made into a printed manual and an Info file, a Texinfo
file @strong{must} begin with lines like this:@refill
@example
@group
\input texinfo
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}
@end group
@end example
@noindent
The contents of the file follow this beginning, and then you @strong{must} end
a Texinfo file with a line like this:@refill
@example
@@bye
@end example
@findex input @r{(@TeX{} command)}
@noindent
The @samp{\input texinfo} line tells @TeX{} to use the
@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
@@-commands into @TeX{} typesetting commands. (Note the use of the
backslash, @samp{\}; this is correct for @TeX{}.) The
@samp{@@setfilename} line provides a name for the Info file and tells
@TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
title for the page headers (or footers) of the printed manual.@refill
The @code{@@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.@refill
Usually, 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:@refill
@example
@group
\input texinfo @@c -*-texinfo-*-
@@c %**start of header
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}
@@c %**end of header
@end group
@end example
@noindent
In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
Texinfo mode when you edit the file.
The @code{@@c} lines which surround the @samp{@@setfilename} and
@samp{@@settitle} lines are optional, but you need them in order to
run @TeX{} or Info on just part of the file. (@xref{Start of Header},
for more information.)@refill
Furthermore, you will usually provide a Texinfo file with a title
page, indices, and the like. 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.@refill
@node Six Parts, Short Sample, Minimum, Overview
@comment node-name, next, previous, up
@section Six Parts of a Texinfo File
Generally, a Texinfo file contains more than the minimal
beginning and end---it usually contains six parts:@refill
@table @r
@item 1. Header
The @dfn{Header} names the file, tells @TeX{} which definitions' file to
use, and performs other ``housekeeping'' tasks.@refill
@item 2. Summary Description and Copyright
The @dfn{Summary Description and Copyright} segment describes the document
and contains the copyright notice and copying permissions for the Info
file. The segment must be enclosed between @code{@@ifinfo} and
@code{@@end ifinfo} commands so that the formatters place it only in the Info
file.@refill
@item 3. Title and Copyright
The @dfn{Title and Copyright} segment contains the title and copyright pages
and copying permissions for the printed manual. The segment must be
enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
The title and copyright page appear only in the printed @w{manual}.@refill
@item 4. `Top' Node and Master Menu
The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
Info file. It appears only in the Info file, in the `Top' node.@refill
@item 5. Body
The @dfn{Body} of the document may be structured like a traditional book or
encyclopedia or it may be free form.@refill
@item 6. End
The @dfn{End} contains commands for printing indices and generating
the table of contents, and the @code{@@bye} command on a line of its
own.@refill
@end table
@node Short Sample, Acknowledgements, Six Parts, Overview
@comment node-name, next, previous, up
@section A Short Sample Texinfo File
@cindex Sample Texinfo file
Here is a complete but very short Texinfo file, in six parts. The first
three parts of the file, from @samp{\input texinfo} through to
@samp{@@end titlepage}, look more intimidating than they are. Most of
the material is standard boilerplate; when you write a manual, simply
insert the names for your own manual in this segment. (@xref{Beginning a
File}.)@refill
@noindent
In the following, the sample text is @emph{indented}; comments on it are
not. The complete file, without any comments, is shown in
@ref{Sample Texinfo File}.
@subheading Part 1: Header
@noindent
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.
@example
@group
\input texinfo @@c -*-texinfo-*-
@@c %**start of header
@@setfilename sample.info
@@settitle Sample Document
@@c %**end of header
@@setchapternewpage odd
@end group
@end example
@subheading Part 2: Summary Description and Copyright
@noindent
The summary description and copyright segment does not
appear in the printed document.
@example
@group
@@ifinfo
This is a short example of a complete Texinfo file.
Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
@@end ifinfo
@end group
@end example
@subheading Part 3: Titlepage and Copyright
@noindent
The titlepage segment does not appear in the Info file.
@example
@group
@@titlepage
@@sp 10
@@comment The title is printed in a large font.
@@center @@titlefont@{Sample Title@}
@end group
@group
@@c The following two commands start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
@@end titlepage
@end group
@end example
@subheading Part 4: `Top' Node and Master Menu
@noindent
The `Top' node contains the master menu for the Info file.
Since a printed manual uses a table of contents rather than
a menu, the master menu appears only in the Info file.
@example
@group
@@node Top, First Chapter, , (dir)
@@comment node-name, next, previous, up
@end group
@end example
@example
@group
@@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
* Concept Index:: This index has two entries.
@@end menu
@end group
@end example
@subheading Part 5: The Body of the Document
@noindent
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.@refill
@example
@group
@@node First Chapter, Concept Index, Top, Top
@@comment node-name, next, previous, up
@@chapter First Chapter
@@cindex Sample index entry
@end group
@group
This is the contents of the first chapter.
@@cindex Another sample index entry
@end group
@group
Here is a numbered list.
@@enumerate
@@item
This is the first item.
@@item
This is the second item.
@@end enumerate
@end group
@group
The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
commands transform a Texinfo file such as this into
an Info file; and @@TeX@{@} typesets it for a printed
manual.
@end group
@end example
@subheading Part 6: The End of the Document
@noindent
The end segment contains commands both for generating an index in a node
and unnumbered chapter of its own and for generating the table of
contents; and it contains the @code{@@bye} command that marks the end of
the document.@refill
@example
@group
@@node Concept Index, , First Chapter, Top
@@comment node-name, next, previous, up
@@unnumbered Concept Index
@end group
@group
@@printindex cp
@@contents
@@bye
@end group
@end example
@subheading The Results
Here is what the contents of the first chapter of the sample look like:
@sp 1
@need 700
@quotation
This is the contents of the first chapter.
Here is a numbered list.
@enumerate
@item
This is the first item.
@item
This is the second item.
@end enumerate
The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.
@end quotation
@node Acknowledgements, , Short Sample, Overview
@comment node-name, next, previous, up
@section Acknowledgements
@cindex Stallman, Richard M.
@cindex Chassell, Robert J.
@cindex Berry, Karl
Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@:
Chassell} revised and extended it, starting with Edition 1.1. Karl
Berry made updates for the Texinfo 3.8 and subsequent releases, starting
with Edition 2.22.
@cindex Pinard, Fran@,{c}ois
@cindex Zuhn, David D.
@cindex Weisshaus, Melissa
Our thanks go out to all who helped improve this work, particularly to
Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
reported mistakes and obscurities; our special thanks go to Melissa
Weisshaus for her frequent and often tedious reviews of nearly similar
editions. Our mistakes are our own.
Please send suggestions and corrections to:
@example
@group
@r{Internet address:}
bug-texinfo@@gnu.org
@end group
@end example
@noindent
Please include the manual's edition number and update date in your messages.
@node Texinfo Mode, Beginning a File, Overview, Top
@comment node-name, next, previous, up
@chapter Using Texinfo Mode
@cindex Texinfo mode
@cindex Mode, using Texinfo
@cindex GNU Emacs
@cindex Emacs
You may edit a Texinfo file with any text editor you choose. A Texinfo
file is no different from any other @sc{ascii} file. However, GNU Emacs
comes with a special mode, called Texinfo
mode, that provides Emacs commands and tools to help ease your work.@refill
This chapter describes features of GNU Emacs' Texinfo mode but not any
features of the Texinfo formatting language. If you are reading this
manual straight through from the beginning, you may want to skim through
this chapter briefly and come back to it after reading succeeding
chapters which describe the Texinfo formatting language in
detail.@refill
@menu
* Texinfo Mode Overview:: How Texinfo mode can help you.
* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
purpose editing features.
* Inserting:: How to insert frequently used @@-commands.
* Showing the Structure:: How to show the structure of a file.
* Updating Nodes and Menus:: How to update or create new nodes and menus.
* Info Formatting:: How to format for Info.
* Printing:: How to format and print part or all of a file.
* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
@end menu
@node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
@ifinfo
@heading Texinfo Mode Overview
@end ifinfo
Texinfo mode provides special features for working with Texinfo
files:@refill
@itemize @bullet
@item
Insert frequently used @@-commands. @refill
@item
Automatically create @code{@@node} lines.
@item
Show the structure of a Texinfo source file.@refill
@item
Automatically create or update the `Next',
`Previous', and `Up' pointers of a node.
@item
Automatically create or update menus.@refill
@item
Automatically create a master menu.@refill
@item
Format a part or all of a file for Info.@refill
@item
Typeset and print part or all of a file.@refill
@end itemize
Perhaps the two most helpful features are those for inserting frequently
used @@-commands and for creating node pointers and menus.@refill
@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
@section 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 @kbd{M-q} (@code{fill-paragraph})
command will refill a paragraph but not mix an indexing command on a
line adjacent to it into the paragraph.@refill
In addition, Texinfo mode sets the @code{page-delimiter} variable to
the value of @code{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
@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
(@code{backward-page}) commands and narrow to a chapter with the
@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
The GNU Emacs Manual}, for details about the page commands.)@refill
You may name a Texinfo file however you wish, but the convention is to
end a Texinfo file name with one of the three extensions
@file{.texinfo}, @file{.texi}, or @file{.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 @file{.texinfo} or @file{.texi}
extension. Also, Emacs switches to Texinfo mode
when you visit a
file that has @samp{-*-texinfo-*-} in its first line. If ever you are
in another mode and wish to switch to Texinfo mode, type @code{M-x
texinfo-mode}.@refill
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.@refill
@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
@comment node-name, next, previous, up
@section Inserting Frequently Used Commands
@cindex Inserting frequently used commands
@cindex Frequently used commands, inserting
@cindex Commands, inserting them
Texinfo mode provides commands to insert various frequently used
@@-commands into the buffer. You can use these commands to save
keystrokes.@refill
The insert commands are invoked by typing @kbd{C-c} twice and then the
first letter of the @@-command:@refill
@table @kbd
@item C-c C-c c
@itemx M-x texinfo-insert-@@code
@findex texinfo-insert-@@code
Insert @code{@@code@{@}} and put the
cursor between the braces.@refill
@item C-c C-c d
@itemx M-x texinfo-insert-@@dfn
@findex texinfo-insert-@@dfn
Insert @code{@@dfn@{@}} and put the
cursor between the braces.@refill
@item C-c C-c e
@itemx M-x texinfo-insert-@@end
@findex texinfo-insert-@@end
Insert @code{@@end} and attempt to insert the correct following word,
such as @samp{example} or @samp{table}. (This command does not handle
nested lists correctly, but inserts the word appropriate to the
immediately preceding list.)@refill
@item C-c C-c i
@itemx M-x texinfo-insert-@@item
@findex texinfo-insert-@@item
Insert @code{@@item} and put the
cursor at the beginning of the next line.@refill
@item C-c C-c k
@itemx M-x texinfo-insert-@@kbd
@findex texinfo-insert-@@kbd
Insert @code{@@kbd@{@}} and put the
cursor between the braces.@refill
@item C-c C-c n
@itemx M-x texinfo-insert-@@node
@findex texinfo-insert-@@node
Insert @code{@@node} and a comment line
listing the sequence for the `Next',
`Previous', and `Up' nodes.
Leave point after the @code{@@node}.@refill
@item C-c C-c o
@itemx M-x texinfo-insert-@@noindent
@findex texinfo-insert-@@noindent
Insert @code{@@noindent} and put the
cursor at the beginning of the next line.@refill
@item C-c C-c s
@itemx M-x texinfo-insert-@@samp
@findex texinfo-insert-@@samp
Insert @code{@@samp@{@}} and put the
cursor between the braces.@refill
@item C-c C-c t
@itemx M-x texinfo-insert-@@table
@findex texinfo-insert-@@table
Insert @code{@@table} followed by a @key{SPC}
and leave the cursor after the @key{SPC}.@refill
@item C-c C-c v
@itemx M-x texinfo-insert-@@var
@findex texinfo-insert-@@var
Insert @code{@@var@{@}} and put the
cursor between the braces.@refill
@item C-c C-c x
@itemx M-x texinfo-insert-@@example
@findex texinfo-insert-@@example
Insert @code{@@example} and put the
cursor at the beginning of the next line.@refill
@c M-@{ was the binding for texinfo-insert-braces;
@c in Emacs 19, backward-paragraph will take this binding.
@item C-c C-c @{
@itemx M-x texinfo-insert-braces
@findex texinfo-insert-braces
Insert @code{@{@}} and put the cursor between the braces.@refill
@item C-c C-c @}
@itemx C-c C-c ]
@itemx M-x up-list
@findex up-list
Move from between a pair of braces forward past the closing brace.
Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
is, however, more mnemonic; hence the two keybindings. (Also, you can
move out from between braces by typing @kbd{C-f}.)@refill
@end table
To put a command such as @w{@code{@@code@{@dots{}@}}} around an
@emph{existing} word, position the cursor in front of the word and type
@kbd{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---@samp{1} for one word, @samp{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 @code{@@kbd} and @code{@@var}.@refill
This set of insert commands was created after analyzing the frequency
with which different @@-commands are used in the @cite{GNU Emacs
Manual} and the @cite{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 @file{texinfo.el}.@refill
@findex texinfo-start-menu-description
@cindex Menu description, start
@cindex Description for menu, start
@kbd{C-c C-c C-d} (@code{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.
@xref{Menu Parts, , The Parts of a Menu}.)@refill
To use @code{texinfo-start-menu-description}, position point in a menu
entry line and type @kbd{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.@refill
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.@refill
@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
@comment node-name, next, previous, up
@section Showing the Section Structure of a File
@cindex Showing the section structure of a file
@cindex Section structure of a file, showing it
@cindex Structure of a file, showing it
@cindex Outline of file structure, showing it
@cindex Contents-like outline of file structure
@cindex File section structure, showing it
@cindex Texinfo file section structure, showing it
You can show the section structure of a Texinfo file by using the
@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
shows the section structure of a Texinfo file by listing the lines
that begin with the @@-commands for @code{@@chapter},
@code{@@section}, and the like. It constructs what amounts
to a table of contents. These lines are displayed in another buffer
called the @samp{*Occur*} buffer. In that buffer, you can position
the cursor over one of the lines and use the @kbd{C-c C-c} command
(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
in the Texinfo file.@refill
@table @kbd
@item C-c C-s
@itemx M-x texinfo-show-structure
@findex texinfo-show-structure
Show the @code{@@chapter}, @code{@@section}, and such lines of a
Texinfo file.@refill
@item C-c C-c
@itemx M-x occur-mode-goto-occurrence
@findex occur-mode-goto-occurrence
Go to the line in the Texinfo file corresponding to the line under the
cursor in the @file{*Occur*} buffer.@refill
@end table
If you call @code{texinfo-show-structure} with a prefix argument by
typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
@@-commands for @code{@@chapter}, @code{@@section}, and the like,
but also the @code{@@node} lines. (This is how the
@code{texinfo-show-structure} command worked without an argument in
the first version of Texinfo. It was changed because @code{@@node}
lines clutter up the @samp{*Occur*} buffer and are usually not
needed.) You can use @code{texinfo-show-structure} with a prefix
argument to check whether the `Next', `Previous', and `Up' pointers of
an @code{@@node} line are correct.@refill
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
@kbd{C-x n n} (@code{narrow-to-region}) command and
@code{texinfo-show-structure} will work on only that region. To see
the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
information about the narrowing commands.)@refill
@vindex page-delimiter
@cindex Page delimiter in Texinfo mode
In addition to providing the @code{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 @kbd{C-x
]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
commands to move forward and backward by chapter, and to use the
@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
about the page commands.@refill
@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
@comment node-name, next, previous, up
@section Updating Nodes and Menus
@cindex Updating nodes and menus
@cindex Create nodes, menus automatically
@cindex Insert nodes, menus automatically
@cindex Automatically insert nodes, 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 @code{@@node} line that has none and to
create menus in a file that has none.@refill
If you do not use the updating commands, you need to write menus and
node pointers by hand, which is a tedious task.@refill
@menu
* Updating Commands:: Five major updating commands.
* Updating Requirements:: How to structure a Texinfo file for
using the updating command.
* Other Updating Commands:: How to indent descriptions, insert
missing nodes lines, and update
nodes in sequence.
@end menu
@node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
@ifinfo
@subheading The Updating Commands
@end ifinfo
You can use the updating commands@refill
@itemize @bullet
@item
to insert or update the `Next', `Previous', and `Up' pointers of a
node,@refill
@item
to insert or update the menu for a section, and@refill
@item
to create a master menu for a Texinfo source file.@refill
@end itemize
You can also use the commands to update all the nodes and menus in a
region or in a whole Texinfo file.@refill
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 @code{@@node} line, except
for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
a line beginning with @code{@@chapter}, @code{@@section}, or other
similar command.)
You can write the structuring command line on the line that follows
immediately after an @code{@@node} line or else on the line that
follows after a single @code{@@comment} line or a single
@code{@@ifinfo} line. You cannot interpose more than one line between
the @code{@@node} line and the structuring command line; and you may
interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
Commands which work on a whole buffer require that the `Top' node be
followed by a node with an @code{@@chapter} or equivalent-level command.
Note that the menu updating commands will not create a main or master
menu for a Texinfo file that has only @code{@@chapter}-level nodes! The
menu updating commands only create menus @emph{within} nodes for lower level
nodes. To create a menu of chapters, you must provide a `Top'
node.@refill
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.@refill
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 @code{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.@refill
The @code{texinfo-master-menu} command is the primary command:@refill
@table @kbd
@item C-c C-u m
@itemx M-x texinfo-master-menu
@findex texinfo-master-menu
Create or update a master menu that includes all the other menus
(incorporating the descriptions from pre-existing menus, if
any).@refill
With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
update all the nodes and all the regular menus in the buffer before
constructing the master menu. (@xref{The Top Node, , The Top Node and
Master Menu}, for more about a master menu.)@refill
For @code{texinfo-master-menu} to work, the Texinfo file must have a
`Top' node and at least one subsequent node.@refill
After extensively editing a Texinfo file, you can type the following:
@example
C-u M-x texinfo-master-menu
@exdent or
C-u C-c C-u m
@end example
@noindent
This updates all the nodes and menus completely and all at once.@refill
@end table
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.@refill
@need 1000
The commands are:@refill
@table @kbd
@item C-c C-u C-n
@itemx M-x texinfo-update-node
@findex texinfo-update-node
Insert the `Next', `Previous', and `Up' pointers for the node that point is
within (i.e., for the @code{@@node} line preceding point). If the
@code{@@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, @kbd{C-u}, if interactive), this command
updates all @code{@@node} lines in the region (which is the text
between point and mark).@refill
@item C-c C-u C-m
@itemx M-x texinfo-make-menu
@findex texinfo-make-menu
Create or update the menu in the node that point is within.
With an argument (@kbd{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.@refill
Whenever @code{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.@refill
@item C-c C-u C-e
@itemx M-x texinfo-every-node-update
@findex texinfo-every-node-update
Insert or update the `Next', `Previous', and `Up' pointers for every
node in the buffer.@refill
@item C-c C-u C-a
@itemx M-x texinfo-all-menus-update
@findex texinfo-all-menus-update
Create or update all the menus in the buffer. With an argument
(@kbd{C-u} as prefix argument, if interactive), first insert
or update all the node
pointers before working on the menus.@refill
If a master menu exists, the @code{texinfo-all-menus-update} command
updates it; but the command does not create a new master menu if none
already exists. (Use the @code{texinfo-master-menu} command for
that.)@refill
When working on a document that does not merit a master menu, you can
type the following:
@example
C-u C-c C-u C-a
@exdent or
C-u M-x texinfo-all-menus-update
@end example
@noindent
This updates all the nodes and menus.@refill
@end table
The @code{texinfo-column-for-description} variable specifies the
column to which menu descriptions are indented. By default, the value
is 32 although it is often useful to reduce it to as low as 24. You
can set the variable with the @kbd{M-x edit-options} command
(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
, Examining and Setting Variables, emacs, The GNU Emacs
Manual}).@refill
Also, the @code{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 @code{texinfo-insert-node-lines} command to
insert missing @code{@@node} lines into a file. (@xref{Other Updating
Commands}, for more information.)@refill
@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
@comment node-name, next, previous, up
@subsection Updating Requirements
@cindex Updating requirements
@cindex Requirements for updating commands
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.@refill
Each @code{@@node} line, with the exception of the line for the `Top'
node, must be followed by a line with a structuring command such as
@code{@@chapter}, @code{@@section}, or
@code{@@unnumberedsubsec}.@refill
Each @code{@@node} line/structuring-command line combination
must look either like this:@refill
@example
@group
@@node Comments, Minimum, Conventions, Overview
@@comment node-name, next, previous, up
@@section Comments
@end group
@end example
or like this (without the @code{@@comment} line):
@example
@group
@@node Comments, Minimum, Conventions, Overview
@@section Comments
@end group
@end example
@noindent
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
@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill
If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
and be the first node in the file.@refill
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.@refill
Incidentally, the @code{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 @code{makeinfo}, you have no need for the
`update node' commands. (@xref{Create an Info File, , Creating an
Info File}, for more information about @code{makeinfo}.) However,
both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands
require that you insert menus in the file.@refill
@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
@comment node-name, next, previous, up
@subsection Other Updating Commands
In addition to the five major updating commands, Texinfo mode
possesses several less frequently used updating commands:@refill
@table @kbd
@item M-x texinfo-insert-node-lines
@findex texinfo-insert-node-lines
Insert @code{@@node} lines before the @code{@@chapter},
@code{@@section}, and other sectioning commands wherever they are
missing throughout a region in a Texinfo file.@refill
With an argument (@kbd{C-u} as prefix argument, if interactive), the
@code{texinfo-insert-node-lines} command not only inserts
@code{@@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 @code{@@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.@refill
For example, the following marks a whole buffer as a region and inserts
@code{@@node} lines and titles throughout:@refill
@example
C-x h C-u M-x texinfo-insert-node-lines
@end example
(Note that this command inserts titles as node names in @code{@@node}
lines; the @code{texinfo-start-menu-description} command
(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles
as descriptions in menu entries, a different action. However, in both
cases, you need to edit the inserted text.)@refill
@item M-x texinfo-multiple-files-update
@findex texinfo-multiple-files-update @r{(in brief)}
Update nodes and menus in a document built from several separate files.
With @kbd{C-u} as a prefix argument, create and insert a master menu in
the outer file. With a numeric prefix argument, such as @kbd{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 @code{texinfo-multiple-files-update} command is
described in the appendix on @code{@@include} files.
@ifinfo
@xref{texinfo-multiple-files-update}.@refill
@end ifinfo
@iftex
@xref{texinfo-multiple-files-update, ,
@code{texinfo-multiple-files-update}}.@refill
@end iftex
@item M-x texinfo-indent-menu-description
@findex 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 (@kbd{C-u} as prefix argument, if
interactive), the @code{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.@refill
@item M-x texinfo-sequential-node-update
@findex 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 @kbd{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 @code{texinfo-sequential-node-update} command
sequentially updates all the nodes in the region.@refill
@end table
@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
@comment node-name, next, previous, up
@section Formatting for Info
@cindex Formatting for Info
@cindex Running an Info formatter
@cindex Info formatting
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.@refill
You can use either the @code{texinfo-format-region} or the
@code{makeinfo-region} command to format a region:@refill
@table @kbd
@findex texinfo-format-region
@item C-c C-e C-r
@itemx M-x texinfo-format-region
@itemx C-c C-m C-r
@itemx M-x makeinfo-region
Format the current region for Info.@refill
@end table
You can use either the @code{texinfo-format-buffer} or the
@code{makeinfo-buffer} command to format a whole buffer:@refill
@table @kbd
@findex texinfo-format-buffer
@item C-c C-e C-b
@itemx M-x texinfo-format-buffer
@itemx C-c C-m C-b
@itemx M-x makeinfo-buffer
Format the current buffer for Info.@refill
@end table
@need 1000
For example, after writing a Texinfo file, you can type the following:
@example
C-u C-c C-u m
@exdent or
C-u M-x texinfo-master-menu
@end example
@noindent
This updates all the nodes and menus. Then type the following to create
an Info file:
@example
C-c C-m C-b
@exdent or
M-x makeinfo-buffer
@end example
For @TeX{} or the Info formatting commands to work, the file @emph{must}
include a line that has @code{@@setfilename} in its header.@refill
@xref{Create an Info File}, for details about Info formatting.@refill
@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
@comment node-name, next, previous, up
@section Formatting and Printing
@cindex Formatting for printing
@cindex Printing a region or buffer
@cindex Region formatting and printing
@cindex Buffer formatting and printing
@cindex Part of file formatting and printing
Typesetting and printing a Texinfo file is a multi-step process in which
you first create a file for printing (called a DVI file), and then
print the file. Optionally, you may also create indices. To do this,
you must run the @code{texindex} command after first running the
@code{tex} typesetting command; and then you must run the @code{tex}
command again. Or else run the @code{texi2dvi} command which
automatically creates indices as needed (@pxref{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
@code{texinfo-tex-region} and related commands for this purpose. Use
the @code{texinfo-tex-buffer} command to format all of a
buffer.@refill
@table @kbd
@item C-c C-t C-b
@itemx M-x texinfo-tex-buffer
@findex texinfo-tex-buffer
Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
buffer, this command automatically creates or updates indices as
needed.@refill
@item C-c C-t C-r
@itemx M-x texinfo-tex-region
@findex texinfo-tex-region
Run @TeX{} on the region.@refill
@item C-c C-t C-i
@itemx M-x texinfo-texindex
Run @code{texindex} to sort the indices of a Texinfo file formatted with
@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
not run @code{texindex} automatically; it only runs the @code{tex}
typesetting command. You must run the @code{texinfo-tex-region} command
a second time after sorting the raw index files with the @code{texindex}
command. (Usually, you do not format an index when you format a region,
only when you format a buffer. Now that the @code{texi2dvi} command
exists, there is little or no need for this command.)@refill
@item C-c C-t C-p
@itemx M-x texinfo-tex-print
@findex texinfo-tex-print
Print the file (or the part of the file) previously formatted with
@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
@end table
For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
file @emph{must} start with a @samp{\input texinfo} line and must
include an @code{@@settitle} line. The file must end with @code{@@bye}
on a line by itself. (When you use @code{texinfo-tex-region}, you must
surround the @code{@@settitle} line with start-of-header and
end-of-header lines.)@refill
@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related
commands, such as @code{tex-show-print-queue}.@refill
@node Texinfo Mode Summary, , Printing, Texinfo Mode
@comment node-name, next, previous, up
@section 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 @kbd{C-c}. The keys are somewhat
mnemonic.@refill
@subheading Insert Commands
The insert commands are invoked by typing @kbd{C-c} twice and then the
first letter of the @@-command to be inserted. (It might make more
sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
@kbd{C-c C-c} is quick to type.)@refill
@example
C-c C-c c @r{Insert} @samp{@@code}.
C-c C-c d @r{Insert} @samp{@@dfn}.
C-c C-c e @r{Insert} @samp{@@end}.
C-c C-c i @r{Insert} @samp{@@item}.
C-c C-c n @r{Insert} @samp{@@node}.
C-c C-c s @r{Insert} @samp{@@samp}.
C-c C-c v @r{Insert} @samp{@@var}.
C-c C-c @{ @r{Insert braces.}
C-c C-c ]
C-c C-c @} @r{Move out of enclosing braces.}
@group
C-c C-c C-d @r{Insert a node's section title}
@r{in the space for the description}
@r{in a menu entry line.}
@end group
@end example
@subheading Show Structure
The @code{texinfo-show-structure} command is often used within a
narrowed region.@refill
@example
C-c C-s @r{List all the headings.}
@end example
@subheading The Master Update Command
The @code{texinfo-master-menu} command creates a master menu; and can
be used to update every node and menu in a file as well.@refill
@example
@group
C-c C-u m
M-x texinfo-master-menu
@r{Create or update a master menu.}
@end group
@group
C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
@r{create or update all nodes and regular}
@r{menus, and then create a master menu.}
@end group
@end example
@subheading Update Pointers
The update pointer commands are invoked by typing @kbd{C-c C-u} and
then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
@code{texinfo-every-node-update}.@refill
@example
C-c C-u C-n @r{Update a node.}
C-c C-u C-e @r{Update every node in the buffer.}
@end example
@subheading Update Menus
Invoke the update menu commands by typing @kbd{C-c C-u}
and then either @kbd{C-m} for @code{texinfo-make-menu} or
@kbd{C-a} for @code{texinfo-all-menus-update}. To update
both nodes and menus at the same time, precede @kbd{C-c C-u
C-a} with @kbd{C-u}.@refill
@example
C-c C-u C-m @r{Make or update a menu.}
@group
C-c C-u C-a @r{Make or update all}
@r{menus in a buffer.}
@end group
@group
C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
@r{first create or update all nodes and}
@r{then create or update all menus.}
@end group
@end example
@subheading Format for Info
The Info formatting commands that are written in Emacs Lisp are
invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
or @kbd{C-b} for the whole buffer.@refill
The Info formatting commands that are written in C and based on the
@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
@need 800
@noindent
Use the @code{texinfo-format@dots{}} commands:
@example
@group
C-c C-e C-r @r{Format the region.}
C-c C-e C-b @r{Format the buffer.}
@end group
@end example
@need 750
@noindent
Use @code{makeinfo}:
@example
C-c C-m C-r @r{Format the region.}
C-c C-m C-b @r{Format the buffer.}
C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
@end example
@subheading Typeset and Print
The @TeX{} typesetting and printing commands are invoked by typing
@kbd{C-c C-t} and then another control command: @kbd{C-r} for
@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
and so on.@refill
@example
C-c C-t C-r @r{Run @TeX{} on the region.}
C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
C-c C-t C-i @r{Run} @code{texindex}.
C-c C-t C-p @r{Print the DVI file.}
C-c C-t C-q @r{Show the print queue.}
C-c C-t C-d @r{Delete a job from the print queue.}
C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
C-c C-t C-l @r{Recenter the output buffer.}
@end example
@subheading Other Updating Commands
The `other updating commands' do not have standard keybindings because
they are rarely used.
@example
@group
M-x texinfo-insert-node-lines
@r{Insert missing @code{@@node} lines in region.}
@r{With @kbd{C-u} as a prefix argument,}
@r{use section titles as node names.}
@end group
@group
M-x texinfo-multiple-files-update
@r{Update a multi-file document.}
@r{With @kbd{C-u 2} as a prefix argument,}
@r{create or update all nodes and menus}
@r{in all included files first.}
@end group
@group
M-x texinfo-indent-menu-description
@r{Indent descriptions.}
@end group
@group
M-x texinfo-sequential-node-update
@r{Insert node pointers in strict sequence.}
@end group
@end example
@node Beginning a File, Ending a File, Texinfo Mode, Top
@comment node-name, next, previous, up
@chapter Beginning a Texinfo File
@cindex Beginning a Texinfo file
@cindex Texinfo file beginning
@cindex File beginning
Certain pieces of information must be provided at the beginning of a
Texinfo file, such as the name of the file and the title of the
document.@refill
@menu
* Four Parts:: Four parts begin a Texinfo file.
* Sample Beginning:: Here is a sample beginning for a Texinfo file.
* Header:: The very beginning of a Texinfo file.
* Info Summary and Permissions:: Summary and copying permissions for Info.
* Titlepage & Copyright Page:: Creating the title and copyright pages.
* The Top Node:: Creating the `Top' node and master menu.
* Software Copying Permissions:: Ensure that you and others continue to
have the right to use and share software.
@end menu
@node Four Parts, Sample Beginning, Beginning a File, Beginning a File
@ifinfo
@heading Four Parts Begin a File
@end ifinfo
Generally, the beginning of a Texinfo file has four parts:@refill
@enumerate
@item
The header, delimited by special comment lines, that includes the
commands for naming the Texinfo file and telling @TeX{} what
definitions file to use when processing the Texinfo file.@refill
@item
A short statement of what the file is about, with a copyright notice
and copying permissions. This is enclosed in @code{@@ifinfo} and
@code{@@end ifinfo} commands so that the formatters place it only
in the Info file.@refill
@item
A title page and copyright page, with a copyright notice and copying
permissions. This is enclosed between @code{@@titlepage} and
@code{@@end titlepage} commands. The title and copyright page appear
only in the printed @w{manual}.@refill
@item
The `Top' node that contains a menu for the whole Info file. The
contents of this node appear only in the Info file.@refill
@end enumerate
Also, optionally, you may include the copying conditions for a program
and a warranty disclaimer. The copying section will be followed by an
introduction or else by the first chapter of the manual.@refill
Since the copyright notice and copying permissions for the Texinfo
document (in contrast to the copying permissions for a program) are in
parts that appear only in the Info file or only in the printed manual,
this information must be given twice.@refill
@node Sample Beginning, Header, Four Parts, Beginning a File
@comment node-name, next, previous, up
@section Sample Texinfo File Beginning
The following sample shows what is needed.@refill
@example
\input texinfo @@c -*-texinfo-*-
@@c %**start of header
@@setfilename @var{name-of-info-file}
@@settitle @var{name-of-manual}
@@setchapternewpage odd
@@c %**end of header
@@ifinfo
This file documents @dots{}
Copyright @var{year} @var{copyright-owner}
@group
Permission is granted to @dots{}
@@end ifinfo
@end group
@group
@@c This title page illustrates only one of the
@@c two methods of forming a title page.
@end group
@group
@@titlepage
@@title @var{name-of-manual-when-printed}
@@subtitle @var{subtitle-if-any}
@@subtitle @var{second-subtitle}
@@author @var{author}
@end group
@group
@@c The following two commands
@@c start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright@{@} @var{year} @var{copyright-owner}
@end group
Published by @dots{}
Permission is granted to @dots{}
@@end titlepage
@@node Top, Overview, , (dir)
@@ifinfo
This document describes @dots{}
This document applies to version @dots{}
of the program named @dots{}
@@end ifinfo
@group
@@menu
* Copying:: Your rights and freedoms.
* First Chapter:: Getting started @dots{}
* Second Chapter:: @dots{}
@dots{}
@dots{}
@@end menu
@end group
@group
@@node First Chapter, Second Chapter, top, top
@@comment node-name, next, previous, up
@@chapter First Chapter
@@cindex Index entry for First Chapter
@end group
@end example
@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File
@comment node-name, next, previous, up
@section The Texinfo File Header
@cindex Header for Texinfo files
@cindex Texinfo file header
Texinfo files start with at least three lines that provide Info and
@TeX{} with necessary information. These are the @code{\input
texinfo} line, the @code{@@settitle} line, and the
@code{@@setfilename} line. If you want to run @TeX{} on just a part
of the Texinfo File, you must write the @code{@@settitle}
and @code{@@setfilename} lines between start-of-header and end-of-header
lines.@refill
Thus, the beginning of a Texinfo file looks like this:
@example
@group
\input texinfo @@c -*-texinfo-*-
@@setfilename sample.info
@@settitle Sample Document
@end group
@end example
@noindent
or else like this:
@example
@group
\input texinfo @@c -*-texinfo-*-
@@c %**start of header
@@setfilename sample.info
@@settitle Sample Document
@@c %**end of header
@end group
@end example
@menu
* First Line:: The first line of a Texinfo file.
* Start of Header:: Formatting a region requires this.
* setfilename:: Tell Info the name of the Info file.
* settitle:: Create a title for the printed work.
* setchapternewpage:: Start chapters on right-hand pages.
* paragraphindent:: An option to specify paragraph indentation.
* End of Header:: Formatting a region requires this.
@end menu
@node First Line, Start of Header, Header, Header
@comment node-name, next, previous, up
@subsection The First Line of a Texinfo File
@cindex First line of a Texinfo file
@cindex Beginning line of a Texinfo file
@cindex Header 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:@refill
@example
\input texinfo @@c -*-texinfo-*-
@end example
@noindent
This line serves two functions:
@enumerate
@item
When the file is processed by @TeX{}, the @samp{\input texinfo} command
tells @TeX{} to load the macros needed for processing a Texinfo file.
These are in a file called @file{texinfo.tex}, which is usually located
in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
@samp{\}, to mark the beginning of a command, just as Texinfo uses
@samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
is why it appears at the beginning of the file.@refill
@item
When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
specification tells Emacs to use Texinfo mode.@refill
@end enumerate
@node Start of Header, setfilename, First Line, Header
@comment node-name, next, previous, up
@subsection Start of Header
@cindex Start of header line
Write a start-of-header line on the second line of a Texinfo file.
Follow the start-of-header line with @code{@@setfilename} and
@code{@@settitle} lines and, optionally, with other command lines, such
as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
end-of-header line (@pxref{End of Header}).@refill
With these lines, you can format part of a Texinfo file for Info or
typeset part for printing.@refill
A start-of-header line looks like this:@refill
@example
@@c %**start of header
@end example
The odd string of characters, @samp{%**}, is to ensure that no other
comment is accidentally taken for a start-of-header line.@refill
@node setfilename, settitle, Start of Header, Header
@comment node-name, next, previous, up
@subsection @code{@@setfilename}
@cindex Info file requires @code{@@setfilename}
@findex setfilename
In order to serve as the primary input file for either @code{makeinfo}
or @TeX{}, a Texinfo file must contain a line that looks like this:
@example
@@setfilename @var{info-file-name}
@end example
Write the @code{@@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 @code{@@setfilename} line specifies the name of the Info file to be
generated. This name should be different from the name of the Texinfo
file. There are two conventions for choosing the name: you can either
remove the @samp{.texi} extension from the input file name, or replace
it with the @samp{.info} extension.
Some operating systems cannot handle long file names. You can run into
a problem even when the file name you specify is itself short enough.
This occurs because the Info formatters split a long Info file into
short indirect subfiles, and name them by appending @samp{-1},
@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
The subfile name @file{texinfo.info-10}, for example, is too long for
some systems; so the Info file name for this document is @file{texinfo}
rather than @file{texinfo.info}.
@cindex Ignored before @code{@@setfilename}
The Info formatting commands ignore everything written before the
@code{@@setfilename} line, which is why the very first line of
the file (the @code{\input} line) does not show up in the output.
@pindex texinfo.cnf
The @code{@@setfilename} line produces no output when you typeset a
manual with @TeX{}, but it nevertheless is essential: it opens the
index, cross-reference, and other auxiliary files used by Texinfo, and
also reads @file{texinfo.cnf} if that file is present on your system
(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}).
@node settitle, setchapternewpage, setfilename, Header
@comment node-name, next, previous, up
@subsection @code{@@settitle}
@findex settitle
In order to be made into a printed manual, a Texinfo file must contain
a line that looks like this:@refill
@example
@@settitle @var{title}
@end example
Write the @code{@@settitle} command at the beginning of a line and
follow it on the same line by the title. This tells @TeX{} the title
to use in a header or footer. Do not write anything else on the line;
anything on the line after the command is considered part of the
title, including a comment.@refill
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 @code{@@chapter} command.) Page footers are not
printed.@refill
Even if you are printing in a single-sided style, @TeX{} looks for an
@code{@@settitle} command line, in case you include the manual title
in the heading. @refill
The @code{@@settitle} command should precede everything that generates
actual output in @TeX{}.@refill
Although the title in the @code{@@settitle} command is usually the
same as the title on the title page, it does not affect the title as
it appears on the title page. Thus, the two do not need not match
exactly; and the title in the @code{@@settitle} command can be a
shortened or expanded version of the title as it appears on the title
page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
@TeX{} prints page headings only for that text that comes after the
@code{@@end titlepage} command in the Texinfo file, or that comes
after an @code{@@headings} command that turns on headings.
(@xref{headings on off, , The @code{@@headings} Command}, for more
information.)@refill
You may, if you wish, create your own, customized headings and
footings. @xref{Headings, , Page Headings}, for a detailed discussion
of this process.@refill
@node setchapternewpage, paragraphindent, settitle, Header
@comment node-name, next, previous, up
@subsection @code{@@setchapternewpage}
@cindex Starting chapters
@cindex Pages, starting odd
@findex setchapternewpage
In a book or a manual, text is usually printed on both sides of the
paper, chapters start on right-hand pages, and right-hand pages have
odd numbers. But in short reports, text often is printed only on one
side of the paper. Also in short reports, chapters sometimes do not
start on new pages, but are printed on the same page as the end of the
preceding chapter, after a small amount of vertical whitespace.@refill
You can use the @code{@@setchapternewpage} command with various
arguments to specify how @TeX{} should start chapters and whether it
should typeset pages for printing on one or both sides of the paper
(single-sided or double-sided printing).@refill
Write the @code{@@setchapternewpage} command at the beginning of a
line followed by its argument.@refill
For example, you would write the following to cause each chapter to
start on a fresh odd-numbered page:@refill
@example
@@setchapternewpage odd
@end example
You can specify one of three alternatives with the
@code{@@setchapternewpage} command:@refill
@table @asis
@ignore
@item No @code{@@setchapternewpage} command
If the Texinfo file does not contain an @code{@@setchapternewpage}
command before the @code{@@titlepage} command, @TeX{} automatically
begins chapters on new pages and prints headings in the standard
format for single-sided printing. This is the conventional format for
single-sided printing.@refill
The result is exactly the same as when you write
@code{@@setchapternewpage on}.@refill
@end ignore
@item @code{@@setchapternewpage off}
Cause @TeX{} to typeset a new chapter on the same page as the last
chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
format page headers for single-sided printing. (You can override the
headers format with the @code{@@headings double} command; see
@ref{headings on off, , The @code{@@headings} Command}.)@refill
@item @code{@@setchapternewpage on}
Cause @TeX{} to start new chapters on new pages and to typeset page
headers for single-sided printing. This is the form most often
used for short reports.@refill
This alternative is the default.@refill
@item @code{@@setchapternewpage odd}
Cause @TeX{} to start new chapters on new, odd-numbered pages
(right-handed pages) and to typeset for double-sided printing. This is
the form most often used for books and manuals.@refill
@end table
@noindent
Texinfo does not have an @code{@@setchapternewpage even} command.@refill
@noindent
(You can countermand or modify an @code{@@setchapternewpage} command
with an @code{@@headings} command. @xref{headings on off, , The
@code{@@headings} Command}.)@refill
At the beginning of a manual or book, pages are not numbered---for
example, the title and copyright pages of a book are not numbered.
By convention, table of contents pages are numbered with roman
numerals and not in sequence with the rest of the document.@refill
Since an Info file does not have pages, the @code{@@setchapternewpage}
command has no effect on it.@refill
Usually, you do not write an @code{@@setchapternewpage} command for
single-sided printing, but accept the default which is to typeset for
single-sided printing and to start new chapters on new pages. Usually,
you write an @code{@@setchapternewpage odd} command for double-sided
printing.@refill
@node paragraphindent, End of Header, setchapternewpage, Header
@comment node-name, next, previous, up
@subsection Paragraph Indenting
@cindex Indenting paragraphs
@cindex Paragraph indentation
@findex paragraphindent
The Info formatting commands may insert spaces at the beginning of the
first line of each paragraph, thereby indenting that paragraph. You
can use the @code{@@paragraphindent} command to specify the
indentation. Write an @code{@@paragraphindent} command at the
beginning of a line followed by either @samp{asis} or a number. The
template is:@refill
@example
@@paragraphindent @var{indent}
@end example
The Info formatting commands indent according to the value of
@var{indent}:@refill
@itemize @bullet
@item
If the value of @var{indent} is @samp{asis}, the Info formatting
commands do not change the existing indentation.@refill
@item
If the value of @var{indent} is zero, the Info formatting commands delete
existing indentation.@refill
@item
If the value of @var{indent} is greater than zero, the Info formatting
commands indent the paragraph by that number of spaces.@refill
@end itemize
The default value of @var{indent} is @samp{asis}.@refill
Write the @code{@@paragraphindent} command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you write
the command between the start-of-header and end-of-header lines, the
region formatting commands indent paragraphs as specified.)@refill
A peculiarity of the @code{texinfo-format-buffer} and
@code{texinfo-format-region} commands is that they do not indent (nor
fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
@xref{Refilling Paragraphs}, for a detailed description of what goes
on.@refill
@node End of Header, , paragraphindent, Header
@comment node-name, next, previous, up
@subsection End of Header
@cindex End of header line
Follow the header lines with an @w{end-of-header} line.
An end-of-header line looks like this:@refill
@example
@@c %**end of header
@end example
If you include the @code{@@setchapternewpage} command between the
start-of-header and end-of-header lines, @TeX{} will typeset a region as
that command specifies. Similarly, if you include an @code{@@smallbook}
command between the start-of-header and end-of-header lines, @TeX{} will
typeset a region in the ``small'' book format.@refill
@ifinfo
The reason for the odd string of characters (@samp{%**}) is so that the
@code{texinfo-tex-region} command does not accidentally find
something that it should not when it is looking for the header.@refill
The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.@refill
@end ifinfo
@iftex
@xref{Start of Header}.
@end iftex
@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File
@comment node-name, next, previous, up
@section Summary and Copying Permissions for Info
The title page and the copyright page appear only in the printed copy of
the manual; therefore, the same information must be inserted in a
section that appears only in the Info file. This section usually
contains a brief description of the contents of the Info file, a
copyright notice, and copying permissions.@refill
The copyright notice should read:@refill
@example
Copyright @var{year} @var{copyright-owner}
@end example
@noindent
and be put on a line by itself.@refill
Standard text for the copyright permissions is contained in an appendix
to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying
Permissions}, for the complete text.@refill
The permissions text appears in an Info file @emph{before} the first
node. This mean that a reader does @emph{not} see this text when
reading the file using Info, except when using the advanced Info command
@kbd{g *}.
@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File
@comment node-name, next, previous, up
@section The Title and Copyright Pages
A manual's name and author are usually printed on a title page.
Sometimes copyright information is printed on the title page as well;
more often, copyright information is printed on the back of the title
page.
The title and copyright pages appear in the printed manual, but not in the
Info file. Because of this, it is possible to use several slightly
obscure @TeX{} typesetting commands that cannot be used in an Info file.
In addition, this part of the beginning of a Texinfo file contains the text
of the copying permissions that will appear in the printed manual.@refill
@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
standard text for the copyright permissions.@refill
@menu
* titlepage:: Create a title for the printed document.
* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
and @code{@@sp} commands.
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
and @code{@@author} commands.
* Copyright & Permissions:: How to write the copyright notice and
include copying permissions.
* end titlepage:: Turn on page headings after the title and
copyright pages.
* headings on off:: An option for turning headings on and off
and double or single sided printing.
@end menu
@node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @code{@@titlepage}
@cindex Title page
@findex titlepage
Start the material for the title page and following copyright page
with @code{@@titlepage} on a line by itself and end it with
@code{@@end titlepage} on a line by itself.@refill
The @code{@@end titlepage} command starts a new page and turns on page
numbering. (@xref{Headings, , Page 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
@code{@@titlepage} and @code{@@end titlepage} commands. By using the
@code{@@page} command you can force a page break within the region
delineated by the @code{@@titlepage} and @code{@@end titlepage}
commands and thereby create more than one unnumbered page. This is
how the copyright page is produced. (The @code{@@titlepage} command
might perhaps have been better named the
@code{@@titleandadditionalpages} command, but that would have been
rather long!)@refill
@c !!! append refill to footnote when makeinfo can handle it.
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@footnote{We have found that it is helpful to refer to versions
of manuals as `editions' and versions of programs as `versions';
otherwise, we find we are liable to confuse each other in conversation
by referring to both the documentation and the software with the same
words.} 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 @ref{makeinfo top, ,
@code{@@top}}.)@refill
Texinfo provides two main methods for creating a title page. One method
uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
to generate a title page in which the words on the page are
centered.@refill
The second method uses the @code{@@title}, @code{@@subtitle}, and
@code{@@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.@refill
@findex shorttitlepage
For extremely simple applications, Texinfo also provides a command
@code{@@shorttitlepage} which takes a single argument as the title.
The argument is typeset on a page by itself and followed by a blank
page.
@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
@findex titlefont
@findex center
@findex sp @r{(titlepage line spacing)}
You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@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.)@refill
Use the @code{@@titlefont} command to select a large font suitable for
the title itself.@refill
@need 700
For example:
@example
@@titlefont@{Texinfo@}
@end example
Use the @code{@@center} command at the beginning of a line to center
the remaining text on that line. Thus,@refill
@example
@@center @@titlefont@{Texinfo@}
@end example
@noindent
centers the title, which in this example is ``Texinfo'' printed
in the title font.@refill
Use the @code{@@sp} command to insert vertical space. For example:@refill
@example
@@sp 2
@end example
@noindent
This inserts two blank lines on the printed page. (@xref{sp, ,
@code{@@sp}}, for more information about the @code{@@sp}
command.)@refill
A template for this method looks like this:@refill
@example
@group
@@titlepage
@@sp 10
@@center @@titlefont@{@var{name-of-manual-when-printed}@}
@@sp 2
@@center @var{subtitle-if-any}
@@sp 2
@@center @var{author}
@dots{}
@@end titlepage
@end group
@end example
The spacing of the example fits an 8 1/2 by 11 inch manual.@refill
@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
@findex title
@findex subtitle
@findex author
You can use the @code{@@title}, @code{@@subtitle}, and @code{@@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 @code{@@sp} command is needed to
adjust vertical spacing.@refill
Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
commands at the beginning of a line followed by the title, subtitle,
or author.@refill
The @code{@@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.@refill
The @code{@@subtitle} command sets subtitles in a normal-sized font
flush to the right-hand side of the page.@refill
The @code{@@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 @code{@@author} command line is
followed by an @code{@@page} command line.)@refill
There are two ways to use the @code{@@author} command: you can write
the name or names on the remaining part of the line that starts with
an @code{@@author} command:@refill
@example
@@author by Jane Smith and John Doe
@end example
@noindent
or you can write the names one above each other by using two (or more)
@code{@@author} commands:@refill
@example
@group
@@author Jane Smith
@@author John Doe
@end group
@end example
@noindent
(Only the bottom name is underlined with a black rule.)@refill
@need 950
A template for this method looks like this:@refill
@example
@group
@@titlepage
@@title @var{name-of-manual-when-printed}
@@subtitle @var{subtitle-if-any}
@@subtitle @var{second-subtitle}
@@author @var{author}
@@page
@dots{}
@@end titlepage
@end group
@end example
@ifinfo
@noindent
Contrast this form with the form of a title page written using the
@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill
@example
@@titlepage
@@sp 10
@@center @@titlefont@{Name of Manual When Printed@}
@@sp 2
@@center Subtitle, If Any
@@sp 1
@@center Second subtitle
@@sp 2
@@center Author
@@page
@dots{}
@@end titlepage
@end example
@end ifinfo
@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection Copyright Page and Permissions
@cindex Copyright page
@cindex Printed permissions
@cindex Permissions, printed
By international treaty, the copyright notice for a book should be
either on the title page or on the back of the title page. The
copyright notice should include the year followed by the name of the
organization or person who owns the copyright.@refill
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 @code{@@titlepage} and
@code{@@end titlepage} commands.@refill
@findex vskip
@findex filll
@cindex Vertical whitespace (@samp{vskip})
Use the @code{@@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, you can write a somewhat mysterious line after the
@code{@@page} command that reads like this:@refill
@example
@@vskip 0pt plus 1filll
@end example
@noindent
This is a @TeX{} command that is not supported by the Info formatting
commands. The @code{@@vskip} command inserts whitespace. The
@samp{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
@samp{l}s in the word @samp{filll}; this is the correct usage in
@TeX{}.@refill
@findex copyright
In a printed manual, the @code{@@copyright@{@}} command generates a
@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
copyright notice itself has the following legally defined sequence:@refill
@example
Copyright @copyright{} @var{year} @var{copyright-owner}
@end example
It is customary to put information on how to get a manual after the
copyright notice, followed by the copying permissions for the
manual.@refill
Note that permissions must be given here as well as in the summary
segment within @code{@@ifinfo} and @code{@@end ifinfo} that
immediately follows the header since this text appears only in the
printed manual and the @samp{ifinfo} text appears only in the Info
file.@refill
@xref{Sample Permissions}, for the standard text.@refill
@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection Heading Generation
@findex end titlepage
@cindex Headings, page, begin to appear
@cindex Titlepage end starts headings
@cindex End titlepage starts headings
An @code{@@end titlepage} command on a line by itself 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).
(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
You can specify these formats in different ways:@refill
@itemize @bullet
@item
The conventional way is to write an @code{@@setchapternewpage} command
before the title page commands, and then have the @code{@@end
titlepage} command start generating page headings in the manner desired.
(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
@item
Alternatively, you can use the @code{@@headings} command to prevent page
headings from being generated or to start them for either single or
double-sided printing. (Write an @code{@@headings} command immediately
after the @code{@@end titlepage} command. @xref{headings on off, , The
@code{@@headings} Command}, for more information.)@refill
@item
Or, you may specify your own page heading and footing format.
@xref{Headings, , Page Headings}, for detailed
information about page headings and footings.@refill
@end itemize
Most documents are formatted with the standard single-sided or
double-sided format, using @code{@@setchapternewpage odd} for
double-sided printing and no @code{@@setchapternewpage} command for
single-sided printing.@refill
@node headings on off, , end titlepage, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection The @code{@@headings} Command
@findex headings
The @code{@@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 @code{@@setchapternewpage} command. You need the
@code{@@headings} command only if the @code{@@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 @code{@@headings} command
immediately after the @code{@@end titlepage} command.@refill
You can use @code{@@headings} as follows:@refill
@table @code
@item @@headings off
Turn off printing of page headings.@refill
@item @@headings single
Turn on page headings appropriate for single-sided printing.
@refill
@item @@headings double
Turn on page headings appropriate for double-sided printing. The two
commands, @code{@@headings on} and @code{@@headings double}, are
synonymous.@refill
@item @@headings singleafter
@itemx @@headings doubleafter
Turn on @code{single} or @code{double} headings, respectively, after the
current page is output.
@item @@headings on
Turn on page headings: @code{single} if @samp{@@setchapternewpage
on}, @code{double} otherwise.
@end table
For example, suppose you write @code{@@setchapternewpage off} before the
@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
same page as the end of the last chapter. This command also causes
@TeX{} to typeset page headers for single-sided printing. To cause
@TeX{} to typeset for double sided printing, write @code{@@headings
double} after the @code{@@end titlepage} command.
You can stop @TeX{} from generating any page headings at all by
writing @code{@@headings off} on a line of its own immediately after the
line containing the @code{@@end titlepage} command, like this:@refill
@example
@@end titlepage
@@headings off
@end example
@noindent
The @code{@@headings off} command overrides the @code{@@end titlepage}
command, which would otherwise cause @TeX{} to print page
headings.@refill
You can also specify your own style of page heading and footing.
@xref{Headings, , Page Headings}, for more information.@refill
@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File
@comment node-name, next, previous, up
@section The `Top' Node and Master Menu
@cindex @samp{@r{Top}} node
@cindex Master menu
@cindex Node, `Top'
The `Top' node is the node from which you enter an Info file.@refill
A `Top' node should contain a brief description of the Info file and an
extensive, master menu for the whole Info file.
This helps the reader understand what the Info file is
about. Also, you should write the version number of the program to
which the Info file applies; or, at least, the edition number.@refill
The contents of the `Top' node should appear only in the Info file; none
of it should appear in printed output, so enclose it between
@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
print either an @code{@@node} line or a menu; they appear only in Info;
strictly speaking, you are not required to enclose these parts between
@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
@xref{Conditionals, , Conditionally Visible Text}.)@refill
@menu
* Title of Top Node:: Sketch what the file is about.
* Master Menu Parts:: A master menu has three or more parts.
@end menu
@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node
@ifinfo
@subheading `Top' Node Title
@end ifinfo
Sometimes, you will want to place an @code{@@top} sectioning command
line containing the title of the document immediately after the
@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
Sectioning Command}, for more information).@refill
For example, the beginning of the Top node of this manual contains an
@code{@@top} sectioning command, a short description, and edition and
version information. It looks like this:@refill
@example
@group
@dots{}
@@end titlepage
@@ifinfo
@@node Top, Copying, , (dir)
@@top Texinfo
Texinfo is a documentation system@dots{}
@end group
@group
This is edition@dots{}
@dots{}
@@end ifinfo
@end group
@group
@@menu
* Copying:: Texinfo is freely
redistributable.
* Overview:: What is Texinfo?
@dots{}
@end group
@@end menu
@end example
In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
level directory of the whole Info system, which is called @samp{(dir)}.
The `Next' node refers to the first node that follows the main or master
menu, which is usually the copying permissions, introduction, or first
chapter.@refill
@node Master Menu Parts, , Title of Top Node, The Top Node
@subsection Parts of a Master Menu
@cindex Master menu parts
@cindex Parts of a master menu
A @dfn{master menu} is a detailed main menu listing all the nodes in a
file.
A master menu is enclosed in @code{@@menu} and @code{@@end menu}
commands and does not appear in the printed document.@refill
Generally, a master menu is divided into parts.@refill
@itemize @bullet
@item
The first part contains the major nodes in the Texinfo file: the nodes
for the chapters, chapter-like sections, and the appendices.@refill
@item
The second part contains nodes for the indices.@refill
@item
The third and subsequent parts contain a listing of the other, lower
level nodes, often ordered by chapter. This way, rather than go
through an intermediary menu, an inquirer can go directly to a
particular node when searching for specific information. These menu
items are not required; add them if you think they are a
convenience. If you do use them, put @code{@@detailmenu} before the
first one, and @code{@@end detailmenu} after the last; otherwise,
@code{makeinfo} will get confused.
@end itemize
Each section in the menu can be introduced by a descriptive line. So
long as the line does not begin with an asterisk, it will not be
treated as a menu entry. (@xref{Writing a Menu}, for more
information.)@refill
For example, the master menu for this manual looks like the following
(but has many more entries):@refill
@example
@group
@@menu
* Copying:: Texinfo is freely
redistributable.
* Overview:: What is Texinfo?
* Texinfo Mode:: Special features in GNU Emacs.
@dots{}
@dots{}
@end group
@group
* Command and Variable Index::
An entry for each @@-command.
* Concept Index:: An entry for each concept.
@end group
@group
@@detailmenu
--- The Detailed Node Listing ---
Overview of Texinfo
* Info Files:: What is an Info file?
* Printed Manuals:: Characteristics of
a printed manual.
@dots{}
@dots{}
@end group
@group
Using Texinfo Mode
* Info on a Region:: Formatting part of a file
for Info.
@dots{}
@dots{}
@@end detailmenu
@@end menu
@end group
@end example
@node Software Copying Permissions, , The Top Node, Beginning a File
@comment node-name, next, previous, up
@section Software Copying Permissions
@cindex Software copying permissions
@cindex Copying software
@cindex Distribution
@cindex License agreement
If the Texinfo file has a section containing the ``General Public
License'' and the distribution information and a warranty disclaimer
for the software that is documented, this section usually follows the
`Top' node. The General Public License is very important to Project
GNU software. It ensures that you and others will continue to have a
right to use and share the software.@refill
The copying and distribution information and the disclaimer are
followed by an introduction or else by the first chapter of the
manual.@refill
@cindex Introduction, as part of file
Although an introduction is not a required part of a Texinfo file, it
is very helpful. Ideally, it should state clearly and concisely what
the file is about and who would be interested in reading it. In
general, an introduction would follow the licensing and distribution
information, although sometimes people put it earlier in the document.
Usually, an introduction is put in an @code{@@unnumbered} section.
(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
@code{@@appendix} Commands}.)@refill
@node Ending a File, Structuring, Beginning a File, Top
@comment node-name, next, previous, up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending
@findex bye
The end of a Texinfo file should include the commands that create
indices and generate detailed and summary tables of contents.
And it must include the @code{@@bye} command that marks the last line
processed by @TeX{}.@refill
@need 700
For example:
@example
@@node Concept Index, , Variables Index, Top
@@c node-name, next, previous, up
@@unnumbered Concept Index
@@printindex cp
@@contents
@@bye
@end example
@menu
* Printing Indices & Menus:: How to print an index in hardcopy and
generate index menus in Info.
* Contents:: How to create a table of contents.
* File End:: How to mark the end of a file.
@end menu
@node Printing Indices & Menus, Contents, Ending a File, Ending a File
@comment node-name, next, previous, up
@section Index Menus and Printing an Index
@findex printindex
@cindex Printing an index
@cindex Indices, printing and menus
@cindex Generating menus with indices
@cindex Menus generated with indices
To print an index means to include it as part of a manual or Info
file. This does not happen automatically just because you use
@code{@@cindex} or other index-entry generating commands in the
Texinfo file; those just cause the raw data for the index to be
accumulated. To generate an index, you must include the
@code{@@printindex} command at the place in the document where you
want the index to appear. Also, as part of the process of creating a
printed manual, you must run a program called @code{texindex}
(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted
index file. The sorted index file is what is actually used to
print the index.@refill
Texinfo offers six different types of predefined index: the concept
index, the function index, the variables index, the keystroke index, the
program index, and the data type index (@pxref{Predefined Indices}). Each
index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
into separate sections (@pxref{Combining Indices}); or you may define
your own indices (@pxref{New Indices, , Defining New Indices}).@refill
The @code{@@printindex} command takes a two-letter index name, reads
the corresponding sorted index file and formats it appropriately into
an index.@refill
@ignore
The two-letter index names are:
@table @samp
@item cp
concept index
@item fn
function index
@item vr
variable index
@item ky
key index
@item pg
program index
@item tp
data type index
@end table
@end ignore
The @code{@@printindex} command does not generate a chapter heading
for the index. Consequently, you should precede the
@code{@@printindex} command with a suitable section or chapter command
(usually @code{@@unnumbered}) to supply the chapter heading and put
the index into the table of contents. Precede the @code{@@unnumbered}
command with an @code{@@node} line.@refill
@need 1200
For example:
@smallexample
@group
@@node Variable Index, Concept Index, Function Index, Top
@@comment node-name, next, previous, up
@@unnumbered Variable Index
@@printindex vr
@end group
@group
@@node Concept Index, , Variable Index, Top
@@comment node-name, next, previous, up
@@unnumbered Concept Index
@@printindex cp
@end group
@group
@@summarycontents
@@contents
@@bye
@end group
@end smallexample
@noindent
(Readers often prefer that the concept index come last in a book,
since that makes it easiest to find.)@refill
@ignore
@c TeX can do sorting, just not conveniently enough to handle sorting
@c Texinfo indexes. --karl, 5may97.
In @TeX{}, the @code{@@printindex} command needs a sorted index file
to work from. @TeX{} does not know how to do sorting; this is a
deficiency. @TeX{} writes output files of raw index data; use the
@code{texindex} program to convert these files to sorted index files.
(@xref{Format/Print Hardcopy}, for more information.)@refill
@end ignore
@node Contents, File End, Printing Indices & Menus, Ending a File
@comment node-name, next, previous, up
@section Generating a Table of Contents
@cindex Table of contents
@cindex Contents, Table of
@findex contents
@findex summarycontents
@findex shortcontents
The @code{@@chapter}, @code{@@section}, and other structuring commands
supply the information to make up a table of contents, but they do not
cause an actual table to appear in the manual. To do this, you must
use the @code{@@contents} and @code{@@summarycontents}
commands:@refill
@table @code
@item @@contents
Generate a table of contents in a printed manual, including all
chapters, sections, subsections, etc., as well as appendices and
unnumbered chapters. (Headings generated by the @code{@@heading}
series of commands do not appear in the table of contents.) The
@code{@@contents} command should be written on a line by
itself.@refill
@item @@shortcontents
@itemx @@summarycontents
(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
two commands are exactly the same.)@refill
Generate a short or summary table of contents that lists only the
chapters (and appendices and unnumbered chapters). Omit sections, subsections
and subsubsections. Only a long manual needs a short table
of contents in addition to the full table of contents.@refill
Write the @code{@@shortcontents} command on a line by itself right
@emph{before} the @code{@@contents} command.@refill
@end table
The table of contents commands automatically generate a chapter-like
heading at the top of the first table of contents page. Write the table
of contents commands at the very end of a Texinfo file, just before the
@code{@@bye} command, following any index sections---anything in the
Texinfo file after the table of contents commands will be omitted from
the table of contents.@refill
When you print a manual with a table of contents, the table of
contents are printed last and numbered with roman numerals. You need
to place those pages in their proper place, after the title page,
yourself. (This is the only collating you need to do for a printed
manual. The table of contents is printed last because it is generated
after the rest of the manual is typeset.)@refill
@need 700
Here is an example of where to write table of contents commands:@refill
@example
@group
@var{indices}@dots{}
@@shortcontents
@@contents
@@bye
@end group
@end example
Since an Info file uses menus instead of tables of contents, the Info
formatting commands ignore the @code{@@contents} and
@code{@@shortcontents} commands.@refill
@node File End, , Contents, Ending a File
@comment node-name, next, previous, up
@section @code{@@bye} File Ending
@findex bye
An @code{@@bye} command terminates @TeX{} or Info formatting. None of
the formatting commands see any of the file following @code{@@bye}.
The @code{@@bye} command should be on a line by itself.@refill
If you wish, you may follow the @code{@@bye} line with notes. These notes
will not be formatted and will not appear in either Info or a printed
manual; it is as if text after @code{@@bye} were within @code{@@ignore}
@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
with a local variables list. @xref{Compile-Command, , Using Local
Variables and the Compile Command}, for more information.@refill
@node Structuring, Nodes, Ending a File, Top
@comment node-name, next, previous, up
@chapter Chapter Structuring
@cindex Chapter structuring
@cindex Structuring of chapters
The @dfn{chapter structuring} commands divide a document into a hierarchy of
chapters, sections, subsections, and subsubsections. These commands
generate large headings; they also provide information for the table
of contents of a printed manual (@pxref{Contents, , Generating a Table
of Contents}).@refill
The chapter structuring commands do not create an Info node structure,
so normally you should put an @code{@@node} command immediately before
each chapter structuring command (@pxref{Nodes}). The only time you
are likely to use the chapter structuring commands without using the
node structuring commands is if you are writing a document that
contains no cross references and will never be transformed into Info
format.@refill
It is unlikely that you will ever write a Texinfo file that is
intended only as an Info file and not as a printable document. If you
do, you might still use chapter structuring commands to create a
heading at the top of each node---but you don't need to.@refill
@menu
* Tree Structuring:: A manual is like an upside down tree @dots{}
* Structuring Command Types:: How to divide a manual into parts.
* makeinfo top:: The @code{@@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.
@end menu
@node Tree Structuring, Structuring Command Types, Structuring, Structuring
@comment node-name, next, previous, up
@section Tree Structure of Sections
@cindex Tree structuring
A Texinfo file is usually structured like a book with chapters,
sections, subsections, and the like. This structure can be visualized
as a tree (or rather as an upside-down tree) with the root at the top
and the levels corresponding to chapters, sections, subsection, and
subsubsections.@refill
Here is a diagram that shows a Texinfo file with three chapters,
each of which has two sections.@refill
@example
@group
Top
|
-------------------------------------
| | |
Chapter 1 Chapter 2 Chapter 3
| | |
-------- -------- --------
| | | | | |
Section Section Section Section Section Section
1.1 1.2 2.1 2.2 3.1 3.2
@end group
@end example
In a Texinfo file that has this structure, the beginning of Chapter 2
looks like this:@refill
@example
@group
@@node Chapter 2, Chapter 3, Chapter 1, top
@@chapter Chapter 2
@end group
@end example
The chapter structuring commands are described in the sections that
follow; the @code{@@node} and @code{@@menu} commands are described in
following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring
@comment node-name, next, previous, up
@section Types of Structuring Commands
The chapter structuring commands fall into four groups or series, each
of which contains structuring commands corresponding to the
hierarchical levels of chapters, sections, subsections, and
subsubsections.@refill
The four groups are the @code{@@chapter} series, the
@code{@@unnumbered} series, the @code{@@appendix} series, and the
@code{@@heading} series.@refill
Each command produces titles that have a different appearance on the
printed page or Info file; only some of the commands produce
titles that are listed in the table of contents of a printed book or
manual.@refill
@itemize @bullet
@item
The @code{@@chapter} and @code{@@appendix} series of commands produce
numbered or lettered entries both in the body of a printed work and in
its table of contents.@refill
@item
The @code{@@unnumbered} series of commands produce unnumbered entries
both in the body of a printed work and in its table of contents. The
@code{@@top} command, which has a special use, is a member of this
series (@pxref{makeinfo top, , @code{@@top}}).@refill
@item
The @code{@@heading} series of commands produce unnumbered headings
that do not appear in a table of contents. The heading commands never
start a new page.@refill
@item
The @code{@@majorheading} command produces results similar to using
the @code{@@chapheading} command but generates a larger vertical
whitespace before the heading.@refill
@item
When an @code{@@setchapternewpage} command says to do so, the
@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
start new pages in the printed manual; the @code{@@heading} commands
do not.@refill
@end itemize
@need 1000
Here are the four groups of chapter structuring commands:@refill
@c Slightly different formatting for regular sized books and smallbooks.
@ifset smallbook
@sp 1
@tex
{\let\rm=\indrm \let\tt=\indtt
\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil&
\hskip.5em#\hfil\cr
& & & \rm No new pages\cr
\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
& & & \cr
& \tt @@top& & \tt @@majorheading\cr
\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
\tt @@subheading\cr
\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
\tt @@subsubheading\cr}}
@end tex
@end ifset
@ifclear smallbook
@sp 1
@tex
\vbox{
\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil&
\hskip.5em#\hfil& \hskip.5em #\hfil\cr
& & & \cr
& & & \rm No new pages\cr
\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
& & & \cr
& \tt @@top& & \tt @@majorheading\cr
\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
\tt @@subheading\cr
\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
\tt @@subsubheading\cr}}
@end tex
@end ifclear
@ifinfo
@example
@group
@r{No new pages}
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
@@top @@majorheading
@@chapter @@unnumbered @@appendix @@chapheading
@@section @@unnumberedsec @@appendixsec @@heading
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
@end group
@end example
@end ifinfo
@c Cannot line up columns properly inside of an example because of roman
@c proportional fonts.
@ignore
@ifset smallbook
@iftex
@smallexample
@group
@r{No new pages}
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
@@top @@majorheading
@@chapter @@unnumbered @@appendix @@chapheading
@@section @@unnumberedsec @@appendixsec @@heading
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
@end group
@end smallexample
@end iftex
@end ifset
@ifclear smallbook
@iftex
@smallexample
@group
@r{No new pages}
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
@@top @@majorheading
@@chapter @@unnumbered @@appendix @@chapheading
@@section @@unnumberedsec @@appendixsec @@heading
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
@end group
@end smallexample
@end iftex
@end ignore
@node makeinfo top, chapter, Structuring Command Types, Structuring
@comment node-name, next, previous, up
@section @code{@@top}
The @code{@@top} command is a special sectioning command that you use
only after an @samp{@@node Top} line at the beginning of a Texinfo file.
The @code{@@top} command tells the @code{makeinfo} formatter
which node is the `Top'
node. It has the same typesetting effect as @code{@@unnumbered}
(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}).
For detailed information, see
@ref{makeinfo top command, , The @code{@@top} Command}.@refill
@node chapter, unnumbered & appendix, makeinfo top, Structuring
@comment node-name, next, previous, up
@section @code{@@chapter}
@findex chapter
@code{@@chapter} identifies a chapter in the document. Write the
command at the beginning of a line and follow it on the same line by
the title of the chapter.@refill
For example, this chapter in this manual is entitled ``Chapter
Structuring''; the @code{@@chapter} line looks like this:@refill
@example
@@chapter Chapter Structuring
@end example
In @TeX{}, the @code{@@chapter} command creates a chapter in the
document, specifying the chapter title. The chapter is numbered
automatically.@refill
In Info, the @code{@@chapter} command causes the title to appear on a
line by itself, with a line of asterisks inserted underneath. Thus,
in Info, the above example produces the following output:@refill
@example
Chapter Structuring
*******************
@end example
@findex centerchap
Texinfo also provides a command @code{@@centerchap}, which is analogous
to @code{@@unnumbered}, but centers its argument in the printed output.
This kind of stylistic choice is not usually offered by Texinfo.
@c but the Hacker's Dictionary wanted it ...
@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring
@comment node-name, next, previous, up
@section @code{@@unnumbered}, @code{@@appendix}
@findex unnumbered
@findex appendix
Use the @code{@@unnumbered} command to create a chapter that appears
in a printed manual without chapter numbers of any kind. Use the
@code{@@appendix} command to create an appendix in a printed manual
that is labelled by letter instead of by number.@refill
For Info file output, the @code{@@unnumbered} and @code{@@appendix}
commands are equivalent to @code{@@chapter}: the title is printed on a
line by itself with a line of asterisks underneath. (@xref{chapter, ,
@code{@@chapter}}.)@refill
To create an appendix or an unnumbered chapter, write an
@code{@@appendix} or @code{@@unnumbered} command at the beginning of a
line and follow it on the same line by the title, as you would if you
were creating a chapter.@refill
@node majorheading & chapheading, section, unnumbered & appendix, Structuring
@section @code{@@majorheading}, @code{@@chapheading}
@findex majorheading
@findex chapheading
The @code{@@majorheading} and @code{@@chapheading} commands put
chapter-like headings in the body of a document.@refill
However, neither command causes @TeX{} to produce a numbered heading
or an entry in the table of contents; and neither command causes
@TeX{} to start a new page in a printed manual.@refill
In @TeX{}, an @code{@@majorheading} command generates a larger vertical
whitespace before the heading than an @code{@@chapheading} command but
is otherwise the same.@refill
In Info,
the @code{@@majorheading} and
@code{@@chapheading} commands are equivalent to
@code{@@chapter}: the title is printed on a line by itself with a line
of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
@comment node-name, next, previous, up
@section @code{@@section}
@findex section
In a printed manual, an @code{@@section} command identifies a
numbered section within a chapter. The section title appears in the
table of contents. In Info, an @code{@@section} command provides a
title for a segment of text, underlined with @samp{=}.@refill
This section is headed with an @code{@@section} command and looks like
this in the Texinfo file:@refill
@example
@@section @@code@{@@@@section@}
@end example
To create a section, write the @code{@@section} command at the
beginning of a line and follow it on the same line by the section
title.@refill
Thus,
@example
@@section This is a section
@end example
@noindent
produces
@example
@group
This is a section
=================
@end group
@end example
@noindent
in Info.
@node unnumberedsec appendixsec heading, subsection, section, Structuring
@comment node-name, next, previous, up
@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
@findex unnumberedsec
@findex appendixsec
@findex heading
The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
commands are, respectively, the unnumbered, appendix-like, and
heading-like equivalents of the @code{@@section} command.
(@xref{section, , @code{@@section}}.)@refill
@table @code
@item @@unnumberedsec
The @code{@@unnumberedsec} command may be used within an
unnumbered chapter or within a regular chapter or appendix to
provide an unnumbered section.@refill
@item @@appendixsec
@itemx @@appendixsection
@code{@@appendixsection} is a longer spelling of the
@code{@@appendixsec} command; the two are synonymous.@refill
@findex appendixsection
Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
command is used only within appendices.@refill
@item @@heading
You may use the @code{@@heading} command anywhere you wish for a
section-style heading that will not appear in the table of contents.@refill
@end table
@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
@comment node-name, next, previous, up
@section The @code{@@subsection} Command
@findex subsection
Subsections are to sections as sections are to chapters.
(@xref{section, , @code{@@section}}.) In Info, subsection titles are
underlined with @samp{-}. For example,@refill
@example
@@subsection This is a subsection
@end example
@noindent
produces
@example
@group
This is a subsection
--------------------
@end group
@end example
In a printed manual, subsections are listed in the table of contents
and are numbered three levels deep.@refill
@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
@comment node-name, next, previous, up
@section The @code{@@subsection}-like Commands
@cindex Subsection-like commands
@findex unnumberedsubsec
@findex appendixsubsec
@findex subheading
The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
@code{@@subheading} commands are, respectively, the unnumbered,
appendix-like, and heading-like equivalents of the @code{@@subsection}
command. (@xref{subsection, , @code{@@subsection}}.)@refill
In Info, the @code{@@subsection}-like commands generate a title
underlined with hyphens. In a printed manual, an @code{@@subheading}
command produces a heading like that of a subsection except that it is
not numbered and does not appear in the table of contents. Similarly,
an @code{@@unnumberedsubsec} command produces an unnumbered heading like
that of a subsection and an @code{@@appendixsubsec} command produces a
subsection-like heading labelled with a letter and numbers; both of
these commands produce headings that appear in the table of
contents.@refill
@node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
@comment node-name, next, previous, up
@section The `subsub' Commands
@cindex Subsub commands
@findex subsubsection
@findex unnumberedsubsubsec
@findex appendixsubsubsec
@findex subsubheading
The fourth and lowest level sectioning commands in Texinfo are the
`subsub' commands. They are:@refill
@table @code
@item @@subsubsection
Subsubsections are to subsections as subsections are to sections.
(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
subsubsection titles appear in the table of contents and are numbered
four levels deep.@refill
@item @@unnumberedsubsubsec</