texinfo.texi

gcc-2.95.3 Linux下最常用的C编译器

* Sample Include File::         A sample outer file with included files
                                  within it; and a sample included file.
* Include Files Evolution::     How use of the @code{@@include} command
                                  has changed over time.

Page Headings

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

Formatting Mistakes

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

Finding Badly Referenced Nodes

* Using Info-validate::         How to run @code{Info-validate}.
* Unsplit::                     How to create an unsplit file.
* Tagifying::                   How to tagify a file.
* Splitting::                   How to split a file manually.

How to Obtain @TeX{}

* New Texinfo Mode Commands::   The updating commands are especially useful.
* New Commands::                Many newly described @@-commands.
@end detailmenu
@end menu

@node Copying, Overview, Top, Top
@comment  node-name, next, previous,  up
@unnumbered Texinfo Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying Texinfo

The programs currently being distributed that relate to Texinfo include
portions of GNU Emacs, plus other separate programs (including
@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
These programs are @dfn{free}; this means that everyone is free to use
them and free to redistribute them on a free basis.  The Texinfo-related
programs are not in the public domain; they are copyrighted and there
are restrictions on their distribution, but these restrictions are
designed to permit everything that a good cooperating citizen would want
to do.  What is not allowed is to try to prevent others from further
sharing any version of these programs that they might get from
you.@refill

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

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

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

  The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
Licenses that accompany them.@refill

@node Overview, Texinfo Mode, Copying, Top
@comment  node-name,  next,  previous,  up
@chapter Overview of Texinfo
@cindex Overview of Texinfo
@cindex Texinfo overview

@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is
pronounced like ``speck'', not ``hex''.  This odd pronunciation is
derived from, but is not the same as, the pronunciation of @TeX{}.  In
the word @TeX{}, the @samp{X} is actually the Greek letter ``chi''
rather than the English letter ``ex''.  Pronounce @TeX{} as if the
@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
as if the @samp{x} were a `k'.  Spell ``Texinfo'' with a capital ``T''
and write the other letters in lower case.}
is a documentation system that uses a single source file to produce both
on-line information and printed output.  This means that instead of
writing two different documents, one for the on-line help or other on-line
information and the other for a typeset manual or other printed work, you
need write only one document.  When the work is revised, you need revise
only one document.  (You can read the on-line information, known as an
@dfn{Info file}, with an Info documentation-reading program.)@refill

@menu
* Using Texinfo::               Create a conventional printed book
                                  or an Info file.
* Info Files::                  What is an Info file?
* Printed Books::               Characteristics of a printed book or manual.
* Formatting Commands::         @@-commands are used for formatting.
* Conventions::                 General rules for writing a Texinfo file.
* Comments::                    How to write comments and mark regions that
                                  the formatting commands will ignore.
* Minimum::                     What a Texinfo file must have.
* Six Parts::                   Usually, a Texinfo file has six parts.
* Short Sample::                A short sample Texinfo file.
* Acknowledgements::            
@end menu

@node Using Texinfo, Info Files, Overview, Overview
@ifinfo
@heading Using Texinfo
@end ifinfo

Using Texinfo, you can create a printed document with the normal
features of a book, including chapters, sections, cross references,
and indices.  From the same Texinfo source file, you can create a
menu-driven, on-line Info file with nodes, menus, cross references,
and indices.  You can, if you wish, make the chapters and sections of
the printed document correspond to the nodes of the on-line
information; and you use the same cross references and indices for
both the Info file and the printed work.  @cite{The GNU
Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill

To make a printed document, you process a Texinfo source file with the
@TeX{} typesetting program.  This creates a DVI file that you can
typeset and print as a book or report.  (Note that the Texinfo language
is completely different from @TeX{}'s usual language, plain @TeX{}.)  If
you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you
can use the @code{texi2roff} program instead.@refill

To make an Info file, you process a Texinfo source file with the
@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command;
this creates an Info file that you can install on-line.@refill

@TeX{} and @code{texi2roff} work with many types of printers; similarly,
Info works with almost every type of computer terminal.  This power
makes Texinfo a general purpose system, but brings with it a constraint,
which is that a Texinfo file may contain only the customary
``typewriter'' characters (letters, numbers, spaces, and punctuation
marks) but no special graphics.@refill

A Texinfo file is a plain @sc{ascii} file containing text and
@dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
typesetting and formatting programs what to do.  You may edit a
Texinfo file with any text editor; but it is especially convenient to
use GNU Emacs since that editor has a special mode, called Texinfo
mode, that provides various Texinfo-related features.  (@xref{Texinfo
Mode}.)@refill

Before writing a Texinfo source file, you should become familiar with
the Info documentation reading program and learn about nodes,
menus, cross references, and the rest.  (@inforef{Top, info, info},
for more information.)@refill

You can use Texinfo to create both on-line help and printed manuals;
moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
is the format in which documentation for GNU utilities and libraries is
written.@refill

@node Info Files, Printed Books, Using Texinfo, Overview
@comment  node-name,  next,  previous,  up
@section Info files
@cindex Info files

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

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

@ifinfo
@inforef{Top, info, info}, for more information about using Info.@refill
@end ifinfo

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

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

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

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

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

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

If you want to read through an Info file in sequence, as if it were a
printed manual, you can hit @key{SPC} repeatedly, or you get the whole
file with the advanced Info command @kbd{g *}.  (@inforef{Expert,
Advanced Info commands, info}.)@refill

@c !!! dir file may be located in one of many places:
@c     /usr/local/emacs/info            mentioned in info.c DEFAULT_INFOPATH
@c     /usr/local/lib/emacs/info        mentioned in info.c DEFAULT_INFOPATH
@c     /usr/gnu/info                    mentioned in info.c DEFAULT_INFOPATH
@c     /usr/local/info
@c     /usr/local/lib/info
The @file{dir} file in the @file{info} directory serves as the
departure point for the whole Info system.  From it, you can reach the
`Top' nodes of each of the documents in a complete Info system.@refill

@node Printed Books, Formatting Commands, Info Files, Overview
@comment  node-name,  next,  previous,  up
@section Printed Books
@cindex Printed book and manual characteristics
@cindex Manual characteristics, printed
@cindex Book characteristics, printed
@cindex Texinfo printed book characteristics
@cindex Characteristics, printed books or manuals

@cindex Knuth, Donald
A Texinfo file can be formatted and typeset as a printed book or manual.
To do this, you need @TeX{}, a powerful, sophisticated typesetting
program written by Donald Knuth.@footnote{You can also use the
@code{texi2roff} program if you do not have @TeX{}; since Texinfo is
designed for use with @TeX{}, @code{texi2roff} is not described here.
@code{texi2roff} is not part of the standard GNU distribution.}

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

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

@TeX{} is a general purpose typesetting program.  Texinfo provides a
file called @file{texinfo.tex} that contains information (definitions or
@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
to @TeX{} commands, which @TeX{} can then process to create the typeset
document.)  @file{texinfo.tex} contains the specifications for printing
a document.@refill

Most often, documents are printed on 8.5 inch by 11 inch
pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper
(@code{@@afourpaper}).  (@xref{smallbook, , Printing ``Small'' Books}.
Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill

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

@TeX{} is freely distributable.  It is written in a superset of Pascal
called WEB and can be compiled either in Pascal or (by using a
conversion program that comes with the @TeX{} distribution) in C.
(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
about @TeX{}.)@refill

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