Next: , Previous: , Up: Top   [Contents][Index]


2 Invoking Info

GNU Info accepts several options to control the initial node 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]… [menu-item…]

The program accepts the following options:

--all
-a

Find all files matching the given menu-item (a file or node name). 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.

The --index-search and --node options 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 Commands.

--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 5.2 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.

Before Info’s full-screen output is initialized, debugging output goes to standard error. After it is initialized, the debugging output is written to the file infodebug in the current working directory.

--directory directory-path
-d directory-path

Prepend 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). In the absence of --directory options the list of directories searched by Info is constructed from the value of the environment variable INFOPATH. 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 you do not define INFOPATH, Info uses a default path defined when Info was built as the initial list of directories. 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 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. By default, Info starts at a top-level “directory” (constructed by combining the dir files that it finds). With this option, it starts by trying to visit (manual)Top, i.e., the Top node in (typically) manual.info. If no such file (or node) can be found, Info just exits immediately.

Thus, info -f emacs is rather different from info emacs. With the latter, ‘emacs’ is treated as a menu item, meaning a case-insensitive match to the text before the colon in a typical dir entry:

* Emacs: (emacs).  The extensible ...

An exact match (‘* emacs:’) is preferred to a case-folding match. This can often happen when the name of a utility and its containing manual are the same.

If manual is an absolute file name, or begins with ./ or ../, or contains an intermediate directory, Info looks for manual only in that explicitly specified directory, and adds that directory to the value of INFOPATH. For example, info -f /usr/local/share/info/emacs and info -f ./emacs visit the Emacs manual in the given directory, or quits. Otherwise, manual is a simple name (info -f emacs), and Info will only look for it in the directories specified in INFOPATH—not relative to the current directory.

In every directory Info tries, if filename is not found, Info looks for it with a number of known extensions of Info files, namely .info, -info, /index, and .inf. For every known extension, Info looks for a compressed file, if a regular file isn’t found. 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, possibly after one of the known Info files extensions.

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.

--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.

This command can also be invoked from inside Info; see Searching Commands.

--node nodename
-n nodename

Specify a particular node to visit in the initial file that Info loads. This is especially useful in conjunction with --file. 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.

--raw-escapes
--no-raw-escapes
-R

Do not remove ANSI escape sequences from documents. Some versions of Groff (see Groff) produce man pages with ANSI escape sequences for bold, italics, and underlined characters, and for colorized text. By default, Info lets those escape sequences pass through directly to the terminal. If your terminal does not support these escapes, use --no-raw-escapes to make Info remove them.

--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

Tell Info to look for the node that describes how to invoke the program and its command-line options, and begin the session by displaying that node. It 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 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 default key bindings are generally modeled after Emacs. (See Custom Key Bindings, 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.

menu-item

Info treats its remaining arguments as the names of menu items. The first argument is a menu item in the initial node visited (generally dir), 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 emacs buffers

first selects the menu item ‘Emacs’ in the node ‘(dir)Top’, and then selects the menu item ‘Buffers’ in the node ‘(emacs)Top’.

To avoid searching the dir files and just show some arbitrary file, use ‘-f’ and the filename, as in ‘info -f ./foo.info’.

The index search and the search for the node which describes program invocation and command-line options begins after processing all the command-line menu items. Therefore, the Info file searched for the index or the invocation node is the file where Info finds itself after following all the menu items given on the command line. This is so ‘info emacs --show-options’ does what you’d expect.

Finally, Info defines many default key bindings and variables. See Custom Key Bindings, for information on how to customize these settings.


Next: , Previous: , Up: Top   [Contents][Index]