What's GNU: Texinfo

There are two ways to view Info files. (Remember, before you can view a texinfo file, you must create it from the .texi file using either makeinfo or texinfo-format-buffer.) The first is the stand-alone info viewer. This is a rather slick program, with menu completion features, the ability to split the screen to view multiple nodes, and much much more.

It requires a terminal or terminal emulator with cursor motion facilities. If you can run vi or Emacs in your window, or on your screen, then you can run info. The second is with the Info major mode in GNU Emacs. The Emacs Info viewer has almost all the features of the stand-alone info viewer, except the ability to split the screen and view multiple nodes.

As mentioned, info can also follow an infinite chain of cross references, allowing you to browse documentation to your heart's content.

There are several miscellaneous features that should be mentioned. First, you can write footnotes, using @footnote{...}. This creates real footnotes with TeX and a collection of footnotes at the end of the node with Info. If you absolutely must use fancy TeX features, then you can drop into pure TeX mode by bracketing your text with @tex and @end tex. In between these two statements, you must write in pure TeX, with backslash as the escape character, and so on.

Note that @tex and @end tex are different from the @iftex ... @end iftex commands mentioned earlier, which conditionally include text into the printed document.

Finally, there is a simple macro facility in Texinfo. Macros can be set with @set.

@set EDITION 1.23

The value can be retrieved with @value

This is Edition @value{EDITION} of ...

Macros can also be used as flags, for example to indicate if a version is a draft or not. The flags can be tested with @ifset ... @end ifset and @ifclear ... @end ifclear, which test if the macro is set or not, respectively.

@set DRAFT
@ifset DRAFT
@b{This is just a draft, please mark it up and send it back.}
@end ifset
@ifclear DRAFT
Welcome to Edition @value{EDITION} of ....
@end ifclear

The macro facility is particularly useful for the multiple cases near the front of a document where the title, edition number, and program version number are repeated. By using @value in all those places, you can use @set for the title, edition, and version, and only have to update the numbers once. This is a true time saver.

To generate printed documentation, you need to have TeX installed on your system. The texinfo.tex macros need to be in TeX's macro directory. You will also need to install a program named texindex, that comes with the Texinfo distribution, into a public bin directory, where everyone can get to it.

Texinfo files usually have a .texi extension. When TeX runs, it generates unsorted indices. The file name for the unsorted indices match the Texinfo file's name, with the .texi replaced with the two-letter name of the index. For example, the concept index for foogol.texi would be foogol.cp. The unsorted indices are not terribly useful. The texindex program sorts the indices into new files, whose names are the same as the index files, with an s on the end, e.g., foogol.cps. If these files exist, texinfo.tex will include them when TeX is run again.

The typical sequence is to run TeX three times, running texindex in between each run.

$ tex foogol.texi
$ texindex foogol.??
$ tex foogol.texi
$ texindex foogol.??
$ tex foogol.texi

The first run generates unsorted indices, and creates foogol.aux, which lists the page numbers of the nodes. This information is used to fill in the cross-references. The second run generates a complete DVI file, but unfortunately, the cross-references in it could be off by a page or so. The third run gets everything right, and at that point you can arrange to print the file. Typically, this is done with dvips, to generate PostScript.

$ dvips foogol.dvi -o foogol.ps
$ lpr foogol.ps       # or however you print

The Texinfo distribution comes with a shell script named texi2dvi that will figure out how many times TeX should be run. If it has been installed, it is probably the easiest thing to use.

If you don't have TeX, another option is to use a separate package called texi2roff. This reads Texinfo files and generates Troff input that can be processed with GNU Troff (groff). You have your choice of Troff macro packages, -me, -ms, and -mm.

TeX is preferred to texi2roff, but at least the latter is an option. The generated Troff may need some massaging by hand, but should otherwise be fairly usable. Unfortunately, the most recent version of texi2roff is considered obsolete, and is no longer being distributed by the FSF.

Also of note is a package called LaTexinfo, which is a set of LaTeX macros and a modified version of makeinfo for doing the same thing as texinfo.tex and the regular makeinfo. Texinfo files are not compatible with LaTexinfo, unfortunately. Use archie to find a recent copy of LaTexinfo if you prefer to use LaTeX.