info.texi

[Juri Linkov]

Since updating info.texi is one of the tasks needed to be finished for
the next Emacs release, I took on this task, fixed mistakes in the
existing manual and documented new features.  Please look at the
resulted patch below.

PS: I also have a proposal on a better node partition in info.texi,
but I will send a separate patch, because after moving Info nodes
up and down, small changes will not be visible in the diff.

Index: man/info.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/info.texi,v
retrieving revision 1.45
diff -c -r1.45 info.texi
*** man/info.texi       23 Jun 2005 01:17:30 -0000      1.45
--- man/info.texi       4 Aug 2005 00:05:57 -0000
***************
*** 14,21 ****
  This file describes how to use Info, the on-line, menu-driven GNU
  documentation system.
  
! Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
! Free Software Foundation, Inc.
  
  @quotation
  Permission is granted to copy, distribute and/or modify this document
--- 14,21 ----
  This file describes how to use Info, the on-line, menu-driven GNU
  documentation system.
  
! Copyright (C) 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
! 2003, 2004, 2005 Free Software Foundation, Inc.
  
  @quotation
  Permission is granted to copy, distribute and/or modify this document
***************
*** 238,244 ****
  (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.
--- 238,244 ----
  (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.
***************
*** 284,290 ****
    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
! @samp{Next} and @samp{Prev} (and also some others which you didn't yet
  learn about).
  
    This all probably seems insultingly simple so far, but @emph{please
--- 284,290 ----
    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
! @samp{Next} and @samp{Previous} (and also some others which you didn't yet
  learn about).
  
    This all probably seems insultingly simple so far, but @emph{please
***************
*** 674,680 ****
  next subtopic line.  To move to a previous subtopic line, type
  @address@hidden is, press and hold the @key{META} key and then
  press @key{TAB}.  (On some keyboards, the @key{META} key might be labeled
! @samp{Alt}.)
  
    Once you move cursor to a subtopic line, press @key{RET} to go to
  that subtopic's node.
--- 674,683 ----
  next subtopic line.  To move to a previous subtopic line, type
  @address@hidden is, press and hold the @key{META} key and then
  press @key{TAB}.  (On some keyboards, the @key{META} key might be labeled
! @samp{Alt}.)  On window systems, which intercept @address@hidden key
! combination (usually for switching between windows), you can use
! @address@hidden to move to a previous subtopic line (press and hold
! the @key{Shift} key and then press @key{TAB}).
  
    Once you move cursor to a subtopic line, press @key{RET} to go to
  that subtopic's node.
***************
*** 727,733 ****
  @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
! same place where you were reading in @samp{Help-M}.)
  
    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).
--- 730,737 ----
  @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 you came from via the
! @kbd{u} command.)
  
    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).
***************
*** 785,792 ****
     type a @kbd{Control-g} and see how the @samp{f} gives up.
  @end format
  
!   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
--- 789,802 ----
     type a @kbd{Control-g} and see how the @samp{f} gives up.
  @end format
  
!   The @key{TAB} and @address@hidden (or @address@hidden) 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
***************
*** 795,830 ****
  looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo:
  The GNU Documentation Format}.  (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 visible-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 @code{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.
--- 805,826 ----
  looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo:
  The GNU Documentation Format}.  (After following this link, type
  @kbd{l} to get back to this node.)  Here the name @samp{texinfo}
! between parentheses 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 not hidden as well, so you can always know
! that you are going to be switching to another manual and which one.
! However, Emacs normally hides some other text in cross-references.
! If you put your mouse over the cross reference, then the information
! appearing in a separate box (tool tip) or in the echo area, will show
! the full cross-reference including the file name and the node name of
! the cross reference.  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 visible without having to move
! your mouse over the cross reference, use @kbd{M-x visible-mode}, or
! set @code{Info-hide-note-references} to a value other than @code{t}
! (@pxref{Emacs Info Variables}).
  
  @format
  >> Now type @kbd{n} to learn more commands.
***************
*** 845,852 ****
  the start of the containing node.)
  
    You can get to the index from the main menu of the file with the
! @kbd{m} command; then you can use the @kbd{m} command again in the
! index node to go to the node that describes the topic you want.
  
    There is also a short-cut Info command, @kbd{i}, which does all of
  that for you.  It searches the index for a given topic (a string) and
