4.4BSD/usr/src/contrib/emacs-18.57/man/texinfo.texinfo
\input texinfo @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename ../info/texinfo
@settitle Texinfo 1.1
@comment %**end of header (This is for running Texinfo on a region.)
@iftex
@finalout
@end iftex
@ifinfo
This file documents Texinfo, a documentation system that uses a single
source file to produce both on-line help and a printed manual.
This is edition 1.1 of the Texinfo documentation, and is for the Texinfo
that is distributed as part of Version 18 of GNU Emacs.
Copyright (C) 1988 Free Software Foundation, Inc.
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 Foundation.
@end ifinfo
@setchapternewpage odd
@titlepage
@sp 11
@center @titlefont{Texinfo}
@sp 2
@center The GNU Documentation Format
@sp 2
@center by Richard M. Stallman and Robert J. Chassell
@sp 2
@center Edition 1.1
@sp 2
@center May 1988
@comment Include the Distribution inside the titlepage environment so
@c that headings are turned off.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988 Free Software Foundation, Inc.
@sp 2
This is version 1.1 of the Texinfo documentation, and is for @*
the Texinfo that is distributed as part of Version 18 of GNU Emacs.
@sp 2
Published by the Free Software Foundation @*
675 Massachusetts Avenue, @*
Cambridge, MA 02139 USA @*
Printed copies are available for $10 each.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage
@node Top, License, (dir), (dir)
@menu
* License:: Licensing information.
* Overview:: What is Texinfo?
* Texinfo Mode:: Special features in GNU Emacs.
* Beginning a File:: What to put at the beginning of a Texinfo file.
* Ending a File:: What to put at the end of a Texinfo file.
* Structuring:: How to make nodes and chapters.
* Quotations and Examples:: How to insert quotations and examples.
* Lists and Tables:: How to make lists and tables.
* Cross References:: How to make cross references.
* Formatting Paragraphs:: How to format paragraphs.
* Marking Text:: How to mark code, definitions, variables etc.
* Conditionals:: Putting text in only Info or the printed work.
* Printing Hardcopy:: How to print a hardcopy of the manual.
* Creating an Info File:: How to create an on-line Info file.
* Catching Mistakes:: How to find problems.
Indices, nodes containing large menus
* Command Index:: An item for each @@-command.
* Concept Index:: An item for each concept.
A detailed node listing
Overview
* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the printed manual.
* Conventions:: General syntactic conventions.
* Short Sample:: A short sample Texinfo file.
Using Texinfo Mode
* Info on a Region:: Formatting a region for Info.
* Showing the Structure:: Showing the structure of a file.
* Inserting:: Inserting frequently used commands.
Beginning a Texinfo File.
* First Line:: The first line of a Texinfo file.
* Start-of-Header:: Identifying the start of the header.
* Setfilename:: Specifying the name of the Info file.
* Settitle:: Specifying the title used by the headings.
* Setchapternewpage:: Starting chapters on odd numbered pages.
* Titlepage:: The title and copyright page.
* Center:: Centering a line.
* Copyright & Printed Permissions:: Ensuring free distributability.
* Top Node:: The master menu.
* License and Distribution:: Your are free to copy and distribute this.
Ending a Texinfo File
* Contents:: Generating tables of contents.
* Indices:: Generating indices.
* Index Entries:: Defining the entries of an index.
* Combining Indices:: Putting two or more indices together.
* Printing Indices & Menus:: Printing an index and generating menus.
Node and Chapter Structuring
* Chapter:: Creating a chapter.
* Unnumbered and Appendix:: Chapter-like parts.
* Section:: Creating sections
* Subsection:: Creating subsections.
* Subsubsection:: Creating subsubsections.
* Node:: Creating nodes.
* Menu:: Creating menus.
Making quotations and examples
* Quotation:: Inserting long quotations.
* Example:: Inserting examples of code and the like.
* Display:: Inserting displayed text.
Making lists and two column tables
* Itemize:: Creating itemized lists.
* Enumerate:: Creating enumerated lists.
* Table:: Creating two column tables.
* Itemx:: Putting an extra item in the
first column of a table.
Making Cross References
* Xref:: Making a regular cross reference.
* Pxref:: Making a parenthetical cross reference.
* Inforef:: Making a cross reference to an Info file.
Formatting Paragraphs
* Refilling & Noindent:: Refilling paragraphs
and preventing indentation
* Refill:: Using the @code{@@refill} command.
* Noindent:: Using the @code{@@noindent} command.
Breaks, Blank Lines and Groups
* Line Breaks:: Inserting line breaks in @TeX{}.
* Sp:: Inserting blank lines.
* Br:: Inserting paragraph breaks.
* W:: Preventing line breaks.
* Page:: Starting new pages.
* Group:: Holding text together on one page.
* Need:: Keeping text together.
Marking Text Within a Paragraph
* Code:: A literal example of a piece of a program.
* Samp:: A literal example of a sequence of characters.
* File:: The name of a file.
* Kbd:: The names of keys or else characters you type.
* Key:: The conventional name for a key on a keyboard.
* Ctrl:: Indicates the ASCII control character.
* Var:: A variable.
* Dfn:: The introductory or defining use of a term.
* Cite:: The name of a book.
Inserting Braces, @samp{@@} and Periods
* Braces Atsigns Periods:: Inserting braces, @samp{@@} and periods.
* Dots Bullets Tex:: Inserting dots, bullets and the @TeX{} logo
* Emphasis:: Emphasizing text.
Emphasizing Text
* Emph and Strong:: Emphasizing text.
* Fonts:: Selecting italic, bold or typewriter fonts.
Creating an Info File
* Installing an Info File:: Putting the Info file in the
@file{info} directory.
Catching Mistakes
* Debugging with Info:: Catching errors with info formatting.
* Using the Emacs Lisp Debugger:: Using the Emacs Lisp Debugger
* Debugging with Tex:: Catching errors with @TeX{} formatting.
* Using texinfo-show-structure:: Using @code{texinfo-show-structure}
to catch mistakes.
* Using Occur:: Using @code{occur} to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.
Finding badly referenced nodes
* Info-Validating a Large File:: Running @code{Info-validate}
on a large file.
* Splitting:: Splitting a file manually.
Appendices
* Command Syntax:: Details about the syntax.
* Include Files:: Making one printed file out of
several Info files.
* TeX Input:: Where @TeX{} finds its @samp{\input} file.
* Sample Permissions:: You may copy GNU Software.
* Ifinfo Permissions:: What to put in the `ifinfo' section.
* Titlepage Permissions:: What to put in the `@@titlepage' section.
@end menu
@node License, Overview, Top, Top
@comment node-name, next, previous, up
@unnumbered Licensing Information
The programs currently being distributed that relate to Texinfo
include two portions of GNU Emacs, plus two other separate programs
(@code{texindex} and @code{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.
Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to Texinfo, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.
To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of the Texinfo related programs, you must give the recipients all
the rights that you have. You must make sure that they, too, receive or
can get the source code. And you must tell them their rights.
Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to Texinfo.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.
The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
Licenses that accompany them. The programs that are part of GNU Emacs
are covered by the GNU Emacs copying terms (@pxref{License, , , emacs,
The GNU Emacs Manual}), and other programs are covered by licenses that
are contained in their source files.
@node Overview, Texinfo Mode, License, Top
@comment node-name, next, previous, up
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview
Texinfo is a documentation system that uses a single source file for both
on-line help and a printed manual. This means that instead of writing two
different documents, one for the on-line help and the other for the printed
manual, only one document needs to be written. When the system is revised,
only one file has to be revised.@refill
Using Texinfo, you can create a document with the normal features of a book
such as chapters, sections, cross references and indices. The chapters and
sections of the printed manual can be made to correspond to the nodes of
the on-line help. The cross references and indices can be used in both the
on-line help and in the printed document. Indices are generated
semi-automatically. The @cite{GNU Emacs Manual} is a good example of a
Texinfo file.@refill
To make the printed manual, the Texinfo source file is processed by the
@TeX{} typesetting program; the resulting DVI file can be typeset and
printed as a book. To make the on-line help, the Texinfo source file is by
processed the @kbd{M-x texinfo-format-buffer} command; the resulting Info
file is installed in the @file{info} directory.@refill
Since the Texinfo source file is used for a dual task---to create both the
on-line help and the printed manual---it must be written in a special
format that uses @@-commands (words preceded by an @samp{@@}) to indicate
chapters, sections, nodes, examples, index entries and the like.@refill
Before writing a Texinfo source file, you should be familiar with the
on-line Info documentation reading program. (@inforef{Info, info, info},
for more information.) If you are writing a document that will be both
on-line and printed, you will need both Info and @TeX{}.
To make an Info file, you use the @kbd{M-x texinfo-format-buffer} command
in GNU Emacs.@refill
To make a printed manual, you need to use @TeX{}, a powerful,
sophisticated typesetting program written by Donald Knuth. @TeX{} is
freely distributable. It is written in a dialect 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. (For information about getting
@TeX{}, @pxref{TeX Mode, , , emacs, The GNU Emacs Manual})
When @TeX{} processes a Texinfo source file, @TeX{} makes use of a macro
definitions file called @file{texinfo.tex} that comes with the GNU Emacs
distribution in the @file{emacs/man} sources directory. (The first line of
every Texinfo file has a command that says @code{\input texinfo}; this
tells @TeX{} to use the @file{texinfo.tex} file.)@refill
If the @file{texinfo.tex} file has not already been copied to the directory
which contains the other @TeX{} macro definition files when Emacs was
installed, you will probably want to copy it to that directory. Usually,
this is the @file{/usr/lib/tex/macros} directory. For more information,
@pxref{TeX Input, , @TeX{} Input Initialization}
Documentation for GNU utilities and libraries should be written in Texinfo
format.
@menu
* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the Printed Manual.
* Conventions:: General Syntactic Conventions.
* Short Sample:: A short sample Texinfo file.
@end menu
@node Info File, Printed Manual, , Overview
@comment node-name, next, previous, up
@section Characteristics of the Info file
@cindex Characteristics of the Info file
@cindex Info file characteristics
A Texinfo file can be transformed into a printed manual and an on-line Info
file.
An on-line Info file is a file formatted so that the Info documentation
reading program can operate on it. 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 the other nodes to which the current node points.
@ifinfo
@inforef{Info, info, info}, for more information about using Info.
@end ifinfo
Normally, most of the nodes are arranged in a tree which branches down.
Each node may have any number of child nodes that describe subtopics of the
node's topic. The names of these child nodes, if any, are listed in a
@dfn{menu} within the parent node; this allows certain Info commands to
be used to move to one of the child nodes. Each child node records the
parent node name, as its `Up' pointer. Thus, if a node were at the logical
level of a `chapter', its child nodes would be `sections'; likewise,
the child nodes of a section would be subsections.
The root of the tree is the top node of the file, through which users
enter the file from the Info directory. By convention, this node is always
called @samp{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.
Generally you enter the Info file from the top; then you can either traverse
the file systematically by going from node to node or you can search large
menus that correspond to indices and go directly to the node that has the
information you want.
If you want to read through an Info file in sequence, as if it were a
printed manual, you can get the whole file with the advanced Info command
@kbd{g *}. (@inforef{Expert, info, info}.)@refill
All the children of any one parent are linked together in a bidirectional
chain of `Next' and `Previous' pointers. This means that all the nodes
that are logically parallel to sections within a chapter are all linked
together. Normally the order in this chain is the same as the order of the
children in the parent's menu. The last child has no `Next' pointer, and
the first child normally has the parent as its `Previous' pointer (as well
as its `Up' pointer, of course).
Structuring the nodes in a tree is a matter of convention, not a
requirement. In fact, the `Up', `Previous' and `Next' pointers of a node
can point to any other nodes, and the menu can contain any other nodes.
The structure of nodes can be any directed graph. But it is usually more
comprehensible to make it a tree. Info provides another kind of pointer
between nodes, called a reference, that can be sprinkled through the text
of a node. This is usually the best way to represent links that do not fit
the tree structure.
Most often the nodes fall into a strict tree structure that corresponds to
the structure of chapters and sections in the printed
manual. But there are times when this is not right for the material being
discussed. Therefore, Texinfo uses separate commands to specify the node
structure of the Info file and the section structure of the printed manual.
Also, Texinfo requires that you specify menus explicitly, rather than
generate them automatically based on an assumed tree structure.
@node Printed Manual, Conventions, Info File, Top
@comment node-name, next, previous, up
@section Characteristics of the Printed Manual
@cindex Printed manual characteristics
@cindex Characteristics, printed manual
A Texinfo file can be formatted and typeset as a printed manual. The
printed manual will be the same as any other book; it will have a title
page, copyright page, table of contents, and preface as you would expect,
as well as chapters, numbered or unnumbered sections and subsections, not
to mention page headers, cross references and indices.
Texinfo can be used for writing a book without ever having the intention of
converting it into on-line help. Texinfo can be used for writing a novel;
and it can even be used to write a memo, although this application is not
recommended since electronic mail is so much easier.
Texinfo uses the formatting language called @TeX{} for typesetting. A file
called @file{texinfo.tex} contains information (definitions or
@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. (The
macros tell @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,
either with 7 inch by 9.25 inch pages or with 8.5 inch by 11 inch pages.
(This is 178 mm by 235 mm or else 216 mm by 280 mm.) Also, by changing the
parameters in @file{texinfo.tex} you can easily change the size of the
printed document. In addition, you can readily 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 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 commands that Texinfo supports are
necessarily limited.
@node Conventions, Short Sample, Printed Manual, Overview
@comment node-name, next, previous, up
@section General Syntactic Conventions
@cindex General syntactic conventions
@cindex Syntactic conventions
@cindex Conventions, syntactic
Texinfo files contain 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 which converts them into Info files.
All ASCII printing characters except @samp{@@}, @samp{@{} and @samp{@}} can
appear in body text 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. @samp{@{}
and @samp{@}} appearing anywhere else will be treated by @TeX{} as a
grouping but treated by the code that produces an Info file as themselves;
this inconsistency is undesirable, so don't let it occur. To put one of
these special characters into the document, put an @samp{@@} character in
front of it. For example, you would insert @samp{@@@@}, @samp{@@@{}, and
@samp{@@@}}.@refill
It is customary in @TeX{} to use doubled single-quote characters to begin
and end quotations, @samp{``} like these @samp{''}. This convention should
be followed in Texinfo files. Also, three hyphens in a row, @samp{---},
are used for a dash---like this. In @TeX{}, a single or even a double
hyphen produces a dash that is shorter than you want.@refill
@comment Remove for version 19
@TeX{} ignores the line-breaks in the input text, except for blank lines,
which separate paragraphs. Info generally preserves the line breaks that
are present in the input file. Therefore, break the lines in the Texinfo
file the way you want them to appear in the output Info file, and let
@TeX{} take care of itself.
Since Info does not normally refill paragraphs when it processes them, a
line with @@-commands in it will sometimes look bad after Info has run on
it. To cause Info to refill the paragraph after finishing with the other
processing, you need to put the command @code{@@refill} at the end of the
paragraph. (@xref{Refilling & Noindent, , Refilling paragraphs and
Preventing indentation}.)@refill
To prevent a paragraph from being indented in the printed manual, put the
command @code{@@noindent} on a line by itself before the start of the text
that should not be indented.
If you mark off a region of the Texinfo file with the @code{@@iftex} and
@code{@@end iftex} commands so that the region will appear only in the
printed copy, you can use @TeX{} commands that cannot be used in the Info
file.
In order to be made into a printed manual, a Texinfo file @strong{must}
begin with lines that looks like
@example
\input texinfo @@c -*-texinfo-*-
@@setfilename @var{info-file-name}
@@settitle @var{Name of Manual}
@end example
@noindent
The @samp{\input texinfo} line tells @TeX{} to use the @file{texinfo.tex}
file. This line is usually followed by a start-of-header line (not shown
here) and then by the @samp{@@setfilename @var{info-file-name}} and
@samp{@@settitle @var{Name of Manual}} lines. These two lines are needed
to provide a name for the Info file and to specify the name used on the
left-hand page headers of the printed manual.@refill
The two lines that contain the @code{@@setfilename} and @code{@@settitle}
commands usually are sandwiched between the start-of-header line and the
end-of-header line. (@xref{Start-of-Header}, for more information.) The
start-of-header and end-of-header lines are needed if you are going to run
@TeX{} or Info on just part of a file.@refill
@node Short Sample, , Conventions, Overview
@comment node-name, next, previous, up
@section A Short Sample Texinfo File
@cindex Sample texinfo file
A Texinfo file looks like the following, which is a complete but very short
Texinfo file. The @code{@@comment} command introduces comments that will
not appear in either the Info file or the printed manual; they are for the
person who reads the Texinfo file.
The first part of the file, from @samp{\input texinfo} through to
@samp{@@end titlepage}, looks more intimidating than it is. Most of the
material is standard boilerplate; when you write a manual, you just put in
the name of your own manual in this section.@refill
All the commands that tell @TeX{} how to typeset the printed manual and
tell @code{texinfo-format-buffer} how to create an Info file are preceded
by @samp{@@}; thus, @code{@@node} indicates a node and @code{@@chapter}
indicates the start of a chapter.
@example
\input texinfo @@c -*-texinfo-*-
@@setfilename name-of-texinfo-file
@@settitle Name of Manual
@@setchapternewpage odd
@@ifinfo
@@comment The following line inserts the copyright notice
@@comment into the Info file.
Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
@@end ifinfo
@@comment The titlepage section does not appear in the Info file.
@@titlepage
@@sp 10
@@comment The title is printed in a large font.
@@center @@titlefont@{Sample Title@}
@@comment The following two commands start the copyright page
@@comment for the printed manual. This will not appear in the Info file.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright@{@} year copyright-owner
@@end titlepage
@@comment The Top node contains the master menu for the Info file.
@@comment This appears only in the Info file, not the printed manual.
@@node Top, First Chapter, (dir), (dir)
@@comment node-name, next, previous, up
@@menu
* First Chapter:: The first chapter is the
only chapter in this sample.
@@end menu
@@node First Chapter, , Top, Top
@@comment node-name, next, previous, up
@@chapter First Chapter
@@cindex Reference to First Chapter
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 @@kbd@{M-x texinfo-format-buffer@} command transforms a Texinfo file
like this into an Info file; and @@TeX@{@} typesets it for a printed
manual.
@@node Concept Index, , Previous Node, Top
@@comment node-name, next, previous, up
@@unnumbered Concept Index
@@printindex cp
@@contents
@@bye
@end example
Here is what the contents of the first chapter of the sample look like:
@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 @kbd{M-x texinfo-format-buffer} command transforms a Texinfo file like
this into an Info file; and @TeX{} typesets it for a printed manual.
@end quotation
@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
In GNU Emacs, Texinfo mode is a major mode for editing Texinfo files.
This means that Emacs has commands and features especially designed for
working with Texinfo files. Like all other Emacs features, you can
customize or enhance these as you wish. In particular, the keybindings are
very easy to change. The keybindings described here are the default or
standard ones.
The major features of Texinfo mode are:
@itemize @bullet
@item
Paragraph filling control.
@item
A command to show the structure of the file.
@item
Pre-defined keystroke commands to insert commonly used strings of text.
@item
Formatting a part of a file for Info, rather than the whole file.
@end itemize
In general, in Texinfo mode, the GNU Emacs editing commands are like those
in text-mode. The major difference is that the paragraph separation
variable and syntax table are set up so expression commands skip Texinfo
bracket groups. This means, for example, that the @kbd{M-q}
(@code{fill-paragraph}) command will refill a paragraph but not the
@@-command on a line adjacent to it.@refill
By convention, the Texinfo file name shall end with the extension
@file{.texinfo} so that Emacs knows to use Texinfo mode for editing it.
@menu
* Info on a Region:: Formatting part of a file for Info.
* Showing the Structure:: Showing the structure of a file.
* Inserting:: Inserting frequently used commands.
@end menu
@node Info on a Region, Showing the Structure, Texinfo Mode, Texinfo Mode
@comment node-name, next, previous, up
@section Formatting a Region for Info
@cindex Running Info on a region
@cindex Info, formatting on a region
@findex texinfo-format-region
To see what part of a Texinfo file will look like after it has been
transformed into an Info file, use the command @kbd{C-c C-f}
(@code{texinfo-format-region}). This command formats the current region of
the Texinfo file for Info and writes it to a temporary buffer called
@samp{*Info Region*}.@refill
For @code{texinfo-format-region} to work, the file @strong{must} include a
line that has @code{@@setfilename} in its header.@refill
The command is:
@table @kbd
@item C-c C-f
texinfo-format-region
@end table
@node Showing the Structure, Inserting, Info on a Region, Texinfo Mode
@comment node-name, next, previous, up
@section Showing the Structure of a File
@cindex Showing the structure of a file
@cindex Structure of a file, showing it
@cindex File structure, showing it
@cindex Texinfo file structure, showing it
You can show the structure of a Texinfo file by using the @kbd{C-c C-s}
command (@code{texinfo-show-structure}). This command shows the structure
of a Texinfo file by listing the lines with the @@-commands for
@code{@@node}, @code{@@chapter}, @code{@@section} and the like. These
lines are displayed in another window called the @samp{*Occur*} window. In
that window, 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
The two commands are:
@table @kbd
@item C-c C-s
texinfo-show-structure
@item C-c C-c
occur-mode-goto-occurrence
@end table
Often, when you are working on a manual, you will be interested only in the
structure of the current chapter. In this case, you can mark off the
region of the buffer that you are interested in with the @kbd{C-x n}
(@code{narrow-to-region}) command and @code{texinfo-show-structure} will
work on only that region. (To see the whole buffer again, use @kbd{C-x w}
(@code{widen}).)@refill
@node Inserting, , Showing the Structure, Texinfo Mode
@comment node-name, next, previous, up
@section Inserting Frequently Used Commands
@cindex Inserting frequently used commands
@cindex Frequently used commands, inserting them
@cindex Commands, inserting them
Texinfo mode provides commands that insert various frequently used
@@-commands into the buffer. You can use these commands to save
keystrokes. And you can insert balanced curly braces with the @kbd{M-@{}
command, (@code{texinfo-insert-braces}) and later use the @kbd{M-@}}
command (@code{up-list}) to move forward past the closing brace.@refill
The special commands are invoked by typing @kbd{C-c} twice and then the
first letter of the @@-command.
@table @kbd
@item C-c C-c c
texinfo-insert-@@code
@item C-c C-c d
texinfo-insert-@@dfn
@item C-c C-c e
texinfo-insert-@@end
@item C-c C-c i
texinfo-insert-@@item
@item C-c C-c n
texinfo-insert-@@node
@item C-c C-c s
texinfo-insert-@@samp
@item C-c C-c v
texinfo-insert-@@var
@item M-@{
texinfo-insert-braces
@item M-@}
up-list
@end table
This list was generated by analyzing the frequency with which commands were
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}.
@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
Various pieces of information have to be provided to Texinfo at the
beginning of a Texinfo file, such as the name of the file, the title
of the document and the like. Generally, the beginning of a Texinfo file
has four parts:
@enumerate
@item
The header, marked by start-of-header and end-of-header lines, that
includes the commands for naming the Texinfo file and telling @TeX{} what
definitions' file to use when processing the file.
@item
A section, marked by the @code{@@ifinfo} and @code{@@end ifinfo} commands,
that contains a short statement of what the file is about, the copyright
notice and copying permissions. This section appears only in the Info file.
@item
A section, marked by the @code{@@titlepage} and @code{@@end titlepage}
commands, that contains the title page, the copyright page and copying
permissions. This section appears only in the printed manual.
@item
The @samp{Top} node that contains an extensive menu for the whole Info
file. The contents of this node only appear in the Info file.
@end enumerate
If the Texinfo file has a section containing licensing information and a
warranty disclaimer, that section usually follows the @samp{Top} node. The
licensing section will be followed by a preface or else by the first
chapter of the manual.
Since the copyright notice and the copying permissions are in sections that
appear only in the Info file or only in the printed manual, this
information has to be repeated twice.
The following sample shows what is needed.
@example
\input texinfo @@c -*-texinfo-*-
@@comment %**start of header (This is for running Texinfo on a region.)
@@setfilename name-of-texinfo-file
@@settitle Name of Manual
@@setchapternewpage odd
@@comment %**end of header (This is for running Texinfo on a region.)
@@ifinfo
This file documents @dots{}
Copyright @@copyright@{@} year copyright-owner
Permission is granted to @dots{}
@@end ifinfo
@@titlepage
@@sp 10
@@center @@titlefont@{Name of Manual When Printed@}
@@sp 2
@@center Subtitle, If Any
@@sp 2
@@center Author
@@comment The following two commands start the copyright page.
@@page
@@vskip 0pt plus 1filll
Copyright @@copyright@{@} year copyright-owner
Published by @dots{}
Permission is granted to @dots{}
@@end titlepage
@@node Top, Overview, (dir), (dir)
@@menu
* First Chapter:: The first chapter is usually an overview.
* Second Chapter:: @dots{}
<many more menu items here>
@@end menu
@@node First Chapter, Second Chapter, top, top
@@comment node-name, next, previous, up
@@chapter First Chapter
@@cindex Reference to First Chapter
@end example
@menu
* Header:: Necessary first lines.
* Permissions for Info:: Copyright notice and copying permissions.
* Titlepage & Copyright Page:: Printed title and copyright pages.
* Top Node:: The top node and master menu.
* License and Distribution:: The importance of the license.
@end menu
@node Header, Permissions for Info , Beginning a File, 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. If you want to run @TeX{} on just a part of
the Texinfo File, you also have to mark these heading lines with
start-of-header and end-of-header lines.@refill
@menu
* First Line:: The first line of a Texinfo file.
* Start-of-Header:: Identifying the start of the header.
* Setfilename:: Specifying the name of the Info file.
* Settitle:: Specifying the title used by the headings.
* Setchapternewpage:: Starting chapters on odd numbered pages.
* End-of-Header:: Identifying the end of the header.
@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
Every Texinfo file that is to be the top-level input to @TeX{} must begin
with a line that looks like this:
@example
\input texinfo @@c -*-texinfo-*-
@end example
@noindent
The line serves two functions:
@enumerate
@item
When the file is processed by @TeX{}, it loads 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.@refill
@item
When the file is edited in GNU Emacs, it causes Texinfo mode to be used.@refill
@end enumerate
The @samp{\input texinfo} line should be followed by the start-of-header
line. This makes it possible for the command for running @TeX{} on a part
of the Texinfo file (@code{texinfo-hardcopy-region}) to operate. The
reason for this is that the @code{texinfo-hardcopy-region} command will
look on the line preceding the start-of-header line for the @samp{\input
texinfo} line.
@node Start-of-Header, Setfilename, First Line, Header
@comment node-name, next, previous, up
@subsection @samp{start-of-header}
@cindex start-of-header
@findex start-of-header
The start-of-header line should immediately follow the first line of the
Texinfo file.
@ifinfo
The @code{texinfo-hardcopy-region} command will look at the
line preceding the start-of-header line to find the @samp{\input
texinfo} line.
@end ifinfo
Usually, the start-of-header line looks like this:
@example
@@comment %**start of header (This is for running Texinfo on a region.)
@end example
The reason for the odd string of characters (@samp{%**}) is so that the
@code{texinfo-hardcopy-region} command does not accidently find something
that it shouldn't when it is looking for the header.
In the default configuration, the phrase @samp{(This is for running Texinfo
on a region.)} is not needed and is just included to make it easier for
someone reading the Texinfo file.
The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.
@node Setfilename, Settitle, Start-of-Header, Header
@comment node-name, next, previous, up
@subsection @@setfilename
@cindex Setfilename command
@cindex Info file requirement for @@setfilename
@findex setfilename
In order to be made into an Info file, a Texinfo file must contain a line
that looks like this:
@example
@@setfilename @var{info-file-name}
@end example
@noindent
This line specifies the name of the Info file to be generated. In fact, there
can be other things in the file before this line, but they are ignored in
the generation of an Info file. The @code{@@setfilename} line is ignored
when a printed manual is generated.
@node Settitle, Setchapternewpage, Setfilename, Header
@comment node-name, next, previous, up
@subsection @@settitle
@findex settitle
In order to be made into a printed manual file, a Texinfo file must contain
a line that specifies the title of the manual. Texinfo uses this
information during printing to put the title on every other page as a
heading; Texinfo puts the current chapter title on the other pages.
Texinfo can find the name of the chapter title from the information
provided by the @code{@@chapter} command, but you must tell it the manual
title with @code{@@settitle}:
@example
@@settitle @var{Title}
@end example
@noindent
This command, on a line by itself, causes @var{title} to be used for the
headings. Usually, you will use the same words for the title on the title
page and for the title specified by this command for the headings, but the
two could be different. For example, the title on the title page may be
longer than the title specified by the @code{settitle} command.
The @code{@@settitle} command should precede everything that generates
actual output.
@node Setchapternewpage, End-of-Header, Settitle, Header
@comment node-name, next, previous, up
@subsection @@setchapternewpage
@cindex Starting chapters
@cindex Pages, starting odd
@findex setchapternewpage
Conventionally, chapters start on the page on the right hand side of a
book; and the right hand page has an odd number. To make sure that Texinfo
does this, you can use the command @code{@@setchapternewpage}. For
example, to cause each chapter to start on a fresh odd-numbered page:
@example
@@setchapternewpage odd
@end example
Page numbering is turned on by the @code{@@end titlepage} command, so the
@code{@@setchapternewpage} should come before it. Although it can occur
anywhere in the beginning of the file, it is most convenient to put it in
this location.
@node End-of-Header, , Setchapternewpage, Header
@comment node-name, next, previous, up
@subsection @samp{end-of-header}
@cindex end-of-header
The end-of-header line should follow the line containing the
@code{@@setchapternewpage} command.
Usually, the end-of-header line looks like this:
@example
@@comment %**end of header (This is for running Texinfo on a region.)
@end example
@ifinfo
In the default configuration, the phrase @samp{(This is for running Texinfo
on a region.)} is not needed and is just included to make it easier for
someone reading the Texinfo file.
The reason for the odd string of characters (`%**') is so that the
@code{texinfo-hardcopy-region} command does not accidently find something
that it shouldn't when it is looking for the header.
The start-of-header line and the end-of-header line are Texinfo mode
variables that you can change.
@end ifinfo
@iftex
Also, @pxref{Start-of-Header}
@end iftex
@node Permissions for Info, Titlepage & Copyright Page, Header, Beginning a File
@comment node-name, next, previous, up
@section Copying Permissions for Info
Since the title page and the copyright page appear only in the printed copy
of the manual, the same information has to inserted in a section that
appears only in the Info file. This section usually contains a brief
description of the contents of the Info file, a copyright notice and
copying permissions.
The copyright notice should read:
@example
Copyright @var{year} @var{copyright-owner}
@end example
@noindent
and be put on a line by itself.
Standard text for the copyright permissions is contained in the appendix.
@xref{Ifinfo Permissions}, for the complete text.
@node Titlepage & Copyright Page, Top Node, Permissions for Info, Beginning a File
@comment node-name, next, previous, up
@section The Title and Copyright Pages
@cindex Titlepage
@cindex Copyright 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 a couple of slightly
obscure @TeX{} typesetting commands that could not 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.
@menu
* Titlepage:: Creating a title page for the printed manual.
* Center:: Centering a line.
* Copyright & Printed Permissions:: Inserting the copyright notice
and printed permissions.
@end menu
@node Titlepage, Center , Titlepage & Copyright Page, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @@titlepage
@cindex Titlepage
@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. The title page and copyright page material
appears only in the printed manual, not in the Info file.
Also, the @code{@@end titlepage} command starts a new page and turns on
page numbering (generation of headings). Therefore, 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 create more than one unnumbered page. This is how the copyright page
is produced.@refill
@findex titlefont
To select a large font suitable for the title itself, you can use the
command @code{@@titlefont}. For example:
@example
@@center @@titlefont@{Texinfo@}
@end example
Also, you can use @code{@@sp} commands to adjust vertical spacing.
For example:
@example
@@sp 2
@end example
@noindent
In the sample, the spacing was chosen to fit an 8 1/2 by 11 inch manual.
@node Center, Copyright & Printed Permissions, Titlepage, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection @@center
@cindex Centering a line
@findex center
A line containing @code{@@center @var{text}} produces a line of output
containing @var{text}, centered between the margins.@refill
@node Copyright & Printed Permissions,, Center, Titlepage & Copyright Page
@comment node-name, next, previous, up
@subsection The Copyright Page and Printed Permissions
@cindex Copyright
@cindex Printed permissions
@cindex Permissions, printed
By international treaty, the copyright notice for a book should either be
on the title page or on the back of the title page. Other locations in a
book are not official and do not provide copyright protection. The
copyright notice should include the year followed by the name of the person
or organization who has the copyright.
When the copyright notice is on the back of the title page, the page is not
numbered. Therefore, in Texinfo, the information on the copyright page
should be within the region delineated by the @code{@@titlepage} and
@code{@@end titlepage} commands.@refill
@findex vskip
@findex filll
To cause a page break, the @code{@@page} command is used. In the sample,
the @code{@@page} command is followed by the somewhat mysterious line that
reads: @samp{@@vskip 0pt plus 1filll}. This is a line that uses @TeX{}
commands to push the copyright notice and the other text on the copyright
page towards the bottom of the page. The @code{@@vskip} command means to
skip lines and put in white space. The @samp{0pt plus 1filll} means to put
in zero points of mandatory white space, and as much optional white space
as needed. Note the use of three @samp{l}s in the word @samp{filll}; this
is the correct use in @TeX{}.@refill
@findex copyright
The @code{@@copyright@{@}} command generates a @samp{c} inside a circle.
The copyright notice itself has the following legally defined sequence:
@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 (the address of the Free Software Foundation, for example)
and the permissions.
Note that the permissions have to be repeated here as well as in the
`ifinfo' section that immediately follows the header since this section
appears only in the printed manual and the `ifinfo' section appears only in
the Info file.
Standard text for the permissions appears in the appendix.
@xref{Sample Permissions}.
@node Top Node, License and Distribution, Titlepage & Copyright Page, Beginning a File
@comment node-name, next, previous, up
@section The Top Node and Master Menu
@cindex Top node
@cindex Master menu
The @samp{Top} node contains an extensive, master menu for the whole Info
file. The contents of this node appear only in the Info file. Nothing in
this node should appear in the printed file. Since a node line by itself
and a menu by itself are not printed, the contents of this node do not have
to be within a region delineated by @code{@@ifinfo} and @code{@@end ifinfo}
commands. However, any text within the node should be marked off in that
manner. You may want to put a short summary before the master menu inside
a region delineated by @code{@@ifinfo} and @code{@@end ifinfo} commands.
Usually, the `Previous' and `Up' nodes refer to the top level directory of
the whole Info system, with pointers to @samp{(dir)}.@refill
Generally, the top menu is divided into parts.
@itemize @bullet
@item
The first part contains the major nodes in the Texinfo file: the nodes for
the chapters, chapter-like sections and the major appendices.
@item
The second part contains entries for the indices. In an Info file, it is
very useful to have indices here at the beginning of the file in the top
node rather than at the end, as in a printed book.
@item
The third and subsequent parts contain a listing of the other, lower level
nodes, often ordered by chapter. This way, an inquirer can go directly to
a particular node if he or she is searching for specific information.
(These nodes are not required; use them if you think they are a
convenience.)
@end itemize
Each section in the menu can be introduced a descriptive line. So long as
the line does not begin with an asterisk, it will not be treated as a menu
item. (@xref{Menu, , Making Menus}, for more information.)
For example, the Top node of this manual looks like this (but with many
more entries):
@example
@@node Top, Overview, (dir), (dir)
@@menu
* Overview:: What is Texinfo?
* Texinfo Mode:: Special features in GNU Emacs.
@dots{}
Indices, nodes containing large menus
* Command Index:: An item for each @@-command.
* Concept Index:: An item for each concept.
A detailed node listing
Overview
* Info File:: Characteristics of the Info file.
* Printed Manual:: Characteristics of the printed manual.
Using Texinfo Mode
* Info on a Region:: Formatting a region for Info.
* Showing the Structure:: Showing the structure of a file.
@dots{}
@dots{}
@end example
@node License and Distribution, , Top Node, Beginning a File
@comment node-name, next, previous, up
@section Licensing and Distribution Information
@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, this section
usually follows the @samp{Top} node. The licensing and distribution
information and the disclaimer are followed by a preface or else by the
first chapter of the manual.
The licensing agreement is very important to Project GNU documentation and
software. Without it, you may find that you can no longer get the software
or its documentation. This sounds paradoxical, but the state of the world
is such that documentation and software that does not have a
``restrictive'' license to make them freely distributable may be lost to
the public. This has happened.@refill
For a good example of the text that could be used for the Distribution,
General Public License and NO WARRANTY sections of your document, see the
latest version of the @cite{GNU Emacs Manual}.
@cindex Preface
Although a preface 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, the preface
would follow the licensing and distribution information, although sometimes
people put it earlier in the document. Usually, a preface is put in an
@code{@@unnumbered} section. (@xref{Unnumbered and Appendix}.)
@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 indices, the commands to
generate detailed and summary tables of contents and the @@-command
that tells @TeX{} that it has reached the end of the file.
For example, a Texinfo file might be ended as follows:
@example
@@node Concept Index, , Previous Node, Top
@@comment node-name, next, previous, up
@@unnumbered Concept Index
@@printindex cp
@@contents
@@bye
@end example
The @code{@@bye} command should be on a line by itself and every Texinfo
file must end with such a line. This command terminates @TeX{} processing
and forces out unfinished pages.@refill
@menu
* Contents:: Generating a table of contents
* Indices:: Generating, sorting and printing indices
@end menu
@node Contents, Indices , , Ending a File
@comment node-name, next, previous, up
@section Generating a Table of Contents
@cindex Table of contents
@cindex Contents, Table of
The commands @code{@@chapter}, @code{@@section}, etc., supply the
information to make up a table of contents, but they do not cause an actual
table to be generated. To do this, you must use the commands
@code{@@contents} and @code{@@summarycontents}.@refill
@table @code
@item @@contents
The table of contents command outputs (into a printed manual) a complete
table of contents, based on the @code{@@chapter}, @code{@@unnumbered} and
other sectioning commands. This command should be used on a line by
itself.@refill
@item @@summarycontents
The summary contents command generates a summary table of contents that
lists only the chapters (and appendices and unnumbered chapters); sections,
subsections and subsubsections are omitted. This command should be used on
a line by itself. Only large manuals need a summary table of
contents.@refill
@end table
You can use either one of these commands, or both. Each command
automatically generates a chapter-like heading at the top of the page.
Tables of contents should be generated at the very end of the manual, just
before the @code{@@bye} command; the tables of contents commands should
follow any indices that are output, so that the indices will appear in the
contents.@refill
@group
@example
@var{indices}@dots{}
@@summarycontents
@@contents
@@bye
@end example
@end group
The commands @code{@@contents} and @code{@@summarycontents} are ignored when an
Info file is being generated.
@node Indices, , Contents, Ending a File
@comment node-name, next, previous, up
@section Creating Indices
@cindex Indices
@cindex Creating indices
Using Texinfo, you can generate printed indices and Info file menus without
having to sort and collate entries manually. Texinfo will do this for you
automatically. Each index covers a certain kind of entry (functions, or
variables, or concepts, etc.)@: and lists all of those entries in
alphabetical order, together with information on how to find the discussion
of each entry. In a printed manual, this information consists of page
numbers. In an Info file, it consists of a menu item leading to the first
node referenced.
When you are making index entries, it is good practice to think of the
different categories under which people may look for something. Different
people @emph{do not} think of the same words when they look something up.
They think of different words. A helpful index will have items indexed
under all the different words that people may use. For example, someone might
think it obvious that the two letter names for indices should be listed
under ``Indices, two letter names'', since the word ``Index'' is the
general concept. But another reader may remember the specific concept of
two letter names and search for the entry listed as ``Two letter names for
indices''. A good index will have both entries and will help both kinds of
user.
Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
have to do it yourself.
Normally, six indices are provided for:
@itemize @bullet
@item
A @dfn{program index} listing names of programs and leading to the places
where those programs are documented.@refill
@item
A @dfn{function index} listing functions (such as, entry points of
libraries).@refill
@item
A @dfn{variables index} listing variables (such as, external variables of
libraries).@refill
@item
A @dfn{data type index} listing data types (such as, structures defined in
header files).@refill
@item
A @dfn{keystroke index} listing keyboard commands.@refill
@item
A @dfn{concept index} listing concepts that are discussed.@refill
@end itemize
@noindent
Not every manual needs all of these. This manual has two indices: a
concept index and an @@-command index (that uses the function index but is
called a command index in the chapter heading). Two or more indices can be
combined into one using the @code{@@synindex} command. @xref{Combining
Indices}.
@menu
* Index Entries:: Defining the entries of an index
* Combining Indices::
* Printing Indices & Menus::
@end menu
@node Index Entries, Combining Indices, , Indices
@comment node-name, next, previous, up
@subsection Defining the Entries of an Index
@cindex Defining the entries of an index
@cindex Index entries
@cindex Entries for an index
The data to make an index comes from many individual commands scattered
throughout the Texinfo source file. Each command says to add one entry to
a particular index; after processing, it will give the current page number
or node name as the reference.
@table @code
@item @@cindex @var{concept}
Make an entry in the concept index for @var{concept}, referring to the
current page or node.@refill
@item @@findex @var{function}
Make an entry in the function index for @var{function}, referring to the
current page or node.@refill
@item @@vindex @var{variable}
Make an entry in the variable index for @var{variable}, referring to the
current page or node.@refill
@item @@pindex @var{program}
Make an entry in the program index for @var{program}, referring to the
current page or node.@refill
@item @@kindex @var{key}
Make an entry in the key index for @var{key}, referring to the
current page or node.@refill
@item @@tindex @var{data type}
Make an entry in the data type index for @var{data type}, referring to the
current page or node.@refill
@end table
If the same name is indexed on several pages, all the pages are listed in
the printed manual's index. However, @strong{only} the @strong{first} node
referenced will appear in the index of an Info file. This means that it is
best to write indices in which each entry will refer to only one place in the
Texinfo file. Fortunately, this constraint is a feature rather than loss
since it means that the index will be easy to use. Otherwise, it can be
easy to create an index which has many pages listed for an entry and you
don't know which one you need.@refill
You are not actually required to use indices for their canonical
purposes. For example, you might wish to index some C preprocessor macros.
You could put them in the function index along with actual functions, just
by writing @code{@@findex} commands for them; then, when you print the
``function index'', you could give it the title `Function and Macro Index'
and all will be consistent for the reader. Or you could put the macros in
with the data types by writing @code{@@tindex} commands for them, and give
that index a suitable title so the reader will understand.@refill
@node Combining Indices, Printing Indices & Menus, Index Entries, Indices
@comment node-name, next, previous, up
@subsection Combining Indices
@cindex Combining Indices
@cindex Indices, combining them
Sometimes you will want to combine two disparate indices such as functions
and variables, perhaps because you have few enough of one of them that
a separate index for them would look silly.
You could put variables into the function index by writing @code{@@findex}
commands for them instead of @code{@@vindex} commands, and produce a
consistent manual by printing the function index with the title `Function
and Variable Index' and not printing the `Variable Index' at all; but this
is not a robust procedure. It works only as long as your document is never
included in part of or together with another document that is designed to
have a separate variable index; if you did that, the variables from your
document and those from the other would not end up together.
What you should do instead when you want functions and variables in one
index is to index the variables with @code{@@vindex} as they should be, but
use the @code{@@synindex} command to redirect these @code{@@vindex}
commands to the function index. @code{@@synindex} takes two arguments: the
name of an index to redirect, and the name of an index to redirect it to.
For this purpose, the indices are given two-letter names:
@cindex Two letter names for indices
@cindex Indices, two letter names
@cindex Names for indices
@table @samp
@item cp
the concept index
@item vr
the variable index
@item fn
the function index
@item ky
the key index
@item pg
the program index
@item tp
the data type index
@end table
Thus, @code{@@synindex vr fn} at the front of a Texinfo file
will cause all entries designated for the variable index to go to
the function index instead.
@node Printing Indices & Menus, , Combining Indices, Indices
@comment node-name, next, previous, up
@subsection Printing an Index and Generating Menus
@cindex Printing an index
@cindex Indices, printing
@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 print an index, you must
include the @code{@@printindex} command at the place in the document where
you want the index to appear. Also, for the case of the printed manual,
you must run a program called @code{texindex} to sort the raw data to
produce a sorted index file, which is what will actually be used to print
the index.@refill
The Texinfo command that is used to print indices is @code{@@printindex}.
It takes the two-letter index name (@pxref{Combining Indices}) as an
argument without braces, and reads the corresponding sorted index file and
formats it appropriately into an index.@refill
@ifinfo
The two-letter index names are:
@table @samp
@item cp
the concept index.
@item vr
the variable index.
@item fn
the function index.
@item ky
the key index.
@item pg
the program index.
@item tp
the data type index.
@end table
@end ifinfo
@code{@@printindex} does not generate a chapter heading for the index.
Consequently, you should precede the 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. And before that, you will
probably put a @code{@@node} command. For example,@refill
@example
@@node Variables Index, Concept Index, Function Index, Top
@@comment node-name, next, previous, up
@@unnumbered Variable Index
@@printindex vr
@@node Concept Index, , Variables Index, Top
@@comment node-name, next, previous, up
@@unnumbered Concept Index
@@printindex cp
@@summarycontents
@@contents
@@bye
@end example
In @TeX{}, @code{@@printindex} needs a sorted index file to work from.
@TeX{} does not know how to do sorting; this is one of the main
deficiencies of @TeX{}. You must invoke the program @code{texindex} to do
so, giving it the names of the raw index files to be sorted as arguments.
You do not have to run @code{texindex} on all of them; only the ones you
are going to print. (@xref{Printing Hardcopy}, for more information.)
@node Structuring, Quotations and Examples, Ending a File, Top
@comment node-name, next, previous, up
@chapter Node and Chapter Structuring
@cindex Node and chapter structuring
@cindex Chapter structuring
@cindex Node structuring
@cindex Structuring of nodes and chapters
@findex node
The chapter structuring commands divide a document into a hierarchy of
chapters, sections, subsections and subsubsections. These commands
generate large headings.
In a printed manual, the table of contents is based on the information
specified by the chapter structuring commands.
Although the chapter structuring commands used for creating a printed
document are entirely different from the node commands for structuring an
Info file, you are likely to use the two kinds of command together since
the single Texinfo file is usually designed to be read both as an Info file
and as a printed manual. 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 will never be put into Info format, for
example, a novel, a letter, an article or a memorandum.
It is unlikely that you will ever write a Texinfo file that is only
intended as an on-line Info file and not as a printable document. However,
Texinfo is flexible enough so that you can do this if you wish.
Although a Texinfo file can be structured in a variety of ways, it is
usually structured like a book with chapters, sections, subsections and the
like. This structure can also be visualized as a tree (or rather as an
upside down tree) with the root at the top and each level corresponding to
chapters or sections or whatnot. In Info format, you reach the nodes on
each level by using the the `Next' and `Previous' pointers in the node
line. For example, you go from one chapter to the next or previous chapter
by using the the pointers to the next and previous chapters. In Info, you
go the level above by using an `Up' pointer and you go to the level below
through a `Menu'. In the printed manual, cross references are indicated by
page and section numbers; in the on-line file, cross references are
specified by inline menu items.
@group
Here is a diagram that shows a Texinfo file with three chapters;
each chapter has two sections.
@example
top
|
|
---------------------------------------------
| | |
| | |
Chapter 1 Chapter 2 Chapter 3
| | |
| | |
---------- ---------- ----------
| | | | | |
Sect. 1.1 Sect. 1.2 Sect. 2.1 Sect. 2.2 Sect. 3.1 Sect. 3.2
@end example
@end group
In this structure, the node for Chapter 2 looks like this:
@example
@@node Chapter 2, Chapter 3, Chapter 1, top
@@comment node-name, next, previous, up
@end example
To get to Sections 2.1 and 2.2, you need a menu inside of Chapter 2 that
says:
@example
@@menu
* Sect. 2.1:: Description of this section.
* Sect. 2.2::
@@end menu
@end example
@noindent
This menu is located inside Chapter 2, after the beginning of the chapter,
just before Section 2.1.
Note that a menu entry has three parts: the menu item name, the name of the
node and, optionally, a description of the item (in that order). If the
menu item name and the name of the node are the same, you can put two
colons after the item name, as is shown in the example. (If the second part
is different from the first, the first part is terminated by a colon and
the second part terminated by a tab, newline, comma or period.)
(@xref{Menu}.)
The node for Sect. 2.1 will look like this:
@example
@@node Sect. 2.1, Sect. 2.2, , Chapter 2
@@comment node-name, next, previous, up
@end example
This node does not have a `Previous' node.
Usually, an @code{@@node} command and a chapter structuring command are
used in sequence, along with indexing commands. For example, the node for
the chapter on ending a file looks like this:
@group
@example
@@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
@end example
@end group
The chapter structuring commands fall into four groups that have the
characteristics of chapters, sections, subsections and subsubsections.
The groups are:
@group
@table @code
@item @@chapter
@itemx @@unnumbered
@itemx @@appendix
For chapters and chapter-like parts of a document.
@item @@section
@itemx @@unnumberedsec
@itemx @@appendixsec
For sections and section-like parts of a document.
@item @@subsection
@itemx @@unnumberedsubsec
@itemx @@appendixsubsec
For subsections and subsection-like parts of a document.
@item @@subsubsection
@itemx @@unnumberedsubsubsec
@itemx @@appendixsubsubsec
For subsubsections and subsubsection-like parts of a document.
@end table
@end group
In the sections that follow, the chapter structuring commands are described
first and then the @code{@@node} and @code{@@menu} commands.
@menu
* Chapter::
* Unnumbered and Appendix::
* Section::
* Subsection::
* Subsubsection::
* Node::
* Menu::
@end menu
@node Chapter, Unnumbered and Appendix, , Structuring
@comment node-name, next, previous, up
@section @@chapter
@findex chapter
@code{@@chapter} identifies a chapter in the document. It is followed by a
single argument which is the rest of the line, as in
@example
@@chapter Node and Chapter Structuring
@end example
In @TeX{}, it creates a chapter in the document, specifying the chapter
title.
In the Info file, @code{@@chapter} causes its argument to appear on a line
by itself, with a line of asterisks inserted underneath. Thus, the above
example produces the following output:@refill
@example
Node and Chapter Structuring
****************************
@end example
@node Unnumbered and Appendix, Section, Chapter, Structuring
@comment node-name, next, previous, up
@section @@unnumbered, @@appendix
@findex unnumbered
@findex appendix
These commands are equivalent to @code{@@chapter} for Info file output.
(@xref{Chapter}.) In a printed manual, they generate chapters that are
numbered differently in the table of contents. @code{@@unnumbered}
chapters appear without chapter numbers of any kind, and @code{@@appendix}
chapters are given a letter instead of a number.
@node Section, Subsection, Unnumbered and Appendix, Structuring
@comment node-name, next, previous, up
@section @@section
@findex section
@code{@@section} is like @code{@@chapter} except that in @TeX{} it makes a
section rather than a chapter. (@xref{Chapter}.) Sections go within
chapters. In the Info file, @code{@@chapter} and @code{@@section} differ
only in that @code{@@section} underlines with @samp{=}. For example,@refill
@example
This is a section
=================
@end example
@section @@unnumberedsec, @@appendixsec
@findex unnumberedsec
@findex appendixsec
Use these constructs for sections within chapters made by
@code{@@unnumbered} or @code{@@appendix}. (@xref{Section}.)@refill
@node Subsection, Subsubsection, Section, Structuring
@comment node-name, next, previous, up
@section @@subsection
@findex subsection
Subsections are to sections as sections are to chapters. (@xref{Section}.)
They are underlined with @samp{-}. For example,@refill
@example
This is a subsection
--------------------
@end example
@section @@unnumberedsubsec, @@appendixsubsec
@findex unnumberedsubsec
@findex appendixsubsec
Use these constructs for subsections within sections within chapters made
by @code{@@unnumberedsec} or @code{@@appendixsec}. (@xref{Subsection}.)@refill
@node Subsubsection, Node, Subsection, Structuring
@comment node-name, next, previous, up
@section @@subsubsection And Other Subsection Commands
@findex unnumberedsubsubsec
@findex appendixsubsubsec
@findex subsubsection
Subsubsections are to subsections as subsections are to sections.
(@xref{Subsection}.) They are underlined with periods. The equivalent
commands for @code{@@unnumberedsubsec} and @code{@@appendixsubsec} are
@code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec}. For
example,@refill
@example
This is a subsubsection
.......................
@end example
@node Node, Menu, Subsubsection, Structuring
@comment node-name, next, previous, up
@section @@node
@code{@@node} defines the beginning of a new node in the Info output file
(@inforef{Top, info, info}.). It is followed by four arguments, separated
by commas, that make up the rest of the line. Since it is often hard to
remember the order in which are arguments are listed, @code{texinfo-mode}
provides the @kbd{C-c C-c n} command (@code{texinfo-insert-@@node}) which
automatically inserts a comment line listing the arguments. For
example,@refill
@example
@@node Texinfo Mode, Beginning a File, Overview, Top
@@comment node-name, next, previous, up
@end example
@noindent
defines a node named @samp{Texinfo Mode}, whose `Next' pointer is to node
@samp{Beginning a File}, whose `Previous' pointer is to node
@samp{Overview}, and whose `Up' pointer is to node @samp{Top}. What this
means is that Texinfo changes @w{@code{@@node @var{args}}} into the special
text string necessary to separate Info nodes and to identify the node that
is starting and say what nodes it points to.@refill
The pointer names should be the names of nodes defined elsewhere. For this
example, nodes named @samp{Beginning a File}, @samp{Overview} and
@samp{Top} should be defined elsewhere in the file with other @code{@@node}
commands. It does not matter whether they are before or after the node
that refers to them.@refill
Normally, a node's `Up' pointer should point at the node whose menu
mentions that node. The node's `Next' pointer should point at the node
that follows that node and its `Previous' pointer should point at the node
that precedes it in that menu.@refill
In @TeX{}, @code{@@node} is nearly ignored. It generates no text. Its
only function is to identify the name to use for cross-references to the
chapter or section which follows the @code{@@node} command and which which
makes up the body of the node. (Cross references are made with
@code{@@xref}. @xref{Cross References}.)@refill
@code{@@node} should be followed immediately by a chapter-structuring
command such as @code{@@chapter}, @code{@@section}, @code{@@subsection} or
@code{@@subsubsection}.@refill
The easiest way to write a node is to use the Texinfo mode keyboard command
@kbd{C-c C-c n} to insert @samp{@@node} and a comment line listing the
names of each of the pointers in their proper order. This way you won't
lose track of which arguments are for which pointers. The template is
especially useful if you are not familiar with Texinfo. It is important to
pick a suitable node name. Generally, these begin with an uppercase letter
as if the node name were a heading for a chapter or section. Do not use
any of the Texinfo @@-commands in the name; these commands confuse Info.
The node name should be informative. Unfortunately, long names will not
fit onto the line, which can be awkward. Sometimes it is better to use
long but informative names rather than short ones.
Some people insert the names of the `Next', `Previous' and `Up' pointers at
the same time they insert the node's own name. This is because it is
easier to keep track of the node structure as you create a document than it
is to sort it out after you have dozens of nodes. Others wait to insert
the `Next', `Previous' and `Up' pointers until they have a nearly final
version of the document. This is because they expect to change the
organization of the document while they write it and insert or delete
sections and move them around. The command @code{texinfo-show-structure}
can be used to find the `Next', `Previous' and `Up' pointers of a node.
(See @xref{Using texinfo-show-structure}.)
However you do it, it is best to name the node whenever you write the
section so you can easily make cross references to the section. A large
number of cross references are an especially important feature of a good
Info file.
After you have inserted the node-line, you should immediately write an
@@-command for the chapter or section and insert its name. Next, (and this
is important!), put in several index entries. Usually, you will find at
least two and often as many as four or five ways of referring to the node
in the index. Use them all. This will make it much easier for people to
find the node.@refill
The top node of the file, named @samp{Top}, should have as its parent the
name of a node in another file, where there is a menu that leads to this
file. Specify the file name in parentheses. If the file is to be
installed directly in the Info directory file, use @samp{(dir)} as the
parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
in the file @file{dir}, which is the main menu of Info. For example,@refill
@example
@@node Top, Overview, (dir), (dir)
@@comment node-name, next, previous, up
@end example
For more information about installing an Info file in the @file{info}
directory, @pxref{Installing an Info File}
@node Menu, , Node, Structuring
@comment node-name, next, previous, up
@section @@menu
@cindex Menus
@findex menu
Info file nodes can contain @dfn{menus} which point to other nodes. You
must type the menus in by hand, and surround them with lines containing
@code{@@menu} and @code{@@end menu}. In Info, the @code{@@menu} line
changes into @samp{* Menu:}, which indicates the beginning of a menu to the
Info program. Otherwise, the contents are unchanged by Texinfo, except for
the processing of any other @@-commands within. The entire menu construct
has no effect in the printed manual and will not appear there.@refill
By convention, a menu is put at the end of a node. This way, it is easy
for someone using Info to find the menu, using the @kbd{M->}
(@code{end-of-buffer}) command.
In a menu, every line that begins with a @samp{*} lists a single topic. A
line that does not start with a @samp{*} will also appear in the menu and
can be used as a comment.
A menu item has three parts:
@enumerate
@item
The menu item name.
@item
The name of the node.
@item
A description of the item.
@end enumerate
@noindent
Only the first part is required. This part is the name of the topic---the
name of the menu item that the user must give to the @kbd{m} command to
select this topic when using Info. The first part comes right after the
asterisk and a space, and is followed by a colon, spaces and tabs, and then
the name of the node which discusses that topic. The name of the node is
terminated by a tab, comma, newline or period. If the node name and topic
name are the same, rather than give the name twice, put two colons after
the name instead. For example, @samp{* Name::}. (You should do this
whenever possible, since it reduces visual clutter in the menu).
If the second part is present, it may be terminated with a tab, comma, or
newline; or with a period.
For example,@refill
@group
@example
@@menu
A Section on Foo and Switches
* Foo:: The node named Foo tells you how to go fooing.
* Sw: Switches. Type @@code@{m Sw@} to see node @@code@{Switches@}
which describes the switches available here.
@@end menu
@end example
@end group
@noindent
produces
@group
@example
* menu:
A Section on Foo and Switches
* Foo:: The node named foo tells you how to go fooing.
* Sw: Switches. Type `m Sw' to see node `Switches'
which describes the switches available here.
@end example
@end group
In this example, the menu has two items. @samp{Foo} is both a menu item
name and the name of the node referred to by that item. @samp{Sw} is the
other menu item name, and it refers to the node named @samp{Switches}.
Since no file name is specified with @samp{Foo} or @samp{Switches}, they
must be the names of other nodes in the same Info file.
Nodes in other Info files can be referred to by putting the file name in
parentheses at the beginning of the node name. For example,
@example
@@menu
* Outlining: (emacs) Outline Mode. The major mode for editing outlines.
* Rebinding: (emacs) Rebinding. How to redefine the meaning of a key.
@@end menu
@end example
@noindent
When this is done, the item has to have at least two parts: the first part
is the menu item name and the second part is the name of the node.
@node Quotations and Examples, Lists and Tables, Structuring, Top
@comment node-name, next, previous, up
@chapter Making Quotations and Examples
@cindex Quotations
@cindex Examples
Quotations and examples are blocks of text, consisting of one or more whole
paragraphs that are set off from the bulk of the text and treated
differently. They are usually indented.
In Texinfo, an insertion is always begun by writing an @@-command on a line
by itself, and ended by writing an @code{@@end} command that is also on a
line by itself. For instance, an @dfn{example} is a kind of insertion that
is begun with @code{@@example} and ended with @code{@@end example}.@refill
@findex end
There are three commands for quotations and examples:
@table @code
@item @@quotation
Used to indicated text that is quoted.@refill
@item @@example
Used to illustrate code, commands and the like in a fixed width font
without filling.@refill
@item @@display
Used for illustrative text.
@end table
@menu
* Quotation::
* Example::
* Display::
@end menu
@node Quotation, Example, , Quotations and Examples
@comment node-name, next, previous, up
@section @@quotation
@cindex Quotations
@findex quotation
@code{@@quotation} is used to indicate text that is excerpted from another
(real or hypothetical) printed work. The inside of a quotation is
processed normally except that
@enumerate
@item
The margins are narrower.
@item
Paragraphs are not indented.
@item
Interline spacing and interparagraph spacing are reduced.
@end enumerate
Thus, the input
@example
@@quotation
This is
a foo.
@@end quotation
@end example
@noindent
produces in the printed manual
@quotation
@quotation
This is a foo.
@end quotation
@end quotation
@noindent
and in the Info file
@quotation
@example
This is
a foo.
@end example
@end quotation
@node Example, Display, Quotation, Quotations and Examples
@comment node-name, next, previous, up
@section @@example
@cindex Examples
@findex example
@code{@@example} is used to indicate an example that is not part of the
running text. In the printed manual, this is done by switching to
a fixed width font, turning off filling, and making extra spaces
and blank lines significant. In the Info file, an analogous result
is obtained by indenting each line with five extra spaces.
@code{@@example} should appear on a line by itself; this line will
disappear from the output. Mark the end of the example with a line
containing @code{@@end example}, which will likewise disappear. For
example:@refill
@example
@@example
mv foo bar
@@end example
@end example
@noindent
produces
@example
mv foo bar
@end example
Since the lines containing @code{@@example} and @code{@@end example} will
disappear, you will want to put a blank line before the @code{@@example} and
another blank line after the @code{@@end example}. (Remember that blank
lines between the beginning @code{@@example} and the ending @code{@@end
example} will appear in the output.)@refill
Don't use tabs in lines of an example! @TeX{} has trouble with tabs: it
treats them like single spaces, and that is not what they look like.
@node Display, , Example, Quotations and Examples
@comment node-name, next, previous, up
@section @@display
@cindex Display
@findex display
@code{@@display} is just like @code{@@example} except that, in the
printed manual, @code{@@display} does not select the fixed-width font.
In fact, it does not specify the font at all, so that the text appears
in the same font it would have appeared in without the @code{@@display}.@refill
@node Lists and Tables, Cross References, Quotations and Examples, Top
@comment node-name, next, previous, up
@chapter Making Lists and Tables
@cindex Making lists and tables
@cindex Lists and tables, making them
@cindex Tables and lists, making them
Texinfo has several ways of making lists and two-column tables. Lists can
be bulleted or numbered while two-column tables can highlight the items in
the first column.
For example, this is an enumerated list:
@enumerate
@item
This is a numbered item.
@item
This is the second item in this list.
@item
This is the third item on this list.
@end enumerate
Texinfo will automatically indent the text in lists or tables and number an
enumerated list. This last feature is useful if you are reordering the
list, since you do not have to renumber it yourself.
Lists or tables are always begun by an @@-command on a line by itself and
ended with an @code{@@end} command on a line by itself. For example, an
enumerated list begins with the command @code{@@enumerate} and ends with
the command @code{@@end enumerate}; and an itemized list begins with the
command @code{@@itemize} and ends with the command @code{@@end
itemize}.@refill
@findex end
The elements of a list are begun with the @code{@@item} command.
Here is an itemized list of the different kinds of table and lists:
@itemize @bullet
@item
Itemized lists with or without bullets.
@item
Numbered lists.
@item
two-column tables with highlighting.
@end itemize
@menu
* Itemize::
* Enumerate::
* Table::
@end menu
@node Itemize, Enumerate, , Lists and Tables
@comment node-name, next, previous, up
@section @@itemize
@cindex Itemize
@findex itemize
@code{@@itemize} is used to produce sequences of indented paragraphs, with
a mark inside the left margin at the beginning of each paragraph. The rest
of the line that starts with @code{@@itemize} should contain the character
or Texinfo commands to generate such a mark. Usually, it is the @@-command
@code{@@bullet}. Whatever mark you choose, ultimately, it should result in
a single character in the Texinfo file, or the indentation will come out
wrong. When you write the command, omit the @samp{@{@}} after the command
if you use just one command and nothing else.
The text of the indented paragraphs themselves come after the @code{@@itemize},
up to another line that says @code{@@end itemize}.
Before each paragraph for which a mark in the margin is desired, place a
line that says just @code{@@item}. Don't put any other text on this line.
@findex item
Info indents the lines in an itemized list by five columns, but it does not
fill them. This can produce lines in the Info file that are too wide. You
can either write shorter lines in the Texinfo file by setting the fill
column to five columns less than it is normally, or else you can tell Info
to refill the paragraphs by adding the @@-command @code{@@refill} to the
end of the paragraph. (@xref{Refill}, for more information about the use of
the @code{@@refill} command.)
Usually, you should put a blank line before an @code{@@item}. This puts a
blank like in the Info file. Except when the entries are very brief, a
blank line looks better.
Here is an example of the use of @code{@@itemize}, followed by the output
it produces. Note that @code{@@bullet} produces a @samp{*} in Texinfo and
a round dot in @TeX{}.
@group
@example
@@itemize @@bullet
@@item
Some text for foo.
@@item
Some text
for bar.
@@end itemize
@end example
@end group
@noindent
produces
@group
@quotation
@itemize @bullet
@item
Some text for foo.
@item
Some text
for bar.
@end itemize
@end quotation
@end group
@node Enumerate, Table, Itemize, Lists and Tables
@comment node-name, next, previous, up
@section @@enumerate
@cindex Enumerate
@findex enumerate
@code{@@enumerate} is like @code{@@itemize} except that the marks in the
left margin contain successive integers starting with 1. (@xref{Itemize}.)
Do not put any argument on the same line as @code{@@enumerate}.@refill
@group
@example
@@enumerate
@@item
Some text for foo.
@@item
Some text
for bar.
@@end enumerate
@end example
@end group
@noindent
produces
@quotation
@enumerate
@item
Some text for foo.
@item
Some text
for bar.
@end enumerate
@end quotation
If you want, you can put a blank line between the entries in the list.
This often makes it easier to read the Info file. For example,
@group
@example
@@enumerate
@@item
This is the first item.
@@item
This is the second item.
@@end enumerate
@end example
@end group
@ifinfo
Info indents the lines of the enumerated list by five columns, but it does
not fill them. As a result, the lines in the Info file may be too wide.
To prevent this, you can either write shorter lines in the Texinfo file
file by setting the fill column to five columns less than it is normally,
or else you can tell Info to refill the paragraphs by adding the @@-command
@code{@@refill} to the end of the paragraph. (@xref{Refill}, for more
information about the use of the @code{@@refill} command.)
@end ifinfo
@iftex
Info indents the lines of the enumerated list by five columns, but it does
not fill them, just as it does with an itemized list. You may want to use
shorter lines for text within an enumerated list or use the @code{@@refill}
command at the end of the paragraph. (@xref{Refill}, for more information
about the use of the @code{@@refill} command.)
@end iftex
@node Table, , Enumerate, Lists and Tables
@comment node-name, next, previous, up
@section @@table
@cindex Tables, making two-column
@findex table
@code{@@table} is similar to @code{@@itemize}, but allows you to specify a
name or heading line for each item. (@xref{Itemize}.) The command is used
to produce two-column tables, and is especially useful for glossaries and
explanatory exhibits.@refill
You must follow each use of @code{@@item} inside of @code{@@table} with
text to serve as the heading line for that item. This text is put on the
same line as the @code{@@item} command. Each heading line is put into the
first column of the table and the supporting text, which you put on the line
following the line beginning with @code{@@item}, goes into the second
column.@refill
@findex item
Also, @code{@@table} itself must be followed by an argument that is a
Texinfo command such as @code{@@code}, @code{@@var}, @code{@@kbd} or
@code{@@asis}. Although these commands are usually followed by arguments
in braces, in this case you use the command name without an argument.
(@code{@@item} supplies the argument.) This command will be applied to
the text that goes into the first column of each item and determines how it
will be highlighted. For example, @code{@@samp} will cause the text in the
first column to be highlighted as if it were acted on by an @code{@@samp}
command.@refill
@code{@@asis} is a command that does nothing; in that case, each item will
come out without highlighting, unless that particular piece of text
contains @@-commands for highlighting.@refill
(Various other command names might work with @code{@@table}. However, only
commands that normally take arguments in braces may be used.)@refill
@ifinfo
Usually, you should put a blank line before an @code{@@item}. This puts a
blank like in the Info file. Except when the entries are very brief, a
blank line looks better.
@end ifinfo
The following table, for example, highlights the text in the first column
as if each item were acted on by an @code{@@samp} command:@refill
@example
@@table @@samp
@@item foo
This is the text for
@@samp@{foo@}.
@@item bar
Text for @@samp@{bar@}.
@@end table
@end example
@noindent
produces
@quotation
@table @samp
@item foo
This is the text for
@samp{foo}.
@item bar
Text for @samp{bar}.
@end table
@end quotation
Info indents the lines of text in the second column, but does not fill
them. As a result, the lines in the Info file may be too wide. To prevent
this, cause Info to refill the paragraphs after processing by adding the
@@-command @code{@@refill} to the end of the paragraph. (@xref{Refill}, for
more information about the use of the @code{@@refill} command.)
If you want to list two or more named items with a single block of text,
use the @code{@@itemx} command.
@menu
* Itemx::
@end menu
@node Itemx, , Table, Table
@comment node-name, next, previous, up
@subsection @@itemx
@cindex Itemx
@findex itemx
@code{@@itemx} is used inside a @code{@@table} when you have two or more
named items for the same block of text. Use @code{@@itemx} for all but the
first of the items. It works exactly like @code{@@item} except that it
does not generate extra vertical space above the item text.
For example,@refill
@example
@@table @@code
@@item upcase
@@itemx downcase
These two functions accept a character or a string as argument,
and return the corresponding upper case (lower case) character
or string. @@refill
@@end table
@end example
@noindent
produces
@quotation
@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as argument,
and return the corresponding upper case (lower case) character
or string. @refill
@end table
@end quotation
A more complicated example of the use of @code{@@itemx} comes from the
chapter on structuring commands. Here is how the list showing how
the chapter structuring commands fall into four groups was constructed.
(@xref{Structuring, , Chapter Structuring Commands}.)
@group
@example
@@table @@code
@@item @@@@chapter
@@itemx @@@@unnumbered
@@itemx @@@@appendix
For chapters and chapter-like parts of a document.
@@item @@@@section
@@itemx @@@@unnumberedsec
@@itemx @@@@appendixsec
For sections and section-like parts of a document.
@@item @@@@subsection
@@itemx @@@@unnumberedsubsec
@@itemx @@@@appendixsubsec
For subsections and subsection-like parts of a document.
@@item @@@@subsubsection
@@itemx @@@@unnumberedsubsubsec
@@itemx @@@@appendixsubsubsec
For subsubsections and similar parts of a document.
@@end table
@end example
@end group
@noindent
and this is what the resulting table looks like:
@table @code
@item @@chapter
@itemx @@unnumbered
@itemx @@appendix
For chapters and chapter-like parts of a document.
@item @@section
@itemx @@unnumberedsec
@itemx @@appendixsec
For sections and section-like parts of a document.
@item @@subsection
@itemx @@unnumberedsubsec
@itemx @@appendixsubsec
For subsections and subsection-like parts of a document.
@item @@subsubsection
@itemx @@unnumberedsubsubsec
@itemx @@appendixsubsubsec
For subsubsections and similar parts of a document.
@end table
Also, either column of a table can be empty.
@node Cross References, Formatting Paragraphs, Lists and Tables, Top
@comment node-name, next, previous, up
@chapter Making Cross References
@cindex Making cross references
@cindex Cross references
@cindex References
Cross references are used to refer the reader to other parts of the same or
different Texinfo files. In Texinfo, @dfn{nodes} are the points to which
cross-references can refer.
In general, a document should be designed so that it can be read
sequentially. People soon tire of flipping back and forth to find
information that should be presented to them as they need it. However,
there will be information (often too detailed for whatever the current
context may be) that is related to whatever is presented and to which
reference should be made. More important, in an on-line help system or in
a reference manual, readers do @emph{not} read everything in sequence from
beginning to end. Instead, they look up what they need. For this reason,
such creations should contain many cross references to help the reader find
other information that he or she may not have read.
Although nodes are not a fundamental concept in a printed manual, they
still serve to define a cross-reference point and the variants of
@code{@@xref} still serve to make references. Thus, if you are writing a
manual that will only be printed, and will not be used on-line, you
continue to use the @code{@@node} command for when you make cross
references.
There are several kinds of cross reference command.
@table @code
@item @@xref
Used to start a sentence in the printed manual saying, `See @dots{}' @*
or an entry in the Info file saying @samp{*note @dots{}}.
@item @@pxref
Used to make a reference that starts with a lowercase @samp{see} @*
and is usually contained within parentheses.@refill
@item @@inforef
Used to make a reference to an Info file for which there is no printed
manual.@refill
@end table
@menu
* Xref::
* Pxref::
* Inforef::
@end menu
@node Xref, Pxref, Cross References, Cross References
@comment node-name, next, previous, up
@section @@xref
@cindex Xref for cross references
@findex xref
@cindex Cross references using xref
@code{@@xref} generates a cross-reference. In Texinfo, it turns into
an Info cross-reference which the Info @samp{f} command can use
to go directly to another node. In @TeX{}, it turns into a sentence
of the form
@example
See section @var{section} [@var{topic}], page @var{page}
@end example
@noindent
but does not generate a period to end it.
@code{@@xref} must refer to an Info node created by @code{@@node}, by the
node's name.
@code{@@xref} is followed by an argument inside braces; but actually the
text inside the braces is treated as several arguments, separated by
commas. Whitespace after these commas is ignored. A period or comma
@strong{must} follow the closing brace of an @code{@@xref}. It is required
to terminate the cross reference. This period or comma will appear in the
output, both in the Info file and in the printed manual.
The simplest form of @code{@@xref} takes one argument, the name of another
node in the same Info file. Here we show the input text, followed by a
blank line and then the output text for Info files and the output text for
printed manuals.
@example
@@xref@{node-name@}, for more info.
*note node-name::, for more info.
@end example
@quotation
See section @var{nnn} [node-name], page @var{ppp}, for more info.
@end quotation
With two arguments, the second one is used as the name of the Info
cross-reference, while the first argument is still the node that the
cross-reference points to:
@example
@@xref@{node-name, name-for-note@}, for more info.
*note name-for-note: node-name, for more info.
@end example
@quotation
See section @var{nnn} [node-name], page @var{ppp}, for more info.
@end quotation
A third argument replaces the node name when it actually appears in the
@TeX{} output. It should state the topic discussed by the section being
referenced. Often, you will want to use initial uppercase letters so it
will be easier to read when the reference is printed. Use a third argument
when the node name is unsuitable because of syntax, grammar or diction.
@example
@@xref@{node-name, name-for-note, Topic Description@}, for more info.
*note name-for-note: node-name, for more info.
@end example
@quotation
See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
@end quotation
If a third argument is given and the second one is empty,
then the third argument serves both purposes:
@example
@@xref@{node-name, , Topic Description@}, for more info.
*note Topic Description: node-name, for more info.
@end example
@quotation
See section @var{nnn} [Topic Description], page @var{ppp}, for more info.
@end quotation
A fourth argument specifies the name of the Info file in which the
referenced node is located, assuming it is not the one in which the
reference appears. @code{@@xref} with only four arguments is used when the
reference is not within one Info file, but is within a single printed
manual---when multiple Texinfo files are incorporated into the same @TeX{}
run but make separate Info files. (This is seldom the case and usually you
will use five arguments if you are making a reference that is outside the
current Info file.)
@example
@@xref@{node-name, name-for-note, Topic, info-file-name@},
for more info.
*note name-for-note: (info-file-name) node-name, for more info.
@end example
@quotation
See section @var{nnn} [Topic], page @var{ppp}, for more info.
@end quotation
A fifth argument is used when you are making a reference to another Info
file which is also part of another printed manual. Write the title of the
manual in this slot. Since a different manual is made during a different
@TeX{} run, the printed reference will not have a page number.
@noindent
Whenever you refer to another manual, use this version of @code{@@xref}
with five arguments.
@example
@@xref@{node-name, name-for-note, Topic, info-file-name, A Printed Manual@},
for more info.
*note name-for-note: (info-file-name) node-name, for more info.
@end example
@quotation
See section Topic of @i{A Printed Manual}, for more info.
@end quotation
@noindent
The name of the printed manual will be typeset in italics.
Often, you will leave out the second argument when you use the long version
of @code{@@xref}. In this case, the third argument, the topic description,
will replace the node name:
@example
@@xref@{node-name, , Topic Description, info-file-name, A Printed Manual@},
for more info.
*note Topic Description: (info-file-name) node-name, for more info.
@end example
@quotation
See section Topic Description of @i{A Printed Manual}, for more info.
@end quotation
@node Pxref, Inforef, Xref, Cross References
@comment node-name, next, previous, up
@section @@pxref
@cindex Cross references using pxref
@cindex Pxref for cross references
@findex pxref
@code{@@pxref} is nearly the same as @code{@@xref}; it differs in only
two ways:
@enumerate
@item
The output starts with lower case `see' rather than `See'.@refill
@item
A period is generated automatically in the Info file output to end the Info
cross-reference, but no period is generated for the printed manual.@refill
@end enumerate
The purpose of @code{@@pxref} is to be used inside parentheses as part of
another sentence. In the printed manual, no period is needed after the
cross reference text itself (within the parentheses), but a period is
needed after the cross reference text in the Info file because only thus
can Info recognize the end of the cross-reference. @code{@@pxref} spares
you the need to use complicated methods to put a period into one form of
the output and not the other.
@code{@@pxref} can be used with up to five arguments just like
@code{@@xref}. (@xref{Xref}.)@refill
@node Inforef, , Pxref, Cross References
@comment node-name, next, previous, up
@section @@inforef
@cindex Inforef for cross references
@cindex Cross references using inforef
@findex inforef
@code{@@inforef} is used for cross-references to Info files for which there
are no printed manuals. Even in a printed manual, @code{@@inforef}
generates a reference directing the user to look in an Info file.
@code{@@inforef} takes exactly three arguments. The syntax is
@code{@@inforef@{@var{node}, @var{name}, @var{file}@}}.
@example
@@inforef@{node-name, name-for-note, info-file-name@}, for more information.
*note name-for-note: (info-file-name) node-name, for more information.
@end example
@quotation
See Info file @file{info-file-name}, node `node-name', for more information.
@end quotation
@node Formatting Paragraphs, Marking Text, Cross References, Top
@comment node-name, next, previous, up
@chapter Formatting Paragraphs
@cindex Formatting paragraphs
@cindex Paragraphs, formatting
Usually, a Texinfo file will be processed both by @TeX{} and by the
@kbd{M-x texinfo-format-buffer} command. Consequently, you must make sure
that text will come out looking right both in the printed manual and in the
on-line help.@refill
For example, unless told otherwise, @kbd{M-x texinfo-format-buffer} will
not refill a paragraph after processing it although @TeX{} will. This
means that a paragraph with numerous or large @@-commands may not look
properly filled after processing by Info. The @@-commands are removed from
the text but the lines are not refilled so some are much shorter than they
were. To cause the @kbd{M-x texinfo-format-buffer} command to refill such
a paragraph, put @code{@@refill} at the end of the paragraph.@refill
@TeX{} may also format a document improperly. For example, page breaks may
occur in the ``wrong place''; to control this, text can be held together by a
group command that keeps the text within the group from being split across
two pages.
@iftex
The first section that follows is about refilling and preventing
indentation; the second section is about line and paragraph breaks,
creating blank lines, and grouping text.
@end iftex
@menu
* Refilling & Noindent:: Refilling paragraphs & preventing indentation
* Breaks Blank-Lines Groups:: Line and paragraph breaks, blank lines, grouping
@end menu
@node Refilling & Noindent, Breaks Blank-Lines Groups, Formatting Paragraphs, Formatting Paragraphs
@comment node-name, next, previous, up
@section Refilling Paragraphs and Preventing Indentation
@cindex Refilling paragraphs automatically
@cindex Preventing indentation in the printed text
The @code{@@refill} and @code{@@noindent} commands are used just after or
just before paragraphs which, after processing by either Info or @TeX{},
might look bad. The @code{@@refill} command refills a paragraph in the
Info file after all the other processing has been done. In the printed
manual, the @code{@@noindent} command prevents a piece of text that is a
continuation of the preceding paragraph from being indented as if it were a
new paragraph.@refill
@menu
* Refill:: Refilling an info paragraph after other processing.
* Noindent:: Preventing paragraph indentation in continuation text.
@end menu
@node Refill, Noindent, Refilling & Noindent, Refilling & Noindent
@comment node-name, next, previous, up
@subsection @@refill
@findex refill
If a paragraph contains sizable @@-constructs, it may look badly filled
after @code{texinfo-format-buffer} is through with it.
Put @code{@@refill} at the end of the paragraph to tell
@code{texinfo-format-buffer} to refill the paragraph after finishing all
other processing on it. @code{@@refill} has no effect on @TeX{}, which
always fills everything that ought to be filled. For example,@refill
@example
To use @@code@{foo@}, pass @@samp@{xx%$@} and @@var@{flag@} and type @@kbd@{x@}
after running @@code@{make-foo@}.@@refill
@end example
@noindent
produces (in the Info file)
@example
To use `foo', pass `xx%$' and FLAG and type `x' after running `make-foo'.
@end example
@noindent
whereas without the @code{@@refill} it would produce
@example
To use `foo', pass `xx%$' and FLAG and type `x'
after running `make-foo'.
@end example
@noindent
with the line broken at the same place as in the Texinfo input file.
Do not put a space before @code{@@refill}; otherwise the command might be
put at the beginning of the line when you refill the paragraph in the
Texinfo file with @kbd{M-q} (@code{fill-paragraph}). If this were to
happen, the @code{@@refill} command might fail to work
@node Noindent, , Refill, Refilling & Noindent
@comment node-name, next, previous, up
@subsection @@noindent
@findex noindent
If you have text following an @code{@@example} or other similar ``special
paragraph'' that reads as a continuation of the text before the
@code{@@example}, it is good to prevent this text from being indented as a
new paragraph. To accomplish this, put @code{@@noindent} on a line by
itself before the start of the text that should not be indented. For
example,@refill
@example
@@example
This is an example
@@end example
@@noindent
This line will not be indented.
@end example
@noindent
produces
@example
This is an example
@end example
@noindent
This line will not be indented.
To adjust the number of blank lines properly in the Info file output,
remember that the line containing @code{@@noindent} does not generate a
blank line, and neither does the @code{@@end example} line.
In the Texinfo source file for this documentation, each of the lines that
says `produces' is preceded by a line containing @code{@@noindent}.
@node Breaks Blank-Lines Groups, , Refilling & Noindent, Formatting Paragraphs
@comment node-name, next, previous, up
@section Breaks, Blank Lines and Groups
Texinfo has several commands for making blank lines, for forcing paragraph
and page breaks in the printed manual and for preventing text from running
from one page to the next.
@table @code
@item @@*
Force a line break in the printed manual. This
command has no effect on the Info file.@refill
@item @@sp
Generate blank lines in both the printed manual and in the Info file.@refill
@item @@br
Force a paragraph break in the printed manual. This command has no effect
on the Info file.@refill
@item @@w
Prevent text from being split across two lines in the printed manual. This
command has no effect on the Info file.@refill
@item @@page
Start a new page in the printed manual. This
command has no effect on the Info file.@refill
@item @@group
Hold text together that must appear on one printed page. This
command has no effect on the Info file.@refill
@item @@need
Start a new printed page if required space not on this one. This
command has no effect on the Info file.@refill
@end table
@menu
* Line Breaks:: Force a line break in the printed manual.
* Sp:: Generate blank lines.
* Br:: Force a paragraph break in the printed manual.
* W:: Prevent a paragraph break in the printed manual.
* Page:: Start a new page in the printed manual.
* Group:: Hold text together that must appear on one printed page.
* Need:: Start a new printed page if required space not on this one.
@end menu
@node Line Breaks, Sp, Breaks Blank-Lines Groups, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@*
@findex asterisk
@findex *
@cindex Line breaks
@cindex Breaks in a line
@code{@@*} forces a line break in the printed manual. It has no effect on
the Info file output, where line breaks follow those in the source file.
If you want a line break at a certain spot in both forms of output, break
the line there in the source file and put @code{@@*} at the end of the
line.
@node Sp, Br, Line Breaks, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@sp
@findex sp (line spacing)
@cindex Spaces from line to line
@cindex Line spacing
A line containing @code{@@sp @var{n}} generates @var{n} blank lines of
space in either the printed manual or the Info file. For example,
@example
@@sp 2
@end example
@noindent
generates two blank lines.
@node Br, W, Sp, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@br
@findex br (paragraph breaks)
@cindex Paragraph breaks
@cindex Breaks in a paragraph
In a printed manual, a line containing @code{@@br} forces a paragraph
break; in the Info file output, it does nothing (not even a blank line
results from it).
@node W, Page, Br, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@w
@findex w (preventing a line break)
@cindex Line breaks, preventing
In a printed manual, @code{@@w@{@var{text}@}} outputs @var{text} and prohibits
line breaks within @var{text}. @code{@@w} has no effect on the Info file
output; it is the same as would result from just @var{text}.
@node Page, Group, W, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@page
@cindex Page breaks
@findex page
A line containing @code{@@page} starts a new page in a printed manual. The
line has no effect on Info files since they are not paginated.
@node Group, Need, Page, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@group
@cindex Group
@cindex Holding text together vertically
@cindex Vertically holding text together
@findex group
A line containing @code{@@group} begins an unsplittable vertical group,
which must appear entirely on one page. The group is terminated by a line
containing @code{@@end group}. These two lines produce no output of their
own, and in the Info file output they have no effect at all.
If you forget to end a group, you may get strange and unfathomable error
messages when you run @TeX{}. This is because @TeX{} keeps trying to put
the rest of the Texinfo file into the group and error messages do not start
to get generated until @TeX{} has gone a long way. It's a good rule of
thumb to look for a missing @code{@@end group} if you get incomprehensible
error messages in @TeX{}.
@node Need, , Group, Breaks Blank-Lines Groups
@comment node-name, next, previous, up
@subsection @@need
@cindex Need
@findex need
A line containing @code{@@need @var{n}} starts a new page in a printed
manual if fewer than @var{n} mils (thousandths of an inch) remain on the
current page. The line has no effect on Info files since they are not
paginated.@refill
@node Marking Text, Conditionals , Formatting Paragraphs, Top
@comment node-name, next, previous, up
@chapter Marking Text Within a Paragraph
@cindex Marking text within a paragraph
In Texinfo, text within a paragraph can be marked in a variety of ways.
The most important way is to specify whether a word or phrase is a
definition, a metasyntactic variable, a literal example of a program or
what not.
In addition, there are special commands for inserting single characters
that have special meaning in Texinfo, such as braces, and for inserting
symbols with special handling, such as dots and bullets. Finally, there
are ways to emphasize words.
@menu
* Specifying:: Specifying commands, files and so on.
* Braces Atsigns Periods:: Inserting braces, @samp{@@} and periods.
* Dots Bullets Tex:: Inserting dots, bullets and the @TeX{} logo
* Emphasis:: Emphasizing text.
@end menu
@node Specifying, Braces Atsigns Periods, , Marking Text
@comment node-name, next, previous, up
@section Specifying Definitions, Files, Commands etc.
@cindex Highlighting
@cindex Specifying commands, files and the like
@cindex Definitions, specifying them within text
@cindex Commands, specifying them within text
@cindex Files, specifying them within text
Texinfo has a variety of commands for specifying just what kind of object a
piece of text refers to. Metasyntactic variables, for example, are marked
by one @@-command and code by another. Texinfo uses this information to
determine how to highlight the text. Since the pieces of text are labelled
by commands that tell what kind of object they are, it is easy to change
the way Texinfo formats and typesets such text. For example, code is
usually illustrated in a typewriter font, but it would be easy to change
the way Texinfo highlights code to use another font. This change would not
effect how metasyntatic variables are highlighted. If straight typesetting
commands were used in the body of the file, you would have to check every
single occurrence to make sure that you were changing code and not
something else that should not be changed.
In addition, the commands can be used to generate useful information from
the file, such as lists of functions or file names. It is possible, for
example, to write code in Emacs Lisp (or a keyboard macro) to insert an
index entry after every paragraph that contains the text labelled by a
specified command. You could do this to construct an index of functions if
you had not already made the entries.
The commands serve a variety of purposes:
@table @code
@item @@code
Indicates text that is a literal example of a piece of a program.@refill
@item @@samp
Indicates text that is a literal example of a sequence of characters.@refill
@item @@file
Indicates the name of a file.@refill
@item @@kbd
Indicates the names of keys on the keyboard or characters you type.@refill
@item @@key
Used for the conventional name for a key on a keyboard.@refill
@item @@ctrl
Indicates an ASCII control character.
@item @@var
Indicates a metasyntactic variable.
@item @@dfn
Indicates the introductory or defining use of a term.
@item @@cite
Indicates the name of a book.
@end table
@menu
* Code:: A literal example of a piece of a program.
* Samp:: A literal example of a sequence of characters.
* File:: The name of a file.
* Kbd:: The names of keys or else characters you type.
* Key:: The conventional name for a key on a keyboard.
* Ctrl:: Indicates the ASCII control character.
* Var:: A variable.
* Dfn:: The introductory or defining use of a term.
* Cite:: The name of a book.
@end menu
@node Code, Samp, , Specifying
@comment node-name, next, previous, up
@subsection @@code
@findex code
@code{@@code} is used to indicate text that is a piece of a program which
consists of entire syntactic tokens. The text follows, enclosed in braces.
For example, @code{@@code} is used for an expression in a program, the name
of a variable or function used in a program, or a keyword. @code{@@code}
is not used for a piece of a token, such as when speaking about the
characters used in a token; for example, when you are explaining what
letters or printable symbols can be used in the names of functions. It is
also not used for input to programs unless the input is written in a
language that is like a programming language. For example, it is not used
for the single character commands of GNU Emacs although it is used for the
names of Emacs Lisp functions that the keyboard commands invoke.
You should also @code{@@code} for command names in command languages that
resemble programming languages, such as Texinfo or the shell. Note,
however, that @code{@@code} is not used for options such as @samp{-c} when
such options stand alone. There is some argument as to whether an entire
shell command incorporating an option should be written using @code{@@code}
or @code{@@samp}.@refill
It is an error to alter the case of a word inside an @code{@@code}
command. This is a particularly insidious error if the language being
documented is case sensitive. If the command is @code{printf}, then
@code{Printf} is a misspelling. If you do not like having such a command
with lower case at the beginning of a sentence, you may wish to rearrange
the sentence.
In the printed manual, @code{@@code} puts the argument in bold face.
In the Info file, it uses `@dots{}' quotation. For example:
@example
To compare two files, showing text inserted or removed, use @@code@{diff@}.
@end example
@noindent
produces
@quotation
To compare two files, showing text inserted or removed, use @code{diff}.
@end quotation
@iftex
In the Info file, it looks like this:
@example
@dots{}, use `diff'
@end example
@end iftex
@node Samp, File, Code, Specifying
@comment node-name, next, previous, up
@subsection @@samp
@findex samp
@code{@@samp} is used to indicate text that is a literal example of a
sequence of characters in a file, string, pattern, etc. The text follows,
enclosed in braces. The argument appears within `@dots{}' quotation in
both the Info file and the printed manual; in addition, it is printed in a
fixed-width font.
@example
To match @@samp@{foo@} at the end of the line, use the regexp @@samp@{foo$@}.
@end example
@noindent
produces
@quotation
To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
@end quotation
Any time you are referring to single characters, you should use @code{@@samp}
unless @code{@@kbd} is more appropriate. Basically, @code{@@samp} is a
catchall for whatever is not covered by @code{@@code}, @code{@@file},
@code{@@kbd}.
Punctuation marks that are part of the English text that surrounds the
strings you are specifying are @emph{never} included within the braces. In
the following sentence, for example, the commas and period are outside of
the braces:
@example
A symbol name ends in @@samp@{a@}, @@samp@{b@}, or @@samp@{c@}.
@end example
@node File, Kbd, Samp, Specifying
@comment node-name, next, previous, up
@subsection @@file
@findex file
@code{@@file} is used to indicate text that is the name of a file or
directory. Currently, it is equivalent to @code{@@samp} in its effects on
the output. For example,@refill
@example
The @@file@{.el@} files are in
the @@file@{/gnu/emacs/lisp@} directory.
@end example
@noindent
produces
@quotation
The @file{.el} files are in
the @file{/gnu/emacs/lisp} directory.
@end quotation
@node Kbd, Key, File, Specifying
@comment node-name, next, previous, up
@subsection @@kbd
@findex kbd
@code{@@kbd} is used much like @code{@@code}. The difference is that
@code{@@kbd} is for names of keys on the keyboard, or of characters you can
type. For example, to refer to the command @kbd{M-a}, you would use
@example
@@kbd@{M-a@}
@end example
@noindent
and to refer to @kbd{M-x shell}, you would use
@example
@@kbd@{M-x shell@}
@end example
The @code{@@kbd} command has the same effect as @code{@@code} in Info,
but may produce a different font in a printed manual.@refill
You can embed another @@-command inside the braces of a @code{@@kbd}
command. This is the way to describe a command that would be described
more verbosely as ``press an @samp{r} and then press the @key{RET} key'':
@example
@@kbd@{r @@key@{RET@}@}
@end example
@noindent
This produces: @kbd{r @key{RET}}
You also use the @code{@@kbd} command if you are spelling out the letters
you type; for example:
@example
To give the @@code@{logout@} command,
type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
@end example
@noindent
This produces
@quotation
To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.
@end quotation
@node Key, Ctrl, Kbd, Specifying
@comment node-name, next, previous, up
@subsection @@key
@findex key
@code{@@key} is used for the conventional name for a key on a keyboard, as
in
@example
@@key@{RET@}
@end example
Often, @code{@@key} is used within the argument of a @code{@@kbd}
command, whenever the sequence of characters to be typed includes one or
more keys that are described by name.@refill
For example, to produce @kbd{C-x @key{ESC}} you would use
@example
@@kbd@{C-x @@key@{ESC@}@}
@end example
The recommended names to use for keys are in upper case and are
@table @t
@item SPC
Space.
@item RET
Return.
@item LFD
Linefeed.
@item TAB
Tab.
@item BS
Backspace.
@item ESC
Escape.
@item DEL
Delete.
@item SFT
Shift.
@item CTL
Control.
@item META
Meta.
@end table
There are subtleties to handling words like `meta' or `ctrl' which are
names of shift keys. When mentioning a character in which the shift key is
used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone without the
@code{@@key} command, but when you are referring to shift key in isolation,
use the @code{@@key} command. For example, you would use
@samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and @samp{@@key@{META@}} to
produce @key{META}.
@node Ctrl, Var, Key, Specifying
@comment node-name, next, previous, up
@subsection @@ctrl
@findex ctrl
@code{@@ctrl} is used to describe an ASCII control character. The pattern
of usage is @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
whose control-equivalent is wanted. Thus, you put in an @samp{f} when
you want to indicate a @samp{control-f}
Thus, to specify @samp{control-f}, you would enter
@example
@@ctrl@{f@}
@end example
@noindent
which produces
@quotation
@ctrl{f}
@end quotation
In the Info file, this generates the specified control character, output
literally into the file. This is done so a user can copy the specified
control character (along with whatever else he or she wants) into another
Emacs buffer and use it. Since the `control-h',`control-i', and
`control-j' characters are formatting characters, they should not be
indicated this way.@refill
In a printed manual, this generates text to describe or identify that
control character: an uparrow followed by the character @var{ch}.
@node Var, Dfn, Ctrl, Specifying
@comment node-name, next, previous, up
@subsection @@var
@findex var
@code{@@var} is used to indicate metasyntactic variables. A metasyntactic
variable is something that stands for another piece of text. You would use
a metasyntactic variable in the documentation of a function to describe the
arguments that are passed to that function.
@code{@@var} is not used for names of particular variables in programming
languages. For example, the Texinfo variable @code{texinfo-tex-command} is
not a metasyntactic variable.
Its effect in the Info file is to upcase the argument; in the printed
manual, to italicize it. Example:
@example
To delete file @@var@{filename@}, type @@code@{rm @@var@{filename@}@}.
@end example
@noindent
produces
@quotation
To delete file @var{filename}, type @code{rm @var{filename}}.
@end quotation
In some documentation styles, metasyntactic variables are shown with angle
brackets, for example:
@example
@dots{}, type rm <filename>
@end example
@node Dfn, Cite, Var, Specifying
@comment node-name, next, previous, up
@subsection @@dfn
@findex dfn
@code{@@dfn} is used to identify the introductory or defining use of a
technical term. The command should be used only in a passage whose purpose
is to introduce a term which will be used again or which the reader ought
to know. Mere passing mention of a term for the first time doesn't deserve
@code{@@dfn}. It generates italics in the printed manual, and double
quotation marks in the Info file. Example:
@example
Getting rid of a file is called @@dfn@{deleting@} it.
@end example
@noindent
produces
@quotation
Getting rid of a file is called @dfn{deleting} it.
@end quotation
@node Cite, , Dfn, Specifying
@comment node-name, next, previous, up
@subsection @@cite
@findex cite
@code{@@cite} is used for the name of a book. It produces italics
in the printed manual, and quotation marks in the Info file.
@node Braces Atsigns Periods, Dots Bullets Tex, Specifying , Marking Text
@comment node-name, next, previous, up
@section Inserting Braces, @samp{@@} and Periods
@cindex Inserting braces, @@ and periods
@cindex Braces, inserting
@cindex Periods, inserting
@cindex Single characters, commands to insert
@cindex Commands to insert single characters
@samp{@@} and curly braces are special characters in Texinfo. This means
that you have to put an @samp{@@} in front of these characters in order to
insert them into text.
Periods are also special. Depending on whether the period is inside of or
at the end of a sentence, less or more space is inserted after a period in
a typeset manual. Since it is not always possible for Texinfo to determine
when a period ends a sentence and when it is used in an abbreviation,
special commands are needed. (Usually, Texinfo figures out how to handle
periods, so you don't have to use the special commands; you just enter a
period as you would if you were using a typewriter, which means you put two
spaces after the period that ends a sentence and after a colon.)@refill
@menu
* Inserting an Atsign:: inserting an atsign.
* Insert Left Brace:: Inserting a left brace.
* Insert Colon:: Preventing unintended additional whitespace.
* Insert Period:: Inserting a period that does end a sentence.
@end menu
@node Inserting An Atsign, Insert Left Brace, , Braces Atsigns Periods
@comment node-name, next, previous, up
@subsection @@@@
@findex at-signs
@comment for version 19: this does not work findex @@
@code{@@@@} stands for a single @@ in either printed or Info output.
@node Insert Left Brace, Insert Colon, Inserting an Atsign, Braces Atsigns Periods
@comment node-name, next, previous, up
@subsection @@@{
@findex left-braces
@comment for version 19: this does not work findex @{
@code{@@@{} stands for a single @{ in either printed or Info output.
@subsection @@@}
@findex right-braces
@comment for version 19: this does not work findex @}
@code{@@@}} stands for a single @} in either printed or Info output.
@node Insert Colon, Insert Period, Insert Left Brace, Braces Atsigns Periods
@comment node-name, next, previous, up
@subsection @@:
@findex at-sign colons
@comment for version 19: this does not work findex @:
@code{@@:}@: is used after a character such as period or colon which
normally causes @TeX{} to increase the width of the following whitespace,
to suppress that effect. For example, it can be used after periods that
end abbreviations and do not end sentences. @code{@@:}@: has no effect
on the Info file output.
@example
It displays @@code@{Foo:@}@@: at that time.
@end example
@noindent
produces
@quotation
It displays @code{Foo:}@: at that time.
@end quotation
The meanings of @code{@@:}@: and @code{@@.}@: in Texinfo are designed to
work well with the Emacs sentence motion commands. This means they are
different from their meanings in some other formatting systems that use
@@-commands.
@refill
@node Insert Period, , Insert Colon, Braces Atsigns Periods
@comment node-name, next, previous, up
@subsection @@.
@findex at-sign periods
@comment for version 19: this does not work at-sign period
@code{@@.}@: stands for a period that really does end a sentence, useful
when @TeX{} would otherwise assume by its heuristics that that is not so.
This happens when there is a single-capital-letter word at the end of a
sentence: @TeX{} normally guesses that it is an abbreviation.
In the Info file output, @code{@@.}@: is equivalent to a simple @samp{.}.
The Texinfo program preserves the amount of space that you use, so put
two spaces after a period if you intend it to be the end of a sentence
(as well as using @code{@@.}, if necessary, for the printed manual's sake).
@example
Give it to X. Give it to X@@. Give it to X@@.
@end example
@noindent
produces
@quotation
Give it to X. Give it to X@. Give it to X@.
@end quotation
@node Dots Bullets Tex, Emphasis, Braces Atsigns Periods, Marking Text
@comment node-name, next, previous, up
@section Inserting Dots, Bullets and @TeX{}
@cindex Dots, inserting
@cindex Bullets, inserting
@cindex TeX-logo, inserting
@cindex Special typesetting commands
@cindex Typesetting commands for dots and the like
An ellipsis, a line of dots, is typeset differently than a string of
periods; more whitespace is put between the dots in the ellipsis than is
put between the periods. Because of this, a special command is used in
Texinfo for inserting dots. Also, the trademark, @TeX{}, is typeset in a
special fashion and it needs an @@-command, as does the command for
inserting the copyright symbol. The @code{@@bullet} command is special,
too. Each of these commands is followed by a pair of braces, @samp{@{@}},
without any whitespace between the name of the command and the braces.
@menu
* Dots:: Inserting dots.
* Bullet:: Inserting bullets.
* Tex:: Inserting the @TeX{} trademark.
@end menu
@node Dots, Bullet, , Dots Bullets Tex
@comment node-name, next, previous, up
@subsection @@dots@{@}
@findex dots
@cindex Inserting dots
@cindex Dots, inserting
@code{@@dots@{@}} generates an ellipsis which is three dots in a row,
appropriately spaced, like this: `@dots{}'. Do not simply write three
periods in the input file; that would work for the Info file output, but
would produce the wrong amount of space between the periods in the printed
manual.
@iftex
Here is an ellipsis: @dots{}
Here are three periods in a row: ...
The three periods in a row are closer together than the dots in the ellipsis.
@end iftex
@node Bullet, Tex, Dots, Dots Bullets Tex
@comment node-name, next, previous, up
@subsection @@bullet@{@}
@findex bullet
@code{@@bullet@{@}} generates a large round dot, or the closest possible
thing to one.
Here is a bullet: @bullet{}
@node Tex, , Bullet, Dots Bullets Tex
@comment node-name, next, previous, up
@subsection @@TeX@{@}
@findex TeX
@code{@@TeX@{@}} generates `@TeX{}'. In a printed manual, this is a special
logo that is different from three ordinary letters.
@node Emphasis, , Dots Bullets Tex, Marking Text
@comment node-name, next, previous, up
@section Emphasizing Text
@cindex Emphasizing text
Usually, Texinfo changes the font automatically to mark words in the text
according to what category the words belong to. The @code{@@code} command,
for example, does this. Most often, this is the best way to mark specified
words. However, sometimes you will want to emphasize text directly.
Texinfo has two ways to do this: commands that tell Texinfo to emphasize
the text but leave the method to the program, and commands that specify the
font to use. The first method is generally the best and it makes it
possible to change the style of a document without have to re-edit it line
by line.
@menu
* Emph and Strong:: Emphasizing text.
* Fonts:: Selecting italic, bold or typewriter fonts.
@end menu
@node Emph and Strong, Fonts, , Emphasis
@comment node-name, next, previous, up
@subsection @@emph and @@strong
@findex emph
@findex strong
@code{@@emph} and @code{@@strong} are two forms of emphasis. @code{@@strong}
is stronger.
In printed output, @code{@@emph} produces @emph{italics} and @code{@@strong}
produces @strong{bold}.
In the Info file, both of these commands put asterisks around the
argument.
@node Fonts, , Emph and Strong, Emphasis
@comment node-name, next, previous, up
@subsection @@i, @@b and @@t
@findex i (italic font)
@findex b (bold font)
@findex t (typewriter font)
These three commands specify font changes in the printed manual and have no
effect in the Info file. @code{@@i} requests @i{italic} font (in some
versions of @TeX{}, a slanted font is used), @code{@@b} requests @b{bold}
face, and @code{@@t} requests the @t{fixed-width} font used by
@code{@@kbd}. All three commands apply to an argument that follows,
surrounded by braces.@refill
If possible, you should avoid using these three commands. If you find a
need to use one, it probably indicates a lack in the Texinfo language.
@node Conditionals, Printing Hardcopy, Marking Text, Top
@comment node-name, next, previous, up
@chapter Conditionals
@cindex Conditionals
@cindex Ifinfo
@cindex Iftex
@findex ifinfo
@findex iftex
You may not always be able to use the same text for both the printed manual
and the on-line Info file. In this case, you can use the conditional
commands to specify which text is for the printed manual and which is for
the Info file.
@code{@@ifinfo} begins text that should be ignored by @TeX{} when it
typesets the printed manual. The text appears only in the Info file. The
@code{@@ifinfo} command should appear on a line by itself. End the
info-only text with a line containing @code{@@end ifinfo} by itself. At
the beginning of a Texinfo file, the Info permissions are contained within a
region marked by @code{@@ifinfo} and @code{@@end ifinfo}.@refill
Likewise, @code{@@iftex} and @code{@@end iftex} lines delimit text that
will not appear in the Info file but will appear in the printed manual.@refill
For example,
@example
@@iftex
This text will appear only in the printed manual.
@@end iftex
@@ifinfo
However, this text will appear only in the info manual.
@@end ifinfo
@end example
@noindent
The preceding example produces the following. Note how you only see one of
the two lines, depending on whether you are reading the on-line Info version
or the printed version of this manual.
@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in the info manual.
@end ifinfo
The @code{@@titlepage} command is a special variant of @code{@@iftex} that
is used for making the title and copyright pages of the printed manual.
@menu
* Using Tex Commands:: Using commands from regular @TeX{}.
@end menu
@node Using Tex Commands, , Conditionals, Conditionals
@comment node-name, next, previous, up
@section Using @TeX{} Commands
@cindex Using TeX commands
@cindex TeX commands, using them
Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
can embed ordinary @TeX{} commands. Info will ignore these commands since
they are only in that part of the file that is seen by @TeX{}. The @TeX{}
commands are the same as any @TeX{} commands except that an @samp{@@}
replaces the @samp{\} used by @TeX{}. For example, in the
@code{@@titlepage} section of a Texinfo file, the @TeX{} command
@code{@@vskip} is used to format the copyright page.@refill
You can enter @TeX{} completely, and use @samp{\} in the @TeX{} commands by
delineating a region with the @code{@@tex} and @code{@@end tex} commands.
(These commands automatically put the region inside of @code{@@iftex} and
@code{@@end iftex} commands.) For example,@refill
@example
@@tex
Here you would put text with @TeX{} commands;
such as $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
that will appear only in the printed manual.
@@end tex
@end example
@noindent
In the Info file, nothing between @code{@@tex} and @code{@@end tex} will
appear.@refill
@iftex
In the printed manual, the mathematics will look like this:
@tex
$\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$
@end tex
@end iftex
@node Printing Hardcopy, Creating an Info File, Conditionals, Top
@comment node-name, next, previous, up
@chapter Printing Hardcopy
@cindex Printing hardcopy
@cindex Hardcopy, printing it
@cindex Making a printed manual
@cindex Sorting indices
@cindex Indices, sorting
@findex texindex (for sorting indices)
There are three shell commands for printing a hardcopy of a Texinfo file.
One is for formatting the file, the second is for sorting the index and the
third is for printing the formatted document. When you use the shell
commands, you can either work directly in the operating system shell or
work within a shell inside of GNU Emacs.
The typesetting program @TeX{} is used for formatting a Texinfo file.
@TeX{} is a very powerful typesetting program and, if used right, does an
exceptionally good job. The @@-commands in a Texinfo file are translated
by a file called @file{texinfo.tex} into commands that @TeX{} understands.
(That is why the beginning of every Texinfo file starts with the line that
says @samp{\input texinfo}; this command tells @TeX{} to use the
@file{texinfo.tex} file in processing the Texinfo file. Customarily,
@file{texinfo.tex} is in a directory called @file{/usr/lib/tex/macros}.)
@code{texinfo-format-buffer} reads the very same @@-commands in the Texinfo
file and processes them differently from @TeX{} to make an Info
file.@refill
Usually, the @TeX{} formatting command is the shell command @code{tex}
followed by the name of the Texinfo file. The @TeX{} command produces a
formatted DVI file as well as several auxiliary files containing indices,
cross references, etc. The DVI file (for @dfn{DeVice Independent} file)
can be printed on a wide variety of printers.@refill
The @TeX{} formatting command itself does not sort the indices. This is a
misfeature of @TeX{}. Hence, to generate a printed index, you first need a
sorted index to work from.@refill
@TeX{} outputs raw, unsorted index files under names that obey a standard
convention. These names are the name of your main input file to @TeX{},
with everything after the first period thrown away, and the two letter
names of indices added at the end. For example, the raw index output files
for the input file @file{foo.texinfo} would be @file{foo.cp},
@file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and
@file{foo.ky}. Those are exactly the arguments to give to @code{texindex}.
Or else, you can use @samp{??} as ``wild-cards'' and give the command in
this form:@refill
@example
texindex foo.??
@end example
For each file specified, @code{texindex} generates a sorted index file
whose name is made by appending @samp{s} to the input file name. The
@code{@@printindex} command knows to look for a file of that name.
@code{texindex} does not alter the raw index output file. After you have
sorted the indices, you need to rerun the @TeX{} command on the Texinfo
file. This regenerates a formatted DVI file with the index entries in the
correct order.@refill
To summarize, this is a three step process:
@enumerate
@item
Run the @TeX{} command on the Texinfo file. This generates the formatted
DVI file as well as the raw index files with two letter extensions.@refill
@item
Run the shell command @code{texindex} on the raw index files to sort them.
The arguments to @code{texindex} are the names of the raw index files.
@code{texindex} creates sorted index files whose names are the names of the
raw index files with an @samp{s} appended. To cause @code{texindex} to
sort all the raw index files, append @samp{??} to the Texinfo file name in
place of the @file{.texinfo} extension.@refill
@item
Rerun the @TeX{} command on the Texinfo file. This regenerates a formatted
DVI file with the index entries in the correct order. This second run also
makes all the cross references correct as well. (The tables of contents
are always correct.)@refill
@end enumerate
You need not run @code{texindex} after each @TeX{} run. If you don't, the
next @TeX{} run will use whatever sorted index files happen to exist from
the previous use of @code{texindex}. This is usually ok while you are
debugging.
Finally, the document can be printed out with the DVI print command
(a shell command). Depending on the system used, the DVI print command
will be a command such as @code{lpr -d}. The DVI print command may require
a file name without any extension or with a @samp{.dvi} extension.
The following commands, for example, sort the indices, format and print
the @cite{Bison Manual} (where @samp{%} is the shell prompt):
@example
% tex bison.texinfo
% texindex bison.??
% tex bison.texinfo
% lpr -d bison.dvi
@end example
@noindent
(Remember that the words for the shell commands may be different at your
site; but these are commonly used versions.)
It is often most convenient to give formatting and printing commands from a
shell within GNU Emacs. This way, you can easily keep track of errors. To
create a shell within Emacs, type @kbd{M-x shell}. In this shell, you can
format and print the document. You can switch to and from this shell while
it is running and do other things. If you are formatting a very long
document on a slow machine, this can be very convenient; on a VAX 750, for
example, formatting often takes 8 seconds or more per page depending on how
loaded the computer is. Faster machines take correspondingly less time.
@menu
* Requirements:: Formatting requirements.
* Compile-Command:: Formatting with the compile command.
@end menu
@node Requirements, Compile-Command, , Printing Hardcopy
@comment node-name, next, previous, up
@section Formatting Requirements
@cindex Requirements for formatting
@cindex Formatting requirements
Every Texinfo file that is to be input to @TeX{} must begin with a line
that looks like
@example
\input texinfo @@c -*-texinfo-*-
@end example
@noindent
This serves two functions.
@enumerate
@item
When the file is processed by @TeX{}, it loads the macros needed for
processing a Texinfo file.@refill
@item
When the file is edited in Emacs, it causes Texinfo mode to be used.@refill
@end enumerate
Every Texinfo file must end with a line saying
@example
@@bye
@end example
which terminates @TeX{} processing and forces out unfinished pages.
You also have to include two lines that specify the Info file name and the
title of the printed manual:
@example
@@setfilename @var{name-of-texinfo-file}
@@settitle @var{Name of Manual}
@end example
You might also want to include a line saying
@example
@@setchapternewpage odd
@end example
@noindent
to cause each chapter to start on a fresh odd-numbered page.
By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
format. However, you can direct @TeX{} to typeset a document in a 7 by
9.25 inch format that is suitable for bound books by inserting the
following command on a line by itself at the beginning of the Texinfo
file, before the @code{@@setchapternewpage} command:
@example
@@smallbook
@end example
@noindent
The Free Software Foundation distributes printed copies of the @cite{GNU
Emacs Manual} in this size.
Finally, @TeX{} sometimes is unable to typeset a line without extending
it into the right margin. This can occur when @TeX{} comes upon what it
interprets as a long word that it cannot hyphenate, like a net address,
or a very long title. When this happens, @TeX{} prints an error message
like this:
@example
Overfull \hbox (20.76302pt too wide)
@end example
@noindent
and gives the line number along with the text of the offending line
marked at all the places that @TeX{} knows to hyphenate words. (In
@TeX{} lines are in `horizontal boxes', hence the term, `hbox'.)
If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur or you can decide to leave it. A
small excursion into the right margin often does not matter and may not
even be noticable. However, unless told otherwise, @TeX{} will print a
large, ugly, black rectangle beside every line that is overfull. This is
so you will notice the location of the problem if you are correcting a
draft. To prevent such monstrosities from marring your final printout,
put the following in the beginning of the Texinfo file on lines of their
own, before the @code{@@setchapternewpage} command:
@example
@@iftex
@@finalout
@@end iftex
@end example
@xref{Titlepage}, for information about creating a title page.
@xref{Contents}, for information about creating a table of contents.@refill
@node Compile-Command, , Requirements, Printing Hardcopy
@comment node-name, next, previous, up
@section Using Local Variables and the Compile Command
@cindex Local variables
@cindex Compile command for formatting
@cindex Formatting with the compile command
Another way to give the @TeX{} formatting command to Texinfo is to put that
command in a @dfn{local variables list} at the end of the Texinfo file.
You can then specify the @TeX{} formatting command as a
@code{compile-command} and have Emacs run the @TeX{} formatting command by
giving the command @kbd{M-x compile}. This creates a special shell called
the @samp{*compilation buffer*}. For example, at the end of the
@file{gdb.texinfo} file, after the @code{@@bye}, you would put the
following:@refill
@example
@@c Local Variables:
@@c compile-command: "tex gdb.texinfo"
@@c End:
@end example
@noindent
This technique is most often used by programmers who compile programs
this way.
@node Creating an Info File, Catching Mistakes, Printing Hardcopy, Top
@comment node-name, next, previous, up
@chapter Creating an On-line Info file
@cindex Creating an on-line Info file
@cindex Running Info
@cindex Info, creating an on-line file
@cindex Formatting a file for Info
@cindex Indirect subfiles
@findex texinfo-format-buffer
In GNU Emacs, using Texinfo mode, you can see what part or all of a Texinfo
file will look like in Info by using the keyboard command @kbd{C-c C-f}
(@code{texinfo-format-region}). This formats a region and displays in a
temporary buffer called @samp{*Info Region*}; however, this command does
not turn on Info reading program---it just displays what the region will
look like. The @code{texinfo-format-region} command is described more
extensively in the chapter on using Texinfo mode. @xref{Info on a Region}.
@refill
In GNU Emacs, the way to create a working Info file is to visit the file
and invoke
@example
@kbd{M-x texinfo-format-buffer}
@end example
@noindent
A new buffer is created and the Info file text is generated there.
@kbd{C-x C-s} will save it under the name specified in the
@code{@@setfilename} command.@refill
If the Texinfo file has more than 30,000 bytes,
@code{texinfo-format-buffer} will automatically create a @dfn{tag table}
for it. With a tag table, Info can jump to new nodes more quickly than it
can otherwise. In addition, if the file has more than 100,000 bytes in it,
@code{texinfo-format-buffer} will split the file into shorter Indirect
subfiles of about 50,000 bytes each. Files are split so that Info does not
have to make a large buffer to hold the whole of a large Info file;
instead, Info allocates just enough memory for the small, split off file
that is needed at the time. This way, Emacs avoids wasting memory when you
run Info. (Before splitting was implemented, Info files were always short
and @dfn{include} files were designed as a way to create a single, large
printed manual out of the smaller Info files. @xref{Include Files}, for
more information.)@refill
When the file is split, Info itself works through a shortened version of
the original file that contains the tag table and references to the files
that were split off. The split off files are called @dfn{indirect} files.
The split off files have names that are created by appending @samp{-1},
@samp{-2}, @samp{-3} and so on to the file names specified by the
@code{@@setfilename} command. The shortened version of the original file
continues to have the name specified by @code{@@setfilename}.
At one stage in writing this document, for example, the Info file was saved
as @file{test-texinfo} and that file looked like this:
@group
@example
Info file: test-texinfo, -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo
^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
@dots{}
@end example
@end group
@noindent
(But @file{test-texinfo} had far more nodes than are shown here.) Each of
the split off, indirect files, @file{test-texinfo-1},
@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
after the line that says @samp{Indirect:}. The tag table is listed after
the line that says @samp{Tag table:}. @refill
You cannot run the @kbd{M-x Info-validate} node checking command on indirect
files. For information on how to prevent files from being split and how to
validate the structure of the nodes, @pxref{Info-Validating a Large
File}@refill
@menu
* Installing an Info File:: Putting the Info file in the info directory.
@end menu
@node Installing an Info File, , Creating an Info File, Creating an Info File
@comment node-name, next, previous, up
@section Installing an Info file
@cindex Installing an Info file
@cindex Info file installation
@cindex Dir directory for Info installation
An Info file is usually installed in the GNU Emacs directory called
@file{info}. For Info to work, this directory must contain all the Info
files, including the split off files. In addition, the @file{info}
directory must have a file that serves as a top level directory for the
Info system. This file is called @file{dir}.
For example, in the @file{info} directory, the file called @file{dir} has
the top level menu for all the Info files in the system. This file has a
master menu that looks like this:
@example
* Menu:
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible self-documenting text editor.
* Texinfo: (texinfo). With one source file, make either a printed
manual using TeX or an Info file using
Texinfo.
@end example
To add a new Info file, just add it to this menu. For example, if you
were adding documentation for GDB, you would make the following entry:
@example
* GDB: (gdb). The source-level C debugger.
@end example
@noindent
The first item is the menu item name; it is followed by a colon. The
second item is the name of the Info file, in parentheses; it is followed by
a period. The third part of the entry is the description of the item.
The top node of the file, named @samp{top}, should have as its parent the
name of a node in another file, where there is a menu that leads to this
file. Specify the file name in parentheses. If the file is to be
installed directly in the Info directory file, use @samp{(dir)} as the
parent of the top node; this is short for @samp{(dir)top}, the node @samp{top}
in the file @file{dir}, which is the main menu of Info.
@node Catching Mistakes, Command Syntax, Creating an Info File, Top
@comment node-name, next, previous, up
@chapter Catching Mistakes
@cindex Structure of Texinfo, catching mistakes
@cindex Nodes, catching mistakes
@cindex Nodes, correcting mistakes
@cindex Catching mistakes
@cindex Correcting mistakes
@cindex Mistakes, catching
@cindex Problems, catching
@cindex Debugging the Texinfo structure
Besides mistakes with the content of what ever you are describing, there
are two kinds of mistake you can make with Texinfo: you can make mistakes
with @@-commands, and you can make mistakes with the structure of the
nodes and chapters.
There are two tools for catching the first kind of mistake and two for
catching the second.
For finding problems with @@-commands, your best action is to run @kbd{M-x
texinfo-format-region} on regions of your file as you write it. In Texinfo
mode, the @code{texinfo-format-region} command is bound to @kbd{C-c C-f}.
In addition, you can run @TeX{} on the whole file.@refill
For finding problems with the structure of nodes and chapters, you can use
@kbd{C-c C-s} (@code{texinfo-show-structure}) (and the related @code{occur}
command) and you can use the @kbd{M-x Info-validate} command.
@menu
* Debugging with Info:: Catching errors with info formatting.
* Debugging with Tex:: Catching errors with @TeX{} formatting.
* Using texinfo-show-structure:: Using @code{texinfo-show-structure}
to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.
@end menu
@node Debugging with Info, Debugging with Tex, , Catching Mistakes
@comment node-name, next, previous, up
@section Catching Errors with Info Formatting
@cindex Catching errors with Info Formatting
@cindex Debugging with Info Formatting
After you have written part of a Texinfo file, you can use the @kbd{M-x
texinfo-format-region} command to see whether the region formats properly.
In Texinfo mode, this command is bound to the keyboard command @kbd{C-c
C-f}.
If you have made a mistake with an @@-command, @kbd{M-x
texinfo-format-region} will stop processing at or after the error and give
an error message. To see where in the file the error occurred, switch to
the @samp{*Info Region*} buffer; the cursor will be in a position that is
after the location of the error. Also, the text will not be formatted
after the place the error occurred.@refill
For example, if you accidently end a menu with the command @code{@@end
menus} with an `s' on the end, instead of with @code{@@end menu}, you will
get an error message that says:
@example
@@end menus is not handled by texinfo.
@end example
@noindent
The cursor will stop at the point in the file where the error occurs, or
not long after it. It will look like this:
@group
@example
@@menu
* Using texinfo-show-structure:: Using @code{texinfo-show-structure}
to catch mistakes.
* Running Info-Validate:: Checking for unreferenced nodes.
@@end menus
@end example
@end group
The @code{texinfo-format-region} command does not always recognize errors.
For example, no errors were reported when @code{texinfo-format-region} was
run on the whole itemized list of which the following is a part:
@example
name of the Texinfo file as an extension. The @@samp@{??@} are `wildcards'
that cause the shell to substitute all the raw index files. (@@xref@{sorting
indices), for more information about sorting indices.) @@refill
@@cindex Sorting indices
@@cindex Indices, sorting
@@item
@@emph@{Third@}, rerun the @@TeX@{@} command on the Texinfo file. This
regenerates a formatted DVI file with the index entries in the correct
order. This second run also makes all the cross references and table of
contents correct as well.
@end example
@noindent
Instead, @code{texinfo-format-region} ran without reporting the error, but
it produced output with very long lines, containing some of the original
@code{@@cindex} commands mixed in. (It is not practical to display these
over long lines here.
However, when @code{texinfo-format-region} was run on part of the list
that is shown, it did give an error message, @samp{Search failed:
"[@{,@}"}. (This error message is explained in the section on using the
Emacs Lisp Debugger, @pxref{Using the Emacs Lisp Debugger})
Sometimes @code{texinfo-format-region} will stop long after the original
error; this is because it does not discover the problem until then. In this
case, you will have to backtrack.@refill
@node Using the Emacs Lisp Debugger, , ,Debugging with Info
@comment node-name, next, previous, up
@subsection Using the Emacs Lisp Debugger
@cindex Using the Emacs Lisp debugger
@cindex Emacs Lisp debugger
@cindex Debugger, using the Emacs Lisp
If an error is especially elusive, you can turn on the Emacs Lisp debugger
and look at the backtrace; this tells you where in the
@code{texinfo-format-region} function the problem occurred. You can turn
on the debugger with the command:@refill
@example
M-x set-variable @key{RET} debug-on-error @key{RET} t
@end example
@noindent
and turn it off with
@example
M-x set-variable @key{RET} debug-on-error @key{RET} nil
@end example
Often, when you are using the debugger, it is easier to follow what is
going on if you use the Emacs Lisp files that are not byte-compiled. The
byte-compiled sources send octal numbers to the debugger that may look
mysterious. To use the uncompiled source files, load @file{texinfmt.el}
and @file{texinfo.el} with the @kbd{M-x load-file} command.@refill
The debugger will not catch an error if @code{texinfo-format-region} does
not detect one. In the example shown above, @code{texinfo-format-region}
did not find the error when the whole list was formatted, but only when
part of the list was formatted. When @code{texinfo-format-region} did not
find an error, the debugger did not find one either. @refill
However, when @code{texinfo-format-region} did report an error, it invoked
the debugger. This is the backtrace it produced:
@example
Signalling: (search-failed "[@},]")
re-search-forward("[@},]")
(while ...)
(let ...)
texinfo-format-parse-args()
(let ...)
texinfo-format-xref()
funcall(texinfo-format-xref)
(if ...)
(let ...)
(if ...)
(while ...)
texinfo-format-scan()
(save-excursion ...)
(let ...)
texinfo-format-region(103370 103631)
* call-interactively(texinfo-format-region)
@end example
The backtrace is read from the bottom up. @code{texinfo-format-region} was
called interactively; and it, in turn, called various functions, including
@code{texinfo-format-scan}, @code{texinfo-format-xref} and
@code{texinfo-format-parse-args}. Inside the function
@code{texinfo-format-parse-args}, the function @code{re-search-forward} was
called; it was this function that could not find the missing right hand
brace.@refill
@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs Manual}, for
more information.@refill
@node Debugging with Tex, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
@comment node-name, next, previous, up
@section Catching Errors with @TeX{} Formatting
@cindex Catching errors with TeX Formatting
@cindex Debugging with TeX Formatting
You can also catch mistakes when you format a file with @TeX{}.
Usually, you will want to do this after you have run
@code{texinfo-format-buffer} on the same file.
@code{texinfo-format-buffer} is usually faster and sometimes gives error
messages that make more sense. @xref{Debugging with Info}, for more
information.@refill
For example, @TeX{} was run on the same itemized list discussed
in the section on the use of @code{texinfo-format-region}
(@pxref{Debugging with Info}); the fragment with the error looked like
this:
@example
name of the texinfo file as an extension. The @@samp@{??@} are `wildcards'
that cause the shell to substitute all the raw index files. (@@xref@{sorting
indices, for more information about sorting indices.) @@refill
@end example
@noindent
This produced the following output, after which @TeX{} stopped:
@example
Runaway argument?
@{sorting indices, for more information about sorting indices.) @@refill @@ETC.
! Paragraph ended before \xref was complete.
<to be read again>
\par
l.27
?
@end example
In this case, @TeX{} produced an accurate and understandable error message:
@samp{Paragraph ended before \xref was complete.} (Note, however, that
@TeX{} translated the @samp{@@} into a @samp{\}.) Also, @samp{\par} is an
internal @TeX{} command of no relevance to Texinfo.)
Unfortunately, @TeX{} is not always so helpful, and sometimes you have to be
truly a Sherlock Holmes to discover what went wrong.
In any case, if you run into a problem like this, you can do one of two
things.
@enumerate
@item
You can tell @TeX{} to continue running and to ignore errors
as best it can by typing @kbd{r @key{RET}} at the
@samp{?} prompt.@refill
This is often the best thing to do. However, beware: the one error may
produce a cascade of additional error messages as it consequences are felt
through the rest of the file.@refill
@item
You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
at the @samp{?} prompt.
@end enumerate
Sometimes @TeX{} will format a file without producing error messages even
though there is a problem. This usually occurs if a command is not ended
but @TeX{} is able to continue processing anyhow. For example, if you fail
to end an itemized list with the @code{@@end itemize} command, @TeX{} will
write a DVI file that you can print out. The only error message that
@TeX{} will give you is the somewhat mysterious comment that
@example
(\end occurred inside a group at level 1)
@end example
@noindent
However, if you print the DVI file, you will find that the text of the file
that follows the itemized list is entirely indented as if it were part of
the last item in the itemized list. The error message is the way @TeX{}
says that it expected to find an @code{@@end} command somewhere in the
file; but that it could not locate where it was needed. @refill
Another source of notoriously hard to find errors is a missing @code{@@end
group} command. If you ever are stumped by incomprehensible errors, look
for a missing @code{@@end group} command first.@refill
If you do not have the header lines in the file, @TeX{} may stop in the
beginning of its run and display output that looks like the following.
The @samp{*} indicates that @TeX{} is waiting for input.@refill
@example
This is TeX, Version 2.0 for Berkeley UNIX (preloaded format=plain-cm
87.10.25) (#tz-bar-a02987.tex [1])
*
@end example
@noindent
In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
put the header lines into the Texinfo file and run the @TeX{} command
again.@refill
@node Using texinfo-show-structure, Running Info-Validate, Debugging with Tex, Catching Mistakes
@comment node-name, next, previous, up
@section Using @code{texinfo-show-structure}
@cindex Showing the structure of a file
@cindex Using texinfo-show-structure to catch mistakes
@cindex texinfo-show-structure for catching mistakes
@findex texinfo-show-structure
It is not always easy to keep track of the nodes, chapters, sections and
subsections of a Texinfo file. This is especially true if you are revising
or adding to a Texinfo file that someone else has written.
In GNU Emacs, in Texinfo mode, there is a command that will list all the
lines that begin with the @@-commands that specify the structure: @@node,
@@chapter, @@section, @@appendix and so on. This is the
@code{texinfo-show-structure} command. It is bound to the keyboard command
@kbd{C-c C-s}. @code{texinfo-show-structure} displays the lines that begin
with the node and chapter structuring @@-commands in another window called
the @samp{*Occur*} buffer. For example, when @code{texinfo-show-structure}
is run on the first part of this chapter, it produces the following:@refill
@example
Lines matching
"^@@\\(chapter\\|unnum\\|appendix\\|sect\\|sub\\|heading\\|major
\\|node\\)" in buffer new-texinfo-manual.texinfo.
2:@@node catching mistakes, @@-Command Syntax, running info, top
4:@@chapter Catching Mistakes
41:@@node debugging with info, debugging with tex, , catching mistakes
43:@@section Catching errors with Info Formatting
@end example
This means that lines 2, 4, 41 and 43 began with @code{@@node},
@code{@@chapter}, @code{@@node}, and @code{@@section} respectively. If you
move your cursor into the @samp{*Occur*} window, 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.
@xref{Other Repeating Search, , Using Occur, emacs, The GNU Emacs Manual},
for more information about @code{occur-mode-goto-occurrence}.@refill
The first line in the @samp{*Occur*} window describes the @dfn{regular
expression} specified by @var{texinfo-heading-pattern}. This regular
expression is the pattern that @code{texinfo-show-structure} looks for.
@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
for more information.@refill
When you give the @code{texinfo-show-structure} command, it will show the
structure of the whole buffer. If you want to see the structure of just a
part of the buffer, of one chapter, for example, use the @kbd{C-x n}
(@code{narrow-to-region}) command to mark the region. (@xref{Narrowing, ,
, emacs, The GNU Emacs Manual}.) This is how the example used above was
generated. (To see the whole buffer again, use @kbd{C-x w}
(@code{widen}).)@refill
You can remind yourself of the structure of a Texinfo file by looking at
the list in the @samp{*Occur*} window; and if you have mis-named a node
or left out a section, you can correct the mistake.
@menu
* Using Occur::
@end menu
@node Using Occur, , Using texinfo-show-structure, Using texinfo-show-structure
@comment node-name, next, previous, up
@subsection Using @code{occur}
@cindex Using occur
@cindex Occur, using the command
Sometimes the @code{texinfo-show-structure} command produces too much
information. Perhaps you want to remind yourself of the overall structure
of a Texinfo file, and are overwhelmed by the detailed list produced by
@code{texinfo-show-structure}. In this case, you can use the @code{occur}
command itself. To do this, type
@example
@kbd{M-x occur}
@end example
@noindent
and then, when prompted, type a @dfn{regexp}, a regular expression for the
pattern you want to match.
(@xref{Regexps, , Regular Expressions, emacs, The GNU Emacs Manual}.)
@code{occur} works from the current location of
the cursor in the buffer to the end of the buffer. If you want to run
@code{occur} on the whole buffer, place the cursor at the beginning of the
buffer. For example, to see all the lines that contain the word
@samp{@@chapter} in them, just type @samp{@@chapter}. This will produce a
list of the chapters. It will also list all the sentences with
@samp{@@chapter} in the middle of the line. If you want to see only those
lines that start with the word @samp{@@chapter}, type @samp{^@@chapter}
when prompted by @code{occur}. If you want to see all the lines that end
with a word or phrase, end the last word with a @samp{$}; for example,
@samp{catching mistakes$}. This can be helpful when you want to see all
the nodes that are part of the same chapter or section and therefore have
the same `Up' pointer.@refill
@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
for more information.@refill
@node Running Info-Validate, , Using texinfo-show-structure, Catching Mistakes
@comment node-name, next, previous, up
@section Finding Badly Referenced Nodes
@cindex Running Info-validate
@cindex Info-validate, running the command
@cindex Nodes, checking for badly referenced nodes
@cindex Checking for badly referenced nodes
@cindex Looking for badly referenced nodes
@cindex Finding badly referenced nodes
@cindex Badly referenced nodes
You can check whether any of the `Next', `Previous', `Up' or other node
pointers fail to point to a node with the @code{Info-validate} command.
This command checks that every node pointer points to an existing node.
To use this command, you first need to load the @code{info} library and then do
@kbd{M-x Info-validate}.
@example
@kbd{M-x load-library @key{RET} info @key{RET}}
@kbd{M-x Info-validate}
@end example
@noindent
(Note that all the @code{Info} commands require an uppercase `I'.)
If your file is ok, you will receive a message that says ``File appears
valid''. However, if you have a pointer that does not point to a node,
error messages will be displayed in a buffer called @samp{*problems in
info file*}.
For example, @code{Info-validate} was run on a test file that contained
only the first node of this manual. One of the messages said:
@example
In node "Overview", invalid Next: Texinfo Mode
@end example
@noindent
This meant that the node called @samp{Overview} had a `Next' pointer that
did not point to anything (which was true in this case, since the test file
had only one node in it).
Now suppose we add a node named @samp{Texinfo Mode} to our test case
but we don't specify a `Previous' for this node. Then we will get
the following error message:
@example
In node "Texinfo Mode", should have Previous: Overview
@end example
@noindent
This is because every `Next' pointer should be matched by a
`Previous' (in the node where the `Next' points) which points back.
@code{Info-validate} also checks that all menu items and cross-references
point to actual nodes.
Significantly, @code{Info-validate} does not work with large files that
have been split. (Info thinks of a large file as being over 100,000 bytes,
approximately.) In order to use @code{Info-validate} on a large file, you
must run @code{texinfo-format-buffer} with an argument so that it does not
split the Info file, and then create a tag table.
@menu
* Info-Validating a Large File:: Running @code{Info-validate} on a large file.
* Splitting:: Splitting a file manually.
@end menu
@node Info-Validating a Large File, Splitting, Running Info-Validate, Running Info-Validate
@comment node-name, next, previous, up
@subsection Running @code{Info-validate} on a Large File.
@cindex Running Info-validate on a large file
@cindex Info validating a large file
@cindex Validating a large file
You can run @code{Info-validate} only on a single Info file. The command
will not work on indirect subfiles that are generated when the master file
is split. If you have a large file (longer than 100,000 bytes), you need
to run the @code{texinfo-format-buffer} command in such a way that it does
not create indirect subfiles. You will also need to create a tag table.
When you have done this, you can run @code{Info-validate} and look for
badly referenced nodes.@refill
After you have validated the node structure, you can rerun
@code{texinfo-format-buffer} in the normal way so it will construct the tag
table and split the file automatically or, you can make the tag table and
split the file manually.@refill
To prevent the @code{texinfo-format-buffer} command from splitting a
Texinfo file into smaller Info files, give a prefix to the @kbd{M-x
texinfo-format-buffer} command:
@example
C-u M-x texinfo-format-buffer
@end example
@noindent
When you do this, Texinfo will not split the file and will not create a tag
table for it. @refill
@cindex Making a tag table manually
@cindex Tag table, making manually
Before you can run @kbd{M-x Info-validate} on the Info file, you need to
create a tag table for it. In order to do this, you first need to load the
@code{info} library into Emacs with the following command:@refill
@example
M-x load-library @key{RET} info @key{RET}
@end example
@noindent
Then you can give the command:
@example
M-x Info-tagify
@end example
This creates a file which you can validate.@refill
@example
M-x Info-validate
@end example
After you have checked the validity of the nodes, you can either run
@kbd{M-x texinfo-format-buffer} as you would normally, or else tagify and
split the file manually with the two commands @code{Info-tagify} and
@code{Info-split}.@refill
@node Splitting, ,Info-Validating a Large File , Running Info-Validate
@comment node-name, next, previous, up
@subsection Splitting a File Manually
@cindex Splitting an Info file manually
@cindex Info file, splitting manually
If the file has more than 100,000 or so bytes in it, you should split it or
else let the @code{texinfo-format-buffer} command do it for you
automatically. (Generally you will let @code{texinfo-format-buffer} do
this job for you. @xref{Creating an Info File}.)@refill
The split off files are called the indirect subfiles.
Info files are split to save memory. With smaller files, Emacs does not
have make such a large buffer to hold the information. This way, Emacs
can save memory.
If the Info file has more than 30 nodes, you should also make a tag table for
it. @xref{Info-Validating a Large File}, for information about creating a
tag table.
Before running @code{Info-split}, you need to load the @code{info} library
into Emacs by giving the command @kbd{M-x load-library @key{RET} info
@key{RET}}. After you have done this, you can give the two commands:@refill
@example
M-x Info-tagify
M-x Info-split
@end example
@noindent
(Note that the @samp{I} in @samp{Info} is uppercase.)
When you use the @code{Info-split} command, the buffer is modified into a
(small) Info file which lists the indirect subfiles. This file should be
saved in place of the original visited file. The indirect subfiles are
written in the same directory the original file is in, with names generated
by appending @samp{-} and a number to the original file name.
The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.
@c ;;;;;;;;;;;;;;;; Appendix starts here ;;;;;;;;;;;;;;;;
@node Command Syntax, Include Files , Catching Mistakes , Top
@comment node-name, next, previous, up
@appendix @@-Command Syntax
@cindex @@-Command Syntax
The character @samp{@@} is used to start special Texinfo commands. (It has the
same meaning that @samp{\} has in plain @TeX{}.) Syntactically, there
are three classes of @@-commands:
@table @asis
@item 1. Non-alphabetic commands: @@ followed by a punctuation character.
These commands are always part of the text within a paragraph, and
never take any argument. The two characters (@@ and the other one)
are complete in themselves. For example, @code{@@.}, @code{@@:},
@code{@@@{} and @code{@@@}}.@refill
@item 2. Alphabetic commands used within a paragraph.
These commands have @@ followed by a letter or a word, followed by an
argument within braces. For example, the command @code{@@dfn} indicates
the introductory or defining use of a term; it is used as follows: @samp{In
Texinfo, @@-commands are @@dfn@{mark-up@} commands.}@refill
@item 3. Alphabetic commands used outside of paragraphs.
Each such command occupies an entire line. The line starts with @@,
followed by the name of the command (a word) such as @code{@@center} or
@code{@@cindex}. If no argument is needed, the word is followed by the end
of the line. If there is an argument, it is separated from the command
name by a space.@refill
@end table
Thus, the alphabetic commands fall into two classes that have different
argument syntax. You cannot tell which class a command falls in by the
appearance of its name, but you can tell by the command's meaning: if it
makes sense to use the command together with other words as part of a
paragraph, the command is in class 2 and must be followed by an argument in
braces; otherwise, it is in class 3 and uses the rest of the line as its
argument.
The purpose of having different syntax for commands of classes 2 and 3 is
to make the Texinfo file easier to read, and also to help the GNU Emacs
paragraph and filling commands work properly. There is only one exception
to this rule: the command @code{@@refill}, which is always used at the end
of a paragraph immediately following the final period or other punctuation
character. @code{@@refill} takes no argument. @code{@@refill} never
confuses the Emacs paragraph commands because it cannot start at the
beginning of a line.@refill
@node Include Files, TeX Input, Command Syntax, Top
@comment node-name, next, previous, up
@appendix Include Files
@cindex Include files
When Info was first created, it was customary to create many small Info
files on one subject. By doing this, Emacs did not have to make a large
buffer to hold the whole of a large Info file; instead, Emacs allocated
just enough memory for the small Info file that was needed at the time.
This way, Emacs could avoid wasting memory. Include files were designed as
a way to create a single, large printed manual out of several smaller Info
files.
However, because large Info files can now be split, include files are no
longer strictly necessary and they are used infrequently. Most often, they
are now used in projects where several different people are writing
different sections of a document simultaneously.
@appendixsec How Include Files Work
In a Texinfo file, a line of the form @code{@@include @file{filename}} is
ignored when the Info file is generated, but in a printed manual it causes
the contents of the file @file{filename} to be processed and included in the
manual. The contents of the file @file{filename} can be ignored by Info
because the first file can refer to @file{filename} with menus as well as
cross references. In the Info system, all the information is, as it were,
`in one place'. However, when two printed manuals are made from two
separate Texinfo files, the two manuals are separate, and even if they give
each other as references, the references are to separate documents.
Consequently, you will sometimes want to create a comprehensive, printed
manual that contains all the necessary information together in one place.
@code{@@include} files are special Texinfo files that are used only for
making such a comprehensive manual. They are listed inside an outer file
that contains nothing but the beginning and end matter of a Texinfo file
and a number of @code{@@include} commands listing the included files.
An @code{@@include} file--a file that will be listed inside an outer file
and processed with the @code{@@include} command--should not start with
@samp{\input texinfo}, as that has already been done by the outer file, and
the character @samp{\} has already been redefined to generate a backslash
in the output. Instead, an @code{@@include} file usually begins with a
node; it lacks the beginning and ending of a Texinfo file that are
described in the chapters on beginning and ending a file. @xref{Beginning
a File}, and @pxref{Ending a File} @refill
Likewise, an @code{@@include} file should not end with @code{@@bye}, since
that would terminate @TeX{} processing immediately.
Here is an example of a outer Texinfo file with @code{@@include} files
within it:@refill
@example
\input texinfo @@c -*-texinfo-*-
@@setfilename include
@@settitle Include Manual
@@setchapternewpage odd
@@titlepage
@@sp 12
@@center @@titlefont@{Include Manual@}
@@sp 2
@@center by Whom Ever
@@page
Copyright @@copyright@{@} 1988 Free Software Foundation, Inc.
@@end titlepage
@@include foo.texinfo
@@include bar.texinfo
@@unnumbered Concept Index
@@printindex cp
@@summarycontents
@@contents
@@bye
@end example
@node TeX Input, Sample Permissions, Include Files, Top
@comment node-name, next, previous, up
@appendix @TeX{} Input Initialization
@cindex TeX Input Initialization
@cindex TEXINPUTS environment variable
@cindex profile initialization file
@cindex cshrc initialization file
You must put an input command on the first line of every Texinfo file to
tell @TeX{} to use the @file{texinfo.tex} file when it is processing the
Texinfo source file. Otherwise @TeX{} will not know what to do with the
@@-commands. (The @TeX{} input command is written as @samp{\input
texinfo}. @xref{First Line}.)@refill
@TeX{} needs to be told where to find the @file{texinfo.tex} file that you
have told it to input. The preferred way to do this is to put
@file{texinfo.tex} in the default inputs directory, which is the
@file{/usr/lib/tex/macros} directory. If this is done (as it usually is
when GNU Emacs is installed), @TeX{} will find the file and you don't have
to do anything. Alternatively, you can put @file{texinfo.tex} in the
directory in which the Texinfo source file is located.@refill
However, you may want to specify the location of the @code{\input} file
yourself. One way to do this is to write the complete path for the file
after the @code{\input} command. Another way is to set the
@samp{TEXINPUTS} environment variable in your @file{.cshrc} or
@file{.profile} file. The @samp{TEXINPUTS} environment variable will tell
@TeX{} where to find the @file{texinfo.tex} file and any other file that
you might want @TeX{} to use.@refill
Whether you use a @file{.cshrc} or @file{.profile} file depends on whether
you use @samp{csh} or @samp{sh} for your shell command interpreter. When
you use @samp{csh}, it looks to the @file{.cshrc} file for initialization
information, and when you use @samp{sh}, it looks to the @file{.profile}
file.@refill
In a @file{.cshrc} file, you could use the following @code{csh} command
sequence:@refill
@example
setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
@end example
@noindent
In a @file{.profile} file, you could use the following @code{sh} command
sequence:
@example
TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
export TEXINPUTS
@end example
@noindent
This would cause @TeX{} to look for @file{\input} file first in the current
directory, indicated by the @samp{.}, then in a hypothetical user's
@file{me/mylib} directory, and finally in the system library.@refill
@node Sample Permissions, Command Index, TeX Input, Top
@comment node-name, next, previous, up
@appendix Standard text for Copying Permissions
@cindex Permissions
@cindex Copying permissions
Texinfo files should contain sections that tell the readers that they have
the right to copy and distribute the Info file, the printed manual and any
accompanying software. This appendix contains the standard text of the
Free Software Foundation copying permission notice. For an example of the
text that could be used for the Distribution, General Public License and NO
WARRANTY sections of a document, see the latest version of the @cite{GNU
Emacs Manual}.
The texts of the Free Software Foundation copying permission notice in the
@code{@@ifinfo} section and in the @code{@@titlepage} section are slightly
different.
The @code{@@ifinfo} section usually begins with a line that says what the
file documents. This is what a person looking at the file will first read
if he or she reads the unprocessed Texinfo file or if he or she uses the
advanced Info command @kbd{g *}. @inforef{Expert, info, info}, for more
information. (If the reader uses the regular Info commands, he or she will
usually start reading at the first node and skip this first section, which
is not in a node.)
In the @code{@@ifinfo} section, the summary sentence should be followed by
a copyright notice and then by the copying permission notice. One of the
copying permission paragraphs is enclosed in @code{@@ignore} and
@code{@@end ignore} commands. This paragraph states that the Texinfo file
can be processed through @TeX{} and printed, provided the printed manual
carries the proper copying permission notice. This paragraph is not made
part of the Info file since it is not relevant to the Info file; but it is
a mandatory part of the Texinfo file since it permits people to process the
Texinfo file in @TeX{}.@refill
In the printed manual, the Free Software Foundation copying permission
notice follows the copyright notice and publishing information and is
located within the region delineated by the @code{@@titlepage} and
@code{@@end titlepage} commands. The copying permission notice is exactly
the same as the notice in the @code{@@ifinfo} section except that the
paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
not part of the notice.@refill
To make it simpler to copy the permission notice into each section of the
Texinfo file, the complete permission notices for each section are
reproduced in full below even though most of the information is
redundant.@refill
Note that you my have to specify the correct name of a section mentioned in
the permission notice. For example, in the @cite{GDB Manual}, the name of
the section referring to the General Public License is called the ``GDB
General Public License'', but in the sample shown below, that section is
referred to generically as the ``General Public License''.
@menu
* Ifinfo Permissions::
* Titlepage Permissions::
@end menu
@node Ifinfo Permissions, Titlepage Permissions, Sample Permissions, Sample Permissions
@comment node-name, next, previous, up
@appendixsec Ifinfo Copying Permissions
@cindex Ifinfo permissions
In the @code{@@ifinfo} section of the Texinfo file, the standard Free
Software Foundation permission notices reads as follows:
@example
This file documents @dots{}
Copyright 1988 Free Software Foundation, Inc.
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 a 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 also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and 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 the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.
@end example
@node Titlepage Permissions, , Ifinfo Permissions, Sample Permissions
@comment node-name, next, previous, up
@appendixsec Titlepage Copying Permissions
@cindex Titlepage permissions
In the @code{@@titlepage} section of the Texinfo file, the standard Free
Software Foundation copying permission notices follows the copyright notice
and publishing information. The standard phrasing is:
@example
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 also that the
sections entitled ``Distribution'' and ``General Public License'' are
included exactly as in the original, and 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 the sections entitled ``Distribution'' and ``General Public
License'' may be included in a translation approved by the author instead
of in the original English.
@end example
@node Command Index, Concept Index, Sample Permissions, Top
@comment node-name, next, previous, up
@unnumbered Command Index
(When used in a Texinfo file, @@-commands are preceded by an
@samp{@@}.)@refill
@printindex fn
@node Concept Index, , Command Index, Top
@comment node-name, next, previous, up
@unnumbered Concept Index
@printindex cp
@summarycontents
@contents
@bye