texinfo.texinfo

早期freebsd实现

@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
                                  |
                                  |