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)