See the description of the --section option for details of where the entry will be placed and a description of the expected format of the dir file.
If filename ends in .gz, it is taken to refer to a file compressed with gzip; if it doesn't exist, but a corresponding filename.gz does, the latter is used instead.
When adding or updating entries, the file must exist at the path specified (possibly with an additional .gz extension).
If the removal results in a section becoming empty, the section heading (and the spare blank line) will be removed as well, unless this is the last section in the file or --keep-old is specified. See the --section option for details about the expected format of the dir file.
If there are several suitable entries in the dir file, only those in the first matching contiguous group will be removed and the others silently ignored.
It is not an error for no suitable entry to be found, though install-info will issue a warning unless the --quiet option was specified.
When --remove is specified the --maxwidth, --align and --calign formatting options are silently ignored.
If a new entry is to be created, install-info will attempt to insert it within the section in alphabetic order. If the entries in the section aren't already sorted, the new location within the section will be unpredictable. The order of existing entries will not be changed.
If the --section option is not specified, install-info will look for a title in the Info file itself by looking for an entry of the form
If no section title is found, the default is to append new entries to the end of the file. The last section (even if it only consists of the title line) should always exist to ensure that new sections are created in the right place. The final section should be titled to reflect the fact that Info files with no better specified location are appended to it.
If there is already an entry for the Info file being installed, it is replaced in situ with the new entry.
If a section is specified when removing an entry, the section is ignored and a warning is issued.
If a section is requested when adding an entry, but the file contains no section headings at all, then install-info will create both the requested section and a Miscellaneous section at the end of the file.
If the entry found in the Info file itself extends across several lines, each giving a menu entry, the text found in the file is used verbatim. In this case, the alphabetic ordering scheme is turned off, and the entries are inserted at the top of section in question. In this case, the --menuentry, --maxwidth, --align, --calign and --menuentry options are ignored.
If there is no dir entry in the file, the program will try to find a paragraph early in the file starting this file documents. It will capitalise the first character of the remainder, and use that.
It is an error for none of these methods to yield a description.
If a description argument is given when --remove is specified, it is ignored and a warning is issued.
When removing entries, the value of the --menuentry option must match the actual menu entry field in the menu item to be removed (case not significant). If --menuentry is omitted, no check on the menu entry is done.
If the file being installed already has an entry in the Info dir file, the old entry will be left alone instead of being replaced; the default is to overwrite any old entry found with the newly generated one.
If --remove is specified, --keep-old will prevent the removal of the section heading which would otherwise happen if the section is made empty by the removal.
This is free software; see the GNU General Public Licence version 2 or later for copying conditions. There is NO WARRANTY.