comparison man/info.texi @ 83532:b19aaf4ab0ee

Merged from [e-mail]. Patches applied: * [e-mail]/emacs--devo--0--patch-331 Update from CVS * [e-mail]/emacs--devo--0--patch-332 Update from CVS * [e-mail]/emacs--devo--0--patch-333 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-334 Update from CVS * [e-mail]/emacs--devo--0--patch-335 Add note about "link" button-class to etc/TODO * [e-mail]/emacs--devo--0--patch-336 Update from CVS * [e-mail]/emacs--devo--0--patch-337 Update from CVS * [e-mail]/emacs--devo--0--patch-338 Update from CVS * [e-mail]/emacs--devo--0--patch-339 Update from CVS * [e-mail]/emacs--devo--0--patch-340 Update from CVS * [e-mail]/emacs--devo--0--patch-341 Update from CVS * [e-mail]/emacs--devo--0--patch-342 Update from CVS * [e-mail]/emacs--devo--0--patch-343 Update from CVS * [e-mail]/emacs--devo--0--patch-344 Update from CVS * [e-mail]/emacs--devo--0--patch-345 Update from CVS * [e-mail]/emacs--devo--0--patch-346 Update from CVS * [e-mail]/emacs--devo--0--patch-347 Update from CVS * [e-mail]/emacs--devo--0--patch-348 Update for ERC 5.1.3. * [e-mail]/emacs--devo--0--patch-349 Update from CVS * [e-mail]/emacs--devo--0--patch-350 Merge from gnus--rel--5.10 * [e-mail]/gnus--rel--5.10--patch-111 Update from CVS: texi/gnus.texi (Summary Buffer Lines): Fix typo. * [e-mail]/gnus--rel--5.10--patch-112 Update from CVS * [e-mail]/gnus--rel--5.10--patch-113 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-114 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-572

83531:a387c138b28e

@cindex small screen, moving around
Since your terminal has a relatively small number of lines on its
screen, it is necessary to give you special advice at the beginning.

If you see the text @samp{--All----} near the bottom right corner
of the screen, it means the entire text you are looking at fits on the
screen.  If you see @samp{--Top----} instead, it means that there is
more text below that does not fit.  To move forward through the text
and see another screen full, press @key{SPC}, the Space bar.  To move
back up, press the key labeled @samp{Backspace} or @samp{DEL} (on some
keyboards, this key might be labeled @samp{Delete}).

@ifinfo
Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and
see what they do.  At the end are instructions of what you should do
next.

  The top line of a node is its @dfn{header}.  This node's header
(look at it now) says that the @samp{Next} node after this one is the
node called @samp{Help-P}.  An advanced Info command lets you go to
any node whose name you know.  In the stand-alone Info reader program,
the header line shows the names of this node and the Info file as
well.  In Emacs, the header line is duplicated in a special typeface,
and the duplicate remains at the top of the window all the time even
if you scroll through the node.

  Besides a @samp{Next}, a node can have a @samp{Previous} link, or an
@samp{Up} link, or both.  As you can see, this node has all of these
links.

@noindent
@samp{>>} in the margin means it is really time to try a command.

@format
>> If you are in Emacs and have a mouse, and if you already practiced
   typing @kbd{n} to get to the next node, click now with the middle
   mouse button on the @samp{Next} link to do the same ``the mouse way''.
@end format

@node Help-P, Help-^L, Help, Getting Started
@comment  node-name,  next,  previous,  up

command.  Another @kbd{n} command now would take you to the next
node, @samp{Help-^L}.

@format
>> But do not type @kbd{n} yet.  First, try the @kbd{p} command, or
   (in Emacs) click the middle mouse button on the @samp{Prev} link.
   That takes you to the @samp{Previous} node.  Then use @kbd{n} to
   return here.
@end format

  If you read this in Emacs, you will see an @samp{Info} item in the
menu bar, close to its right edge.  Clicking the mouse on the
@samp{Info} menu-bar item opens a menu of commands which include

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.

@kindex SPC @r{(Info mode)}
@kindex DEL @r{(Info mode)}
@kindex BACKSPACE @r{(Info mode)}
@findex Info-scroll-up

   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.  But you could observe the
effect of the @kbd{b} key if you use a smaller window.

@kindex ? @r{(Info mode)}
@findex Info-summary
  You have just learned a considerable number of commands.  If you
