21.2.5 Invoking install-info

install-info inserts menu entries from an Info file into the top-level dir file in the Info system (see the previous sections for an explanation of how the dir file works). install-info also removes menu entries from the dir file. It’s most often run as part of software installation, or when constructing a dir file for all manuals on a system. Synopsis:

install-info [option…] [info-file [dir-file]]

If info-file or dir-file are not specified, the options (described below) that define them must be. There are no compile-time defaults, and standard input is never used. install-info can read only one Info file and write only one dir file per invocation.

If dir-file (however specified) does not exist, install-info creates it if possible (with no entries).

If any input file is compressed with gzip (see Gzip), install-info automatically uncompresses it for reading. And if dir-file is compressed, install-info also automatically leaves it compressed after writing any changes. If dir-file itself does not exist, install-info tries to open dir-file.gz, dir-file.xz, dir-file.bz2, dir-file.lz, and dir-file.lzma, in that order.

Options:

--add-once

Specifies that the entry or entries will only be put into a single section.

--align=column

Specifies the column that the second and subsequent lines of menu entry’s description will be formatted to begin at. The default for this option is ‘35’. It is used in conjunction with the ‘--max-width’ option. column starts counting at 1.

--append-new-sections

Instead of alphabetizing new sections, place them at the end of the DIR file.

--calign=column

Specifies the column that the first line of menu entry’s description will be formatted to begin at. The default for this option is ‘33’. It is used in conjunction with the ‘--max-width’ option. When the name of the menu entry exceeds this column, entry’s description will start on the following line. column starts counting at 1.

--debug

Report what is being done.

--delete

Delete the entries in info-file from dir-file. The file name in the entry in dir-file must be info-file (except for an optional ‘.info’ in either one). Don’t insert any new entries. Any empty sections that result from the removal are also removed.

--description=text

Specify the explanatory portion of the menu entry. If you don’t specify a description (either via ‘--entry’, ‘--item’ or this option), the description is taken from the Info file itself.

--dir-file=name

Specify file name of the Info directory file. This is equivalent to using the dir-file argument.

--dry-run

Same as ‘--test’.

--entry=text

Insert text as an Info directory entry; text should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all added. If you don’t specify any entries, they are determined from information in the Info file itself.

--help

Display a usage message with basic usage and all available options, then exit successfully.

--info-file=file

Specify Info file to install in the directory. This is equivalent to using the info-file argument.

--info-dir=dir

Specify the directory where the directory file dir resides. Equivalent to ‘--dir-file=dir/dir’.

--infodir=dir

Same as ‘--info-dir’.

--item=text

Same as ‘--entry=text’. An Info directory entry is actually a menu item.

--keep-old

Do not replace pre-existing menu entries. When ‘--remove’ is specified, this option means that empty sections are not removed.

--max-width=column

Specifies the column that the menu entry’s description will be word-wrapped at. column starts counting at 1.

--maxwidth=column

Same as ‘--max-width’.

--menuentry=text

Same as ‘--name’.

--name=text

Specify the name portion of the menu entry. If the text does not start with an asterisk ‘*’, it is presumed to be the text after the ‘*’ and before the parentheses that specify the Info file. Otherwise text is taken verbatim, and is taken as defining the text up to and including the first period (a space is appended if necessary). If you don’t specify the name (either via ‘--entry’, ‘--item’ or this option), it is taken from the Info file itself. If the Info does not contain the name, the basename of the Info file is used.

--no-indent

Suppress formatting of new entries into the dir file.

--quiet

--silent

Suppress warnings, etc., for silent operation.

--remove

Same as ‘--delete’.

--remove-exactly

Also like ‘--delete’, but only entries if the Info file name matches exactly; .info and/or .gz suffixes are not ignored.

--section=sec

Put this file’s entries in section sec of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don’t specify any sections, they are determined from information in the Info file itself. If the Info file doesn’t specify a section, the menu entries are put into the Miscellaneous section.

--section regex sec

Same as ‘--regex=regex --section=sec --add-once’.

install-info tries to detect when this alternate syntax is used, but does not always guess correctly. Here is the heuristic that install-info uses:

1. If the second argument to --section starts with a hyphen, the original syntax is presumed.
2. If the second argument to --section is a file that can be opened, the original syntax is presumed.
3. Otherwise the alternate syntax is used.

When the heuristic fails because your section title starts with a hyphen, or it happens to be a filename that can be opened, the syntax should be changed to ‘--regex=regex --section=sec --add-once’.

--regex=regex

Put this file’s entries into any section that matches regex. If more than one section matches, all of the entries are added in each of the sections. Specify regex using basic regular expression syntax, more or less as used with grep, for example.

--test

Suppress updating of the directory file.

--version

Display version information and exit successfully.