--- 841,849 ----
  the start of the containing node.)
  
    You can get to the index from the main menu of the file with the
! @kbd{m} command and the name of the index node; then you can use the
! @kbd{m} command again in the index node to go to the node that
! describes the topic you want.
  
    There is also a short-cut Info command, @kbd{i}, which does all of
  that for you.  It searches the index for a given topic (a string) and
***************
*** 854,861 ****
  @xref{Info Search}, for a full explanation.
  
  @kindex l @r{(Info mode)}
! @findex Info-last
! @cindex going back in Info mode
    If you have been moving around to different nodes and wish to
  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
--- 851,858 ----
  @xref{Info Search}, for a full explanation.
  
  @kindex l @r{(Info mode)}
! @findex Info-history-back
! @cindex going back in Info history
    If you have been moving around to different nodes and wish to
  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
***************
*** 863,869 ****
  @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
--- 860,866 ----
  @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
***************
*** 875,880 ****
--- 872,884 ----
  which the header says is the @samp{Previous} node (from this node, the
  @samp{Prev} link leads to @samp{Help-Xref}).
  
+ @kindex r @r{(Info mode)}
+ @findex Info-history-forward
+ @cindex going forward in Info history
+   You can use the @kbd{r} command (@code{Info-history-forward} in Emacs)
+ to revisit nodes in the history list in the reverse direction, so that
+ @kbd{r} will return you to the node you came from by typing @kbd{l}.
+ 
  @kindex d @r{(Info mode)}
  @findex Info-directory
  @cindex go to Directory node
***************
*** 898,908 ****
  some specific top-level menu item.  The Emacs command run by @kbd{t}
  is @code{Info-top-node}.
  
-   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.
- 
  @format
  >> Now type @kbd{n} to see the last node of the course.
  @end format
--- 902,907 ----
***************
*** 969,975 ****
  
    The node name @samp{*} specifies the whole file.  So you can look at
  all of the current file by typing @address@hidden or all of any
! other file with @kbd{g(@var{filename})@key{RET}}.
  
  @subheading @address@hidden choose a menu subtopic by its number
  
--- 968,974 ----
  
    The node name @samp{*} specifies the whole file.  So you can look at
  all of the current file by typing @address@hidden or all of any
! other file with @kbd{g(@var{filename})address@hidden
  
  @subheading @address@hidden choose a menu subtopic by its number
  
***************
*** 1017,1023 ****
  @findex clone-buffer
  @cindex multiple Info buffers
    If you are reading Info in Emacs, you can select a new independent
! Info buffer in another 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}.)
--- 1016,1022 ----
  @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}.)
***************
*** 1028,1033 ****
--- 1027,1041 ----
  @kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they
  select in another window.
  
+   Another way to produce new Info buffers in Emacs is to use a numeric
+ prefix argument for the @kbd{C-h i} command (@code{info}).
+ With a numeric argument, it selects an Info buffer with the number
+ appended to the default @samp{*info*} buffer name.  So @kbd{C-u 2 C-h
+ i} will select the buffer @samp{*info*<2>}.  If such a buffer doesn't
+ exist yet, it will create a new Info buffer with that name and with
+ the contents of the Directory node.  This is useful if you want to
+ browse multiple Info manuals simultaneously.
+ 
  @node Info Search, Add, Advanced, Expert Info
  @comment  node-name,  next,  previous,  up
  @section How to search Info documents for specific subjects
***************
*** 1083,1092 ****
    In Emacs, @kbd{i} runs the command @code{Info-index}.
  
  @findex info-apropos
  If you don't know what manual documents something, try the @kbd{M-x
! info-apropos} command.  It prompts for a string and then looks up that
! string in all the indices of all the Info documents installed on your
! system.
  
  @kindex s @r{(Info mode)}
  @findex Info-search
--- 1091,1102 ----
    In Emacs, @kbd{i} runs the command @code{Info-index}.
  
  @findex info-apropos
+ @findex index-apropos
  If you don't know what manual documents something, 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 a string and then looks up
! that string in all the indices of all the Info documents installed on
! your system.
  
  @kindex s @r{(Info mode)}
  @findex Info-search
***************
*** 1095,1104 ****
  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 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).
