File Manager

Editing File: /usr/share/doc/info/html/Invoking-Info.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for Stand-alone GNU Info (version 6.7,
23 September 2019), a program for viewing documents in Info format
(usually created from Texinfo source files).

Copyright (C) 1992, 1993, 1996, 1997, 1998, 1999, 2001,
2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012,
2013, 2014, 2015, 2016, 2017, 2018, 2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
"GNU Free Documentation License" in the Texinfo manual.

This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license. -->

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Invoking Info (Stand-alone GNU Info 6.7)</title>

</head>

<body lang="en">
<div class="header">

Next: <a href="Cursor-Commands.html" accesskey="n" rel="next">Cursor Commands</a>, Previous: <a href="Stand_002dalone-Info.html" accesskey="p" rel="prev">Stand-alone Info</a>, Up: <a href="index.html" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]
</div>
<hr>
<h2 class="chapter">2 Invoking Info</h2>

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:

<div class="example">
<pre class="example">info [<var>option</var>&hellip;] [<var>manual</var>] [<var>menu-or-index-item</var>&hellip;]
</pre></div>

Info will look for an entry called <var>manual</var> in the directory
files, which are named <samp>dir</samp>, that it finds in its search path.
The search is case-insensitive and considers substrings.
(If <var>manual</var> is not given, by default Info displays a composite
directory listing, constructed by combining the <samp>dir</samp> files.)
A basic example:

<div class="example">
<pre class="example">info coreutils
</pre></div>

This looks for an entry labelled <code>coreutils</code>, or
<code>Coreutils</code>, etc., and if found, displays the referenced file
(e.g., <samp>coreutils.info</samp>) at the location given.
<code>info coreu</code> will find it too, if there is no better match.

Another example:

<div class="example">
<pre class="example">info ls
</pre></div>

Assuming the normal <code>dir</code> entry for <code>ls</code>, this will show the
<code>ls</code> documentation, which happens to be within the
<code>coreutils</code> manual rather than a separate manual. The <code>dir</code>
entries can point to an any node within a manual, so that users don&rsquo;t
have to be concerned with the exact structure used by different
authors.




If no entry is found in the directories, Info looks for files in its
search path with names based on <var>manual</var>. If <var>manual</var> is
not found, Info looks for it with a number of known extensions of Info
files, namely <samp>.info</samp>, <samp>-info</samp>, <samp>/index</samp>, and <samp>.inf</samp>.
For every known extension, if a regular file is not found, Info looks
for a compressed file. Info supports files compressed with <code>gzip</code>,
<code>xz</code>, <code>bzip2</code>, <code>lzip</code>, <code>lzma</code>, <code>compress</code> and
<code>yabba</code> programs, assumed to have extensions <samp>.z</samp>, <samp>.gz</samp>,
<samp>.xz</samp>, <samp>.bz2</samp>, <samp>.lz</samp>, <samp>.lzma</samp>, <samp>.Z</samp>, and
<samp>.Y</samp> respectively.<a id="DOCF1" href="#FOOT1">1</a>

You can specify the name of a node to visit with the <code>--node</code> or 
<code>-n</code> 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 &lsquo;<samp>Files</samp>&rsquo; node within the 
&lsquo;<samp>emacs</samp>&rsquo; manual:

<div class="example">
<pre class="example">info emacs -n Files
info '(emacs)Files'
</pre></div>

If you want to load a file without looking in the search path, specify
<var>manual</var> 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 <code>--file</code> option for similar behavior, described
below.)
Examples:

<div class="example">
<pre class="example">info /usr/local/share/info/bash.info
info ./document.info
</pre></div>

Info looks for <var>manual</var> 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
&lsquo;<samp>Top</samp>&rsquo; node of the file loaded, the second argument is a menu item
in the first argument&rsquo;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,

<div class="example">
<pre class="example">info emacs buffers
info texinfo Overview 'Using Texinfo'
</pre></div>

The first example selects the menu item &lsquo;<samp>Buffers</samp>&rsquo; in the node
&lsquo;<samp>(emacs)Top</samp>&rsquo;. The second example loads the <samp>texinfo</samp> file and
looks in its top-level menu for a &lsquo;<samp>Overview</samp>&rsquo; item, looks in the menu
of the node referenced, and finally displays the node referenced by the
&lsquo;<samp>Using Texinfo</samp>&rsquo; item.

If there was only one <var>menu-or-index-item</var> argument and it wasn&rsquo;t
found as a menu item, Info looks for it as an index entry. For example:

<div class="example">
<pre class="example">info libc printf
</pre></div>

This loads the libc Info manual and first looks for <code>printf</code> in
the top-level menu as usual; since it isn&rsquo;t there (at this writing),
it then looks in the indices. If it&rsquo;s found there (which it is),
the relevant node at the given location is displayed.

A complete list of options follows.

<dl compact="compact">
<dd></dd>
<dt><code>--all</code></dt>
<dt><code>-a</code></dt>
<dd>
Find all files matching <var>manual</var>. Three usage patterns are
supported, as follows.

