Mercurial > emacs

--- a/man/info.texi	Thu Jul 03 01:54:21 2003 +0000
+++ b/man/info.texi	Thu Jul 03 01:59:39 2003 +0000
@@ -6,7 +6,7 @@
 @syncodeindex vr cp
 @syncodeindex ky cp
 @comment %**end of header
-@comment $Id: info.texi,v 1.26 2002/10/02 23:24:31 karl Exp $
+@comment $Id: info.texi,v 1.27 2002/11/06 00:45:03 karl Exp $

 @copying
 This file describes how to use Info, the on-line, menu-driven GNU
@@ -51,7 +51,7 @@
 @end titlepage

 @ifnottex
-@node Top
+@node Top, Getting Started, (dir), (dir)
 @top Info: An Introduction

 The GNU Project distributes most of its on-line manuals in the
@@ -125,13 +125,14 @@
 * Help::                How to use Info
 * Help-P::              Returning to the Previous node
 * Help-^L::             The Space, DEL, B and ^L commands.
+* Help-Inv::            Invisible text in Emacs Info.
 * Help-M::              Menus
 * Help-Xref::           Following cross-references
 * Help-Int::            Some intermediate Info commands
 * Help-Q::              Quitting Info
 @end menu

-@node Help-Small-Screen
+@node Help-Small-Screen, Help, Getting Started, Getting Started
 @section Starting Info on a Small Screen

 @ifnotinfo
@@ -213,6 +214,10 @@

 You are talking to the program Info, for reading documentation.

+  There are two ways to use Info: from within Emacs or as a
+stand-alone reader that you can invoke from a shell using the command
+@command{info}.
+
 @cindex node, in Info documents
   Right now you are looking at one @dfn{Node} of Information.
 A node contains text describing a specific topic at a specific
@@ -283,9 +288,9 @@
    link, to get to the node @samp{Help-^L} and learn more.
 @end format

-@node Help-^L, Help-M, Help-P, Getting Started
+@node Help-^L, Help-Inv, Help-P, Getting Started
 @comment  node-name,  next,  previous,  up
-@section The Space, DEL, B and ^L commands.
+@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
@@ -409,30 +414,103 @@

 @format
 >> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
-   to see the description of the @kbd{m} command.
+   to visit the next node.
 @end format

-@node Help-M, Help-Xref, Help-^L, Getting Started
+@node Help-Inv, Help-M, Help-^L, Getting Started
+@comment  node-name,  next,  previous,  up
+@section Invisible text in Emacs Info
+
+  Before discussing menus, we need to make some remarks that are only
+relevant to users reading Info using Emacs.  Users of the stand-alone
+version can skip this node by typing @kbd{]} now.
+
+@cindex invisible text in Emacs
+  In Emacs, certain text that appears in the stand-alone version is
+normally hidden, technically because it has the @samp{invisibility}
+property.  Invisible text is really a part of the text.  It becomes
+visible (by default) after killing and yanking, it appears in printed
+output, it gets saved to file just like any other text, and so on.
+Thus it is useful to know it is there.
+
+@findex vis-mode
+You can make invisible text visible by using the command @kbd{M-x
+vis-mode}.  @code{vis-mode} is a minor mode, so using it a second time
+will make the text invisible again.  Use this command and watch its
+effect on the ``menu'' below and the top line of this node.
+
+If you prefer to @emph{always} see the invisible text, you can set
+@code{Info-hide-note-references} to @code{nil}.  Enabling
+@code{vis-mode} permanently is not a real alternative, because Emacs
+Info also uses (although less extensively) another text property that
+can change the text being displayed, the @samp{display} property.
+Only the invisibility property is affected by @code{vis-mode}.  When,
+in this tutorial, we refer to the @samp{Emacs} behavior, we mean the
+@emph{default} Emacs behavior.
+
+Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands.
+
+@menu
+* ]:         Help-].               Node telling about ].
+* stuff:     Help-].               Same node.
+* Help-]::                         Yet again, same node.
+@end menu
+
+@node Help-], , , Help-Inv
+@subsection The @kbd{]} and @kbd{[} commands.
+
+If you type @kbd{n} now, you get an error message saying that this
+node has no next node.  Similarly, if you type @kbd{p}, the error
+message tells you that there is no previous node.  (The exact message
+depends on the Info reader you use.)  This is because @kbd{n} and
+@kbd{p} carry you to the next and previous node @emph{at the same
+level}.  The present node is contained in a menu (see next) of the
+node you came from, and hence is considered to be at a lower level.
+It is the only node in the previous node's menu (even though it was
+listed three times). Hence it has no next or previous node that
+@kbd{n} or @kbd{p} could move to.
+
+If you systematically move through a manual by typing @kbd{n}, you run
+the risk of skipping many nodes.  You do not run this risk if you
+systematically use @kbd{@key{SPC}}, because, when you scroll to the
+bottom of a node and type another @kbd{@key{SPC}}, then this carries
+you to the following node in the manual @emph{regardless of level}.
+If you immediately want to go to that node, without having to scroll
+to the bottom of the screen first, you can type @kbd{]}.
+
+Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node
+regardless of level, after you scrolled to the beginning of the
+present node.  If you want to go to the preceding node immediately,
+you can type @kbd{[}.
+
+For instance, typing this sequence will come back here in three steps:
+@kbd{[ n [}.  To do the same backward, type @kbd{] p ]}.
+
+Now type @kbd{]} to go to the next node and learn about menus.
+
+@node Help-M, Help-Xref, Help-Inv, Getting Started
 @comment  node-name,  next,  previous,  up
 @section Menus and the @kbd{m} command

 @cindex menus in an Info document
 @cindex Info menus
