GNU Info accepts several options to control the initial node or nodes being viewed, and to specify which directories to search for Info files. Here is a template showing an invocation of GNU Info from the shell:
info [option...] [manual] [menu-or-index-item...]
Info will look for an entry called manual in the directory files, which are named dir, that it finds in its search path. The search is case-insensitive and considers substrings. (If manual is not given, by default Info displays a composite directory listing, constructed by combining the dir files.) A basic example:
info coreutils
This looks for an entry labelled coreutils
, or
Coreutils
, etc., and if found, displays the referenced file
(e.g., coreutils.info) at the location given.
info coreu
will find it too, if there is no better match.
Another example:
info ls
Assuming the normal dir
entry for ls
, this will show the
ls
documentation, which happens to be within the
coreutils
manual rather than a separate manual. The dir
entries can point to any node within a manual, so that users don’t
have to be concerned with the exact structure used by different
authors.
If no entry is found in the directories, Info looks for a file called manual in its search path. If not found, Info looks for it with the file extensions .info, -info, and .inf. For each of these known extensions, if a regular file is not found, Info looks for a compressed file.2
You can specify the name of a node to visit with the --node
or
-n
option. Alternatively, you can specify the file and node
together using the same format that occurs in Info cross-references.
These two examples both load the ‘Files’ node within the
‘emacs’ manual:
info emacs -n Files info '(emacs)Files'
If you want to load a file without looking in the search path, specify
manual either as an absolute path, or as a path relative to the
current directory which contains at least one slash character. (You
can also use the --file
option for similar behavior, described
below.)
Examples:
info /usr/local/share/info/bash.info info ./document.info
Info looks for manual only in the explicitly specified directory, and adds that directory to its search path.
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 ‘Top’ 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,
info emacs buffers info texinfo Overview 'Using Texinfo'
The first example selects the menu item ‘Buffers’ in the node ‘(emacs)Top’. The second example loads the texinfo file and looks in its top-level menu for a ‘Overview’ item, looks in the menu of the node referenced, and finally displays the node referenced by the ‘Using Texinfo’ item.
If there was only one menu-or-index-item argument and it wasn’t found as a menu item, Info looks for it as an index entry. For example:
info libc printf
This loads the libc Info manual and first looks for 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),
the relevant node at the given location is displayed.
If Info is invoked when its standard output is not a terminal, it does not attempt to start an interactive session; rather, it writes the contents of the loaded nodes and subnodes to standard output, as if the --output=- and --subnodes options were given. This can be used to pipe the contents of Info nodes to another program, such as a pager.
A complete list of options follows.
--all
¶-a
Find all files matching manual. Three usage patterns are supported, as follows.
First, if --all
is used together with --where,
info
prints the names of all matching files found on
standard output (including ‘*manpages*’ if relevant) and exits.
Second, if --all
is used together with --output, the
contents of all matched files are dumped to the specified output
file.
Otherwise, an interactive session is initiated. If more than one file
matches, a menu node is displayed listing the matches and allowing you
to select one. This menu node can be brought back at any time by
pressing C-x f. If there is only one match, info
starts as usual.
When used with the --index-search option, info
displays a menu of matching index entries (just as the
virtual-index
command does; see Index Commands).
The --node option cannot be used together with this option.
--apropos=string
¶-k string
Specify a string to search in every index of every Info file installed on your system. Info looks up the named string in all the indices it can find, prints the results to standard output, and then exits. If you are not sure which Info file explains certain issues, this option is your friend. (If your system has a lot of Info files installed, searching all of them might take some time!)
You can invoke the apropos command from inside Info; see Searching an Info File.
--debug=number
¶-x number
Print additional debugging information. The argument specifies the verbosity level, so a higher level includes all the information from lower levels. For all available debugging output, use -x -1. Info version 7.1.1 has these levels:
1
Print information about file handling, such as looking for dir files and nodes written with ‘--output’.
2
Print operations relating to INFOPATH
.
3
Print information about node searching.
Debugging output goes to standard error.
--directory directory-path
¶-d directory-path
Add directory-path to the list of directory paths searched
when Info needs to find a file. You may issue --directory
multiple times; once for each directory which contains Info files,
or with a list of such directories separated by a colon (or semicolon
on MS-DOS/MS-Windows).
Directories specified in the environment variable INFOPATH
are added
to the directories specified with --directory
, if any. The value of
INFOPATH
is a list of directories usually separated by a colon;
on MS-DOS/MS-Windows systems, the semicolon is used. If the value of
INFOPATH
ends with a colon (or semicolon on MS-DOS/MS-Windows),
the initial list of directories is constructed by appending the
build-time default to the value of INFOPATH
.
If you do not define INFOPATH
, Info uses a default path defined
when Info was built as the initial list of directories.
Regardless of whether INFOPATH
is defined, the default
documentation directory defined when Info was built is added to the
search path. If you do not want this directory to be included, set
the infopath-no-defaults
variable to On
(see infopath-no-defaults).
If the list of directories contains the element PATH
, that
element is replaced by a list of directories derived from the value of
the environment variable PATH
. Each path element of the form
dir/base is replaced by dir/share/info
or
dir/info
, provided that directory exists.
--dribble=file
¶Specify a file where all user keystrokes will be recorded. This file can be used later to replay the same sequence of commands, see the ‘--restore’ option below.
--file manual
¶-f manual
Specify a particular manual to visit without looking its name up in any dir files.
With this option, it starts by trying to visit
(manual)Top
, i.e., the Top
node in (typically)
manual.info. As above, it tries various file extensions
to find the file. If no such file (or node) can be found, Info exits
without doing anything. As with the dir lookup described above,
any extra menu-or-index-item arguments are used to locate a node
within the loaded file.
If manual is an absolute file name, or begins with ./ or
../, or contains an intermediate directory, Info will only look
for the file in the directory specified, and add this directory to
INFOPATH
. (This is the same as what happens when --file
is not given.)
--help
¶-h
Output a brief description of the available Info command-line options.
--index-search string
¶After processing all command-line arguments, go to the index in the selected Info file and search for index entries which match string. If such an entry is found, the Info session begins with displaying the node pointed to by the first matching index entry; press , to step through the rest of the matching entries. If no such entry exists, print ‘no entries found’ and exit with nonzero status. This can be used from another program as a way to provide online help, or as a quick way of starting to read an Info file at a certain node when you don’t know the exact name of that node.
When used with the --all option, info
displays a menu of matching index entries (just as the
virtual-index
command does; see Index Commands).
This command can also be invoked from inside Info; see Searching an Info File.
--init-file INIT-FILE
Read key bindings and variable settings from INIT-FILE instead of the .infokey file in your home directory. See Customizing Key Bindings and Variables.
--node nodename
¶-n nodename
Specify a particular node to visit in the initial file that Info
loads. You may specify --node
multiple times: for an interactive
Info, each nodename is visited in its own window; for a
non-interactive Info (such as when --output
is given) each
nodename is processed sequentially.
You can specify both the file and node to the --node
option
using the usual Info syntax, but don’t forget to escape the open and
close parentheses and whitespace from the shell; for example:
info --node "(emacs)Buffers"
--output file
¶-o file
Direct output to file. Each node that Info visits will be
output to file instead of interactively viewed. A value of
-
for file means standard output.
--no-raw-escapes
--raw-escapes, -R
By default, Info passes SGR terminal control sequences (also known as
ANSI escape sequences) found in documents directly through to the
terminal. If you use the --no-raw-escapes
options, these
sequences are displayed as other control characters are; for example, an
ESC byte is displayed as ‘^[’. The --raw-escapes
and
-R
options do not do anything, but are included for completeness.
--restore=dribble-file
¶Read keystrokes from dribble-file, presumably recorded during previous Info session (see the description of the ‘--dribble’ option above). When the keystrokes in the files are all read, Info reverts its input to the usual interactive operation.
--show-malformed-multibytes
¶--no-show-malformed-multibytes
Show malformed multibyte sequences in the output. By default, such sequences are dropped.
--show-options
¶--usage
-O
Look for the node that describes how to invoke the
program. The name of the program is taken from the other non-option
arguments on the command line. For example, ‘info emacs -O’ loads
the Emacs Invocation
node of the emacs
manual.
This option is provided to make it easier to find the
most important usage information in a manual without navigating
through menu hierarchies. The effect is similar to the M-x
goto-invocation
command (see goto-invocation) from inside Info.
--speech-friendly
¶-b
On MS-DOS/MS-Windows only, this option causes Info to use standard file I/O functions for screen writes. (By default, Info uses direct writes to the video memory on these systems, for faster operation and colored display support.) This allows the speech synthesizers used by blind persons to catch the output and convert it to audible speech.
--strict-node-location
¶This option causes Info not to search “nearby” to locate nodes, and instead strictly use the information provided in the Info file. The practical use for this option is for debugging programs that write Info files, to check that they are outputting the correct locations. Due to bugs and malfeasances in the various Info writing programs over the years and versions, it is not advisable to ever use this option when just trying to read documentation.
--subnodes
¶This option only has meaning when given in conjunction with
--output
. It means to recursively output the nodes appearing in
the menus of each node being output. Menu items which resolve to
external Info files are not output, and neither are menu items which are
members of an index. Each node is only output once.
-v name=value
¶--variable=name=value
Set the info
variable name to value.
See Manipulating Variables.
--version
¶Prints the version information of Info and exits.
--vi-keys
¶This option binds functions to keys differently, to emulate the key
bindings of vi
and Less. The bindings activated by this option
are documented in infokey
format. (See Customizing Key Bindings and Variables
for a more general way of altering GNU Info’s key bindings.)
--where
¶--location
-w
Show the filename that would be read and exit, instead of actually reading it and starting Info.
Finally, Info defines many default key bindings and variables. See Customizing Key Bindings and Variables for information on how to customize these settings.
Info supports files
compressed with gzip
, xz
, bzip2
, lzip
,
lzma
, compress
and yabba
programs, assumed
to have extensions .z, .gz, .xz, .bz2,
.lz, .lzma, .Z, and .Y respectively.
On MS-DOS, Info allows for the Info
extension, such as .inf
, and the short compressed file extensions,
such as .z and .gz, to be merged into a single extension,
since DOS doesn’t allow more than a single dot in the basename of
a file. Thus, on MS-DOS, if Info looks for bison, file names
like bison.igz and bison.inz will be found and decompressed
by gunzip
.