When you install an Info file onto your system, you can use the program
install-info
to update the Info directory file dir.
Normally the makefile for the package runs install-info
, just
after copying the Info file into its proper installed location.
In order for the Info file to work with install-info
, you include
the commands @dircategory
and
@direntry
…@end direntry
in the Texinfo source
file. Use @direntry
to specify the menu entries to add to the
Info directory file. Use @dircategory
to specify a category
for the manual, which determines which part of the Info directory to
put it in. See Directory Category.
Here is how these commands are used in this manual:
@dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. … … @end direntry
Here’s what this produces in the Info file:
INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. … … END-INFO-DIR-ENTRY
The install-info
program sees these lines in the Info file, and
that is how it knows what to do.
Always use the @direntry
and @dircategory
commands near
the beginning of the Texinfo input, before the first @node
command. If you use them later on in the input, install-info
will not notice them.
install-info
will automatically reformat the description of the
menu entries it is adding. As a matter of convention, the description
of the main entry (above, ‘The GNU documentation format’) should
start at column 32, starting at zero (as in
what-cursor-position
in Emacs). This will make it align with
most others. Description for individual utilities best start in
column 48, where possible. For more information about formatting see
the ‘--calign’, ‘--align’, and ‘--max-width’ options in
Invoking install-info
.
If you use @dircategory
more than once in the Texinfo source,
each usage specifies the ‘current’ category; any subsequent
@direntry
commands will add to that category.
Each ‘Invoking’ node for every program installed should have a
corresponding @direntry
. This lets users easily find the
documentation for the different programs they can run, as with the
traditional man
system.