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