💾 Archived View for gmi.noulin.net › mobileNews › 2683.gmi captured on 2022-06-11 at 23:37:31. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
Oct 01, 1994 By Arnold Robbins
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.
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.
Processing Texinfo Files
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.
What is Texinfo?
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
Basic Structure Of A Texinfo Document
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
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
history and acknowledgements.
using this Info file.
How to run a @code{foogol} program.
Command line syntax.
.....
@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.
Indices
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.
In-Line Font Changes
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.
Tables And Lists
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.
Examples
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.
...
Cross-References
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:
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.
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.
Summary
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.
Acknowledgements
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.