info.texi

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

* Tags::                 How to make tag tables for Info files.
* Checking::             Checking an Info File
* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
@end menu

@node Expert, Add,  , Advanced Info
@comment  node-name,  next,  previous,  up
@section Advanced Info Commands

@kbd{g}, @kbd{s}, @kbd{1}, -- @kbd{9}, and @kbd{e}

If you know a node's name, you can go there by typing @kbd{g}, the
name, and @key{RET}.  Thus, @kbd{gTop@key{RET}} would go to the node
called @samp{Top} in this file (its directory node).
@kbd{gExpert@key{RET}} would come back here.

Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.

To go to a node in another file, you can include the filename in the
node name by putting it at the front, in parentheses.  Thus,
@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is
node @samp{Top} in the file @file{dir}.

The node name @samp{*} specifies the whole file.  So you can look at
all of the current file by typing @kbd{g*@key{RET}} or all of any
other file with @kbd{g(FILENAME)@key{RET}}.

The @kbd{s} command allows you to search a whole file for a string.
It switches to the next node if and when that is necessary.  You
type @kbd{s} followed by the string to search for, terminated by
@key{RET}.  To search for the same string again, just @kbd{s} followed
by @key{RET} will do.  The file's nodes are scanned in the order
they are in in the file, which has no necessary relationship to the
order that they may be in in the tree structure of menus and @samp{next} pointers.
But normally the two orders are not very different.  In any case,
you can always do a @kbd{b} to find out what node you have reached, if
the header is not visible (this can happen, because @kbd{s} puts your
cursor at the occurrence of the string, not at the beginning of the
node).

If you grudge the system each character of type-in it requires, you
might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ...
@kbd{9}.  They are short for the @kbd{m} command together with an
argument.  @kbd{1} goes through the first item in the current node's
menu; @kbd{2} goes through the second item, etc.

If you display supports multiple fonts, and you are using Emacs' Info
mode to read Info files, the @samp{*} for the fifth menu item is
underlines, and so is the @samp{*} for the ninth item; these underlines
make it easy to see at a glance which number to use for an item.

On ordinary terminals, you won't have underlining.  If you need to
actually count items, it is better to use @kbd{m} instead, and specify
the name.

The Info command @kbd{e} changes from Info mode to an ordinary
Emacs editing mode, so that you can edit the text of the current node.
Type @kbd{C-c C-c} to switch back to Info.  The @kbd{e} command is allowed
only if the variable @code{Info-enable-edit} is non-@code{nil}.

@node Add, Menus, Expert, Advanced Info
@comment  node-name,  next,  previous,  up
@section Adding a new node to Info

To add a new topic to the list in the Info directory, you must:
@enumerate
@item
Create some nodes, in some file, to document that topic.
@item
Put that topic in the menu in the directory.  @xref{Menus, Menu}.
@end enumerate

Usually, the way to create the nodes is with Texinfo @pxref{Top,, Overview of
Texinfo, texinfo, Texinfo: The GNU Documentation Format}); this has the
advantage that you can also make a printed manual from them.  However,
if hyou want to edit an Info file, here is how.

  The new node can live in an existing documentation file, or in a new
one.  It must have a @key{^_} character before it (invisible to the
user; this node has one but you cannot see it), and it ends with either
a @key{^_}, a @key{^L}, or the end of file.  Note: If you put in a
@key{^L} to end a new node, be sure that there is a @key{^_} after it
to start the next one, since @key{^L} cannot @emph{start} a node.
Also, a nicer way to make a node boundary be a page boundary as well
is to put a @key{^L} @emph{right after} the @key{^_}.

  The @key{^_} starting a node must be followed by a newline or a
@key{^L} newline, after which comes the node's header line.  The
header line must give the node's name (by which Info finds it),
and state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if
there are any).  As you can see, this node's @samp{Up} node is the node
@samp{Top}, which points at all the documentation for Info.  The @samp{Next}
node is @samp{Menus}.

  The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next},
