SiteMap Search ElispArea HowTo Glossary RecentChanges News Problems Suggestions
Eritrea, Independence Day

InfoPath

This page explains how InfoMode finds Info manuals. If you have manuals on your machine in different locations, you might need to read this.

InfoMode uses the ‘INFOPATH’ environment variable to initialize, so that the Info mode integrated in Emacs gives the same results as the standalone Info reader. `INFOPATH is an environment variable containing a list of paths to the Info files installed on a system and is used by standalone Info readers to locate Info files. The Info reader built into Emacs also uses INFOPATH, which ensures that Emacs will display the same Info files as the other Info readers installed on the system.

When InfoMode is invoked by typing C-h i, Emacs parses INFOPATH and creates a list of Info directories in Info-directory-list. If you do not have INFOPATH set, you can use Emacs variable Info-default-directory-list for the same thing. This variable is only consulted when INFOPATH is not set, however. If INFOPATH is not set, the default list of directories for the standalone Info reader (reported under info/C-h) will likely differ from the default list for the emacs Info reader.

If INFOPATH doesn’t exist and ‘Info-directory-list’ isn’t set, Emacs is forced to improvise. During Emacs startup Info-default-directory-list is created: this contains a list of directory names that, on a GNU/Linux system, can usually be relied on to contain Info files. The last directory in Info-default-directory-list is the info directory within the Emacs installation directory: this guarantees that Emacs will be able to display its own Info files even if it fails to find any others.

The order of directories in these lists is relevant. It determines the order of the entries in the main Info menu (‘dir’), so it determines which copy of a manual is opened whenever several copies with the same name exist. The first one found will be opened.

Example of setting the list for use in Emacs on Windows:

       (setq Info-default-directory-list
             (append '("c:/Emacs/site-lisp/gnus-5.8.3/texi" "c:/Emacs/info")
                     Info-default-directory-list
                     '("~/info" "~/full-man/info")))

This code adds directories before and after the original list of directories (‘Info-default-directory-list’). Directory ~/info allows for extension and customization of the documentation system for personal use - `~’ is your home directory.

As Emacs will always use INFOPATH if it exists, there is no point in trying to modify Info-default-directory-list on a system where INFOPATH is defined. Even on a system that doesn’t have an INFOPATH it will almost always be better to create INFOPATH than to try to configure Emacs through Info-default-directory-list.

The only exception is on a native Microsoft Windows installation that doesn’t have any standalone Info readers installed. Under Windows, installing a new version of Emacs will not usually update INFOPATH and this means that, unless you remember to update it manually, INFOPATH will still point to the Info files for the previous Emacs installation. And it is really hard to spot that you are looking slightly out-of-date Info pages!

So for native Windows it is strategically better to avoid INFOPATH and to use Info-default-directory-list. As noted above, this always contains the Info directory for the executing version of Emacs so all that is required is to add any other Info directories to the list. The easiest way is to use add-to-list in file site-start.el or the InitFile:-

    (add-to-list 'Info-default-directory-list "C:/path/to/my/info")

The add-to-list function adds the specified directory to the front of the list, which means that the directory will be searched before the standard Emacs Info directory. This is normally the behaviour you want.

Even though the docstrings of at least GnuEmacs 21.2.1 claim otherwise, dir-files along the Info-additional-directory-list are not excluded when the Info top-menu is rendered. For some reason, this feature is not supported anymore. Some might be sorry for this, because it used to make possible having one’s own, clean dir-file, and still let the references to other manuals work. The standalone inforeader info(1) still supports this.

One good setup is to have the environment variable INFOPATH point to one’s own info directories, say ~/info, and then set ‘Info-additional-directory-list’ to ‘Info-default-directory-list’ in DotEmacs or similar Emacs startup file. This way the top-directory that one gets with C-h i lists the users own info-dir, from the file ~/info/dir first (which might end in some visible separator), onto which the system-wide info-dir is appended. for convenience, one might want to add a link from one’s own personal info-dir to the system-wide info-dir. Binding d then takes one to one’s own info-dir, and a u from there leads to the system-wide version. Here’s what tekonivel’s setup looks like:

First, the environment variable is set upon shell startup, say in .profile:

    export INFOPATH="~/info"

then in DotEmacs

    (add-hook 'Info-mode-hook		; After Info-mode has started
        (lambda ()
    	    (setq Info-additional-directory-list Info-default-directory-list)
    	))

And then the ~/info/dir file will include, at the top

    ^_
    File: dir,		Node: Top,	Up: (/usr/info/dir)
      ##
            This is your very own [D]irectory of Info manuals.
     ###    To see the common directory set up for the system,
      ##    move [U]p from here.
      ##
    * Menu:

and at the bottom write an informative text followed by an empty new line:

    ---- User's `dir' ends here ----

A bit of a hassle, but ought to do it.

Also remember that even if a manual is not on the menu you’re looking at, you can move to any node, say (texinfo)Directory File along any of Info’s paths with Info-goto-node, at g. Do mind the parentheses.


CategoryDocumentation CategoryHelp CategoryModes CategoryPaths