Creating Info Manuals And Adding Them Into Emacs

Once I got used to browsing Info manuals in Emacs, I wished I didn’t have to go look at online docs all the time.

Of all the manuals out there, how many can I get in Info format?

I quickly discovered that any document written in Sphinx (which many Python library docs are) can be converted to Info format.

Here is an example of how useful having an Info file within Emacs is: In my Django models.py file, I have the following comment near the top:

# Reference: (do not delete this comment)
# "(django)Field Options<2>"
# "(django)Field types<3>"
# "(django)Relationship fields"
# "(django)Managing files"

Then, using Hyperbole, I just put my cursor on one of these lines, hit M-Ret and I’m taken straight to that portion of the documentation.

Below I’ll outline the steps I used to get the official Python docs as an Info file.

First, make sure Sphinx is installed on your system.

Get the Python source code. In the Doc directory, run make texinfo.

(This works because the Python docs’ Makefile has a TexInfo target. If it doesn’t, see sphinx-build for how to manually make the TexInfo files.)

Go into the directory with the texinfo file. Run make.

In this directory, if a dir file is not present, create one with the following contents:

This is the file .../info/dir, which contains the
topmost node of the Info hierarchy, called (dir)Top.
The first time you invoke Info you start off looking at this node.

File: dir,               Node: Top           This is the top of the INFO tree

  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "?" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.

  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.

* Menu:

Languages
* Python: (python.info). Python documentation

Here Languages is the category it will show up in when you go to the top level of your Info tree. You can replace it with whatever you deem is appropriate.

Move the file(s) to your desired target directory.

Finally, add the location in your emacs config:

(add-to-list 'Info-additional-directory-list "/home/me/path/to/info/directory)

I don’t recall whether you need to restart Emacs for it to show up.

This works relatively well. The one minor headache is that every inline link in the documentation will be preceded with see. Below is a sample from the Django Info file. It is annoying in the beginning but before long your brain automatically skips the word.

install-info python.info --dir=/home/user/info/dir