texinfo: Installing Dir Entries

Installing an Info File

Invoking install-info

Other Info Directories

Back to Software Index

23.2.4 Installing Info Directory Files
--------------------------------------

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, and use '@dircategory' to specify which part
of the Info directory to put it in.  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 Note: 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.

  When choosing a category name for the '@dircategory' command, we
recommend consulting the Free Software Directory
(http://www.gnu.org/directory).  If your program is not listed there, or
listed incorrectly or incompletely, please report the situation to the
directory maintainers (<bug-directory@gnu.org>) so that the category
names can be kept in sync.

  Here are a few examples (see the 'util/dir-example' file in the
Texinfo distribution for large sample 'dir' file):

     Emacs
     Localization
     Printing
     Software development
     Software libraries
     Text creation and manipulation

  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.