[5605] info-stnd invocation doc tweaks

[karl]

Revision: 5605
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5605
Author:   karl
Date:     2014-05-25 18:52:26 +0000 (Sun, 25 May 2014)
Log Message:
-----------
info-stnd invocation doc tweaks

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/NEWS
    trunk/doc/info-stnd.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2014-05-25 18:51:22 UTC (rev 5604)
+++ trunk/ChangeLog     2014-05-25 18:52:26 UTC (rev 5605)
@@ -1,3 +1,8 @@
+2014-05-25  Karl Berry  <address@hidden>
+
+       * doc/info-stnd.texi (Invoking info): tweaks to invocation examples;
+       mention GROFF_SGR, etc.
+
 2014-05-25  Gavin Smith  <address@hidden>
 
        * info/window.c (window_new_screen_size): Call forget_window_and_nodes

Modified: trunk/NEWS
===================================================================
--- trunk/NEWS  2014-05-25 18:51:22 UTC (rev 5604)
+++ trunk/NEWS  2014-05-25 18:52:26 UTC (rev 5605)
@@ -37,6 +37,10 @@
   . --plaintext output can be split.
 
 * info:
+  . invoking `info foo bar' looks for bar as an index entry if
+    not found as a top-level menu item.
+  . invoking info with an absolute or explicitly relative file name
+    (./foo.info, /tmp/foo.info, etc.) just visits that file.
   . new option --init-file allows overriding ~/.info.
   . new variable infopath-no-defaults allows omitting the compile-time
     Info directory from the Info search path.

Modified: trunk/doc/info-stnd.texi
===================================================================
--- trunk/doc/info-stnd.texi    2014-05-25 18:51:22 UTC (rev 5604)
+++ trunk/doc/info-stnd.texi    2014-05-25 18:52:26 UTC (rev 5605)
@@ -136,20 +136,24 @@
 Here is a template showing an invocation of GNU Info from the shell:
 
 @example
-info address@hidden@dots{}] address@hidden address@hidden@dots{}]
+info address@hidden@dots{}] address@hidden address@hidden@dots{}]
 @end example
 
-Info will look for an entry called @var{manual} in the directory files
-(called @file{dir}) it finds in its search path.  (If @var{manual}
-is not given, Info by default displays a composite directory listing,
-constructed by combining the @file{dir} files.)  For example:
+Info will look for an entry called @var{manual} in the directory
+files, which are named @file{dir}, that it finds in its search path.
+The search is case-insensitive and considers substrings.
+(If @var{manual} is not given, by default Info displays a composite
+directory listing, constructed by combining the @file{dir} files.)
+A basic example:
 
 @example
-info ls
+info coreutils
 @end example
 
-This looks for an entry labelled @code{ls}, and if found, displays the
-referenced file at the location given.  
+This looks for an entry labelled @code{coreutils}, or
address@hidden, etc., and if found, displays the referenced file at
+the location given.  @code{info coreu} will find it too, if there is
+no better match.
 
 @cindex compressed Info files
 @cindex files, compressed
@@ -171,15 +175,16 @@
 like @file{bison.igz} and @file{bison.inz} will be found and decompressed
 by @code{gunzip}.}
 
-(To bypass the directory lookup and look for Info files by their file
-name only, use the @option{--file} option, described below.)
-
address@hidden absolute Info file names
 @cindex relative Info file names
 @cindex file names, relative
 @cindex Info files, relative
 If you want to load a file without looking in the search path, specify
 @var{manual} either as an absolute path, or as a path relative to the
-current directory which contains at least one slash character.  Examples:
+current directory which contains at least one slash character.  (You
+can also use the @code{--file} option for similar behavior, described
+below.)
+Examples:
 
 @example
 info /usr/local/share/info/bash.info
@@ -187,16 +192,17 @@
 @end example
 
 @noindent
-Info looks for @var{manual} only in the explicitly specified directory, and
-adds that directory to the value of @code{INFOPATH}.
+Info looks for @var{manual} only in the explicitly specified
+directory, and adds that directory to the value of @code{INFOPATH}.
 
 @anchor{command-line menu items}
 @cindex menu, following
-Info treats its remaining arguments as the names of menu items.  The
-first argument is a menu item in the @samp{Top} node of the file
-loaded, the second argument is a menu item in the first argument's
-node, etc.  You can easily move to the node of your choice by specifying
-the menu names which describe the path to that node.  For example,
+Info treats any remaining arguments as the names of menu items, or
+(see below) index entries.  The first argument is a menu item in the
address@hidden node of the file loaded, the second argument is a menu item
+in the first argument's node, etc.  You can move to the node of your
+choice by specifying the menu names which describe the path to that
+node.  For example,
 
 @example
 info emacs buffers
@@ -218,8 +224,10 @@
 @end example
 
 @noindent
-This loads the libc manual and looks for @code{printf} in its indices; and
-if found, displays the file at the relevant location.
+This loads the libc Info manual and first looks for @code{printf} in
+the top-level menu as usual; since it isn't there (at this writing),
+it then looks in the indices.  If it's found there (which it is),
+displays the relevant node at the given location.
 
 A complete list of options follows.
 
@@ -351,10 +359,11 @@
 any extra @var{menu-item} arguments are used to locate a node within the
 loaded file.
 
-As with the case when this option is not used, if @var{manual} is an absolute
-file name, or begins with @file{./} or @file{../}, or contains an intermediate
-directory, Info will only look for the file in the directory specified, and add
-this directory to @code{INFOPATH}.
+If @var{manual} is an absolute file name, or begins with @file{./} or
address@hidden/}, or contains an intermediate directory, Info will only look
+for the file in the directory specified, and add this directory to
address@hidden  (This is the same as what happens when @code{--file}
+is not given.)
 
 @item --help
 @itemx -h
@@ -389,8 +398,8 @@
 @cindex @code{--node} (@code{-n}) command line option
 @cindex node, selecting from the command line
 Specify a particular node to visit in the initial file that Info
-loads.  You may specify @code{--node} multiple times; for an interactive
-Info, each @var{nodename} is visited in its own window, for a
+loads.  You may specify @code{--node} multiple times: for an interactive
+Info, each @var{nodename} is visited in its own window; for a
 non-interactive Info (such as when @code{--output} is given) each
 @var{nodename} is processed sequentially.
 
@@ -419,13 +428,15 @@
 @code{--no-raw-escapes} to make Info remove them.
 
 @cindex man pages, bold and underline
-Some versions of Groff (@pxref{Top,,,groff,Groff}) produce man pages with
-ANSI escape sequences for bold, italics, and underlined characters, and for
-colorized text.  If your system @command{man} command uses a version of Groff
-that does this, and your terminal supports these sequences, Info will display
-any bold or underlined text in man pages.  Some versions of Groff can be
-configured to turn off the use of these sequences or use an ``overstrike''
-output format instead.  @xref{grotty,,,*manpages*}.
address@hidden GROFF_SGR
+Some versions of Groff (@pxref{Top,,,groff,Groff}) produce man pages
+with ANSI escape sequences for bold, italics, and underlined
+characters, and for colorized text.  If your @command{man} command
+uses a version of Groff that does this (original GNU Groff does), and
+your terminal supports these sequences, Info will display any bold or
+underlined text in man pages.  Some distributions have modified Groff
+to require setting the @code{GROFF_SGR} environment variable to get
+these sequences.  @xref{Invoking grotty,,, groff, Groff}.
 
 @item address@hidden
 @cindex @code{--restore} command line option