File: spiel.html

package info (click to toggle)
lg-issue76 1-1
links: PTS
area: main
in suites: woody
size: 1,680 kB
ctags: 219
sloc: ansic: 164; sh: 74; makefile: 36
file content (1310 lines) | stat: -rw-r--r-- 42,583 bytes
<!--startcut  ==============================================-->
<!-- *** BEGIN HTML header *** -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD>
<title>Writing Documentation, Part IV: Texinfo LG #76</title>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#0000AF"
ALINK="#FF0000">
<!-- *** END HTML header *** -->

<CENTER>
<A HREF="http://www.linuxgazette.com/">
<IMG ALT="LINUX GAZETTE" SRC="../gx/lglogo.png" 
	WIDTH="600" HEIGHT="124" border="0"></A> 
<BR>

<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="rogers.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="lg_toc76.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue76/spiel.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><A HREF="../lg_faq.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="vermeer.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
<P>
</CENTER>

<!--endcut ============================================================-->

<H4 ALIGN="center">
"Linux Gazette...<I>making Linux just a little more fun!</I>"
</H4>

<P> <HR> <P> 
<!--===================================================================-->

<center>
<H1><font color="maroon">Writing Documentation, Part IV: Texinfo</font></H1>
<H4>By <a href="mailto:cspiel@hammersmith-consulting.com">Christoph Spiel</a></H4>
</center>
<P> <HR> <P>  

<!-- END header -->




<a name="texinfo"></a>

<p>Texinfo is the documentation system preferred by GNU projects.</p>

<p>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
(<em>.texi</em>) 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&nbsp;<em>texinfo.tex</em> (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)). <em>texinfo.tex</em> 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 (<em>.info</em>) files.</p>

<h3><a name="info what's that">Info? What's that?</a></h3>

<p>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, <a
href="#item_texi2html"><code>texi2html(1)</code></a> transforms Texinfo
sources (<em>.texi</em>) directly into HTML; see the section on <a href= 
"#browsers">Browsers</a>.</p>

<h3><a name="document structure">Document Structure</a></h3>

<p>Since Texinfo is based on TeX (see my second article in this series, 
"<a href= 
"../issue74/spiel.html">LaTeX with latex2html</a>"),
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.</p>

<h4><a name="overall structure">Overall Structure</a></h4>

<p>Every Texinfo document starts by reading <em>texinfo.tex</em> with the
plain TeX command&nbsp;<code>\input</code>. This is about the only place where
plain TeX leaks into Texinfo. The part of the file from the inclusion of
<em>texinfo.tex</em> 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&nbsp;<code>@bye</code>.</p>

<p>All Texinfo commands are introduced with an ``<code>@</code>''-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&nbsp;<code>@bye</code>. The following example of a
minimal Texinfo file introduces the comment command, which is <code>@c</code>.
Texinfo comments extend to the end of the line in which they are given.</p>

<blockquote><code>\input texinfo<br>
<br>
<br>
@c === header ===<br>
...<br>
<br>
<br>
@c === body ===<br>
<br>
@c --- Top Node ---<br>
...<br>
<br>
@c --- Sub Nodes ---<br>
...<br>
<br>
<br>
@bye</code></blockquote>

<h4><a name="header">Header</a></h4>

<p>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.</p>

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

<p>Set the document title with
<code>@settitle</code>&nbsp;<em>document-title</em>. Again, the argument
stretches until the end of the line. The title -- as defined by
<code>@settitle</code> -- 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).</p>

<p>Thus, a simple header looks like this:</p>

<pre>
    @setfilename example.info
    @settitle Texinfo Example
</pre>

<p>Other useful commands in the header are:</p>

<ul>
<li>@afourpaper and @afourwide 

<p>By default Texinfo assumes a paper size of 8.5"&nbsp;by&nbsp;11". Outside
Northern America, paper sizes are chosen according to DIN (DIN is the
abbreviation for ``Deutsche Industrie Norm'', ``German Industry Standard'' in
English). The commands&nbsp;<code>@afourpaper</code> and
<code>@afourwide</code> adjust the printable area for sheets of size
DIN&nbsp;A4, where <code>@afourwide</code> selects a somewhat larger printable
area; it does not switch to landscape.</p>

