21.2.3 Info Files in Other Directories

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

1. Write the pathname in the ‘dir’ file as the second part of the menu.
2. 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 variable tells Emacs where to look for ‘dir’ files (the files must be named ‘dir’). 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.)

3. Specify the Info directory name in the INFOPATH 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 ‘/home/bob/info’ directory, you could add an entry like this to the menu in the standard ‘dir’ file:

* Test: (/home/bob/info/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:

(require 'info)
(setq Info-directory-list
 (cons (expand-file-name "/home/bob/info")
       Info-directory-list))

This tells Emacs to merge the system ‘dir’ file with the ‘dir’ file in ‘/home/bob/info’. Thus, Info will list the ‘/home/bob/info/info-test’ file as a menu entry in the ‘/home/bob/info/dir’ file. Emacs does the merging only when M-x info is first run, so if you want to set Info-directory-list in an Emacs session where you've already run info, you must (setq Info-dir-contents nil) to force Emacs to recompose the ‘dir’ file.

Finally, you can tell Info where to look by setting the INFOPATH environment variable in your shell startup file, such as ‘.cshrc’, ‘.profile’ or ‘autoexec.bat’. 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 set the variable in the ‘.cshrc’ initialization file. On MS-DOS/MS-Windows systems, you must set INFOPATH in your ‘autoexec.bat’ file or in the Registry. Each type of shell uses a different syntax.

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

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

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

  INFOPATH=.:$HOME/info:/usr/local/emacs/info export INFOPATH

• In a ‘autoexec.bat’ file, you write this command(11):

  set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info

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. The stand-alone Info reader merges any files named ‘dir’ in any directory listed in the INFOPATH variable into a single menu presented to you in the node called ‘(dir)Top’.

However you set INFOPATH, if its last character is a colon(12), 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.

When you create your own ‘dir’ file for use with Info-directory-list or INFOPATH, it's easiest to start by copying an existing ‘dir’ file and replace all the text after the ‘* Menu:’ with your desired entries. That way, the punctuation and special CTRL-_ characters that Info needs will be present.