comparison man/info.texi @ 44785:a59fec4b6783

Rename Advanced Info to Expert Info. Rename Expert to Advanced. Fix many small errors.

44784:8180d4f92b70

@settitle Info
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
@comment $Id: info.texi,v 1.19 2002/03/16 19:32:15 eliz Exp $

@dircategory Texinfo documentation system
@direntry
* Info: (info).         How to use the documentation browsing system.
@end direntry

@ifinfo
If you are new to Info and want to learn how to use it, type the
command @kbd{h} now.  It brings you to a programmed instruction
sequence.

To learn advanced Info commands, type @kbd{n} twice.  This brings you to
@cite{Info for Experts}, skipping over the `Getting Started' chapter.
@end ifinfo
@end ifnottex

@menu
* Getting Started::             Getting started using an Info reader.
* Advanced Info::               Advanced commands within Info.
* Creating an Info File::       How to make your own Info file.
* Index::                       An index of topics, commands, and variables.
@end menu

@node Getting Started, Advanced Info, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Started

This first part of the Info manual describes how to get around inside
of Info.  The second part of the manual describes various advanced

@node Help-^L, Help-M, Help-P, Getting Started
@comment  node-name,  next,  previous,  up
@section The Space, DEL, B and ^L commands.

  This node's mode line tells you that you are now at node @samp{Help-^L},
and the header line tells you that @kbd{p} would get you back to
@samp{Help-P}.  The node's title is underlined; it says what the node
is about (most nodes have titles).

  This is a big node and it does not all fit on your display screen.
You can tell that there is more that is not visible because you
can see the string @samp{--Top-----} rather than @samp{--All----} near
the bottom right corner of the screen.

@format
>> Try that now.  (We have put in enough verbiage to push this past
   the first screenful, but screens are so big nowadays that perhaps it
   isn't enough.  You may need to shrink your Emacs or Info window.)
   Then come back, with @key{SPS}s.
@end format

  If your screen is very tall, all of this node might fit at once.
In that case, @kbd{b} won't do anything.  Sorry; what can we do?

subtopic.  Lines in the menu that do not start with a @samp{*} have no
special meaning---they are only for the human reader's benefit and do
not define additional subtopics.  Here is an example:

@example
* Foo:  Node about FOO      This tells about FOO
@end example

The subtopic name is Foo, and the node describing it is @samp{Node
about FOO}.  The rest of the line is just for the reader's
Information.  [[ But this line is not a real menu item, simply because

specify.  Often the node name is convenient for the user to specify
and so both it and the subtopic name are the same.  There is an
abbreviation for this:

@example
* Foo::   This tells about FOO
@end example

@noindent
This means that the subtopic name and node name are the same; they are
both @samp{Foo}.

do that, one node-step at a time.  As you move from node to node, Info
records the nodes where you have been in a special history list.  The
@kbd{l} command revisits nodes in the history list; each successive
@kbd{l} command moves one step back through the history.

  If you have been following directions, ad @kbd{l} command now will get
you back to @samp{Help-M}.  Another @kbd{l} command would undo the
@kbd{u} and get you back to @samp{Help-FOO}.  Another @kbd{l} would undo
the @kbd{m} and get you back to @samp{Help-M}.

  In Emacs, @kbd{l} runs the command @code{Info-last}.

@format
>> Now type @kbd{n} to see the last node of the course.
@end format

  @xref{Advanced Info}, for more advanced Info features.

@c If a menu appears at the end of this node, remove it.
@c It is an accident of the menu updating command.

@node Advanced Info
@chapter Info for Experts

  This chapter describes various advanced Info commands.  (If you are
using a stand-alone Info reader, there are additional commands
specific to it, which are documented in several chapters of @ref{Top,,
GNU Info, info-stnd, GNU Info}.)

  This chapter also explains how to write an Info as distinct from a
Texinfo file.  (However, in most cases, writing a Texinfo file is
better, since you can use it @emph{both} to generate an Info file and
to make a printed manual.  @xref{Top,, Overview of Texinfo, texinfo,
Texinfo: The GNU Documentation Format}.)

@menu
* Expert::               Advanced Info commands: g, s, e, and 1 - 5.
* Info Search::          How to search Info documents for specific subjects.
* Add::                  Describes how to add new nodes to the hierarchy.
                           Also tells what nodes look like.
* Menus::                How to add to or create menus in Info nodes.
* Cross-refs::           How to add cross-references to Info nodes.
* Tags::                 How to make tags tables for Info files.
* Checking::             Checking an Info File
* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
@end menu

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

Here are some more Info commands that make it easier to move around.

@findex Info-goto-node
@cindex go to a node by name
  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.  (This is equivalent to @kbd{t}, see
@ref{Help-Int}.)  @kbd{gExpert@key{RET}} would come back here.
@kbd{g} in Emacs runs the command @code{Info-goto-node}.

  Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
But it does allow completion, so you can type @key{TAB} to complete a
partial node name.

  The @kbd{e} command only works in Emacs, where it runs the command
@code{Info-edit}.  The stand-alone Info reader doesn't allow you to
edit the Info file, so typing @kbd{e} there goes to the end of the
current node.

@node Info Search, Add, Expert, Advanced Info
@comment  node-name,  next,  previous,  up
@section How to search Info documents for specific subjects

@cindex searching Info documents
@cindex Info document as a reference

compatibility with other GNU packages that use @kbd{M-s} for a similar
kind of search command.  Both @kbd{s} and @kbd{M-s} run in Emacs the
command @code{Info-search}.


@node Add, Menus, Info Search, 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:

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 you want to edit an Info file, here is how.

@cindex node delimiters
  The new node can live in an existing documentation file, or in a new
one.  It must have a @samp{^_} character before it (invisible to the
user; this node has one but you cannot see it), and it ends with either

@emph{start} a node.  Also, a nicer way to make a node boundary be a
page boundary as well is to put a @samp{^L} @emph{right after} the
@samp{^_}.}

  The @samp{^_} starting a node must be followed by a newline or a
@samp{^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}.

@cindex node header line format
@cindex format of node headers
  The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up}
may appear in any order, anywhere in the header line, but the

  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

@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

@cindex cross reference format
  A cross reference can be placed anywhere in the text, unlike a menu

references.  This makes you ready for reading manuals top to bottom,
as new users should do when they learn a new package.

  Another set of Info commands is useful when you need to find
something quickly in a manual---that is, when you need to use a manual
as a reference rather than as a tutorial.  We urge you to make learn
these search commands as well.  If you want to do that now, follow this
cross reference to @ref{Info Search}.

Yet another set of commands are meant for experienced users; you can
find them by looking in the Directory node for documentation on Info.

   @kbd{mInfo} and Return, to get to the node about Info and
   see what other help is available.
@end format


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

@cindex tags tables in info files
  You can speed up the access to nodes of a large Info file by giving

the beginning of the node's header (ending just after the node name),
a @samp{DEL} character, and the character position in the file of the
beginning of the node.


@node Checking, Emacs Info Variables, Tags, Advanced Info
@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

@findex Info-validate
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 behavior 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

44785:a59fec4b6783

@settitle Info
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@comment %**end of header
@comment $Id: info.texi,v 1.20 2002/03/18 06:45:49 eliz Exp $

@dircategory Texinfo documentation system
@direntry
* Info: (info).         How to use the documentation browsing system.
@end direntry

@ifinfo
If you are new to Info and want to learn how to use it, type the
command @kbd{h} now.  It brings you to a programmed instruction
sequence.

To learn expert-level Info commands, type @kbd{n} twice.  This brings you to
@cite{Info for Experts}, skipping over the `Getting Started' chapter.
@end ifinfo
@end ifnottex