<p><em>Tip:</em> It is a good plan to inspect the paper size settings of any
foreign Texinfo document before you send it to the printer.</p>
</li>

<li>@setchapternewpage on | off | odd 

<dl>
<dt><strong><a name="item_on">on</a></strong><br>
</dt>

<dd>Start a new page for each chapter. Format page headers and footers for
single-sided printing. This is the default setting.</dd>

<dt><strong><a name="item_off">off</a></strong><br>
</dt>

<dd>Do not start a new page for a new chapter; just insert some white space
before the new chapter. Format page headers and footers for single-sided
printing.</dd>

<dt><strong><a name="item_odd">odd</a></strong><br>
</dt>

<dd>Start new chapters on odd-numbered pages. Format page headers and footers
for double-sided (``recto verso'') printing.</dd>
</dl>

<p>Note that no <code>@setchapternewpage&nbsp;even</code>&nbsp;command is
defined.</p>
</li>

<li>@paragraphindent asis | <em>number</em> 

<dl>
<dt><strong><a name="item_asis">asis</a></strong><br>
</dt>

<dd>Do not change indentation</dd>

<dt><strong><a name="item_number"><em>number</em></a></strong><br>
</dt>

<dd>Indent the first line of each paragraph by <em>number</em>&nbsp;spaces,
where <em>number</em> can be zero.</dd>
</dl>
</li>
</ul>

<p>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).</p>

<h4><a name="body">Body</a></h4>

<p>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.</p>

<p>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.</p>

<p>The Info structure is defined with
<code>@node</code>&nbsp;<em>node-name</em>&nbsp;commands, whereas the printed
structure is given -- among others -- with the
commands&nbsp;<code>@chapter</code>&nbsp;<em>chapter-title</em>,
<code>@section</code> <em>section-title</em>, and
<code>@subsection</code>&nbsp;<em>subsection-title</em>. The
<code>@node</code>&nbsp;command always goes first. So we get, for example,</p>

<pre>
    @node Introduction
    @chapter Introduction
</pre>

<p>or</p>

<pre>
    @node Iterative-Processes
    @section Iterative Processes
</pre>

<p>or</p>

<pre>
    @node Numerical Stability
    @subsection Numerical Stability of Iterative Algorithms
</pre>

<p>The argument to <code>@node</code>, assigns the
name&nbsp;<em>node-name</em> to the node. The name consists of one or more
words. Spaces are perfectly valid in <em>node-name</em>, but
periods&nbsp;``<code>.</code>'', commas&nbsp;``<code>,</code>'',
colons&nbsp;``<code>:</code>'', and apostrophes&nbsp;``<code>'</code>'' are
not. It is also better to avoid commands (anything starting with
``<code>@</code>'') 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.</p>

<p>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&nbsp;Nodes and the latter a Menu&nbsp;Nodes.</p>

<dl>
<dt><strong><a name="item_Terminal_Node">Terminal Node</a></strong><br>
</dt>

<dd>The structure of a Terminal&nbsp;Node is 

<blockquote><code>@node</code> <var>node-name</var><br>
<code>@section</code> <var>section-title</var><br>
<br>
<var>text-for-node-and-chapter</var></blockquote>

<p>where I use <code>@section</code> as an example for a sectioning
command.</p>

<p>Terminal&nbsp;Nodes are the ``meat'' of a document. They hold all the
visible information. <em>text-for-node-and-chapter</em> usually consists of
one or more paragraphs, tables, and so on.</p>
</dd>

<dt><strong><a name="item_Menu_Node">Menu Node</a></strong><br>
</dt>

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

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

<blockquote><code>@node</code> <var>node-name</var><br>
<code>@chapter</code> <var>chapter-title</var><br>
<br>
<var>optional-introductory-text-for-node-and-chapter</var><br>
<br>
<code>@menu</code><br>
 <code>*</code> <var>Node name of first section</var><code>::</code>
<var>Synopsis of first section</var><br>
<code>*</code> <var>Node name of second section</var><code>::</code>
<var>Synopsis of second section</var><br>
...<br>
<code>*</code> <var>Node name of last section</var><code>::</code>
<var>Synopsis of last section</var><br>
<code>@end menu</code></blockquote>

