Go to the first, previous, next, last section, table of contents.


Installing an Info File

Info files are usually kept in the `info' directory. You can read Info files using the standalone Info program or the Info reader built into Emacs. (See Info file `info', node `Top', for an introduction to Info.)

For Info to work, the `info' directory must contain a file that serves as a top level directory for the Info system. By convention, this file is called `dir'. (You can find the location of this file within Emacs by typing C-h i to enter Info and then typing C-x C-f to see the pathname to the `info' directory.)

The `dir' file is itself an Info file. It contains the top level menu for all the Info files in the system. The menu looks like this:

* Menu:

* Info:    (info).     Documentation browsing system.
* Emacs:   (emacs).    The extensible, self-documenting
                       text editor.
* Texinfo: (texinfo).  With one source file, make
                       either a printed manual using
                       TeX or an Info file.
...

Each of these menu entries points to the `Top' node of the Info file that is named in parentheses. (The menu entry does not need to specify the `Top' node, since Info goes to the `Top' node if no node name is mentioned. See section Referring to Other Info Files.)

Thus, the `Info' entry points to the `Top' node of the `info' file and the `Emacs' entry points to the `Top' node of the `emacs' file.

In each of the Info files, the `Up' pointer of the `Top' node refers back to the dir file. For example, the line for the `Top' node of the Emacs manual looks like this in Info:

File: emacs  Node: Top, Up: (DIR), Next: Distrib

(Note that in this case, the `dir' file name is written in upper case letters--it can be written in either upper or lower case. Info has a feature that it will change the case of the file name to lower case if it cannot find the name as written.)

Listing a New Info File

To add a new Info file to your system, you must write a menu entry to add to the menu in the `dir' file in the `info' directory. For example, if you were adding documentation for GDB, you would write the following new entry:

* GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a colon. The second part is the name of the Info file, in parentheses, followed by a period. The third part is the description.

The name of an Info file often has a `.info' extension. Thus, the Info file for GDB might be called either `gdb' or `gdb.info'. The Info reader programs automatically try the file name both with and without `.info'; so it is better to avoid clutter and not to write `.info' explicitly in the menu entry. For example, the GDB menu entry should use just `gdb' for the file name, not `gdb.info'.

Info Files in Other Directories

If an Info file is not in the `info' directory, there are three ways to specify its location:

For example, to reach a test file in the `/home/bob/manuals' directory, you could add an entry like this to the menu in the `dir' file:

* Test: (/home/bob/manuals/info-test).  Bob's own test file.

In this case, the absolute file name of the `info-test' file is written as the second part of the menu entry.

Alternatively, you could write the following in your `.emacs' file:

(setq Info-directory-list
      '("/home/bob/manuals"
        "/usr/local/info"))

This tells Emacs to merge the `dir' file from the `/home/bob/manuals' directory with the `dir' file from the `/usr/local/info' directory. Info will list the `/home/bob/manuals/info-test' file as a menu entry in the `/home/bob/manuals/dir' file.

Finally, you can tell Info where to look by setting the INFOPATH environment variable in your `.cshrc' or `.profile' file. If you use a Bourne-compatible shell such as sh or bash for your shell command interpreter, you set the INFOPATH environment variable in the `.profile' initialization file; but if you use csh or tcsh, you must set the variable in the `.cshrc' initialization file. The two types of shells use different syntax.

The `.' indicates the current directory as usual. Emacs uses the INFOPATH environment variable to initialize the value of Emacs's own Info-directory-list variable.

However you set INFOPATH, if its last character is a colon, this is replaced by the default (compiled-in) path. This gives you a way to augment the default path with new directories without having to list all the standard places. For example (using sh syntax:

INFOPATH=/local/info:
export INFOPATH

will search `/local/info' first, then the standard directories. Leading or doubled colons are not treated specially.

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 should use the commands @dircategory and @direntry in the Texinfo source file. Use @direntry to specify the menu entry 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.

If you use @dircategory more than once in the Texinfo source, each usage specifies one category; the new menu entry is added to the Info directory file in each of the categories you specify. If you use @direntry more than once, each usage specifies one menu entry; each of these menu entries is added to the directory in each of the specified categories.

Invoking install-info

install-info inserts menu entries from an Info file into the top-level `dir' file in the Info system (see the previous sections for an explanation of how the `dir' file works). It's most often run as part of software installation, or when constructing a dir file for all manuals on a system. Synopsis:

install-info [option]... [info-file [dir-file]]

If info-file or dir-file are not specified, the various options (described below) that define them must be. There are no compile-time defaults, and standard input is never used. install-info can read only one info file and write only one dir file per invocation.

If dir-file (however specified) does not exist, install-info creates it if possible (with no entries).

Options:

--delete
Delete the entries in info-file from dir-file. The file name in the entry in dir-file must be info-file (except for an optional `.info' in either one). Don't insert any new entries.
--dir-file=name
Specify file name of the Info directory file. This is equivalent to using the dir-file argument.
--entry=text
Insert text as an Info directory entry; text should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all added. If you don't specify any entries, they are determined from information in the Info file itself.
--help
Display a usage message listing basic usage and all available options, then exit successfully.
--info-file=file
Specify Info file to install in the directory. This is equivalent to using the info-file argument.
--info-dir=dir
Equivalent to `--dir-file=dir/dir'.
--item=text
Same as `--entry=text'. An Info directory entry is actually a menu item.
--quiet
Suppress warnings.
--remove
Same as `--delete'.
--section=sec
Put this file's entries in section sec of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself.
--version
Display version information and exit successfully.


Go to the first, previous, next, last section, table of contents.