dpkg/scripts/install-info.8

.\" Hey, Emacs!  This is an -*- nroff -*- source file.
.\" Install-info and this manpage are Copyright 1994 by Ian Jackson.
.\"
.\" This is free software; see the GNU General Public Licence version 2
.\" or later for copying conditions.  There is NO warranty.
.TH INSTALL-INFO 8 "29th November 1995" "Debian Project" "dpkg utilities"
.SH NAME
install\-info \- create or update entry in Info directory
.SH SYNOPSIS
.B install\-info
[\-\-version] [\-\-help] [\-\-debug] [\-\-maxwidth=nnn]
[\-\-section regexp title] [\-\-infodir=xxx] [\-\-align=nnn]
[\-\-quiet] [\-\-menuentry=xxx] [\-\-description=xxx]
[\-\-remove | \-\-remove-exactly ]
[\-\-] filename
.SH DESCRIPTION
.PP
.B install-info
makes, updates or removes entries in the Info directory, the
.B dir
file.  When updating or creating entries, if no description is
specified on the command line or in the Info file it attempts to guess
a description from the contents of the file.

See the description of the
.B \-\-section
option for details of where the entry will be placed and a description
of the expected format of the
.B dir
file.
.SS OPTIONS
.TP
.BI "[\-\-] " filename
Gives the filename of the Info file whose menu entry is to be created,
updated or removed.  If
.B \-\-remove-exactly
is specified, then
.I filename
should be the exact entry name to be removed (i.e. "emacs-20/emacs" or
"gcc"), otherwise the basename of this filename is used as the
referent of the menu entry which is created, unless there's an
overriding START-INFO-DIR entry inside the given file.  This file must
therefore exist (or be about to be installed, or have previously
existed when removing an entry) in the same directory as the
.B dir
file (see the
.B \-\-infodir
option).

If
.I filename
ends in
.B .gz
it is taken to refer to a file compressed with GNU gzip; if it doesn't
exist, but a corresponding
.IB 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
.B .gz
extension).
.TP
.B \-\-remove
Specifies that the entry for the file
.I filename
is to be removed; by default entries are created or updated.

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
.B \-\-keep\-old
is specified.  See the
.B \-\-section
option for details about the expected format of the
.B dir
file.

If there are several suitable entries in the
.B 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
.B install\-info
will issue a warning unless the
.B \-\-quiet
option was specified.

When
.B \-\-remove
is specified the
.BR \-\-maxwidth ", " \-\-align " and " \-\-calign
formatting options are silently ignored.
.TP
.B \-\-remove-exactly
This option is essentially the same as
.B \-\-remove
except that
.I filename
is taken as the exact entry to be removed, rather than as the name
of an existing file.  This can be important when trying to remove
entries that refer to info files in subdirectories
(i.e. "emacs-20/emacs") because
.B \-\-remove
will operate on the basename of the given
.I filename
rather than the exact name given.  (i.e.
.B \-\-remove
"emacs-20/emacs" would cause
.B install-info
to look for "emacs", not "emacs-20/emacs").
.TP
.BI "\-\-section " "regexp title"
Specifies that, if a new entry is to be made, it should be placed in a
section of the
.B dir
file whose title matches
.IR regexp .
If no such section exists one will be created as the second last
section in the file (see below), with title
.IR title .
A section is a part of the
.B dir
menu delimited by blank lines; the first line is assumed to be the
title.

If a new entry is to be created
.B install-info
will attempt to insert it within the section according 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.

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 more well 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
.B install-info
will create both the requested section and a Miscellaneous section at
the end of the file.
.TP
.BI \-\-infodir= infodir
Specifies that the
.B dir
file is, and the installed copy of the new Info file was, is or will
be located in
.IR infodir .
The default is
.BR /usr/info .
.TP
.BI \-\-align= nnn " [deprecated]"
Specifies that the first line of the description should be indented at
least
.I nnn
characters; extra spaces will be added as required.  If necessary
because of the length of the
.B dir
menu entry details it may be offset more.  The default is 27.
.TP
.BI \-\-calign= nnn " [deprecated]"
Specifies that the second and subsequent lines of the description
should be indented at least
.I nnn
characters.  The default is 29.
.TP
.BI \-\-maxwidth= nnn " [deprecated]"
Specifies that the maximum width for the Info file is
.IR nnn .
This is used when wordwrapping the descriptive text.
The default is 79.
.TP
.B \-\-quiet
Prevents the usual display of the new menu entry just before it is
inserted, and of the messages announcing the replacement and removal
of existing entries and the creation and deletion of sections.
.TP
.B \-\-help
Causes
.B install-info
to display its usage information and exit.
.TP
.B \-\-version
Causes
.B install-info
to display its version and copyright information and exit.
.TP
.BI \-\-description= xxx
Specifies that the description to use after the menu entry in new or
updated entries be
.IR xxx .
The default is to use the the value specified in the Info file itself;
this is found by searching for a section of the form
.br
.B START\-INFO\-DIR\-ENTRY
.br
.B * Auto-PGP: (auto-pgp).  PGP under GNU Emacs.
.br
.B END\-INFO\-DIR\-ENTRY

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
.BR \-\-menuentry ", " \-\-maxwidth ", " \-\-align ", " \-\-calign
.RB " and " \-\-menuentry
options are ignored.

If there is no
.B dir
entry in the file the program will try to find a paragraph early in
the file starting
.BR "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
.B \-\-remove
is specified it is ignored and a warning is issued.
.TP
.BI \-\-menuentry= xxx
Specifies that the entry in the menu should be
.IR xxx .
The default is to use the the value specified in the Info file itself.
If this is not present the basename of the Info file is used
.RB "(any " ".info " "is deleted, and the entry is made mixed case)."
See above for details of the format expected for the menu entry in the
Info file.

When removing entries the value of the
.B \-\-menuentry
option must match the actual menu entry field in the menu item to be
removed (case not significant).  If
.B \-\-menuentry
is omitted no check on the menu entry is done.
.TP
.B \-\-keep\-old
Inhibits the replacement of existing entries and the removal of empty
sections.

If the file being installed alreay has an entry in the directory 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
.BR \-\-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.
.TP
.B \-\-test
Enables test mode, which inhibits the update of the directory file.
.TP
.B \-\-debug
Enables debugging mode, in which the results of some internal
processing steps are shown.
.SH "SEE ALSO"
emacs(1), info(1), gzip(1)
.SH COPYRIGHT
Copyright 1994, Ian Jackson.
.B install\-info
is free software; see the GNU General Public Licence version 2 or
later for copying conditions.  There is
.I no
warranty.