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.

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState