|
|
|
|
|
|
|
|
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.
by Arnold Robbins
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.
Texinfo maintains six pre-defined indices; the concept, variable, function, keystroke, program, and data type indices. To add to the concept index, for instance:
@cindex History of @code{Foogol}
@cindex @code{Foogol}, History of
The variable index uses @vindex, the function index @findex, and so on.
You can create your own indices, and it is also possible to merge indices; for example to have variables, functions, and concepts all in the same index. These are typically printed at the end of a document, right before the table of contents, with the @printindex command.
We have already seen @code, that sets text in a constant-width or Courier-like font. There are several other commands that provide special output for different items.
@samp - for in-line code fragments @file - for file names @var - things that can vary, parameters, values, and so on @emph - emphasizes something, using italics @strong - makes a strong point, using bold @r - force roman (normal) text @i - force italic text @b - force bold text
The latter three are for occasional use, usually the other commands suffice.
Texinfo allows you to easily write lists and simple tables.
@enumerate A @c A list "numbered" A, B, C ... @item First item here @item Second item here .... @end enumerate
Leaving off the "A" would have generated a numbered list, and using a small "a" would have used lower-case letters. A simple list with a minus or bullet would be written:
@itemize @bullet @item First item here @item Second item here .... @end itemize
This generates a list with bullets for each item. Using @minus would generate a minus sign. (Minus signs and dashes are different characters when typesetting; minuses are longer.)
There are several kind of tables. Each one takes a formatting code that describes how to format the individual items. For instance, a list of command line options would use @samp.
The list of @code{foogol} command line arguments are:
@table @samp
@item -f @var{filename}
Use @var{filename} as the source file.
@item -o @var{prog}
Use @var{prog} as the executable program.
@item -d
Print the date, time of day, and current phase of the moon.
...
@end table
Two other similar commands are @vtable ... @end vtable, and @ftable ... @end ftable. These are just like @table, but they automatically make an entry for each item in the variable and function indices, respectively, which can save you some typing.
There are several commands for formatting text that is marked off in a special fashion, such as examples, quotations, and so on. The primary one is @example ... @end example which is generally used for program or other computer input and output. The text will be printed indented, in a Courier-like font, and it will not be otherwise filled or adjusted.
The @format ... @end format is like @example, but does not do the indenting. You can quote extended pieces of text by enclosing the quote in @quotation ... @end quotation.
After an example, it is typical to continue a thought without starting a new paragraph. To keep the continuation text from being indented like a new paragraph, precede it with @noindent.
This example shows the results of running our program:
@example $ make_money Congratulations! You are a rich Memory fault - core dumped $ @end example @noindent As we can see, there is a small problem somewhere. ...
A distinguishing feature of Texinfo documents is that they are liberally filled with cross-references. There are several kinds of cross-reference statements, all of which take at least a node name as their argument.
@xref{Introduction}, for a description of the
history of @code{Foogol}.
There are longer forms that can take the full title of a node (from the @chapter command, for example). In TeX, the cross-reference will generate a typical cross-reference, including a page number.
See [Introduction], page 12, for a description of the history of Foogol.
In an Info file, the cross-reference commands put cross-references into the text. The cross reference would look like this:
*Note Introduction, for a description of the history of `Foogol'.
When reading the Info file with a viewer, you can issue a simple command that will instruct the viewer to follow the cross-reference. It is the cross-references that provide the "hypertext" feel to the on-line Info reader. Cross-references are typically references to other nodes within the current document, but they don't have to be! A cross-reference to a node in another Texinfo document can be followed, and the Info reader will go to it just as easily as to a node in the current document.
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.
Texinfo provides a clean input language with everything necessary for producing handsome printed documentation and highly usable on-line hypertext help. The info viewer provides a friendly interface for reading the on-line Info files.
The nicest thing I have found about Texinfo is that you don't need to know TeX to use it. I have been happily writing in Texinfo for around seven years, and have not really needed to learn TeX. Even though Texinfo has over 160 commands, what I've covered in this article is 95% of what most people would use on a day-to-day basis.
I 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. The Texinfo manual comes with the Texinfo distribution, and is of course written in Texinfo; this provides a nice example that uses all of Texinfo's features.
Thanks to Miriam Robbins for making me clarify a number of points in this article, and to Robert J. Chassell of the FSF (primary author of the Texinfo manual) for his comments.
Arnold Robbins is a professional programmer and semi-professional author. He has been doing volunteer work for the GNU project since 1987 and working with Unix and Unix-like systems since 1981.
