Emacs has an ancient (predating hypertext), simple, powerful documentation program called Info. It’s very difficult to find info about it online (try searching for “Info”), so here’s my beginner’s guide.

Info is an output format for the Texinfo typesetting syntax. Texinfo is used for writing documentation that can be output in multiple print and digital formats and is the official documentation format of the GNU project. Info files are strongly associated with Emacs – Emacs is the primary reader for Info files, but there is also a standalone reader. Manuals are organized into a tree of nodes, with a variety of ways to navigate between those nodes.

Info files can technically be written by hand, but it is much more common for them to be compiled from Texinfo. Many Linux/Unix distros come bundled with the TeX toolchain necessary to compile Texinfo, but Windows does not. The TeX/LaTex/Texinfo on Windows post is coming in the near future. For now, stick to precompiled .info files or go dive into TeX yourself.

Emacs ships with several Info manuals – they’re in the emacs/info folder. You can also create your own Info directory, add new manuals to the directory, and create your own manuals. This guide will walk you through the steps needed to get Emacs to find your info directory, add manuals in your directory to the main directory list, and use Info from within Emacs.

[NOTE: This guide assumes you’re following the directory conventions I laid out in my previous post Installing CLISP, Emacs, and SLIME on Windows XP. It also gives you the baseline level of familiarity with Emacs to follow along here.]

1) Setup Emacs to recognize your info directory

You should already have an info directory. Mine is C:\home\peter\info, and from emacs the path is ~/info/. To make this the first directory Emacs looks in when compiling the directory, add this to your .emacs file (feel free to indent better than WordPress allows):

(require ‘info)
(setq Info-directory-list
(cons (expand-file-name “[HOME]/info”)
Info-default-directory-list))

2) Create a dir file in [HOME]/info/

When Emacs is looking in directories for info files, it only looks for a file called “dir” in each directory. This dir file is a special kind of Info file that points to the other Info files in the directory and lists and orders them. In order to make your own dir file, you first need a .info file to link to. I recommend the Structure and Interpretation of Computer Programs in Texinfo manual (download precompiled 400K sicp.info.gz file here). There is a whole syntax for defining nodes, but this is the bare minimum you need to get your manual into the directory.

First, start with the characters “^_”. That doesn’t actually work when you type it in directly, so you need to copy it from Emacs’ info/dir. I looked at that file in a hex editor and it had the value 1F (US – unit separator) – the ASCII values for ^_ are 5E 5F. I had to open the emacs/info/dir file and kill/yank it into my dir file. Kill/yank is Emacs’ version of cut/paste. Like all things Emacs, it’s similar, not exactly the same, and much more powerful. Here are the steps (free Emacs tutorial included):

1. Open the Emacs info dir file with: C-x C-f [HOME]/bin/emacs/info/dir
2. Select the ^_ characters
   1. Put the cursor at the beginning and set the beginning of the region to cut (C-SPC)
   2. Move down to the beginning of the next line and cut to the end of the region (C-W)
   3. Yank it back into the file with C-y
   4. Save the file with C-x C-s
3. Create your dir file with find file (C-x C-f) at ~/info/dir
4. Yank (paste) the text into the file with C-y

That should work, but there’s still more to add to the file. Next is the Tree info – at least your file and node names. This works for your personal dir file:

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

You can put a header if you like (“My Info Manuals”), then on a new line, put:

* Menu:

After that, you can add links to your manuals. The format is:

* TITLE: (filename w/o .info). Summary

For the SICP manual, it would look like this:

* SICP: (sicp). Structure and Interpretation of Computer Programs

You can put a footer after that to separate the manuals in your directory from those in others. The final dir file ends up looking something like this:

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

Peter’s Info Directory
**********************

* Menu:

* SICP: (sicp). Structure and Interpretation of Computer Programs

—- User’s ‘dir’ ends here —-

[Now that you did all that, feel free to download my dir file and change the labels as you see fit. ]

3) Using Info

Info has a similar structure to HTML, where there can be links within and between nodes, but there’s also an explicit tree structure with its own structured navigation. Here’s a pretty complete set of commands, with shorter descriptions and better grouping than the Info help shows.

Basics
C-h i – start Info
q – quit info
? – info commands
SPC – returns from commands screen

Node Navigation
p, n – previous/next node in subtree
[, ] – previous/next node in tree traversal
l, r – back/forward in node nagivation history
u – Move up
space – pagedown or next node
del – pageup or previous node
b – go to beginning of node

Links
M-TAB/TAB – previous/next cross-reference or menu item
m – type name of menu item and go to that node

Jump
d – return to Info directory
t – return to file root
L – go to menu of visited nodes
T – go to table of contents of the current Info file

Search
s – regex search, move to node where next match is found
S – regex search, case sensitive
M-x Info-search-next – repeat previous regex search
i – search for and jump to index topic
, – repeat previous i search
g – move to node specified by name – to filename by searching for (FILENAME)NODENAME
1..9 – jump to 1st-9th item in node’s menu
w – put name of current node into kill ring
M-n – clone Info buffer to new window

——————————-

That’s all for Info – it only takes 10 minutes to go through the Info on Info tutorial and it’s easy to use. This is just one of the many things that takes a couple hours to muscle through the setup and online docs, then it makes things so much easier EVERY SINGLE TIME you use it afterwards. My goal is to take these 2-3 hour research tasks and turn them into a 10 minutes guide. Hopefully by lowering the barriers to competence, more people will seek out and invest in learning the great tools out there that Windows developers tend to miss out on.