--- 1105,1114 ----
  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 the file, which has no necessary relationship to the
  order that they may be 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 look at the echo area 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).
***************
*** 1109,1114 ****
--- 1119,1134 ----
  kind of search command.  Both @kbd{s} and @kbd{M-s} run in Emacs the
  command @code{Info-search}.
  
+ @kindex C-s @r{(Info mode)}
+ @kindex C-r @r{(Info mode)}
+ @findex isearch
+   Using @kbd{s} is not very convenient, because to repeat a search you
+ need to type two keys @kbd{s} and @key{RET} every time.  Instead of this,
+ in Emacs Info and in the stand-alone Info you can use a powerful
+ incremental search started with @kbd{C-s} or @kbd{C-r} which searches
+ through multiple Info nodes.  In Emacs, this behavior is enabled only
+ if the variable @code{Info-isearch-search} is address@hidden
+ (@pxref{Emacs Info Variables}).
  
  @node Add, Menus, Info Search, Expert Info
  @comment  node-name,  next,  previous,  up
***************
*** 1245,1253 ****
  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, Expert Info
  @comment  node-name,  next,  previous,  up
--- 1265,1273 ----
  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 on the node graph, 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
***************
*** 1328,1334 ****
  @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
  it a tags table.  Unlike the tags table for a program, the tags table for
  an Info file lives inside the file itself and is used
--- 1348,1354 ----
  @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
  it a tags table.  Unlike the tags table for a program, the tags table for
  an Info file lives inside the file itself and is used
***************
*** 1408,1429 ****
  @env{INFOPATH} variable in the environment.
  
  If you wish to customize the Info directory search list for both Emacs
! info and stand-alone Info, it is best to set the @env{INFOPATH}
  environment variable, since that applies to both programs.
  
  @item Info-additional-directory-list
  A list of additional directories to search for Info documentation files.
  These directories are not searched for merging the @file{dir} file.
  
! @item Info-fontify
! When set to a address@hidden value, enables highlighting of Info
! files.  The default is @code{t}.  You can change how the highlighting
! looks by customizing the faces @code{info-node}, @code{info-xref},
! @code{info-header-xref}, @code{info-header-node}, @code{info-menu-5},
! @code{info-menu-header}, and @address@hidden (where
! @var{n} is the level of the section, a number between 1 and 4).  To
! customize a face, type @kbd{M-x customize-face @key{RET} @var{face}
! @key{RET}}, where @var{face} is one of the face names listed here.
  
  @item Info-use-header-line
  If address@hidden, Emacs puts in the Info buffer a header line showing
--- 1428,1457 ----
  @env{INFOPATH} variable in the environment.
  
  If you wish to customize the Info directory search list for both Emacs
! Info and stand-alone Info, it is best to set the @env{INFOPATH}
  environment variable, since that applies to both programs.
  
  @item Info-additional-directory-list
  A list of additional directories to search for Info documentation files.
  These directories are not searched for merging the @file{dir} file.
  
! @item Info-mode-hook
! Hooks run when @code{Info-mode} is called.  By default, it contains
! the hook @code{turn-on-font-lock} which enables highlighting of Info
! files.  You can change how the highlighting looks by customizing the
! faces @code{info-node}, @code{info-xref}, @code{info-xref-visited},
! @code{info-header-xref}, @code{info-header-node}, @code{info-menu-header},
! @code{info-menu-star}, and @address@hidden (where @var{n}
! is the level of the section, a number between 1 and 4).  To customize
! a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}},
! where @var{face} is one of the face names listed here.
! 
! @item Info-fontify-maximum-menu-size
! Maximum size of menu to fontify if @code{font-lock-mode} is address@hidden
! 
! @item Info-fontify-visited-nodes
! If address@hidden, menu items and cross-references pointing to visited
! nodes are displayed in the @code{info-xref-visited} face.
  
  @item Info-use-header-line
  If address@hidden, Emacs puts in the Info buffer a header line showing
***************
*** 1448,1453 ****
--- 1476,1484 ----
  @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-isearch-search
+ If address@hidden, isearch in Info searches through multiple nodes.
  
  @item Info-enable-active-nodes
  When set to a address@hidden value, allows Info to execute Lisp code

-- 
Juri Linkov
http://www.jurta.org/emacs/