texinfo.texinfo

早期freebsd实现

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