[Emacs-diffs] Changes to emacs/man/info.texi

[Luc Teirlinck]

Index: emacs/man/info.texi
diff -c emacs/man/info.texi:1.27 emacs/man/info.texi:1.28
*** emacs/man/info.texi:1.27    Tue Nov  5 19:45:03 2002
--- emacs/man/info.texi Wed Jul  2 21:59:39 2003
***************
*** 6,12 ****
  @syncodeindex vr cp
  @syncodeindex ky cp
  @comment %**end of header
! @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
--- 6,12 ----
  @syncodeindex vr cp
  @syncodeindex ky cp
  @comment %**end of header
! @comment $Id: info.texi,v 1.28 2003/07/03 01:59:39 teirllm Exp $
  
  @copying
  This file describes how to use Info, the on-line, menu-driven GNU
***************
*** 51,57 ****
  @end titlepage
  
  @ifnottex
! @node Top
  @top Info: An Introduction
  
  The GNU Project distributes most of its on-line manuals in the
--- 51,57 ----
  @end titlepage
  
  @ifnottex
! @node Top, Getting Started, (dir), (dir)
  @top Info: An Introduction
  
  The GNU Project distributes most of its on-line manuals in the
***************
*** 125,137 ****
  * Help::                How to use Info
  * Help-P::              Returning to the Previous node
  * Help-^L::             The Space, DEL, B and ^L commands.
  * Help-M::              Menus
  * Help-Xref::           Following cross-references
  * Help-Int::            Some intermediate Info commands
  * Help-Q::              Quitting Info
  @end menu
  
! @node Help-Small-Screen
  @section Starting Info on a Small Screen
  
  @ifnotinfo
--- 125,138 ----
  * 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, Help, Getting Started, Getting Started
  @section Starting Info on a Small Screen
  
  @ifnotinfo
***************
*** 213,218 ****
--- 214,223 ----
  
  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,291 ****
     link, to get to the node @samp{Help-^L} and learn more.
  @end format
  
! @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
--- 288,296 ----
     link, to get to the node @samp{Help-^L} and learn more.
  @end format
  
! @node Help-^L, Help-Inv, 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
***************
*** 409,438 ****
  
  @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.
  @end format
  
! @node Help-M, Help-Xref, Help-^L, 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.
  
    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
  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:
--- 414,516 ----
  
  @format
  >> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link,
!    to visit the next node.
  @end format
  
! @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 @address@hidden, because, when you scroll to the
! bottom of a node and type another @address@hidden, 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, @address@hidden 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), @kbd{p} (previous), @address@hidden,
! @address@hidden, @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 @address@hidden 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{:}, 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,450 ****
  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:}.]]
  
    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
--- 522,532 ----
  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 @address@hidden 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,469 ****
  
  @noindent
  This means that the subtopic name and node name are the same; they are
! both @samp{Foo}.
  
  @format
  >> Now use @key{SPC} to find the menu in this node, then come back to
--- 545,551 ----
  
  @noindent
  This means that the subtopic name and node name are the same; they are
! 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,503 ****
  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.
  
  @findex Info-menu
    The command to go to a subnode via a menu is @kbd{m}.  After you type
--- 570,587 ----
  the @dfn{name of the subtopic}.  Once you have typed @kbd{m}, Info
  tries to read the subtopic name.
  
!   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,540 ****
--- 619,626 ----
  * 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,623 ****
  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
--- 696,701 ----
***************
*** 656,662 ****
    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}.
  
  @kindex f @r{(Info mode)}
  @findex Info-follow-reference
--- 734,741 ----
    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}.  (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,704 ****
--- 778,824 ----
    The @key{TAB} and @address@hidden 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,750 ****
  @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.
  @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}).
  
  @kindex d @r{(Info mode)}
  @findex Info-directory
--- 848,864 ----
  @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-last}.
  
  @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
  
    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-Xref}).
  
  @kindex d @r{(Info mode)}
  @findex Info-directory
***************
*** 796,805 ****
  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}.)
  
  @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.
--- 910,919 ----
  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}.
  
  @menu
! * 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,1063 ****
  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.
  
    If the node name and topic name are the same, then rather than
  giving the name twice, the abbreviation @samp{* @var{name}::} may be
--- 1163,1177 ----
  reads from the terminal.
  
  @cindex menu and menu entry format
!   A menu begins with a line starting with @address@hidden 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,1283 ****
--- 1392,1405 ----
  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 address@hidden value, @key{SPC} and @key{BACKSPACE} (or
  @key{DEL}) keys in a menu visit subnodes of the current node before
***************
*** 1286,1292 ****
  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}.
  
  @item Info-enable-active-nodes
  When set to a address@hidden value, allows Info to execute Lisp code
--- 1408,1414 ----
  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{nil}.
  
  @item Info-enable-active-nodes
  When set to a address@hidden value, allows Info to execute Lisp code