LINUX GAZETTE
[ Prev ][ Table of Contents ][ Front Page ][ Talkback ][ FAQ ][ Next ]

"Linux Gazette...making Linux just a little more fun!"


Writing Documentation, Part IV: Texinfo

By Christoph Spiel


Texinfo is the documentation system preferred by GNU projects.

The major design goal of the Texinfo format is to produce high quality printed output as well as online browsable output from the same source (.texi) file. Texinfo obtains the basis for a high quality hardcopy with a trick: it builds on plain TeX and adapts it by reading the file texinfo.tex (Your system might have more than one copy of this file. Check that you are really using a recent version (2002-01-04.07 as of this writing)). texinfo.tex does all the necessary formatting setup. It extends TeX to recognize hyper-references and all the gizmos that is needed for online documentation. Rendered for online viewing, Texinfo source yields Info (.info) files.

Info? What's that?

Info is an ASCII file format suitable for browsing hyperlinked documents. It is intended to be portable to all platforms which run GNU applications. Info focuses on textual data; this is, all Info files are viewable from a text console. High resolution graphics are available only in printed output. Thus, Info is the GNU counterpart of HTML minus some graphical extras. However, texi2html(1) transforms Texinfo sources (.texi) directly into HTML; see the section on Browsers.

Document Structure

Since Texinfo is based on TeX (see my second article in this series, "LaTeX with latex2html"), we expect to see again a header-body division. Also, the support for hyperlinks calls for additional structuring that we will meet in the form of so-called nodes.

Overall Structure

Every Texinfo document starts by reading texinfo.tex with the plain TeX command \input. This is about the only place where plain TeX leaks into Texinfo. The part of the file from the inclusion of texinfo.tex up to the so called Top node -- more on nodes later -- is the document's header. The Top node opens up the body of the document, which extends to the closing command @bye.

All Texinfo commands are introduced with an ``@''-character. The at-character is followed by one or more letters. Only a few commands require curly braces to group together their arguments. We have already encountered the end-of-document command @bye. The following example of a minimal Texinfo file introduces the comment command, which is @c. Texinfo comments extend to the end of the line in which they are given.

\input texinfo


@c === header ===
...


@c === body ===

@c --- Top Node ---
...

@c --- Sub Nodes ---
...


@bye

Header

The header of a Texinfo file is optional, but it appears in all documents. It at least contains the name of the online-reading output file, and the title used in the printed output.

The output filename is set with the command @setfilename output-filename. I recommend adding the extension .info to output-filename, because files without an extension are harder to access with common shell tools--just think of ls *.info! The argument of @setfilename reaches right to the end of the line, thus you cannot add a comment after setting the output filename. Bummer!

Set the document title with @settitle document-title. Again, the argument stretches until the end of the line. The title -- as defined by @settitle -- is used for page headers or footers in the printed output. It has nothing to do with the document title used on the title page (if a title page exists at all).

Thus, a simple header looks like this:

    @setfilename example.info
    @settitle Texinfo Example

Other useful commands in the header are:

Tip: All GNU development projects ship with documentation in Texinfo format. If you want to print the documentation on your local output device, it is a good plan to modify the header of the Texinfo files to match your paper size (Letter, A4) and printing equipment (duplex unit, and so on).

Body

The body of a Texinfo document is a mixture of sectioning commands for printing (the TeX part: chapters, sections, sub-sections, and so on) and grouping commands for online viewing (the Info part: nodes). In theory both parts can impose different structures on the document, however this would seriously confuse readers -- probably not what you want when writing technical documentation.

I will present a simplified way of writing the body, where the structure of the online version and of the printed version closely go together. This saves the writer the headaches of manually setting up the structure for the online version at the price of sacrificing some additional navigation possibilities. The simplified way requires pairing the Info structure information with that of the printed version.

The Info structure is defined with @node node-name commands, whereas the printed structure is given -- among others -- with the commands @chapter chapter-title, @section section-title, and @subsection subsection-title. The @node command always goes first. So we get, for example,

    @node Introduction
    @chapter Introduction

or

    @node Iterative-Processes
    @section Iterative Processes

or

    @node Numerical Stability
    @subsection Numerical Stability of Iterative Algorithms

