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

• New Info File: Listing a new info file.
• Other Info Directories: How to specify Info files that are located in other directories.

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, write a menu entry for it in the menu in the `dir' file in the `info' directory. Also, move the new Info file itself to 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.

Conventionally, the name of an Info file has a `.info' extension. Thus, you might list the name of the file like this:

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

However, Info will look for a file with a `.info' extension if it does not find the file under the name given in the menu. This means that you can refer to the file `gdb.info' as `gdb', as shown in the first example. This looks better.

Info Files in Other Directories

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

• Write the pathname in the `dir' file as the second part of the menu.
• If you are using Emacs, list the name of the file in a second `dir' file, in its directory; and then add the name of that directory to the Info-directory-list variable in your personal or site initialization file. This tells Emacs's Info reader reader where to look for `dir' files. Emacs merges the files named `dir' from each of the listed directories. (In Emacs Version 18, you can set the Info-directory variable to the name of only one directory.)
• Specify the `info' directory name in an environment variable in your `.profile' or `.cshrc' initialization file. (Only you and others who set this environment variable will be able to find Info files whose location is specified this way.)

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

* Test: (/usr/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
      '("/usr/bob/manuals" 
        "/usr/local/emacs/info"))

This tells Emacs to merge the `dir' file from the `/usr/bob/manuals' directory with the `dir' file from the `"/usr/local/emacs/info'" directory. Info will list the `/usr/bob/manuals/info-test' file as a menu entry in the `/usr/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 sh or bash for your shell command interpreter, you must set the INFOPATH environment variable in the `.profile' initialization file; but if you use csh, you must set the variable in the `.cshrc' initialization file. The two files require slightly different command formats.

• In a `.cshrc' file, you could set the INFOPATH variable as follows:

  setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info
  

• In a `.profile' file, you would achieve the same effect by writing:

  INFOPATH=.:~bob/manuals:/usr/local/emacs/info
  export INFOPATH
  

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