What's GNU: Texinfo

We will just cover the high points of Texinfo. There is a complete manual (around 200 pages) that describes Texinfo in full detail. If you intend to actually write a manual, or do major surgery on an existing one, then it will be worth your while to read the Texinfo manual first. (Nicely printed and bound versions of the Texinfo manual can be purchased from the Free Software Foundation. Doing so not only saves wear and tear on your laser printer and gives you a nicely bound book, it also directly contributes to the production of more free software.)

Texinfo comes in the texinfo-3.1.tar.gz software distribution from the Free Software Foundation (ftp://prep.ai.mit.edu/pub/gnu is the site). This contains all the software (except TeX) needed to use Texinfo.

Texinfo is designed to be processed by two (really three) different sets of programs. The first is TeX, the text processing system written by Donald Knuth. TeX is a freely available, fairly large software suite. If you acquired a CD-ROM Linux distribution, TeX was probably already set up for you. The file texinfo.tex is a series of TeX macros that tells TeX how to format Texinfo files, and must be installed in the TeX macros directory.

Texinfo allows you to produce output in several paper sizes: 6 by 9.25 inch (normal book), 8.5 by 11 inch (standard American sheet of paper) or A4 (standard European paper).

The second program is called makeinfo. This program reads your Texinfo files and generates a formatted Info file or files. These files can then be viewed with an Info viewer. If you are a GNU Emacs user, then you have a third option, texinfo-format-buffer within Emacs. This will also generate a formatted Info file. The makeinfo program is preferred; it is written in C and is faster than texinfo-format-buffer. It is also somewhat smarter, and it does not require Emacs underneath it.

To view an Info document, you need an Info viewer. There are two choices, Info mode in GNU Emacs, or the stand-alone info viewer that comes with the Texinfo distribution. We'll talk about viewing a little bit later.

An important point to remember when writing Texinfo documents is that you are writing for two audiences; those using info and those reading the printed book. This dual nature of the document has a strong influence on the design of the Texinfo language; there are a number of constructs that are used for one case and ignored for the other. There are Info-to-HTML converters in use at a number of WWW sites on the Internet, and makeinfo is being enhanced to generate HTML directly, although there is not yet a release date for this version of makeinfo.

Texinfo documents are structured like conventional books, with chapters, sections, subsections, and subsubsections. (Four levels is as deep as you can go, but that is almost always more than you need.) Each chapter, section and so on is referred to as a “node”. In fact, this structure is actually what Computer Scientists like to refer to as a tree. The “root” of the document is a special node called the “top” node. Computer Scientists draw their trees starting at the top and growing downwards. **********Place figure here

We'll take an abbreviated tour through a Texinfo document.

\input texinfo  @c -*-texinfo-*-
@c %**start of header (This is for running texinfo on a region.)
@setfilename Foogol.info
@settitle Foogol Language Programming
@c %**end of header (This is for running texinfo on a region.)

This is the front of the document. It reads in the Texinfo macros, and sets the Info file name and the title to be used in page headers. The @c starts a comment. Shown here are magic comments that make GNU Emacs happy (the %**start of header, and so on). These comments are boilerplate; just put them there and don't worry about what they mean (I don't; I'm not an Emacs user).

@ignore
@ifinfo
@format
START-INFO-DIR-ENTRY
* Foogol: (foogol.info).   A Wonderful Programming Language.
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@end ignore

This is the entry for the dir file in the /usr/local/info directory. This is how info knows what Info files are available. Most of the text surrounding the middle line is so that separate shell scripts can find and extract this line and add it to the dir file. Unfortunately, the FSF is not yet distributing these scripts. In short, this is more boilerplate; the middle line is the important one. It describes your document in one line. Right now, you have to manually update the dir file when installing a new Info file in the /usr/local/info directory.

This shows a number of things about Texinfo. First, the @ is the command character. All special constructs in Texinfo start with @. (Use @@ to get a real “@”.) Second, many constructs come in pairs, @foo ... @end foo. Things between @ignore and @end ignore are skipped by all the Texinfo processors.

The @ifinfo ... @end ifinfo lines bracket text that is meant only for an Info file, and not for printed TeX documentation. There is also a corresponding @iftex ... @end iftex construct for things that should only be in the printed document, and not in the Info file.

The @format and @end format bracket example text that is not indented. (In this case, since it's being ignored, it has no effect.)

(The whole business with the dir line is a bit unusual. It is a feature in transition, that will eventually become a mainstream part of the Texinfo language. Right now, it's done as shown, with everything ignored by the Texinfo processors. You don't have to do this in your Texinfo documents, but it doesn't hurt, either.)

Next comes information describing what is documented, the edition of the document, and the version of the program being documented. This is followed by the copyright information and permission notices.

@ifinfo
This file documents @code{foogool}, a programming language that does
really neat things.
This is Edition 1.23 of @cite{The Foogol Language}, for the 3.21 version
of the GNU implementation of FOOGOL.@refill
Copyright (C) ...
Permission is granted ...
@end ifinfo

The full permissions are documented in any FSF manual and in the Texinfo documentation. They are omitted here for brevity. In this example we also see how Texinfo does in-line font changes. @code{xxx} puts “xxx” into a fixed-width font, like this xxx. In Info, the text is quoted. The @cite{} is used for citations of titles; it sets the enclosed text in italics.

Next comes the title page. Almost all of it is boilerplate; things that have to be there in a set order, where you fill in the values that apply to what you are writing.

@titlepage
@title The FOOGOL Language
@subtitle A User's Guide for GNU FOOGOL
@subtitle Edition 1.23
@subtitle July, 1994
@author Arnold D. Robbins

This starts the actual title page, listing the title, subtitle(s), and author(s) of the document. Title pages only apply to printed materials.

@c Include the Distribution inside the titlepage
@c environment so that headings are turned off.
@c Headings on and off do not work.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994 Free Software Foundation, Inc.
@sp 2
This is Edition 1.23 of @cite{The FOOGOL Language}, @* for the 3.21
version of the GNU implementation of FOOGOL.
@sp 2
Published by the Free Software Foundation @*
675 Massachusetts Avenue @*
Cambridge, MA 02139-3309 USA @*
Phone: +1-617-876-3296 @*
Printed copies are available for $20 each.
Permission is granted ...
@end titlepage

This does the back of the title page, called the copyright page. It lists the copyright information, edition information, information about the publisher, and copying permissions. Again, the Texinfo manual has the full details. This example assumes a GNU manual, but of course, if you are writing a manual, you or your company is the publisher. The @* forces a line break, so that each line in the Texinfo source file will be printed on a separate line in both the printed and Info versions.

@ifinfo
@node Top, Preface, (dir), (dir)
@top General Introduction
@c Preface or Licensing nodes should come right
@c after the Top node, in `unnumbered' sections,
@c then the chapter, `What is foogol'.
This file documents @code{foogol}, a programming language that does
really neat things.
This is Edition 1.23 of @cite{The Foogol Language}, for the 3.21 version
of the GNU implementation of FOOGOL.@refill
@end ifinfo

This is the special “top” node. It should appear only in the Info file, which is why it is bracketed in @ifinfo and @end ifinfo. It has a brief description of what the Info file documents.

Here, for the first time, we see an actual @node statement. The @node lists, in order, this node's name, it's successor, it's predecessor, and the “up” node. The successor and predecessor are usually nodes at the same level in the tree; the up node is the parent. In the case of the top node, it's a little bit different. The successor is the first child node (chapter) in the document, and both the predecessor and up node are the special (dir) node that represents the dir file.

Following any node with children is a menu. The menu lists all of the node's children (usually in order), with a brief description of what each node describes.

@menu
* Preface::        What this Info file is about; brief
                  history and acknowledgements.
* Copying::        Your right to copy and distribute @code{foogol}.
* What Is Foogol:: What is the @code{foogol} language;
                  using this Info file.
* Getting Started:: A basic introduction to using @code{foogol}.
                   How to run a @code{foogol} program.
                   Command line syntax.
.....
* Index::          Concept and Variable Index.
@end menu

The menu for the top node is called the “master menu”. It has entries for at least all the chapter level nodes in the file. More commonly, it has entries for every node in the file, almost in order. Usually, all the chapter level nodes are first, and then all the “interior” nodes come after that, in the order they would be in a book. After all the stuff at the front, you simply settle down and write your document. Each node has a unique name. In makeinfo, case in node names is ignored, while in TeX it is not, so for best results, keep the case in all instances of a node name the same.

Each @node statement is followed by a sectioning command.

@node Introduction, Syntax, Preface, Top
@chapter Introduction To Foogol
The @code{Foogol} language was invented in 1897. ...

There are corresponding @section, @subsection and @subsubsection commands. There are also commands for unnumbered chapters and sections, @unnumbered, @unnumberedsec, @unnumberedsubsec, @unnumberedsubsubsec, and similarly for appendices as well, @appendix, @appendixsec and so on. There are even commands for titles that won't appear in the table of contents: @heading, @subheading, and so on, although these still require separate node names and menu entries.

As you might imagine, keeping the “next”, “previous”, and “up” pointers in synch while writing a document is a bit painful. Fortunately, as long as you have the correct sectioning commands and each node with children has a correct menu, makeinfo will figure out the pointers for you. In practice, this means that you can leave them off. TeX does not care a whole lot about nodes, although it does not ignore them entirely, as we shall see.

The Texinfo major mode in GNU Emacs will construct menus for you, and also automatically update the “next”, “previous”, and “up” pointers. If you don't use Emacs, you must do this manually, or write a separate program to do it for you (which is what I did, using gawk).

At the end of your document, you need to print the table of contents. Texinfo provides both a “summary” contents page, and a full table of contents page.

@summarycontents
@contents
@bye

The @bye ends processing. You can put notes to yourself in the file after the @bye; I use it in The GAWK Manual to keep my “to do” list.