may appear in any order, anywhere in the header line, but the
recommended order is the one in this sentence.  Each keyword must be
followed by a colon, spaces and tabs, and then the appropriate name.
The name may be terminated with a tab, a comma, or a newline.  A space
does not end it; node names may contain spaces.  The case of letters
in the names is insignificant.

  A node name has two forms.  A node in the current file is named by
what appears after the @samp{Node: } in that node's first line.  For
example, this node's name is @samp{Add}.  A node in another file is
named by @samp{(@var{filename})@var{node-within-file}}, as in
@samp{(info)Add} for this node.  If the file name starts with ``./'',
then it is relative to the current directory; otherwise, it is relative
starting from the standard Info file directory of your site.
The name @samp{(@var{filename})Top} can be abbreviated to just
@samp{(@var{filename})}.  By convention, the name @samp{Top} is used for
the ``highest'' node in any single file---the node whose @samp{Up} points
out of the file.  The Directory node is @file{(dir)}.  The @samp{Top} node
of a document file listed in the Directory should have an @samp{Up:
(dir)} in it.

  The node name @kbd{*} is special: it refers to the entire file.
Thus, @kbd{g*} shows you the whole current file.  The use of the
node @kbd{*} is to make it possible to make old-fashioned,
unstructured files into nodes of the tree.

  The @samp{Node:} name, in which a node states its own name, must not
contain a filename, since Info when searching for a node does not
expect one to be there.  The @samp{Next}, @samp{Previous} and @samp{Up} names may
contain them.  In this node, since the @samp{Up} node is in the same file,
it was not necessary to use one.

  Note that the nodes in this file have a file name in the header
line.  The file names are ignored by Info, but they serve as comments
to help identify the node for the user.

@node Menus, Cross-refs, Add, Advanced Info
@comment  node-name,  next,  previous,  up
@section How to Create Menus

  Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. 
The @kbd{m} command searches the current node's menu for the topic which it
reads from the terminal.

  A menu begins with a line starting with @samp{* Menu:}.  The rest of the
line is a comment.  After the starting line, every line that begins
with a @samp{* } lists a single topic.  The name of the topic--the
argument that the user must give to the @kbd{m} command to select this
topic---comes right after the star and space, and is followed by a
colon, spaces and tabs, and the name of the node which discusses that
topic.  The node name, like node names following @samp{Next}, @samp{Previous}
and @samp{Up}, may be terminated with a tab, comma, or newline; it may also
be terminated with a period.

  If the node name and topic name are the same, then rather than
giving the name twice, the abbreviation @samp{* NAME::} may be used
(and should be used, whenever possible, as it reduces the visual
clutter in the menu).

  It is considerate to choose the topic names so that they differ
from each other very near the beginning---this allows the user to type
short abbreviations.  In a long menu, it is a good idea to capitalize
the beginning of each item name which is the minimum acceptable
abbreviation for it (a long menu is more than 5 or so entries).

  The nodes listed in a node's menu are called its ``subnodes'', and
it is their ``superior''.  They should each have an @samp{Up:} pointing at
the superior.  It is often useful to arrange all or most of the
subnodes in a sequence of @samp{Next} and @samp{Previous} pointers so that someone who
wants to see them all need not keep revisiting the Menu.

  The Info Directory is simply the menu of the node @samp{(dir)Top}---that
is, node @samp{Top} in file @file{.../info/dir}.  You can put new entries
in that menu just like any other menu.  The Info Directory is @emph{not} the
same as the file directory called @file{info}.  It happens that many of
Info's files live on that file directory, but they do not have to; and
files on that directory are not automatically listed in the Info
Directory node.

  Also, although the Info node graph is claimed to be a ``hierarchy'',
in fact it can be @emph{any} directed graph.  Shared structures and
pointer cycles are perfectly possible, and can be used if they are
appropriate to the meaning to be expressed.  There is no need for all
the nodes in a file to form a connected structure.  In fact, this file
has two connected components.  You are in one of them, which is under
the node @samp{Top}; the other contains the node @samp{Help} which the
@kbd{h} command goes to.  In fact, since there is no garbage
collector, nothing terrible happens if a substructure is not pointed
to, but such a substructure is rather useless since nobody can
ever find out that it exists.