The argument to @node, assigns the name node-name to the node. The name consists of one or more words. Spaces are perfectly valid in node-name, but periods ``.'', commas ``,'', colons ``:'', and apostrophes ``''' are not. It is also better to avoid commands (anything starting with ``@'') in a node name. Case of node-names is significant. Within a Texinfo document each node must have a unique name. By convention, node names are capitalized just as chapter or section titles are.

A node either contains only data (this is, text, tables, images, and cross-references), or a node defines a navigation menu. I call the former a Terminal Nodes and the latter a Menu Nodes.

Terminal Node
The structure of a Terminal Node is
@node node-name
@section section-title

text-for-node-and-chapter

where I use @section as an example for a sectioning command.

Terminal Nodes are the ``meat'' of a document. They hold all the visible information. text-for-node-and-chapter usually consists of one or more paragraphs, tables, and so on.

Menu Node
Menu nodes provide decentralized tables of contents, this is meta information, from which you can jump to any of the topics referred to in the menu.

The structure of a Menu Node is the same as for a Terminal Node, with the exception that a Menu Node is ended by the definition of a navigation menu. The navigation menu only goes into the Info version, never into the printed one.

@node node-name
@chapter chapter-title

optional-introductory-text-for-node-and-chapter

@menu
* Node name of first section:: Synopsis of first section
* Node name of second section:: Synopsis of second section
...
* Node name of last section:: Synopsis of last section
@end menu

A navigation menu is bracketed by

@menu

@end menu

where every line in between makes up one menu entry. Each menu entry starts with an asterisk ``*'' followed by the name of the node it points to (the target node's name). It is ended by two colons ``::'' and an optional short description of the target:

* Target Node Name:: Optional description of target node

Top Node
One menu node in every Texinfo document plays a special role: the master menu node from which the rest of the document is accessed. This root node is called Top node; we define it with the pair
@node Top
@top name-of-top-node

As the Top node will appear first whenever the online version is browsed (unless you explicitly specify a node to start browsing with), you want to have some introductory text to go with it. This introduction often is not suited for the printed version. The printed version shows no menus at all, remember? Thus, we want to exclude the introductory text from the printed version, which is done with the conditional translation command pair @ifinfo and @end ifinfo. A simple Top node then looks like this:

@ifinfo
@node Top
@top Example
This is an example Texinfo document.

@end ifinfo

@menu
* Name of first chapter:: Synopsis of first chapter
* Name of second chapter:: Synopsis of second chapter
* Name of third chapter:: Synopsis of third chapter
@end menu

Now we are ready to write a complete Texinfo document.

    \input texinfo
    @setfilename example.info
    @settitle Texinfo Example
    @ifinfo
    @node Top
    @top Example
    This is an example Texinfo document.
    @end ifinfo
    @menu
    * Introduction::                 Definitions, Measures, Complexity
    * Evaluation of Polynomials::    Study of a common operation
    @end menu
    @node Introduction
    @chapter Introduction
    In this chapter I define the concepts that will be used throughout the
    rest of the document.  Moreover, measures of efficiencies as well as
    bounds of complexity will be introduced.
    @menu
    * Definitions::               Fundamental stuff
    * Measures of Efficiency::    How to measure efficiency
    * Bounds of Complexity::      Typical bounds of complexity
    @end menu
    @node Definitions
    @section Definitions
    ...
    @node Measures of Efficiency
    @section Measures of Efficiency
    ...
    @node Bounds of Complexity
    @section Bounds of Complexity
    ...
    @node Evaluation of Polynomials
    @chapter Evaluation of Polynomials
    ...
    @bye

Syntax

As we have already seen, Texinfo commands start with an at-sign ``@''. The at-sign is either followed by a single non-letter character or one or more characters. Some commands of the first group include

@@
Insert a literal at-sign (``@'').
@"character
Typeset the umlaut equivalent of character, where character is a single ASCII character like, for example, ``a''. The same holds for accented (@'character), circumflexed (@^character), or cedilla decorated (@,character) characters. See node ``Inserting Accents'' in the Texinfo documentation for details.

and some in the latter group are

@contents
Insert the table of contents where @contents occurs.
@page
Start a new page.
@findex function-name
Generate an index entry for function-name in the index of all functions.

Depending on the command, no argument, one argument, or more than one argument may be required. Some commands require their arguments to be enclosed on curly braces, like cross references, @xref{node-name, cross-reference-name, title-or-topic}. We have seen commands which take rest of the line as their arguments (for example @setfilename).

Sectioning

As with TeX, we just type text, separating paragraphs with blank lines. Paragraphs will be filled or even justified depending on the used translation tools.

Section Body has introduced the main sectioning commands. @node groups the input together in chunks for online reading. An accompanying TeX-like sectioning command does the same for the printed output. In particular Texinfo offers the following sectioning commands: chapter, section, subsection, and subsubsection.

Please remember that -- for a simplified node management -- each @node must be followed by one of the sectioning commands for the printed version.

Title Page

Making a decent title page is easy. The @titlepage command with its sub-commands @title, @subtitle (optional), and @author completely takes care of the layout. If you want the material after the title to go on an odd page add a page break @page right before @end titlepage.

Example:

    @titlepage
    @title A Texinfo Example Document
    @subtitle Playing With the Texinfo Format
    @author Joanne H. Acker
    @page @c -- force odd page
    @end titlepage

Conditional Translation

In the section on the Top Node, we encountered the condition translation command @ifinfo/@end info. Conditional translation means directing parts of a document to one translator only, or, in the negated form @ifnotinfo/@end notinfo, excluding one translator (makeinfo in our example) from processing a chunk of the document.

The opening (@ifformat) and closing sequence (@end format) should appear on lines by themselves.

Three conditionals are available in positive and negative form for diverting data to or away from Info, TeX and HTML.

    @iftex
    ...
    @end tex
    @ifinfo
    ...
    @end info
    @ifhtml
    ...
    @end html
    @ifnottex
    ...
    @end nottex
    @ifnotinfo
    ...
    @end notinfo
    @ifnothtml
    ...
    @end nothtml

Lists

Texinfo features the fundamental types of lists, which any author expects: itemized and enumerated lists. Description lists are written in terms of tables.

All lists nest.

Command @item starts an entry in a list or table. The entry can comprise several paragraphs or further lists. Did I tell you that all lists nest? They do!

Itemized Lists
@itemize glyph
@item Text for first item
@item Text for second item
...
@item Text for last item
@end itemize

Symbol glyph will be put in front of every item. Useful values for glyph are @bullet, @minus, and *.

Enumerated Lists
@enumerate counter-selector
@item Text for first item
@item Text for second item
...
@item Text for last item
@end enumerate

counter-selector selects the type of counter (numeral or letter) and the starting value. If counter-selector is omitted, the list will be decorated with Arabic numerals starting at one.

A positive integer value for counter-selector starts the list at the given value. This is useful when continuing a list. An uppercase or lowercase letter for counter-selector selects letters for the enumeration; again, the list starts with the given letter.

Texinfo cannot render enumerate lists with Roman numerals.

Description Lists
I have mentioned that Texinfo does not offer native description lists, but emulates typesetting them with two-column tables. So, we get the following syntax for description lists:
@table format-selector
@item First term
Description for first item
@item Second term
Description for second item
...
@item Last term
Description for last item
@end table

format-selector determines how the terms are typeset. For no added markup, this is, plain description lists, use @asis as format-selector. If you have code, sample input or output, variables, or keystrokes as terms, use @code, @samp, @var, or @kbd respectively. See section Inline Markup for how to markup specific items.

Within a table, the argument to @item is all the text from @item to the end of the line. Note that this is different from itemized and enumerated lists! Thus, the term in a "description list" can only be a single line. The text after the @item-line up to the next @item or the end of the table becomes the term's description. The description can be several paragraphs long and it can contain other lists, and so on.

Sometimes we need additional terms on separate lines. Because @item puts its argument on a single lines, another command is required: @itemx places an additional term right below an existing term. @itemx is only valid directly after an @item command or @itemx command.

Cross-References

Texinfo supports a variety of cross reference types: with or without additional text, within the same file, across different Texinfo files, and to the outside world.

Nodes are the primary targets of cross references. @anchor{anchor-name} marks additional targets. Command @anchor does not produce any output. The names of anchors must not conflict with node names.

@xref
Insert a decorated cross reference. @xref formats the decoration for the start of a sentence.

Example usage:

    ... is the basis for several multi-point
    methods.  @xref{Multi-point Methods}.  We
    study the single point method ...
@pxref
@pxref behaves like @xref, but it is meant to be used inside parenthesis.

Example usage:

    The algorithm fails at higher order
    roots (@pxref{Higher Order Root}) and
    ill-conditioned roots of order one.
@ref
Inserts an undecorated cross reference. Otherwise it behaves like @xref.

Until now we have only used the one-argument form of the cross referencing commands. However, they accept up to five parameters. Here is how the output changes with the number of parameters. I demonstrate the flexible usage with @xref.

One Argument
@xref{target-name}

produces

*Note target-name::

in the Info version and

See Section target-section [target-name], page target-page

in the printed version, where target-section and target-page are the section number and the page number where the target lives in the printed version.

Two Arguments
@xref{target-name, cross-reference-name}

produces:

*Note cross-reference-name: target-name

and

See Section target-section [target-name], page target-page

Three Arguments
@xref{target-name, cross-reference-name, title-or-topic}

produces:

*Note cross-reference-name: target-name

and

See Section target-section [title-or-topic], page target-page

Five Arguments
@xref{target-name, cross-reference-name, title-or-topic, info-file-name, printed-manual-title}

produces:

*Note cross-reference-name: (info-file-name)target-name

and

See section "title-or-topic" in printed-manual-title

Inline Markup

Texinfo defines a whole bunch of commands to markup special parts of text as being code, input from the user, a filename, and so on.

Tools

makeinfo
makeinfo transforms Texinfo files (.texi) into
  1. Info

    By default, makeinfo generates Info files with the filename selected by @setfilename. Option --no-split prevents makeinfo from breaking the output in chunks (approximately 50KB in size).

    Processing a Texinfo file with makeinfo also thoroughly validates the input file.

  2. Plain ASCII

    Option --no-headers makes makeinfo generate plain ASCII files. Plain ASCII is a useful format for proofreading the online version and also for applying spelling checkers like, for example, diction(1).

texi2html
As you might have guessed from the command's name, texi2html transforms Texinfo into HTML. Option -monolithic forces the output of a single file. Option -split on the other hand forces one file per node.

texi2html by default converts @iftex sections and not @ifinfo ones. You can reverse this behavior with the -expandinfo option.

Note that all of texi2html's options start with a single dash.

texi2dvi
Produce a device independent file .dvi form Texinfo source. To get Postscript, apply dvips(1) to the .dvi file. I have found the options --clean and --quiet useful. The first removes all intermediate files, leaving only the final .dvi file. The second suppresses all non-essential messages (``No gnews is good gnews!'').
texi2pdf
texi2pdf makes a Portable Document File (.pdf) from Texinfo source in one shot. It accepts the same options as texi2dvi does. However, I found, it definitely wants to see option --pdf or it stops, crying for a .dvi file even if this very file exists. Argh! So, my typical calls are
    texi2pdf --quiet --clean --pdf foobar.texi

Browsers

Texinfo differs from all the document preparation systems that we have had a look at so far, for Texinfo can be translated in an online viewing format different from HTML, namely: Info. Having an online viewing format, we need browsers to actually view it!

info

info, the mother of all Info browsers, is a simple but efficient browser for viewing Info files at a console.

To view the Info pages of topic, use

    info topic

To browse Info file info-file, add --file=info-file to the invocation of info, where info-file contains the complete path to the Info file.

If you would like to start browsing at specific node node-name, add --node=node-name.

My favorite mistake is mixing up topic with info-file, this is saying

    info ./cache-profiler.info

when I really mean

    info --file=./cache-profiler.info
pinfo

pinfo is a curses(3) based Info browser with lynx(1) like navigation. pinfo does a nice job colorizing Info pages.

emacs

Emacs version 21.x features an improved Info browsing mode as proves this screen shot.

I know, it's only Emacs Info, but I like it, like it! Yes, I do!

You browse the installed Info documents (`C-h i', info). Or you load an Info file into Emacs and turn the buffer an Info-browser with Info-on-current-buffer (note the capital "I"). If you dislike switching between the Info buffer and you working buffers, open the file to browse in another frame (`C-x 5 f', find-file-other-frame). To open a new frame with an Info browser in it, switch to the *info* buffer in your current emacs and issue view-buffer-other-frame.

For additional browsing pleasure, try Info-speedbar-browser.

xinfo
xinfo is an ancient Info browser for the use under X11. It does not do any colorization. What bothers me most about xinfo -- to the degree that I refuse to use this browser -- is the separation of navigation hot spots and display. This means you have to click in the topmost pane to navigate a menu shown in the second pane. Clicking directly on the menu item in the second pane has no effect.

Here is a screen shot.

tkinfo

My favorite X-based Info browser! It has all the nice features of info(1), starts up fast and has a compact layout.

gnome-help-browser

If you are a Gnome user, you probably know the gnome-help-browser(1x). It displays Info pages, too.

kdehelp

Same for KDE users... You probably know kdehelp(1x). Amongst various other formats it also displays Info pages.

kdehelp is easily convinced to browse a specific Info file:

    kdehelp ./cache-profiler.info

Thumbs up!

konqueror also displays info files (at least konqueror 2.2.2); just type "info:" in the Location: bar.

Overview of Common Info Browsers

Overview of Common Info Browsers. Multi-format browser accept other formats than Info. X11-based browsers require X11 to run. info-like navigation duplicates the navigation commands of info(1).
Application Multi-format X11-based info Navigation
info no no yes
pinfo no no no
emacs no no yes
xinfo no yes yes
tkinfo no yes yes
gnome-help-browser yes yes no
kdehelp yes yes no

Pros and Cons

Pros
Cons

Further Reading

The home page of Texinfo, with lots of references and all that, is located at http://texinfo.org/

Available converters for Texinfo are listed at http://www.fido.de/kama/texinfo/texinfo-en.html

Christoph Spiel

Chris runs an Open Source Software consulting company in Upper Bavaria, Germany. Despite being trained as a physicist -- he holds a PhD in physics from Munich University of Technology -- his main interests revolve around numerics, heterogenous programming environments, and software engineering. He can be reached at cspiel@hammersmith-consulting.com.


Copyright © 2002, Christoph Spiel.
Copying license http://www.linuxgazette.com/copying.html
Published in Issue 76 of Linux Gazette, March 2002

[ Prev ][ Table of Contents ][ Front Page ][ Talkback ][ FAQ ][ Next ]