LinuxCommandLibrary

install-info

Update or create Info directory file

SYNOPSIS

install-info [OPTION]... INFO_FILE [DIR_FILE]
install-info [OPTION]... --delete INFO_FILE [DIR_FILE]

PARAMETERS

--add
    (Default behavior) Adds an entry for INFO_FILE to DIR_FILE. This is implicitly used when neither --add nor --delete is specified.

--delete, --remove
    Removes an entry for INFO_FILE from DIR_FILE. If the entry is not found, a warning is issued but the command generally succeeds.

--dir-file=DIR_FILE, -d DIR_FILE
    Specifies the Info directory file to update. If not specified, `install-info` searches for a default dir file in common Info directories (e.g., `/usr/share/info/dir`).

--info-dir=DIR
    Specifies the directory where the Info files are located. This option helps `install-info` resolve relative paths if INFO_FILE is not an absolute path. It's often used by package managers to specify the installed Info directory.

--entry=ENTRY
    Specifies the exact menu entry string to add or delete. This is the text that will appear in the Info directory menu for the documentation.

--section=SECTION
    Specifies the section under which the entry should appear in the Info directory menu. Examples include 'Texinfo', 'GNU', 'Programming', etc. This helps organize documentation within the Info reader.

--description=DESCRIPTION
    Provides a one-line description for the menu entry. This descriptive text is displayed alongside the menu entry in the Info directory.

--item=ITEM
    Similar to --entry, but typically used for more specific sub-items or when adding an entry that isn't a top-level document.

--max-width=NUM
    Sets the maximum width of the output when processing data read from standard input. This is less commonly used for typical `install-info` operations.

--no-chdir
    Prevents `install-info` from changing its current working directory before processing. This can be relevant when dealing with complex path configurations.

--quiet, -q
    Suppresses most output messages, making the command run silently unless an error occurs.

--verbose
    Prints more information about what `install-info` is doing, useful for debugging or understanding its operations.

--version
    Displays version information for `install-info` and exits.

--help
    Displays a help message with usage instructions and available options, then exits.

DESCRIPTION

The `install-info` command is a utility used to manage the dir file, which serves as the central index for the GNU Info system documentation. When new Info format documentation files are installed on a system, `install-info` adds entries for these files into the main Info directory file (usually `/usr/share/info/dir` or `/usr/info/dir`). This allows the Info reader program to easily locate and display the new documentation.

Conversely, when Info files are removed, `install-info` can delete their corresponding entries from the dir file, ensuring the index remains accurate and free of broken links. It plays a crucial role in keeping the system's documentation organized and accessible to users through the Info navigation tool, automating what would otherwise be a tedious manual process.

CAVEATS

Using `install-info` requires appropriate permissions to write to the specified Info directory file (DIR_FILE), which often resides in a system-wide location like `/usr/share/info/dir`. Therefore, it's frequently invoked with `sudo` or by package managers as part of software installation or removal processes.

Incorrect usage, especially specifying an incorrect INFO_FILE or DIR_FILE, can lead to orphaned entries in the Info directory or failure to correctly register new documentation. It's generally best practice to let package managers handle `install-info` calls during software installation/uninstallation.

Manually editing the Info `dir` file directly is highly discouraged as it can lead to corruption or inconsistencies that `install-info` might not be able to resolve automatically.

DEFAULT INFO DIRECTORY

By default, `install-info` attempts to update the Info directory file located at `/usr/share/info/dir`. On some older systems or specific distributions, it might default to `/usr/info/dir`. This path can be explicitly overridden using the --dir-file option if a different central Info index needs to be managed.

INTEGRATION WITH PACKAGE MANAGERS

In most Linux distributions, `install-info` is primarily called by package managers (e.g., `dpkg` on Debian/Ubuntu, `rpm` on Red Hat/Fedora, `pacman` on Arch Linux) as part of their post-installation or pre-uninstallation scripts. This ensures that the system's Info index is automatically updated whenever new software with Info documentation is installed or removed, providing a seamless user experience for accessing documentation via the `info` command.

HISTORY

`install-info` is an integral part of the GNU Texinfo documentation system, which has been the standard for creating and distributing GNU project documentation for many years. It was developed as a crucial component to automate the process of keeping the central Info directory index up-to-date.

Its design reflects the need for a robust, scriptable utility to manage the complex interconnections within the Info file hierarchy. It has been maintained by the GNU project as part of the Texinfo distribution since its early days, evolving alongside the Info system itself and ensuring consistent documentation management across GNU/Linux systems.

SEE ALSO

info(1), makeinfo(1), texinfo(5)

Copied to clipboard