@node Cross-refs, Tags, Menus, Advanced Info
@comment  node-name,  next,  previous,  up
@section Creating Cross References

  A cross reference can be placed anywhere in the text, unlike a menu
item which must go at the front of a line.  A cross reference looks
like a menu item except that it has @samp{*note} instead of @kbd{*}.
It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are
so often part of node names.  If you wish to enclose a cross reference
in parentheses, terminate it with a period first.  Here are two
examples of cross references pointers:

@example
*Note details: commands.  (See *note 3: Full Proof.)
@end example

They are just examples.  The places they ``lead to'' do not really exist!

@node Tags, Checking, Cross-refs, Advanced Info
@comment  node-name,  next,  previous,  up
@section Tag Tables for Info Files

  You can speed up the access to nodes of a large Info file by giving
it a tag table.  Unlike the tag table for a program, the tag table for
an Info file lives inside the file itself and is used 
automatically whenever Info reads in the file.

  To make a tag table, go to a node in the file using Emacs Info mode and type
@kbd{M-x Info-tagify}.  Then you must use @kbd{C-x C-s} to save the
file.

  Once the Info file has a tag table, you must make certain it is up
to date.  If, as a result of deletion of text, any node moves back
more than a thousand characters in the file from the position
recorded in the tag table, Info will no longer be able to find that
node.  To update the tag table, use the @code{Info-tagify} command again.

  An Info file tag table appears at the end of the file and looks like
this:

@example
^_
Tag Table:
File: info, Node: Cross-refs^?21419
File: info,  Node: Tags^?22145
^_
End Tag Table
@end example

@noindent
Note that it contains one line per node, and this line contains
the beginning of the node's header (ending just after the node name),
a Delete character, and the character position in the file of the
beginning of the node.

@node Checking, Emacs Info Variables, Tags, Advanced Info
@comment  node-name,  next,  previous,  up
@section Checking an Info File

  When creating an Info file, it is easy to forget the name of a node
when you are making a pointer to it from another node.  If you put in
the wrong name for a node, this is not detected until someone
tries to go through the pointer using Info.  Verification of the Info
file is an automatic process which checks all pointers to nodes and
reports any pointers which are invalid.  Every @samp{Next}, @samp{Previous}, and
@samp{Up} is checked, as is every menu item and every cross reference.  In
addition, any @samp{Next} which does not have a @samp{Previous} pointing back is
reported.  Only pointers within the file are checked, because checking
pointers to other files would be terribly slow.  But those are usually
few.

  To check an Info file, do @kbd{M-x Info-validate} while looking at
any node of the file with Emacs Info mode.

@node Emacs Info Variables, , Checking, Advanced Info
@section Emacs Info-mode Variables

The following variables may modify the behaviour of Info-mode in Emacs;
you may wish to set one or several of these variables interactively, or
in your @file{~/.emacs} init file.  @xref{Examining, Examining and Setting
Variables, Examining and Setting Variables, emacs, The GNU Emacs
Manual}.

@vtable @code
@item Info-enable-edit
Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command.  A
non-@code{nil} value enables it.  @xref{Add, Edit}.

@item Info-enable-active-nodes
When set to a non-@code{nil} value, allows Info to execute Lisp code
associated with nodes.  The Lisp code is executed when the node is
selected.

@item Info-directory-list
The list of directories to search for Info files.  Each element is a
string (directory name) or @code{nil} (try default directory).

@item Info-directory
The standard directory for Info documentation files.  Only used when the
function @code{Info-directory} is called.
@end vtable

@node Create an Info File,  , Advanced Info, Top
@comment  node-name,  next,  previous,  up
@chapter Creating an Info File from a Makeinfo file

@code{makeinfo} is a utility that converts a Texinfo file into an Info
file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
GNU Emacs functions that do the same.

@xref{Create an Info File, , Creating an Info File, texinfo, the Texinfo
Manual}, to learn how to create an Info file from a Texinfo file.

@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation
Format}, to learn how to write a Texinfo file.

@bye