First, if <code>--all</code> is used together with <samp>--where</samp>,
<code>info</code> prints the names of all matching files found on
standard output (including &lsquo;<samp>*manpages*</samp>&rsquo; if relevant) and exits.

Second, if <code>--all</code> is used together with <samp>--output</samp>, 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 <kbd>C-x f</kbd>. If there is only one match, <code>info</code>
starts as usual.

When used with the <samp>--index-search</samp> option, <code>info</code>
displays a menu of matching index entries (just as the
<code>virtual-index</code> command does; see <a href="Index-Commands.html">Index Commands</a>).

The <samp>--node</samp> option cannot be used together with this option.

</dd>
<dt><code>--apropos=<var>string</var></code></dt>
<dt><code>-k <var>string</var></code></dt>
<dd>



Specify a string to search in every index of every Info file installed
on your system. Info looks up the named <var>string</var> 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
<a href="Searching-Commands.html">Searching Commands</a>.

</dd>
<dt><code>--debug=<var>number</var></code></dt>
<dt><code>-x <var>number</var></code></dt>
<dd>

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
<samp>-x&nbsp;-1</samp>. Info version 6.7 has these levels:

<dl compact="compact">
<dt><code>1</code></dt>
<dd>Print information about file handling, such as looking for <samp>dir</samp>
files and nodes written with &lsquo;<samp>--output</samp>&rsquo;.

</dd>
<dt><code>2</code></dt>
<dd>Print operations relating to <code>INFOPATH</code>.

</dd>
<dt><code>3</code></dt>
<dd>Print information about node searching.
</dd>
</dl>

Debugging output goes to standard error.

</dd>
<dt><code>--directory <var>directory-path</var></code></dt>
<dt><code>-d <var>directory-path</var></code></dt>
<dd>


Add <var>directory-path</var> to the list of directory paths searched
when Info needs to find a file. You may issue <code>--directory</code>
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 <code>INFOPATH</code> are added
to the directories specified with <code>--directory</code>, if any. The value of
<code>INFOPATH</code> is a list of directories usually separated by a colon;
on MS-DOS/MS-Windows systems, the semicolon is used. If the value of
<code>INFOPATH</code> 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 <code>INFOPATH</code>.

If you do not define <code>INFOPATH</code>, Info uses a default path defined
when Info was built as the initial list of directories. 

Regardless of whether <code>INFOPATH</code> 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 <code>infopath-no-defaults</code> variable to <code>On</code>
(see <a href="Variables.html#infopath_002dno_002ddefaults">infopath-no-defaults</a>).
 
If the list of directories contains the element <code>PATH</code>, that
element is replaced by a list of directories derived from the value of
the environment variable <code>PATH</code>. Each path element of the form
<var>dir/base</var> is replaced by <var>dir</var><code>/share/info</code> or
<var>dir</var><code>/info</code>, provided that directory exists.

</dd>
<dt><code>--dribble=<var>file</var></code></dt>
<dd>


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
&lsquo;<samp>--restore</samp>&rsquo; option below.

</dd>
<dt><code>--file <var>manual</var></code></dt>
<dt><code>-f <var>manual</var></code></dt>
<dd>



Specify a particular manual to visit without looking its name up in any
<samp>dir</samp> files.

With this option, it starts by trying to visit
<code>(<var>manual</var>)Top</code>, i.e., the <code>Top</code> node in (typically)
<samp><var>manual</var>.info</samp>. 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 <samp>dir</samp> lookup described above,
any extra <var>menu-or-index-item</var> arguments are used to locate a node 
within the loaded file.

If <var>manual</var> is an absolute file name, or begins with <samp>./</samp> or
<samp>../</samp>, or contains an intermediate directory, Info will only look
for the file in the directory specified, and add this directory to
<code>INFOPATH</code>. (This is the same as what happens when <code>--file</code>
is not given.)

</dd>
<dt><code>--help</code></dt>
<dt><code>-h</code></dt>
<dd>
Output a brief description of the available Info command-line options.

</dd>
<dt><code>--index-search <var>string</var></code></dt>
<dd>


After processing all command-line arguments, go to the index in the
selected Info file and search for index entries which match
<var>string</var>. If such an entry is found, the Info session begins with
displaying the node pointed to by the first matching index entry;
press <kbd>,</kbd> to step through the rest of the matching entries. If no
such entry exists, print &lsquo;<samp>no entries found</samp>&rsquo; 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&rsquo;t know the exact name of that node.

When used with the <samp>--all</samp> option, <code>info</code>
displays a menu of matching index entries (just as the
<code>virtual-index</code> command does; see <a href="Index-Commands.html">Index Commands</a>).

This command can also be invoked from inside Info; see <a href="Searching-Commands.html">Searching Commands</a>.

</dd>
<dt><code>--init-file <var>INIT-FILE</var></code></dt>
<dd>
Read key bindings and variable settings from <var>INIT-FILE</var> instead
of the <samp>.infokey</samp> file in your home directory. See <a href="Custom-Key-Bindings.html">Custom Key Bindings</a>.

</dd>
<dt><code>--node <var>nodename</var></code></dt>
<dt><code>-n <var>nodename</var></code></dt>
<dd>