-  With only the @kbd{n} (next) and @kbd{p} (previous) commands for
-moving between nodes, nodes are restricted to a linear sequence.
-Menus allow a branching structure.  A menu is a list of other nodes
-you can move to.  It is actually just part of the text of the node
-formatted specially so that Info can interpret it.  The beginning of a
-menu is always identified by a line which starts with @samp{* Menu:}.
-A node contains a menu if and only if it has a line in it which starts
-that way.  The only menu you can use at any moment is the one in the
-node you are in.  To use a menu in any other node, you must move to
-that node first.
+  With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}},
+@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between
+nodes, nodes are restricted to a linear sequence.  Menus allow a
+branching structure.  A menu is a list of other nodes you can move to.
+It is actually just part of the text of the node formatted specially
+so that Info can interpret it.  The beginning of a menu is always
+identified by a line which starts with @w{@samp{* Menu:}}.  A node
+contains a menu if and only if it has a line in it which starts that
+way.  The only menu you can use at any moment is the one in the node
+you are in.  To use a menu in any other node, you must move to that
+node first.

   After the start of the menu, each line that starts with a @samp{*}
-identifies one subtopic.  The line usually contains a brief name
-for the subtopic (followed by a @samp{:}), the name of the node that talks
-about that subtopic, and optionally some further description of the
+identifies one subtopic.  The line usually contains a brief name for
+the subtopic (followed by a @samp{:}, normally hidden in Emacs), the
+name of the node that talks about that subtopic (again, normally
+hidden in Emacs), and optionally some further description of the
 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:
@@ -444,7 +522,11 @@
 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
-there is no line above it which starts with @samp{* Menu:}.]]
+there is no line above it which starts with @w{@samp{* Menu:}}.  Also,
+in a real menu item, the @samp{*} would appear at the very start of
+the line.  This is why the ``normally hidden'' text in Emacs, namely
+@samp{: Node about FOO.}, is actually visible in this example, even
+when @code{vis-mode} is off.]]

   When you use a menu to go to another node (in a way that will be
 described soon), what you specify is the subtopic name, the first
@@ -463,7 +545,7 @@

 @noindent
 This means that the subtopic name and node name are the same; they are
-both @samp{Foo}.
+both @samp{Foo}.  (The @samp{::} is normally hidden in Emacs.)

 @format
 >> Now use @key{SPC} to find the menu in this node, then come back to
@@ -488,16 +570,18 @@
 the @dfn{name of the subtopic}.  Once you have typed @kbd{m}, Info
 tries to read the subtopic name.

-  Now look for the line containing many dashes near the bottom of the
-screen.  There is one more line beneath that one, but usually it is
-blank.  When it is blank, Info is ready for a command, such as @kbd{n}
-or @kbd{b} or @key{SPC} or @kbd{m}.  If that line contains text ending
-in a colon, it means Info is reading more input for the last command.
-You can't type an Info command then, because Info is trying to read
-input, not commands.  You must either give the input and finish the
-command you started, or type @kbd{Control-g} to cancel the command.
-When you have done one of those things, the input entry line becomes
-blank again.  Then you can type Info commands again.
+  Now, in the stand-alone Info, look for the line containing many
+dashes near the bottom of the screen.  (This is the stand-alone
+equivalent for the mode line in Emacs.)  There is one more line
+beneath that one, but usually it is blank.  (In Emacs, this is the
+echo area.)  When it is blank, Info is ready for a command, such as
+@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}.  If that line contains
+text ending in a colon, it means Info is reading more input for the
+last command.  You can't type an Info command then, because Info is
+trying to read input, not commands.  You must either give the input
+and finish the command you started, or type @kbd{Control-g} to cancel
+the command.  When you have done one of those things, the input entry
+line becomes blank again.  Then you can type Info commands again.

 @findex Info-menu
   The command to go to a subnode via a menu is @kbd{m}.  After you type
@@ -535,6 +619,8 @@
 * Help-FOO::            And yet another!
 @end menu

+(Turn @code{vis-mode} on if you are using Emacs.)
+
 @format
 >>  Now type just an @kbd{m} and see what happens:
 @end format
@@ -610,14 +696,6 @@
 end of the node's text @kbd{Mouse-2} moves to the next node, or up if
 there's no next node.