want to use one but have trouble remembering which, you should type
a @kbd{?} (in Emacs it runs the @code{Info-summary} command) which
displays a brief list of commands.  When you are finished looking at
the list, make it go away by typing a @key{SPC} repeatedly.

@format
>> Type a @key{?} now.  Press @key{SPC} to see consecutive screenfuls of
   the list until finished.  Then type @key{SPC} several times.  If
   you are using Emacs, the help will then go away automatically.

@findex Info-menu
  The command to go to a subnode via a menu is @kbd{m}.  After you type
the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
You must then type the name of the subtopic you want, and end it with
a @key{RET}.  In Emacs, @kbd{m} runs the command @code{Info-menu}.

@cindex abbreviating Info subnodes
  You can abbreviate the subtopic name.  If the abbreviation is not
unique, the first matching subtopic is chosen.  Some menus put
the shortest possible abbreviation for each subtopic name in capital

usually used to ``stay on the same level but go backwards''.

@kindex u @r{(Info mode)}
@findex Info-up
  You can go back to the node @samp{Help-M} by typing the command
@kbd{u} for ``Up'' (the Emacs command run by @kbd{u} is
@code{Info-up}).  That puts you at the @emph{front} of the node---to
get back to where you were reading you have to type some @key{SPC}s.
(Some Info readers, such as the one built into Emacs, put you at the
menu subtopic line which points to the subnode that the @kbd{u} command
brought you from.)

  Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up}
pointer shown in the header line (provided that you have a mouse).

@format

points to the node named @samp{Help-Cross}.  (The node name is hidden
in Emacs.  Do @kbd{M-x visible-mode} to show or hide it.)

@kindex f @r{(Info mode)}
@findex Info-follow-reference
  There are two ways to follow a cross reference.  You can move the
cursor to it and press @key{RET}, just as in a menu.  @key{RET}
follows the cross reference that the cursor is on.  Or you can type
@kbd{f} and then specify the name of the cross reference (in this
case, @samp{Cross}) as an argument.  In Emacs Info, @kbd{f} runs
@code{Info-follow-reference},

  In the @kbd{f} command, you select the cross reference with its
name, so it does not matter where the cursor was.  If the cursor is on
or near a cross reference, @kbd{f} suggests that reference name in
parentheses as the default; typing @key{RET} will follow that
reference.  However, if you type a different reference name, @kbd{f}
will follow the other reference which has that name.

@format
>> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}.
@end format

@end format

  The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys,
which move between menu items in a menu, also move between cross
references outside of menus.

  Clicking @kbd{Mouse-2} on or near a cross reference also follows the
reference.  You can see that the cross reference is mouse-sensitive by
moving the mouse pointer to the reference and watching how the
underlying text and the mouse pointer change in response.

  Sometimes a cross reference (or a node) can lead to another file (in
other words another ``manual''), or, on occasion, even a file on a
remote machine (although Info files distributed with Emacs or the
stand-alone Info avoid using remote links).  Such a cross reference

retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
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.

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

@format
>> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between
to see what each @kbd{l} does.  You should wind up right back here.
@end format

@kindex C-r @r{(Info mode)}
@findex isearch
  Instead of using @kbd{s} in Emacs Info and in the stand-alone Info,
you can use an incremental search started with @kbd{C-s} or @kbd{C-r}.
It can search through multiple Info nodes.  @xref{Incremental Search,,,
emacs, The GNU Emacs Manual}.  In Emacs, this behavior is enabled only
if the variable @code{Info-isearch-search} is non-@code{nil}
(@pxref{Emacs Info Variables}).

@node Search Index, Go to node, Search Text, Advanced
@comment  node-name,  next,  previous,  up
@section How to search the indices for specific subjects

looking for a description of a command, an option, or a key, just type
their names when @kbd{i} prompts you for a topic.  For example, if you
want to read the description of what the @kbd{C-l} key does, type
@kbd{iC-l@key{RET}} literally.

  In Emacs, @kbd{i} runs the command @code{Info-index}.

@findex info-apropos
@findex index-apropos
If you aren't sure which manual documents the topic you are looking
for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x
index-apropos} command in the stand-alone reader.  It prompts for

@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{gGo to node@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.

you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4},
@dots{}, @kbd{9}.  They are short for the @kbd{m} command together
with a name of a menu subtopic.  @kbd{1} goes through the first item
in the current node's menu; @kbd{2} goes through the second item, etc.
In the stand-alone reader, @kbd{0} goes through the last menu item;
this is so you need not count how many entries are there.  In Emacs,
the digit keys run the command @code{Info-nth-menu-item}.

  If your display supports multiple fonts, colors or underlining, and
