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.)
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'.
If an Info file is not in the `info' directory, there are three ways to specify its location:
Info-directory-listvariable in your personal or site initialization file. This tells Emacs 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-directoryvariable to the name of only one directory.)
INFOPATHenvironment 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/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
environment variable in your `.cshrc' or `.profile' file. If
you use a Bourne-compatible shell such as
your shell command interpreter, you set the
variable in the `.profile' initialization file; but if you use
tcsh, you must set the variable in the
`.cshrc' initialization file. The two types of shells use
INFOPATHvariable as follows:
setenv INFOPATH .:~/manuals:/usr/local/emacs/info
INFOPATH=.:$HOME/manuals:/usr/local/emacs/info export INFOPATH
The `.' indicates the current directory as usual. Emacs uses the
INFOPATH environment variable to initialize the value of Emacs's
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
INFOPATH=/local/info: export INFOPATH
will search `/local/info' first, then the standard directories. Leading or doubled colons are not treated specially.
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
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
@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
install-info program sees these lines in the Info file, and
that is how it knows what to do.
Always use the
@dircategory commands near
the beginning of the Texinfo input, before the first
command. If you use them later on in the input,
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
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).
Go to the first, previous, next, last section, table of contents.