1311 lines
42 KiB
HTML
1311 lines
42 KiB
HTML
<!--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="index.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="../faq/index.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 <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 <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 <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 <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> <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" by 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 <code>@afourpaper</code> and
|
|
<code>@afourwide</code> adjust the printable area for sheets of size
|
|
DIN 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 even</code> 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> 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> <em>node-name</em> commands, whereas the printed
|
|
structure is given -- among others -- with the
|
|
commands <code>@chapter</code> <em>chapter-title</em>,
|
|
<code>@section</code> <em>section-title</em>, and
|
|
<code>@subsection</code> <em>subsection-title</em>. The
|
|
<code>@node</code> 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 <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 ``<code>.</code>'', commas ``<code>,</code>'',
|
|
colons ``<code>:</code>'', and apostrophes ``<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 Nodes and the latter a Menu Nodes.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Terminal_Node">Terminal Node</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>The structure of a Terminal 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 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 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.</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 ``<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> 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 (``<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 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 <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> 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 <a><code>@page</code></a> right before
|
|
<code>@end 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 <code>@ifinfo</code>/<code>@end 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 <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 <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 <a>Inline 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> command or <code>@itemx</code> 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{<}, @samp{>}) 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 (<em>.texi</em>) into
|
|
|
|
<ol>
|
|
<li>Info
|
|
|
|
<p>By default, makeinfo generates Info files with the filename selected by
|
|
<code>@setfilename</code>. Option <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 <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 <code>-monolithic</code> forces the output of a
|
|
single file. Option <code>-split</code> on the other hand forces one file
|
|
per node.
|
|
|
|
<p>texi2html by default converts <code>@iftex</code> sections and not
|
|
<code>@ifinfo</code> ones. You can reverse this behavior with the
|
|
<code>-expandinfo</code> 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 <em>.dvi</em> form Texinfo source.
|
|
To get Postscript, apply <code>dvips(1)</code> to the <em>.dvi</em> 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> 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 (<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 <code>--pdf</code> or it stops,
|
|
crying for a <em>.dvi</em> 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 <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 <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> 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 © 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="index.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="../faq/index.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 ============================================================-->
|