What's GNU: Texinfo

This month's column discusses the Texinfo document formatting language, which is used for all GNU documentation. Its main feature is that one source file can be used to prepare both printed text, and on-line, hypertext-style documentation.
Info Viewers

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.

Miscellaneous Commands

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.

Getting Printed Documentation

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.

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

good, thanks for information

rainkan's picture

also recommend buying and reading the Texinfo manual from the FSF. It is well-written and thorough. You will need to do this anyway if you plan to write a large Texinfo file, as this article has just scratched the surface.
generic nexium,
coumadin diet,
generic lexapro

slib2a6

Peter Schuballa's picture

To get slib2a6 working with scsh-0.4.2 (based on
Scheme48-0.36, I belive), I had to replace all the
"#(" lexemes with "(vector " and do some clean up
for cases where the vector was quoted.

This got SLIB working reasonably well.

re:slib2a6

Gioco's picture

Hi Peter what are you talking about? I don't understand a word.

Re:slib2a6

Dante Rawlings's picture

In my department we have about 300 pages of notes for our freshman
courses typeset in Word with the equation editor. The layout is
really bad. I believe it should all be in TeX in the long term - many of
the equations are hard to read and inconsistently typeset (e.g. a\sin x
looks like roman "asinx", double quotes for second derivative; it
may have been poorly done in Word, though). Unfortunately our
secretary is only now starting to learn TeX.

1. Is there a Word-to-TeX conversion program?

2. What about all the included figures?

3. Should I just forget the whole thing?

It sounds like some people here have changed over from Word to Tex and
might have some ideas.

Thanks,

Great tool

Anonymous's picture

I use it for myself all the time.

Webinar
One Click, Universal Protection: Implementing Centralized Security Policies on Linux Systems

As Linux continues to play an ever increasing role in corporate data centers and institutions, ensuring the integrity and protection of these systems must be a priority. With 60% of the world's websites and an increasing share of organization's mission-critical workloads running on Linux, failing to stop malware and other advanced threats on Linux can increasingly impact an organization's reputation and bottom line.

Learn More

Sponsored by Bit9

Webinar
Linux Backup and Recovery Webinar

Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.

In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.

Learn More

Sponsored by Storix