Specify a particular node to visit in the initial file that Info
loads. You may specify <code>--node</code> multiple times: for an interactive
Info, each <var>nodename</var> is visited in its own window; for a
non-interactive Info (such as when <code>--output</code> is given) each
<var>nodename</var> is processed sequentially.

You can specify both the file and node to the <code>--node</code> option
using the usual Info syntax, but don&rsquo;t forget to escape the open and
close parentheses and whitespace from the shell; for example: 
<tt>info --node &quot;(emacs)Buffers&quot;</tt>

</dd>
<dt><code>--output <var>file</var></code></dt>
<dt><code>-o <var>file</var></code></dt>
<dd>


Direct output to <var>file</var>. Each node that Info visits will be
output to <var>file</var> instead of interactively viewed. A value of
<code>-</code> for <var>file</var> means standard output.

</dd>
<dt><code>--no-raw-escapes</code></dt>
<dt><code>--raw-escapes, -R</code></dt>
<dd>


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 <code>--no-raw-escapes</code> options, these
sequences are displayed as other control characters are; for example, an
<kbd>ESC</kbd> byte is displayed as &lsquo;<samp>^[</samp>&rsquo;. The <code>--raw-escapes</code> and
<code>-R</code> options do not do anything, but are included for completeness.



Some versions of Groff (see <cite><a href="../groff/index.html#Top">Groff</a></cite>) produce man pages
with ANSI escape sequences for bold, italics, and underlined
characters, and for colorized text. If your <code>man</code> 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</code> environment variable to get
these sequences. See <a href="../groff/Invoking-grotty.html#Invoking-grotty">Invoking grotty</a> in <cite>Groff</cite>.

</dd>
<dt><code>--restore=<var>dribble-file</var></code></dt>
<dd>

Read keystrokes from <var>dribble-file</var>, presumably recorded during
previous Info session (see the description of the &lsquo;<samp>--dribble</samp>&rsquo;
option above). When the keystrokes in the files are all read, Info
reverts its input to the usual interactive operation.

</dd>
<dt><code>--show-malformed-multibytes</code></dt>
<dt><code>--no-show-malformed-multibytes</code></dt>
<dd>

Show malformed multibyte sequences in the output. By default, such
sequences are dropped.

</dd>
<dt><code>--show-options</code></dt>
<dt><code>--usage</code></dt>
<dt><code>-O</code></dt>
<dd>


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 <code>M-x
goto-invocation</code> command (see <a href="Node-Commands.html#goto_002dinvocation">goto-invocation</a>) from inside Info.

</dd>
<dt><code>--speech-friendly</code></dt>
<dt><code>-b</code></dt>
<dd>

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.

</dd>
<dt><code>--strict-node-location</code></dt>
<dd>
This option causes Info not to search &ldquo;nearby&rdquo; 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.

</dd>
<dt><code>--subnodes</code></dt>
<dd>
This option only has meaning when given in conjunction with
<code>--output</code>. 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.

</dd>
<dt><code>-v <var>name</var>=<var>value</var></code></dt>
<dt><code>--variable=<var>name</var>=<var>value</var></code></dt>
<dd>

Set the <code>info</code> variable <var>name</var> to <var>value</var>.
See <a href="Variables.html">Variables</a>.

</dd>
<dt><code>--version</code></dt>
<dd>

Prints the version information of Info and exits.

</dd>
<dt><code>--vi-keys</code></dt>
<dd>


This option binds functions to keys differently, to emulate the key
bindings of <code>vi</code> and Less. The bindings activated by this option
are documented in <a href="infokey-format.html"><tt>infokey</tt> format</a>. (See <a href="Custom-Key-Bindings.html">Custom Key Bindings</a> 
for a more general way of altering GNU Info&rsquo;s key bindings.)

</dd>
<dt><code>--where</code></dt>
<dt><code>--location</code></dt>
<dt><code>-w</code></dt>
<dd>


Show the filename that would be read and exit, instead of actually
reading it and starting Info.
</dd>
</dl>

Finally, Info defines many default key bindings and variables.
See <a href="Custom-Key-Bindings.html">Custom Key Bindings</a> for information on how to customize these
settings.

<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h5><a id="FOOT1" href="#DOCF1">(1)</a></h3>
On MS-DOS, Info allows for the Info
extension, such as <code>.inf</code>, and the short compressed file extensions,
such as <samp>.z</samp> and <samp>.gz</samp>, to be merged into a single extension,
since DOS doesn&rsquo;t allow more than a single dot in the basename of
a file. Thus, on MS-DOS, if Info looks for <samp>bison</samp>, file names
like <samp>bison.igz</samp> and <samp>bison.inz</samp> will be found and decompressed
by <code>gunzip</code>.
</div>
<hr>
<div class="header">

Next: <a href="Cursor-Commands.html" accesskey="n" rel="next">Cursor Commands</a>, Previous: <a href="Stand_002dalone-Info.html" accesskey="p" rel="prev">Stand-alone Info</a>, Up: <a href="index.html" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]
</div>

</body>
</html>

Back to Directory File Manager