you are using Emacs' Info mode to read Info files, the third, sixth
and ninth menu items have a @samp{*} that stands out, either in color
or in some other attribute, such as underline; this makes it easy to

@kindex M-n @r{(Info mode)}
@findex clone-buffer
@cindex multiple Info buffers
  If you are reading Info in Emacs, you can select a new independent
Info buffer in the same window by typing @kbd{M-n}.  The new buffer
starts out as an exact copy of the old one, but you will be able to
move independently between nodes in the two buffers.  (In Info mode,
@kbd{M-n} runs the Emacs command @code{clone-buffer}.)

  In Emacs Info, you can also produce new Info buffers by giving a

@node Emacs Info Variables, , Create Info buffer, Advanced
@comment  node-name,  next,  previous,  up
@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
Variables, Examining and Setting Variables, emacs, The GNU Emacs
Manual}.  The stand-alone Info reader program has its own set of
variables, described in @ref{Variables,, Manipulating Variables,
info-stnd, GNU Info}.

83532:b19aaf4ab0ee

@cindex small screen, moving around
Since your terminal has a relatively small number of lines on its
screen, it is necessary to give you special advice at the beginning.

If the entire text you are looking at fits on the screen, the text
@samp{All} will be displayed at the bottom of the screen.  In the
stand-alone Info reader, it is displayed at the bottom right corner of
the screen; in Emacs, it is displayed on the modeline.  If you see the
text @samp{Top} instead, it means that there is more text below that
does not fit.  To move forward through the text and see another screen
full, press @key{SPC}, the Space bar.  To move back up, press the key
labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key
might be labeled @samp{Delete}).

@ifinfo
Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and
see what they do.  At the end are instructions of what you should do
next.

  The top line of a node is its @dfn{header}.  This node's header
(look at it now) says that the @samp{Next} node after this one is the
node called @samp{Help-P}.  An advanced Info command lets you go to
any node whose name you know.  In the stand-alone Info reader program,
the header line shows the names of this node and the Info file as
well.  In Emacs, the header line is displayed with a special typeface,
and remains at the top of the window all the time even if you scroll
through the node.

  Besides a @samp{Next}, a node can have a @samp{Previous} link, or an
@samp{Up} link, or both.  As you can see, this node has all of these
links.

@noindent
@samp{>>} in the margin means it is really time to try a command.

@format
>> If you are in Emacs and have a mouse, and if you already practiced
   typing @kbd{n} to get to the next node, click now with the left 
   mouse button on the @samp{Next} link to do the same ``the mouse way''.
@end format

@node Help-P, Help-^L, Help, Getting Started
@comment  node-name,  next,  previous,  up

command.  Another @kbd{n} command now would take you to the next
node, @samp{Help-^L}.

@format
>> But do not type @kbd{n} yet.  First, try the @kbd{p} command, or
   (in Emacs) click on the @samp{Prev} link.  That takes you to
   the @samp{Previous} node.  Then use @kbd{n} to return here.
@end format

  If you read this in Emacs, you will see an @samp{Info} item in the
menu bar, close to its right edge.  Clicking the mouse on the
@samp{Info} menu-bar item opens a menu of commands which include

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 text @samp{Top} rather than @samp{All} near the bottom of
the screen.

@kindex SPC @r{(Info mode)}
@kindex DEL @r{(Info mode)}
@kindex BACKSPACE @r{(Info mode)}
@findex Info-scroll-up

   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

@kindex ? @r{(Info mode)}
@findex Info-summary
  You have just learned a considerable number of commands.  If you
want to use one but have trouble remembering which, you should type
@kbd{?}, which displays a brief list of commands.  When you are
finished looking at the list, make it go away by typing @key{SPC}
repeatedly.

@format
>> Type a @key{?} now.  Press @key{SPC} to see consecutive screenfuls of
   the list until finished.  Then type @key{SPC} several times.  If
   you are using Emacs, the help will then go away automatically.

@findex Info-menu
  The command to go to a subnode via a menu is @kbd{m}.  After you type
the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }.
You must then type the name of the subtopic you want, and end it with
a @key{RET}.

@cindex abbreviating Info subnodes
  You can abbreviate the subtopic name.  If the abbreviation is not
unique, the first matching subtopic is chosen.  Some menus put
the shortest possible abbreviation for each subtopic name in capital