-  Here is another way to get to Help-FOO, a menu.  You can ignore this
-if you want, or else try it by typing @key{TAB} and then @key{RET}, or
-clicking @kbd{Mouse-2} on it (but then please come back to here).
-
-@menu
-* Help-FOO::
-@end menu
-
 @format
 >> Type @kbd{n} to see more commands.
 @end format
@@ -656,7 +734,8 @@
   In Info documentation, you will see many @dfn{cross references}.
 Cross references look like this: @xref{Help-Cross, Cross}.  That text
 is a real, live cross reference, whose name is @samp{Cross} and which
-points to the node named @samp{Help-Cross}.
+points to the node named @samp{Help-Cross}.  (The node name is hidden
+in Emacs.  Do @kbd{M-x vis-mode} to show or hide it.)

 @kindex f @r{(Info mode)}
 @findex Info-follow-reference
@@ -699,6 +778,47 @@
   The @key{TAB} and @kbd{M-@key{TAB}} key, 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
+looks like this: @xref{Overview,,,texinfo}.  (After following this
+link, type @kbd{l} to get back to this node.)  Here the name
+@samp{texinfo} between parentheses (shown in the stand-alone version)
+refers to the file name.  This file name appears in cross references
+and node names if it differs from the current file.  In Emacs, the
+file name is hidden (along with other text).  (Use @kbd{M-x vis-mode}
+to show or hide it.)
+
+  The remainder of this node applies only to the Emacs version.  If
+you use the stand-alone version, you can type @kbd{n} immediately.
+
+  To some users, switching manuals is a much bigger switch than
+switching sections.  These users like to know that they are going to
+be switching to another manual (and which one) before actually doing
+so, especially given that, if one does not notice, Info commands like
+@kbd{t} (see the next node) can have confusing results.
+
+  If you put your mouse over the cross reference and if the cross
+reference leads to a different manual, then the information appearing
+in a separate box (tool tip) or in the echo area, will mention the
+file the cross reference will carry you to (between parentheses).
+This is also true for menu subtopic names.  If you have a mouse, just
+leave it over the @samp{Overview} cross reference above and watch what
+happens.
+
+  If you always like to have that information available without having
+to move your mouse over the cross reference, set
+@code{Info-hide-note-references} to a value other than t (@pxref{Emacs
+Info Variables}).  You might also want to do that if you have a lot of
+cross references to files on remote machines and have non-permanent or
+slow access, since otherwise you might not be able to distinguish
+between local and remote links.
+
+@format
+>> Now type @kbd{n} to learn more commands.
+@end format
+
 @node Help-Int, Help-Q, Help-Xref, Getting Started
 @comment  node-name,  next,  previous,  up
 @section Some intermediate Info commands
@@ -728,23 +848,17 @@
 @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
->> Try typing three @kbd{l}'s, pausing in between to see what each
-   @kbd{l} does.  Then follow directions again and you will end up
-   back here.
+>> 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

   Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to
 where @emph{you} last were, whereas @kbd{p} always moves to the node
 which the header says is the @samp{Previous} node (from this node, the
-@samp{Prev} link leads to @samp{Help-M}).
+@samp{Prev} link leads to @samp{Help-Xref}).

 @kindex d @r{(Info mode)}
 @findex Info-directory
@@ -796,10 +910,10 @@
 better, since you can use it to make a printed manual or produce other
 formats, such as HTML and DocBook, as well as for generating Info
 files.)  @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
-Documentation Format}.)
+Documentation Format}.

 @menu
-* Advanced::             Advanced Info commands: g, s, e, and 1 - 5.
+* Advanced::             Advanced Info commands: g, e, and 1 - 9.
 * 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.
@@ -1049,15 +1163,15 @@
 reads from the terminal.

 @cindex menu and menu entry format
-  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--what
-the user must type at the @kbd{m}'s command prompt 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.
+  A menu begins with a line starting with @w{@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--what the user must type at the @kbd{m}'s command prompt 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{* @var{name}::} may be
@@ -1278,6 +1392,14 @@
 not scroll with the rest of the buffer, making these links always
 visible.

+@item Info-hide-note-references
+As explained in earlier nodes, the Emacs version of Info normally
+hides some text in menus and cross-references.  You can completely
+disable this feature, by setting this option to @code{nil}.  Setting
+it to a value that is neither @code{nil} nor @code{t} produces an
+intermediate behavior, hiding a limited amount of text, but showing
+all text that could potentially be useful.
+
 @item Info-scroll-prefer-subnodes
 If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
 @key{DEL}) keys in a menu visit subnodes of the current node before
@@ -1286,7 +1408,7 @@
 subnode indicated by the following menu item.  Setting this option to
 @code{nil} results in behavior similar to the stand-alone Info reader
 program, which visits the first subnode from the menu only when you
-hit the end of the current node.  The default is @code{t}.
+hit the end of the current node.  The default is @code{nil}.

 @item Info-enable-active-nodes
 When set to a non-@code{nil} value, allows Info to execute Lisp code