scripts/install-info.8

   1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
   2 .\" Install-info and this manpage are Copyright 1994 by Ian Jackson.
   3 .\"
   4 .\" This is free software; see the GNU General Public Licence version 2
   5 .\" or later for copying conditions.  There is NO warranty.
   6 .TH INSTALL-INFO 8 "29th November 1995" "Debian Project" "Debian GNU/Linux"
   7 .SH NAME
   8 install\-info \- create or update entry in Info directory
   9 .SH SYNOPSIS
  10 .B install\-info
  11 [\-\-version] [\-\-help] [\-\-debug] [\-\-maxwidth=nnn]
  12 [\-\-section regexp title] [\-\-infodir=xxx] [\-\-align=nnn]
  13 [\-\-quiet] [\-\-menuentry=xxx] [\-\-description=xxx] [\-\-remove]
  14 [\-\-] filename
  15 .SH DESCRIPTION
  16 .PP
  17 .B install-info
  18 makes, updates or removes entries in the Info directory, the
  19 .B dir
  20 file.  When updating or creating entries, if no description is
  21 specified on the command line or in the Info file it attempts to guess
  22 a description from the contents of the file.
  23
  24 See the description of the
  25 .B \-\-section
  26 option for details of where the entry will be placed and a description
  27 of the expected format of the
  28 .B dir
  29 file.
  30 .SS OPTIONS
  31 .TP
  32 .BI "[\-\-] " filename
  33 Gives the filename of the Info file whose menu entry is to be created,
  34 updated or removed.  The basename of this filename is used as the
  35 referent of the menu entry which is created.  This file must therefore
  36 exist (or be about to be installed, or have previously existed when
  37 removing an entry) in the same directory as the
  38 .B dir
  39 file (see the
  40 .B \-\-infodir
  41 option).
  42
  43 If
  44 .I filename
  45 ends in
  46 .B .gz
  47 it is taken to refer to a file compressed with GNU gzip; if it doesn't
  48 exist, but a corresponding
  49 .IB filename .gz
  50 does, the latter is used instead.
  51
  52 When adding or updating entries the file must exist at the path
  53 specified (possibly with an additional
  54 .B .gz
  55 extension).
  56 .TP
  57 .B \-\-remove
  58 Specifies that the entry for the file
  59 .I filename
  60 is to be removed; by default entries are created or updated.
  61
  62 If the removal results in a section becoming empty the section heading
  63 (and the spare blank line) will be removed as well, unless this is the
  64 last section in the file or
  65 .B \-\-keep\-old
  66 is specified.  See the
  67 .B \-\-section
  68 option for details about the expected format of the
  69 .B dir
  70 file.
  71
  72 If there are several suitable entries in the
  73 .B dir
  74 file only those in the first matching contiguous group will be removed
  75 and the others silently ignored.
  76
  77 It is not an error for no suitable entry to be found, though
  78 .B install\-info
  79 will issue a warning unless the
  80 .B \-\-quiet
  81 option was specified.
  82
  83 When
  84 .B \-\-remove
  85 is specified the
  86 .BR \-\-maxwidth ", " \-\-align " and " \-\-calign
  87 formatting options are silently ignored.
  88 .TP
  89 .BI "\-\-section " "regexp title"
  90 Specifies that, if a new entry is to be made, it should be placed in a
  91 section of the
  92 .B dir
  93 file whose title matches
  94 .IR regexp .
  95 If no such section exists one will be created as the second last
  96 section in the file (see below), with title
  97 .IR title .
  98 A section is a part of the
  99 .B dir
 100 menu delimited by blank lines; the first line is assumed to be the
 101 title.
 102
 103 If a new entry is to be created
 104 .B install-info
 105 will attempt to insert it within the section according in alphabetic
 106 order; if the entries in the section aren't already sorted the new
 107 location within the section will be unpredictable.  The order of
 108 existing entries will not be changed.
 109
 110 The default is to append new entries to the end of the file.  The last
 111 section (even if it only consists of the title line) should always
 112 exist, to ensure that new sections are created in the right place.
 113 The final section should be titled to reflect the fact that Info files
 114 with no more well specified location are appended to it.
 115
 116 If there is already an entry for the Info file being installed it is
 117 replaced in situ with the new entry.
 118
 119 If a section is specified when removing an entry the section is
 120 ignored and a warning is issued.
 121
 122 If a section is requested when adding an entry but the file contains
 123 no section headings at all then
 124 .B install-info
 125 will create both the requested section and a Miscellaneous section at
 126 the end of the file.
 127 .TP
 128 .BI \-\-infodir= infodir
 129 Specifies that the
 130 .B dir
 131 file is, and the installed copy of the new Info file was, is or will
 132 be located in
 133 .IR infodir .
 134 The default is
 135 .BR /usr/info .
 136 .TP
 137 .BI \-\-align= nnn
 138 Specifies that the first line of the description should be indented at
 139 least
 140 .I nnn
 141 characters; extra spaces will be added as required.  If necessary
 142 because of the length of the
 143 .B dir
 144 menu entry details it may be offset more.  The default is 27.
 145 .TP
 146 .BI \-\-calign= nnn
 147 Specifies that the second and subsequent lines of the description
 148 should be indented at least
 149 .I nnn
 150 characters.  The default is 29.
 151 .TP
 152 .BI \-\-maxwidth= nnn
 153 Specifies that the maximum width for the Info file is
 154 .IR nnn .
 155 This is used when wordwrapping the descriptive text.
 156 The default is 79.
 157 .TP
 158 .B \-\-quiet
 159 Prevents the usual display of the new menu entry just before it is
 160 inserted, and of the messages announcing the replacement and removal
 161 of existing entries and the creation and deletion of sections.
 162 .TP
 163 .B \-\-help
 164 Causes
 165 .B install-info
 166 to display its usage information and exit.
 167 .TP
 168 .B \-\-version
 169 Causes
 170 .B install-info
 171 to display its version and copyright information and exit.
 172 .TP
 173 .BI \-\-description= xxx
 174 Specifies that the description to use after the menu entry in new or
 175 updated entries be
 176 .IR xxx .
 177 The default is to use the the value specified in the Info file itself;
 178 this is found by searching for a section of the form
 179 .br
 180 .B START\-INFO\-DIR\-ENTRY
 181 .br
 182 .B * Auto-PGP: (auto-pgp).  PGP under GNU Emacs.
 183 .br
 184 .B END\-INFO\-DIR\-ENTRY
 185
 186 If the entry found in the Info file itself extends across several
 187 lines, each giving a menu entry, the text found in the file is used
 188 verbatim.  In this case the alphabetic ordering scheme is turned off,
 189 and the entries are inserted at the top of section in question.  In
 190 this case the
 191 .BR \-\-menuentry ", " \-\-maxwidth ", " \-\-align ", " \-\-calign
 192 .RB " and " \-\-menuentry
 193 options are ignored.
 194
 195 If there is no
 196 .B dir
 197 entry in the file the program will try to find a paragraph early in
 198 the file starting
 199 .BR "this file documents" .
 200 It will capitalise the first character of the remainder, and use that.
 201
 202 It is an error for none of these methods to yield a description.
 203
 204 If a description argument is given when
 205 .B \-\-remove
 206 is specified it is ignored and a warning is issued.
 207 .TP
 208 .BI \-\-menuentry= xxx
 209 Specifies that the entry in the menu should be
 210 .IR xxx .
 211 The default is to use the the value specified in the Info file itself.
 212 If this is not present the basename of the Info file is used
 213 .RB "(any " ".info " "is deleted, and the entry is made mixed case)."
 214 See above for details of the format expected for the menu entry in the
 215 Info file.
 216
 217 When removing entries the value of the
 218 .B \-\-menuentry
 219 option must match the actual menu entry field in the menu item to be
 220 removed (case not significant).  If
 221 .B \-\-menuentry
 222 is omitted no check on the menu entry is done.
 223 .TP
 224 .B \-\-keep\-old
 225 Inhibits the replacement of existing entries and the removal of empty
 226 sections.
 227
 228 If the file being installed alreay has an entry in the directory the
 229 old entry will be left alone instead of being replaced; the default is
 230 to overwrite any old entry found with the newly generated one.
 231
 232 If
 233 .BR \-\-remove " is specified " \-\-keep\-old
 234 will prevent the removal of the section heading which would otherwise
 235 happen if the section is made empty by the removal.
 236 .TP
 237 .B \-\-test
 238 Enables test mode, which inhibits the update of the directory file.
 239 .TP
 240 .B \-\-debug
 241 Enables debugging mode, in which the results of some internal
 242 processing steps are shown.
 243 .SH "SEE ALSO"
 244 emacs(1), info(1), gzip(1)
 245 .SH COPYRIGHT
 246 Copyright 1994, Ian Jackson.
 247 .B install\-info
 248 is free software; see the GNU General Public Licence version 2 or
 249 later for copying conditions.  There is
 250 .I no
 251 warranty.