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.
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:

*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.

______________________

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