@menu
* Getting Started::             Getting started using an Info reader.
* Expert Info::                 Info commands for experts.
* Creating an Info File::       How to make your own Info file.
* Index::                       An index of topics, commands, and variables.
@end menu

@node Getting Started, Expert Info, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Getting Started

This first part of the Info manual describes how to get around inside
of Info.  The second part of the manual describes various advanced

@node Help-^L, Help-M, Help-P, Getting Started
@comment  node-name,  next,  previous,  up
@section The Space, DEL, B and ^L commands.

  This node's mode line tells you that you are now at node
@samp{Help-^L}, and the header line tells you that @kbd{p} would get
you back to @samp{Help-P}.  The node's title is highlighted and may be
underlined as well; it says what the node is about.

  This is a big node and it does not all fit on your display screen.
You can tell that there is more that is not visible because you
can see the string @samp{--Top-----} rather than @samp{--All----} near
the bottom right corner of the screen.

@format
>> Try that now.  (We have put in enough verbiage to push this past
   the first screenful, but screens are so big nowadays that perhaps it
   isn't enough.  You may need to shrink your Emacs or Info window.)
   Then come back, by typing @key{SPC} one or more times.
@end format

  If your screen is very tall, all of this node might fit at once.
In that case, @kbd{b} won't do anything.  Sorry; what can we do?

subtopic.  Lines in the menu that do not start with a @samp{*} have no
special meaning---they are only for the human reader's benefit and do
not define additional subtopics.  Here is an example:

@example
* Foo:  Node about FOO.      This tells about FOO.
@end example

The subtopic name is Foo, and the node describing it is @samp{Node
about FOO}.  The rest of the line is just for the reader's
Information.  [[ But this line is not a real menu item, simply because

specify.  Often the node name is convenient for the user to specify
and so both it and the subtopic name are the same.  There is an
abbreviation for this:

@example
* Foo::   This tells about FOO.
@end example

@noindent
This means that the subtopic name and node name are the same; they are
both @samp{Foo}.

do that, one node-step at a time.  As you move from node to node, Info
records the nodes where you have been in a special history list.  The
@kbd{l} command revisits nodes in the history list; each successive
@kbd{l} command moves one step back through the history.

  If you have been following directions, an @kbd{l} command now will get
you back to @samp{Help-M}.  Another @kbd{l} command would undo the
@kbd{u} and get you back to @samp{Help-FOO}.  Another @kbd{l} would undo
the @kbd{m} and get you back to @samp{Help-M}.

  In Emacs, @kbd{l} runs the command @code{Info-last}.

@format
>> Now type @kbd{n} to see the last node of the course.
@end format

  @xref{Expert Info}, for more advanced Info features.

@c If a menu appears at the end of this node, remove it.
@c It is an accident of the menu updating command.

@node Expert Info
@chapter Info for Experts

  This chapter describes various Info commands for experts.  (If you
are using a stand-alone Info reader, there are additional commands
specific to it, which are documented in several chapters of @ref{Top,,
GNU Info, info-stnd, GNU Info}.)

  This chapter also explains how to write an Info as distinct from a
Texinfo file.  (However, in most cases, writing a Texinfo file is
better, since you can use it to make a printed manual or an HTML file
as well as for generating Info files.)  @xref{Top,, Overview of
Texinfo, texinfo, Texinfo: The GNU Documentation Format}.)

@menu
* Advanced::             Advanced Info commands: g, s, e, and 1 - 5.
* Info Search::          How to search Info documents for specific subjects.
* Add::                  Describes how to add new nodes to the hierarchy.
                           Also tells what nodes look like.
* Menus::                How to add to or create menus in Info nodes.
* Cross-refs::           How to add cross-references to Info nodes.
* Tags::                 How to make tags tables for Info files.
* Checking::             Checking an Info File
* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
@end menu

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

Here are some more Info commands that make it easier to move around.

@findex Info-goto-node
@cindex go to a node by name
  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.  (This is equivalent to @kbd{t}, see
@ref{Help-Int}.)  @kbd{gAdvanced{RET}} would come back here.
@kbd{g} in Emacs runs the command @code{Info-goto-node}.

  Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations.
But it does allow completion, so you can type @key{TAB} to complete a
partial node name.

  The @kbd{e} command only works in Emacs, where it runs the command
@code{Info-edit}.  The stand-alone Info reader doesn't allow you to
edit the Info file, so typing @kbd{e} there goes to the end of the
current node.

@node Info Search, Add, Advanced, Expert Info
@comment  node-name,  next,  previous,  up
@section How to search Info documents for specific subjects

@cindex searching Info documents
@cindex Info document as a reference

compatibility with other GNU packages that use @kbd{M-s} for a similar
kind of search command.  Both @kbd{s} and @kbd{M-s} run in Emacs the
command @code{Info-search}.


@node Add, Menus, Info Search, Expert 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:

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 or HTML
from them.  You would use the @samp{@@dircategory} and
@samp{@@direntry} commands to put the manual into the Info directory.
However, if you want to edit an Info file manually and install it
manually, here is how.

@cindex node delimiters
  The new node can live in an existing documentation file, or in a new
one.  It must have a @samp{^_} character before it (invisible to the
user; this node has one but you cannot see it), and it ends with either

@emph{start} a node.  Also, a nicer way to make a node boundary be a
page boundary as well is to put a @samp{^L} @emph{right after} the
@samp{^_}.}

  The @samp{^_} starting a node must be followed by a newline or a
@samp{^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{Expert Info}.  The @samp{Next} node is @samp{Menus}.

@cindex node header line format
@cindex format of node headers
  The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up}
may appear in any order, anywhere in the header line, but the

  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, Expert 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

@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, Expert Info
@comment  node-name,  next,  previous,  up
@section Creating Cross References

@cindex cross reference format
  A cross reference can be placed anywhere in the text, unlike a menu

references.  This makes you ready for reading manuals top to bottom,
as new users should do when they learn a new package.

  Another set of Info commands is useful when you need to find
something quickly in a manual---that is, when you need to use a manual
as a reference rather than as a tutorial.  We urge you to learn
these search commands as well.  If you want to do that now, follow this
cross reference to @ref{Info Search}.

Yet another set of commands are meant for experienced users; you can
find them by looking in the Directory node for documentation on Info.

   @kbd{mInfo} and Return, to get to the node about Info and
   see what other help is available.
@end format


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

@cindex tags tables in info files
  You can speed up the access to nodes of a large Info file by giving

the beginning of the node's header (ending just after the node name),
a @samp{DEL} character, and the character position in the file of the
beginning of the node.


@node Checking, Emacs Info Variables, Tags, Expert Info
@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

@findex Info-validate
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, Expert Info
@section Emacs Info-mode Variables

The following variables may modify the behavior 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