<p>A navigation menu is bracketed by</p>

<blockquote><code>@menu</code><br>
<br>
<code>@end menu</code></blockquote>

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

<p><code>*</code> <em>Target Node Name</em><code>::</code> <em>Optional
description of target node</em></p>
</dd>

<dt><strong><a name="item_Top_Node">Top Node</a></strong><br>
</dt>

<dd>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 <code>Top</code>&nbsp;node; we define it with the pair 

<blockquote><code>@node Top</code><br>
<code>@top</code> <var>name-of-top-node</var></blockquote>

<p>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 <a href=
"#conditional_translation">conditional translation</a> command pair
<code>@ifinfo</code> and <code>@end ifinfo</code>. A simple Top node then
looks like this:</p>

<blockquote><code>@ifinfo</code><br>
<code>@node</code> Top<br>
<code>@top</code> Example<br>
This is an example Texinfo document.<br>
<br>
<code>@end ifinfo</code><br>
<br>
<code>@menu</code><br>
<code>*</code> Name of first chapter<code>::</code> Synopsis of first
chapter<br>
<code>*</code> Name of second chapter<code>::</code> Synopsis of second
chapter<br>
<code>*</code> Name of third chapter<code>::</code> Synopsis of third
chapter<br>
<code>@end menu</code></blockquote>
</dd>
</dl>

<p>Now we are ready to write a complete Texinfo document.</p>

<pre>
    \input texinfo
</pre>

<pre>
    @setfilename example.info
    @settitle Texinfo Example
</pre>

<pre>
    @ifinfo
    @node Top
    @top Example
</pre>

<pre>
    This is an example Texinfo document.
    @end ifinfo
</pre>

<pre>
    @menu
    * Introduction::                 Definitions, Measures, Complexity
    * Evaluation of Polynomials::    Study of a common operation
    @end menu
</pre>

<pre>
    @node Introduction
    @chapter Introduction
</pre>

<pre>
    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.
</pre>

<pre>
    @menu
    * Definitions::               Fundamental stuff
    * Measures of Efficiency::    How to measure efficiency
    * Bounds of Complexity::      Typical bounds of complexity
    @end menu
</pre>

<pre>
    @node Definitions
    @section Definitions
</pre>

<pre>
    ...
</pre>

<pre>
    @node Measures of Efficiency
    @section Measures of Efficiency
</pre>

<pre>
    ...
</pre>

<pre>
    @node Bounds of Complexity
    @section Bounds of Complexity
</pre>

<pre>
    ...
</pre>

<pre>
    @node Evaluation of Polynomials
    @chapter Evaluation of Polynomials
</pre>

<pre>
    ...
</pre>

<pre>
    @bye
</pre>

<h3><a name="syntax">Syntax</a></h3>

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

<dl>
<dt><strong><a name="item_%40%40"><code>@@</code></a></strong><br>
</dt>

<dd>Insert a literal at-sign&nbsp;(``<code>@</code>'').</dd>

<dt><strong><a name=
"item_%40%22character"><code>@"</code><em>character</em></a></strong><br>
</dt>