usually used to ``stay on the same level but go backwards''.

@kindex u @r{(Info mode)}
@findex Info-up
  You can go back to the node @samp{Help-M} by typing the command
@kbd{u} for ``Up''.  This puts you at the menu subtopic line pointing
to the subnode that the @kbd{u} command brought you from.  (Some Info
readers may put you at the @emph{front} of the node instead---to get
back to where you were reading, you have to type some @key{SPC}s.)

  Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up}
pointer shown in the header line (provided that you have a mouse).

@format

points to the node named @samp{Help-Cross}.  (The node name is hidden
in Emacs.  Do @kbd{M-x visible-mode} to show or hide it.)

@kindex f @r{(Info mode)}
@findex Info-follow-reference
  You can follow a cross reference by moving the cursor to it and
press @key{RET}, just as in a menu.  In Emacs, you can also click
@kbd{Mouse-1} on a cross reference to follow it; you can see that the
cross reference is mouse-sensitive by moving the mouse pointer to the
reference and watching how the underlying text and the mouse pointer
change in response.

  Another way to follow a cross reference is to type @kbd{f} and then
specify the name of the cross reference (in this case, @samp{Cross})
as an argument.  For this command, it does not matter where the cursor
was.  If the cursor is on or near a cross reference, @kbd{f} suggests
that reference name in parentheses as the default; typing @key{RET}
will follow that reference.  However, if you type a different
reference name, @kbd{f} will follow the other reference which has that
name.

@format
>> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}.
@end format

@end format

  The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys,
which move between menu items in a menu, also move between cross
references outside of menus.

  Sometimes a cross reference (or a node) can lead to another file (in
other words another ``manual''), or, on occasion, even a file on a
remote machine (although Info files distributed with Emacs or the
stand-alone Info avoid using remote links).  Such a cross reference

retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will
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.

@format
>> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between
to see what each @kbd{l} does.  You should wind up right back here.
@end format

@kindex C-r @r{(Info mode)}
@findex isearch
  Instead of using @kbd{s} in Emacs Info and in the stand-alone Info,
you can use an incremental search started with @kbd{C-s} or @kbd{C-r}.
It can search through multiple Info nodes.  @xref{Incremental Search,,,
emacs, The GNU Emacs Manual}.  In Emacs, you can disable this behavior
by setting the variable @code{Info-isearch-search} to @code{nil}
(@pxref{Emacs Info Variables}).

@node Search Index, Go to node, Search Text, Advanced
@comment  node-name,  next,  previous,  up
@section How to search the indices for specific subjects

looking for a description of a command, an option, or a key, just type
their names when @kbd{i} prompts you for a topic.  For example, if you
want to read the description of what the @kbd{C-l} key does, type
@kbd{iC-l@key{RET}} literally.

@findex info-apropos
@findex index-apropos
If you aren't sure which manual documents the topic you are looking
for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x
index-apropos} command in the stand-alone reader.  It prompts for

@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{gGo to node@key{RET}} would come back here.

  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.

you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4},
@dots{}, @kbd{9}.  They are short for the @kbd{m} command together
with a name of a menu subtopic.  @kbd{1} goes through the first item
in the current node's menu; @kbd{2} goes through the second item, etc.
In the stand-alone reader, @kbd{0} goes through the last menu item;
this is so you need not count how many entries are there.

  If your display supports multiple fonts, colors or underlining, and
you are using Emacs' Info mode to read Info files, the third, sixth
and ninth menu items have a @samp{*} that stands out, either in color
or in some other attribute, such as underline; this makes it easy to

@kindex M-n @r{(Info mode)}
@findex clone-buffer
@cindex multiple Info buffers
  If you are reading Info in Emacs, you can select a new independent
Info buffer in a new Emacs window by typing @kbd{M-n}.  The new buffer
starts out as an exact copy of the old one, but you will be able to
move independently between nodes in the two buffers.  (In Info mode,
@kbd{M-n} runs the Emacs command @code{clone-buffer}.)

  In Emacs Info, you can also produce new Info buffers by giving a

@node Emacs Info Variables, , Create Info buffer, Advanced
@comment  node-name,  next,  previous,  up
@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 init file.  @xref{Examining, Examining and Setting
Variables, Examining and Setting Variables, emacs, The GNU Emacs
Manual}.  The stand-alone Info reader program has its own set of
variables, described in @ref{Variables,, Manipulating Variables,
info-stnd, GNU Info}.