LJ Archive CD

Need More Info?

Bill W. Cunningham

Issue #45, January 1998

Here's how to get the information you need using GNU's hypertext system called info.

Have you ever been reading along in a man page and come across something like, “SEE ALSO gdb entry in info” and wondered what it meant? Still perplexed, did you pick up Running Linux or Unix Unleashed and fail to find one word about info? If so, this article is for you.

Background

info (information) is the GNU project's hypertext system filling the gap between the man pages and printed reference books. info is a viewer for info files. Without going into excruciating detail, info files are rigidly formatted text files that are processed with the texinfo program, and then compiled by makeinfo. They end up in gzip format and usually live in /usr/info/ (at least on Slackware 96). The info program's job is to uncompress them and present them to the reader. Info files can also be viewed with Emacs, but this article will focus only on the stand-alone info program.

The info files make up a cross-referenced, virtual hierarchy of documentation. At the top of this hierarchy is the directory node. If you run info without arguments at your command prompt, the directory node opens on your console. The directory node serves as the master index for all info documentation on your computer and provides a point of entry into all these other files. The files can also be accessed directly, without going to the directory node first. For example, I can type info make at my prompt and go directly to the documentation for make.

info's documentation is divided into nodes—structures that are basically analogous to paragraphs. A node can be one short sentence or several screens. Nodes are physically stored in files. The info program allows both cross and vertical links between nodes. Once inside info, you can move from node to node in a random search for data, or you can quickly find and go to specific information. The documentation's level of detail increases as you move down the hierarchy tree. At any given level of detail, you can follow cross references to related topics at approximately the same level of detail.

Of course, someone has to write the documentation for it to be available, and not all Linux software has data available for info. Most info data deals with gcc, g++, gdb, make and other topics related to programming and systems administration. In other words, lots of info documentation exists for older software; this makes sense as info has been around for a while. Users researching these areas are fortunate in that they will find a gold mine of information that's as easy to read as a man page.

Hands On

Essential GNU Info Reference Card

At this point, you may wish to look at the Reference Card and, with these essential commands in mind, try navigating info on your Linux system. Just enter info at the prompt and start reading. I recommend entering h at the directory node and working through the on-line tutorial first thing. The whole course only takes about half an hour. The only confusing point I found was that info files can only be printed from within Emacs (the M-x print-node option). Neither the tutorial nor the info man page makes this clear, but I found it to be true.

New Info Files

What happens when you get a new software package, mgetty for instance, that includes several info files as part of its native documentation? You could just leave those files where they are and accept the fact that you would have to run info mgetty to view them. Or you could install the new files into the existing hierarchy. You don't even have to move them to the default info directory.

First, note the location of the new info files. I'll stick with mgetty as an example. These files were installed in /usr/local/info/. In this case, the master info file is named /usr/local/info/mgetty.info. Master info files always end with the .info suffix.

Next, add mgetty's entry to info's directory file. To do this, edit the file /usr/info/dir as root. Move down to an appropriate location for the new entry. I chose “Miscellaneous commands and documents”, the next to last section. Menu entries in the dir file consist of three sections. The first is the menu entry name, starting with an asterisk and followed by a colon. The second is the menu file name in parentheses, followed by a period. (The .info suffix isn't needed here, even though it's part of the actual file name.) The third section is the package description, which contains the following entry for mgetty:

*mgetty:        (mgetty).       mgetty documentation.

Add this line to the /usr/info/dir file and exit saving the file. Finally, info has to be able to find mgetty's info files, since they're not in the default directory, /usr/info/. Although we could specify (/usr/local/info/mgetty) in our entry's second part, that would really make the dir file ugly. The most aesthetically pleasing solution is to set the INFOPATH variable. The directories in INFOPATH are searched by the info program for data files. So, add the line:

export INFOPATH=/usr/info:/usr/local/info
to /etc/profile, and on the next login, all users will be able to access mgetty's info documentation just as if it had always been part of the hierarchy. If mgetty is ever upgraded—no problem—info finds the new documentation with no further adjustments.

Suggestions

I wish that movement within nodes responded to the page up and page down keys. That would be more intuitive for most people. Color syntax highlighting might also be a nice touch. Basically, info works fine just as it is.

Conclusions

If you're used to hypertext in the sense of HTML and Netscape, info may seem spartan by comparison. Indeed, a lot of documentation these days is in HTML form, and info may quietly fade away in Netscape's wake. But keep in mind that info's man page was first copyrighted in 1989—quite a while before hypertext in the present sense came about. For an all-ASCII system that's going on 10 years old, it does a pretty darn good job.

Gunnery Sergeant Bill Cunningham, US Marine Corps, got his BS in Computer Science in 1991. He is the LAN Chief for Marine Forces South, Panama Canal Zone. In his leisure time, he plays with his 3 fine kids and helps his wonderful (and expecting) wife pick up coconuts that fall into their yard. He can be reached via e-mail at bill@lancomm.mfs.usmc.mil.


LJ Archive CD