<dd>Typeset the umlaut equivalent of <em>character</em>, where
<em>character</em> is a single ASCII character like, for example, ``a''. The
same holds for accented (<code>@'</code><em>character</em>), circumflexed
(<code>@^</code><em>character</em>), or cedilla decorated
(<code>@,</code><em>character</em>) characters. See node
``Inserting&nbsp;Accents'' in the Texinfo documentation for details.</dd>
</dl>

<p>and some in the latter group are</p>

<dl>
<dt><strong><a name="item_%40contents">@contents</a></strong><br>
</dt>

<dd>Insert the table of contents where @contents occurs.</dd>

<dt><strong><a name="item_%40page">@page</a></strong><br>
</dt>

<dd>Start a new page.</dd>

<dt><strong><a name="item_%40findex_function%2Dname">@findex
<em>function-name</em></a></strong><br>
</dt>

<dd>Generate an index entry for <em>function-name</em> in the index of all
functions.</dd>
</dl>

<p>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,
<code>@xref{</code><em>node-name</em><code>,</code>
<em>cross-reference-name</em><code>,</code>
<em>title-or-topic</em><code>}</code>. We have seen commands which take rest
of the line as their arguments (for example <code>@setfilename</code>).</p>

<h3><a name="sectioning">Sectioning</a></h3>

<p>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.</p>

<p>Section&nbsp;<a>Body</a> has introduced the main sectioning commands.
<code>@node</code> 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:
<code>chapter</code>, <code>section</code>, <code>subsection</code>, and
<code>subsubsection</code>.</p>

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

<h3><a name="title page">Title Page</a></h3>

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

<p>Example:</p>

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

<h3><a name="conditional_translation">Conditional Translation</a></h3>

<p>In the section on the <a href="#item_Top_Node">Top Node</a>, we encountered the
condition translation
command&nbsp;<code>@ifinfo</code>/<code>@end&nbsp;info</code>. Conditional
translation means directing parts of a document to one translator only, or, in
the negated form <code>@ifnotinfo</code>/<code>@end notinfo</code>, excluding
one translator (makeinfo in our example) from processing a chunk of the
document.</p>

<p>The opening (<code>@if</code><em>format</em>) and closing sequence
(<code>@end</code> <em>format</em>) should appear on lines by themselves.</p>

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

<pre>
    @iftex
    ...
    @end tex
</pre>

<pre>
    @ifinfo
    ...
    @end info
</pre>

<pre>
    @ifhtml
    ...
    @end html
</pre>

<pre>
    @ifnottex
    ...
    @end nottex
</pre>

<pre>
    @ifnotinfo
    ...
    @end notinfo
</pre>

<pre>
    @ifnothtml
    ...
    @end nothtml
</pre>

<h3><a name="lists">Lists</a></h3>

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

<p>All lists nest.</p>

<p>Command&nbsp;<code>@item</code> 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!</p>

<dl>
<dt><strong><a name="item_Itemized_Lists">Itemized Lists</a></strong><br>
</dt>

<dd>
<blockquote><code>@itemize</code> <var>glyph</var><br>
<code>@item</code> <var>Text for first item</var><br>
<code>@item</code> <var>Text for second item</var><br>
...<br>
<code>@item</code> <var>Text for last item</var><br>
<code>@end itemize</code></blockquote>

<p>Symbol&nbsp;<em>glyph</em> will be put in front of every item. Useful
values for <em>glyph</em> are <code>@bullet</code>, <code>@minus</code>, and
<code>*</code>.</p>
</dd>

<dt><strong><a name="item_Enumerated_Lists">Enumerated Lists</a></strong><br>
</dt>

<dd>
<blockquote><code>@enumerate</code> <var>counter-selector</var><br>
<code>@item</code> <var>Text for first item</var><br>
<code>@item</code> <var>Text for second item</var><br>
...<br>
<code>@item</code> <var>Text for last item</var><br>
<code>@end enumerate</code></blockquote>

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

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

<p>Texinfo cannot render enumerate lists with Roman numerals.</p>
</dd>

<dt><strong><a name="item_Description_Lists">Description
Lists</a></strong><br>
</dt>

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

<blockquote><code>@table</code> <var>format-selector</var><br>
<code>@item</code> <var>First term</var><br>
<var>Description for first item</var><br>
<code>@item</code> <var>Second term</var><br>
<var>Description for second item</var><br>
...<br>
<code>@item</code> <var>Last term</var><br>
<var>Description for last item</var><br>
<code>@end table</code></blockquote>

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

<p>Within a table, the argument to <code>@item</code> is all the text from
<code>@item</code> 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 <code>@item</code>-line up to the next
<code>@item</code> 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.</p>

<p>Sometimes we need additional terms on separate lines. Because
<code>@item</code> puts its argument on a single lines, another command is
required: <code>@itemx</code> places an additional term right below an
existing term. <code>@itemx</code> is only valid directly after an
<code>@item</code>&nbsp;command or <code>@itemx</code>&nbsp;command.</p>
</dd>
</dl>

<h3><a name="crossreferences">Cross-References</a></h3>

<p>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.</p>

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

<dl>
<dt><strong><a name="item_%40xref">@xref</a></strong><br>
</dt>

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

<p>Example usage:</p>

<pre>
    ... is the basis for several multi-point
    methods.  @xref{Multi-point Methods}.  We
    study the single point method ...
</pre>
</dd>

<dt><strong><a name="item_%40pxref">@pxref</a></strong><br>
</dt>

<dd>@pxref behaves like @xref, but it is meant to be used inside parenthesis. 

<p>Example usage:</p>

<pre>
    The algorithm fails at higher order
    roots (@pxref{Higher Order Root}) and
    ill-conditioned roots of order one.
</pre>
</dd>

<dt><strong><a name="item_%40ref">@ref</a></strong><br>
</dt>

<dd>Inserts an undecorated cross reference. Otherwise it behaves like
@xref.</dd>
</dl>

<p>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.</p>

<dl>
<dt><strong><a name="item_One_Argument">One Argument</a></strong><br>
</dt>

<dd><code>@xref{</code><em>target-name</em><code>}</code> 

<p>produces</p>

<p><code>*Note</code> <em>target-name</em><code>::</code></p>

<p>in the Info version and</p>

<p><code>See Section</code> <em>target-section</em>
<code>[</code><em>target-name</em><code>],</code> <code>page</code>
<em>target-page</em></p>

<p>in the printed version, where <em>target-section</em> and
<em>target-page</em> are the section number and the page number where the
target lives in the printed version.</p>
</dd>

<dt><strong><a name="item_Two_Arguments">Two Arguments</a></strong><br>
</dt>

<dd><code>@xref{</code><em>target-name</em><code>,</code>
<em>cross-reference-name</em><code>}</code> 

<p>produces:</p>

<p><code>*Note</code> <em>cross-reference-name</em><code>:</code>
<em>target-name</em></p>

<p>and</p>

<p><code>See Section</code> <em>target-section</em>
<code>[</code><em>target-name</em><code>],</code> <code>page</code>
<em>target-page</em></p>
</dd>

<dt><strong><a name="item_Three_Arguments">Three Arguments</a></strong><br>
</dt>

<dd><code>@xref{</code><em>target-name</em><code>,</code>
<em>cross-reference-name</em><code>,</code>
<em>title-or-topic</em><code>}</code> 

<p>produces:</p>

<p><code>*Note</code> <em>cross-reference-name</em><code>:</code>
<em>target-name</em></p>

<p>and</p>

<p><code>See Section</code> <em>target-section</em>
<code>[</code><em>title-or-topic</em><code>],</code> <code>page</code>
<em>target-page</em></p>
</dd>

<dt><strong><a name="item_Five_Arguments">Five Arguments</a></strong><br>
</dt>

<dd><code>@xref{</code><em>target-name</em><code>,</code>
<em>cross-reference-name</em><code>,</code>
<em>title-or-topic</em><code>,</code> <em>info-file-name</em><code>,</code>
<em>printed-manual-title</em><code>}</code> 

<p>produces:</p>

<p><code>*Note</code> <em>cross-reference-name</em><code>:</code>
<code>(</code><em>info-file-name</em><code>)</code><em>target-name</em></p>

<p>and</p>

<p><code>See section</code>
<code>"</code><em>title-or-topic</em><code>"</code> <code>in</code>
<em>printed-manual-title</em></p>
</dd>
</dl>

<h3><a name="inline markup">Inline Markup</a></h3>

<p>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.</p>

<ul>
<li><code>@emph{</code><em>text-in-italics</em><code>}</code> 

<p>Render <em>text-in-italics</em> in italics. Info approximates italicization
with underscores that bracket <em>text-in-italics</em>.</p>

<p>Example:</p>

<pre>
    Use tex(1), @emph{not} latex(1) to process
    your Texinfo files.
</pre>
</li>

<li><code>@strong{</code><em>bold-text</em><code>}</code> 

<p>Render <em>bold-text</em> in boldface. Info approximates boldface with
asterisks that bracket <em>bold-text</em>.</p>

<p>Example:</p>

<pre>
    Info files @strong{cannot} contain high
    resolution graphics.
</pre>
</li>

<li><code>@file{</code><em>filename</em><code>}</code> 

<p>Make <em>filename</em> stand out by surrounding it with single quotes, like
<code>`filename'</code>. The printer version typesets <em>filename</em> in
typewriter font.</p>

<p>Example:</p>

<pre>
    Ensure the latest version of
    @file{texinfo.tex} is installed on your Linux box.
</pre>
</li>

<li><code>@url{</code><em>universal-resource-locator</em><code>}</code> 

<p>Identify a universal resource locator (URL). The online version will show
angle brackets around <em>universal-resource-locator</em>. The printed version
does not add angle brackets, but typesets <em>universal-resource-locator</em>
in typewriter font.</p>

<p>Example:</p>

<pre>
    More information on Texinfo can be
    found at @url{<a href="http://texinfo.org/">http://texinfo.org/</a>}.
</pre>
</li>

<li><code>@code{</code><em>program-code</em><code>}</code> 

<p>Mark up short pieces of program code.</p>

<pre>
    Prefer the two-argument form of
    @code{bless}, this is, always write
    @code{bless $objref, $class}.
</pre>
</li>

<li><code>@samp{</code><em>literal-text</em><code>}</code> 

<p>Mark up literal characters, literal text, symbol names, and so on.</p>

<pre>
    Angle brackets (@samp{&lt;}, @samp{&gt;}) are the
    main delimiters used in HTML.
</pre>
</li>

<li><code>@var{</code><em>replaceable-item</em><code>}</code> 

<p>Mark up meta-syntactic variables, the famous <code>foo</code> and
<code>bar</code>.</p>

<pre>
    The Perl command @code{bless} is best called
    with two arguments, like @code{bless
    @var{object_reference}, @var{classname}}.
</pre>
</li>

<li><code>@kbd{</code><em>keystrokes</em><code>}</code> 

<p>Mark up a single keystroke or a series of keystrokes.</p>

<pre>
    Within emacs, type @kbd{C-h i} to start the
    built-in Info browser, or type @kbd{M-x
    info}.
</pre>
</li>

<li><code>@command{</code><em>command-name</em><code>}</code> 

<p>Mark up a command name.</p>

<pre>
    The two most important shell commands are
    @command{ls} and @command{cd}.
</pre>
</li>

<li><code>@option{</code><em>option-name</em><code>}</code> 

<p>Mark up an option name. Use <code>@option</code> in running text like</p>

<pre>
    Option @option{--html} forces
    @command{makeinfo} to generate HTML output
    instead of Info.
</pre>

<p><code>@option</code> is not suited for marking up a command's synopsis. To
mark up a synopsis use the <code>@example</code>-environment. Say</p>

<pre>
    @example
        makeinfo --html --output=@var{output-filename} @var{input-filename}
    @end example
</pre>

<p>and refer to the options in the running text with
<code>@option{--html}</code> and <code>@option{--output}</code>, as well as to
the arguments <code>@var{output-filename}</code> and
<code>@var{input-filename}</code>.</p>
</li>
</ul>

<h3><a name="tools">Tools</a></h3>

<dl>
<dt><strong><a name="item_makeinfo">makeinfo</a></strong><br>
</dt>

<dd>makeinfo transforms Texinfo files&nbsp;(<em>.texi</em>) into 

<ol>
<li>Info 

<p>By default, makeinfo generates Info files with the filename selected by
<code>@setfilename</code>. Option&nbsp;<code>--no-split</code> prevents
makeinfo from breaking the output in chunks (approximately 50KB in size).</p>

<p>Processing a Texinfo file with makeinfo also thoroughly validates the input
file.</p>
</li>

<li>Plain ASCII 

<p>Option&nbsp;<code>--no-headers</code> 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).</p>
</li>
</ol>
</dd>

<dt><strong><a name="item_texi2html">texi2html</a></strong><br>
</dt>

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

<p>texi2html by default converts <code>@iftex</code>&nbsp;sections and not
<code>@ifinfo</code> ones. You can reverse this behavior with the
<code>-expandinfo</code>&nbsp;option.</p>

<p>Note that all of texi2html's options start with a single dash.</p>
</dd>

<dt><strong><a name="item_texi2dvi">texi2dvi</a></strong><br>
</dt>

<dd>Produce a device independent file&nbsp;<em>.dvi</em> form Texinfo source.
To get Postscript, apply <code>dvips(1)</code> to the <em>.dvi</em>&nbsp;file.
I have found the options <code>--clean</code> and <code>--quiet</code> useful.
The first removes all intermediate files, leaving only the final
<em>.dvi</em>&nbsp;file. The second suppresses all non-essential messages
(``No gnews is good gnews!'').</dd>

<dt><strong><a name="item_texi2pdf">texi2pdf</a></strong><br>
</dt>

<dd>texi2pdf makes a Portable Document File&nbsp;(<em>.pdf</em>) from Texinfo
source in one shot. It accepts the same options as texi2dvi does. However, I
found, it definitely wants to see option&nbsp;<code>--pdf</code> or it stops,
crying for a <em>.dvi</em>&nbsp;file even if this very file exists. Argh! So,
my typical calls are 

<pre>
    texi2pdf --quiet --clean --pdf foobar.texi
</pre>
</dd>
</dl>

<h3><a name="browsers">Browsers</a></h3>

<p>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!</p>

<dl>
<dt><strong><a name="item_info">info</a></strong><br>
</dt>

<dd>
<p><code>info</code>, the mother of all Info browsers, is a simple but
efficient browser for <a href="misc/spiel/info-screenshot.png">viewing Info
files</a> at a console.</p>

<p>To view the Info pages of <em>topic</em>, use</p>

<pre>
    info topic
</pre>

<p>To browse Info file&nbsp;<em>info-file</em>, add
<code>--file=</code><em>info-file</em> to the invocation of info, where
<em>info-file</em> contains the complete path to the Info file.</p>

<p>If you would like to start browsing at specific
node&nbsp;<em>node-name</em>, add <code>--node=</code><em>node-name</em>.</p>

<p>My favorite mistake is mixing up <em>topic</em> with <em>info-file</em>,
this is saying</p>

<pre>
    info ./cache-profiler.info
</pre>

<p>when I really mean</p>

<pre>
    info --file=./cache-profiler.info
</pre>
</dd>

<dt><strong><a name="item_pinfo">pinfo</a></strong><br>
</dt>

<dd>
<p>pinfo is a <code>curses(3)</code> based Info browser with
<code>lynx(1)</code> like navigation. pinfo does a <a href= 
"misc/spiel/pinfo-screenshot.png">nice job colorizing</a> Info pages.</p>
</dd>

<dt><strong><a name="item_emacs">emacs</a></strong><br>
</dt>

<dd>
<p>Emacs version 21.x features an improved Info browsing mode as proves this
<a href="misc/spiel/emacs-screenshot.png">screen shot</a>.</p>

<blockquote><em>I know, it's only Emacs Info, but I like it, like it! Yes, I
do!</em></blockquote>

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

<p>For additional browsing pleasure, try
<code>Info-speedbar-browser</code>.</p>
</dd>

<dt><strong><a name="item_xinfo">xinfo</a></strong><br>
</dt>

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

<p>Here is a <a href="misc/spiel/xinfo-screenshot.png">screen shot</a>.</p>
</dd>

<dt><strong><a name="item_tkinfo">tkinfo</a></strong><br>
</dt>

<dd>
<p>My favorite X-based Info browser! It has all the nice features of
<code>info(1)</code>, starts up fast and has a <a href= 
"misc/spiel/tkinfo-screenshot.png">compact layout</a>.</p>
</dd>

<dt><strong><a name=
"item_gnome%2Dhelp%2Dbrowser">gnome-help-browser</a></strong><br>
</dt>

<dd>
<p>If you are a Gnome user, you probably know the
<code>gnome-help-browser(1x)</code>. It <a href=
"misc/spiel/ghb-screenshot.png">displays Info pages</a>, too.</p>
</dd>

<dt><strong><a name="item_kdehelp">kdehelp</a></strong><br>
</dt>

<dd>
<p>Same for KDE users... You probably know <code>kdehelp(1x)</code>. Amongst
various other formats it also <a href=
"misc/spiel/kdehelp-screenshot.png">displays Info pages</a>.</p>

<p>kdehelp is easily convinced to browse a specific Info file:</p>

<pre>
    kdehelp ./cache-profiler.info
</pre>

<p>Thumbs up!</p>

<p><CODE>konqueror</CODE> also displays info files (at least konqueror 2.2.2);
just type "info:" in the Location: bar.</p>  
</dd>
</dl>

<H4>Overview of Common Info Browsers</H4>

<center>
<table border="1" summary="Overview of important features of some common Info 
browsers.">
<caption align="left">Overview of Common Info Browsers. Multi-format browser
accept other formats than Info. X11-based browsers require X11 to run.
<code>info</code>-like navigation duplicates the navigation commands of
<code>info(1)</code>.</caption>

<tr>
<th scope="col">Application</th>
<th scope="col">Multi-format</th>
<th scope="col">X11-based</th>
<th scope="col"><code>info</code> Navigation</th>
</tr>

<tr>
<td><code>info</code></td>
<td align="center">no</td>
<td align="center">no</td>
<td align="center">yes</td>
</tr>

<tr>
<td><code>pinfo</code></td>
<td align="center">no</td>
<td align="center">no</td>
<td align="center">no</td>
</tr>

<tr>
<td><code>emacs</code></td>
<td align="center">no</td>
<td align="center">no</td>
<td align="center">yes</td>
</tr>

<tr>
<td><code>xinfo</code></td>
<td align="center">no</td>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>

<tr>
<td><code>tkinfo</code></td>
<td align="center">no</td>
<td align="center">yes</td>
<td align="center">yes</td>
</tr>

<tr>
<td><code>gnome-help-browser</code></td>
<td align="center">yes</td>
<td align="center">yes</td>
<td align="center">no</td>
</tr>

<tr>
<td><code>kdehelp</code></td>
<td align="center">yes</td>
<td align="center">yes</td>
<td align="center">no</td>
</tr>
</table>
</center>

<h2><a name="pros and cons">Pros and Cons</a></h2>

<dl>
<dt><strong><a name="item_Pros">Pros</a></strong><br>
</dt>

<dd>
<ul>
<li>Texinfo format: user definable macros (not shown in this article)</li>

<li>TeX output: perfect typesetting, fantastic hardcopy quality</li>

<li>Info format: alternative to ubiquitous HTML</li>

<li>Info browsers: uniform, fast and easy navigation</li>
</ul>
</dd>

<dt><strong><a name="item_Cons">Cons</a></strong><br>
</dt>

<dd>
<ul>
<li>Texinfo source format: 

<ul>
<li>4-argument nodes difficult to maintain without emacs(1). (In this article,
I have not shown the 4-argument form, but introduced the simplified 1-argument
form of nodes.)</li>

<li>1-argument nodes plus sectioning commands more difficult than
necessary</li>
</ul>
</li>

<li>Info format: Info is rendered statically, this is, browsers do not refill
paragraphs if the line width in a browser is different from the linewidth when
the Info page was generated. HTML browsers usually handle this automatic
refilling.</li>
</ul>
</dd>
</dl>

<h2><a name="further reading">Further Reading</a></h2>

<p>The home page of Texinfo, with lots of references and all that,
is located at <a
href="http://texinfo.org/">http://texinfo.org/</a></p>

<p>Available converters for Texinfo are listed at <a href= 
"http://www.fido.de/kama/texinfo/texinfo-en.html">http://www.fido.de/kama/texinfo/texinfo-en.html</a></p>





<!-- *** BEGIN bio *** -->
<SPACER TYPE="vertical" SIZE="30">
<P> 
<H4><IMG ALIGN=BOTTOM ALT="" SRC="../gx/note.gif">Christoph Spiel</H4>
<EM>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 
<A
HREF="mailto:cspiel@hammersmith-consulting.com">cspiel@hammersmith-consulting.com</A>.</EM>

<!-- *** END bio *** -->

<!-- *** BEGIN copyright *** -->
<P> <hr> <!-- P --> 
<H5 ALIGN=center>

Copyright &copy; 2002, Christoph Spiel.<BR>
Copying license <A HREF="../copying.html">http://www.linuxgazette.com/copying.html</A><BR> 
Published in Issue 76 of <i>Linux Gazette</i>, March 2002</H5>
<!-- *** END copyright *** -->

<!--startcut ==========================================================-->
<HR><P>
<CENTER>
<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="rogers.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="lg_toc76.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue76/spiel.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><A HREF="../lg_faq.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="vermeer.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
</CENTER>
</BODY></HTML>
<!--endcut ============================================================-->