Next: , Previous: Other Info Directories, Up: Installing an Info File


21.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.

As a matter of convention, please start the description for the main entry (above, ‘The GNU documentation format’) at column 32. This will make it align with most others. Description for individual utilities best start in column 48, where possible.

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. 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.