1086 lines
37 KiB
HTML
1086 lines
37 KiB
HTML
<!--startcut ==============================================-->
|
|
<!-- *** BEGIN HTML header *** -->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
|
<HTML><HEAD>
|
|
<title>Writing Documentation, Part II: LaTeX with latex2html LG #74</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="qubism.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/issue74/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="tougher.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 II: LaTeX with latex2html</font></H1>
|
|
<H4>By <a href="mailto:cspiel@hammersmith-consulting.com">Christoph Spiel</a></H4>
|
|
</center>
|
|
<P> <HR> <P>
|
|
|
|
<!-- END header -->
|
|
|
|
|
|
|
|
|
|
<h3><a name="latex">LaTeX</a></h3>
|
|
|
|
<p>Let me first define what LaTeX is and what its primary goals are. LaTeX is
|
|
a huge add-on macro package for the TeX typesetting system developed by
|
|
Prof. Donald E. Knuth. If we are not overly picky, we mean
|
|
``TeX plus all LaTeX macros'' when we say ``LaTeX system'' or just ``LaTeX''.
|
|
LaTeX itself was written by Leslie Lamport, who found TeX to be very powerful,
|
|
but too difficult for everyday use. Therefore he modeled LaTeX after the
|
|
Scribe system. Scribe puts its emphasis on the logical structure of a document
|
|
instead of the physical markup. (For those readers proficient in HTML
|
|
tag <code><em></code> is an example logical markup and tab
|
|
<code><i></code> is the corresponding physical markup.)</p>
|
|
|
|
<p>LaTeX -- as plain TeX -- allows a normal computer user to
|
|
typeset documents with production-ready quality. It has been intended that a
|
|
LaTeX author prepares articles or even books on her local computer, then walk
|
|
over to the printer shop with a diskette to have the document printed on a
|
|
high-resolution phototypesetter, and finally have it bound as a book (...
|
|
shipped off the book to all bookstores in the alpha-quadrant, make millions
|
|
from it, and two years later win the Intergalactic Pulitzer Prize. -- OK, this
|
|
is a bit of a stretch).</p>
|
|
|
|
<p>In the next sections I will introduce very briefly to LaTeX, but I would
|
|
like to recommend the <em>Not So Short Introduction to LaTeX</em> to everyone
|
|
who wants to learn LaTeX. The 95-pages document is available for free on the
|
|
Net. Please see ``<a href="#further reading">Further Reading</a>'' for
|
|
details.</p>
|
|
|
|
<p>LaTeX gets installed by most current Linux distributions. You can check
|
|
whether it is available on your machine by asking</p>
|
|
|
|
<pre>
|
|
latex --version
|
|
</pre>
|
|
|
|
<p>at the command line. My system responds with</p>
|
|
|
|
<pre>
|
|
TeX (Web2C 7.3.1) 3.14159
|
|
kpathsea version 3.3.1
|
|
Copyright (C) 1999 D.E. Knuth.
|
|
Kpathsea is copyright (C) 1999 Free Software Foundation, Inc.
|
|
There is NO warranty. Redistribution of this software is
|
|
covered by the terms of both the TeX copyright and
|
|
the GNU General Public License.
|
|
For more information about these matters, see the files
|
|
named COPYING and the TeX source.
|
|
Primary author of TeX: D.E. Knuth.
|
|
Kpathsea written by Karl Berry and others.
|
|
</pre>
|
|
|
|
<h4><a name="overall document structure">Overall Document Structure</a></h4>
|
|
|
|
<p>Here is an example of a very short, yet complete LaTeX document:</p>
|
|
|
|
<pre>
|
|
\documentclass{article}
|
|
% preamble
|
|
</pre>
|
|
|
|
<pre>
|
|
\pagestyle{empty}
|
|
</pre>
|
|
|
|
<pre>
|
|
\begin{document}
|
|
% body
|
|
Here comes the text.
|
|
\end{document}
|
|
</pre>
|
|
|
|
<p>Every LaTeX document consists of a preamble and a body. The preamble
|
|
reaches from the definition of the document's class, <code>
|
|
\documentclass[</code><em>options</em><code>]</code>{<em>class</em><code>}</code>,
|
|
up to, but excluding <code>\begin{document}</code>. The body is everything
|
|
from <code>\begin{document}</code> to <code>\end{document}</code>.</p>
|
|
|
|
<p>The preamble in the example features only one command, <code>
|
|
\pagestyle{empty}</code>, which instructs LaTeX to omit all page decorations
|
|
such as running heads or page numbers. The percent signs introduce comments
|
|
that extend to the ends of the respective lines.</p>
|
|
|
|
<h4><a name="syntax">Syntax</a></h4>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Paragraphs">Paragraphs</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Paragraphs are separated by one or more blank lines. The number of blank
|
|
lines does not influence the output; one is as good as many. The same holds
|
|
true for spaces (which separate words, but didn't you know that?): one hundred
|
|
spaces produce the same output as a single space. Newlines, this is
|
|
line-terminators, are counted as spaces, so are tabulator characters.
|
|
|
|
<p>If we apply these simple rules to the three different versions of two
|
|
paragraphs that follow, we conclude that they all will be typeset the same. I
|
|
have added line numbers at the beginning of each line to point out empty
|
|
lines, which separate the paragraphs. The numbers are not part of the
|
|
text.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Version_A">Version A</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
1 I am a short sentence in the first paragraph.
|
|
2
|
|
3 I'm the only sentence in the second paragraph.
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Version_B">Version B</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
1 I am a short sentence
|
|
2 in the first paragraph.
|
|
3
|
|
4 I'm the
|
|
5 only sentence
|
|
6 in the second
|
|
7 paragraph.
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Version_C">Version C</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
1 I am a short sentence in the first paragraph.
|
|
2
|
|
3
|
|
4 I'm the only sentence
|
|
5 in the
|
|
6 second paragraph.
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Special_Characters">Special
|
|
Characters</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Most non-alphanumeric characters carry a special meaning inside LaTeX.
|
|
This is one of the features that appalls LaTeX beginners. However, after some
|
|
time, the user is alert of their particular behavior.
|
|
|
|
<p>I have collected the few most important special characters along with the
|
|
ways how to insert them literally into a text.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_%5C">\</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Introduce a command, like ``<code>\dots</code>'' or ``<code>\/</code>''.
|
|
|
|
<p>Note that ``<code>\\</code>'' does not insert a single backslash character
|
|
into the text as many C-programmers might assume right now. The control
|
|
sequence ``<code>\\</code>'' inserts a line break, whereas a literal
|
|
backslash is produced by ``<code>$\backslash$</code>''. To maximize the
|
|
confusion, ``<code>\ </code> ''--this is a backslash followed by a blank
|
|
space--is a command, too! It inserts a so-called control space, a space (more
|
|
precisely: exactly one space) that is never eaten up like ordinary spaces as
|
|
explained in section <a href="#item_paragraphs">``Paragraphs''</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_%7B%7D">{}</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Group arguments together.
|
|
|
|
<p>You get literal curly braces by quoting them with a backslash like this
|
|
``<code>\{</code>'' and ``<code>\}</code>''.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_%25">%</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Start a comment that reaches to the end of the line.
|
|
|
|
<p>Comments extend up to and include the newline character at the end of a
|
|
line. Thus LaTeX comments differ from one-line comments in all general
|
|
programming languages, as those exclude the newline character. For the user
|
|
this means, he can mask a newline by ending a line with a comment.</p>
|
|
|
|
<pre>
|
|
Hessenberg-%
|
|
Triangular % <- note space directly in front of the %-sign
|
|
Reduction
|
|
</pre>
|
|
|
|
<p>is equivalent to</p>
|
|
|
|
<pre>
|
|
Hessenberg-Triangular Reduction
|
|
</pre>
|
|
|
|
<p>To typeset a literal percent sign, use ``<code>\%</code>''.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_%7E">~</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Make an unbreakable space, like ``&nbsp;'' in HTML.</dd>
|
|
|
|
<dt><strong><a name="item_%24math%24">$<em>math</em>$</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Switch to math mode and back.
|
|
|
|
<p>The sequence <em>math</em> is typeset inline in mathematical
|
|
typesetting mode. To get a literal dollar sign, use ``<code>\$</code>''.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The following table summarizes all ASCII characters that are treated
|
|
specially by LaTeX. The rightmost column of the table suggests one or
|
|
more possible equivalent sequences to get the plain ASCII character into
|
|
the text. As can be guessed from the entries for caret and twiddle,
|
|
<code>\char</code><em>code_number</em> inserts the ASCII character with
|
|
the decimal index <em>code_number</em> into a document.</p>
|
|
|
|
<BLOCKQUOTE>
|
|
<CITE>
|
|
ASCII characters that are special for LaTeX. The right column
|
|
denotes the strings (in LaTeX) which produce the ASCII
|
|
characters in the middle column.
|
|
</CITE>
|
|
</BLOCKQUOTE>
|
|
|
|
<table align="center" border="1" summary="The table provides a
|
|
conversion from ASCII characters to LaTeX.">
|
|
|
|
<tr align="center">
|
|
<th>Name</th>
|
|
<th>ASCII</th>
|
|
<th>LaTeX</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>sharp</td>
|
|
<td><code>#</code></td>
|
|
<td><code>\#</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>dollar</td>
|
|
<td><code>$</code></td>
|
|
<td><code>\$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>percent</td>
|
|
<td><code>%</code></td>
|
|
<td><code>\%</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>ampersand</td>
|
|
<td><code>&</code></td>
|
|
<td><code>\&</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>multiplication sign</td>
|
|
<td><code>*</code></td>
|
|
<td><code>*</code> or <code>$*$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>minus sign</td>
|
|
<td><code>-</code></td>
|
|
<td><code>$-$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>less-than sign</td>
|
|
<td><code><</code></td>
|
|
<td><code>$<$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>greater-than sign</td>
|
|
<td><code>></code></td>
|
|
<td><code>$>$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>backslash</td>
|
|
<td><code>\</code></td>
|
|
<td><code>$\backslash$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>caret</td>
|
|
<td><code>^</code></td>
|
|
<td><code>\char94</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>underscore</td>
|
|
<td><code>_</code></td>
|
|
<td><code>\_</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>curly braces</td>
|
|
<td><code>{</code>, <code>}</code></td>
|
|
<td><code>\{</code>, <code>\}</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>vertical bar</td>
|
|
<td><code>|</code></td>
|
|
<td><code>$|$</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>twiddle</td>
|
|
<td><code>~</code></td>
|
|
<td><code>\char126</code></td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Commands">Commands</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>LaTeX commands usually start with a backslash
|
|
character ``<code>\</code>'' and either extend from the backslash to the
|
|
next non-letter character (kind 1) or consist of exactly one
|
|
non-alphanumeric character (kind 2). So ``<code>\raggedleft</code>'' and
|
|
``<code>\makebox</code>'' are commands of kind 1 whereas
|
|
``<code>\\</code>'' and ``<code>\"</code>'' are commands of kind 2.
|
|
Arguments are passed to commands within curly braces ``{'', ``}''.
|
|
Empty arguments can be omitted.
|
|
|
|
<p>Examples:</p>
|
|
|
|
<pre>
|
|
\raggedleft{} % no argument
|
|
\raggedleft % same as above
|
|
</pre>
|
|
|
|
<pre>
|
|
\makebox{Text inside of a box.} % single argument
|
|
</pre>
|
|
|
|
<pre>
|
|
\parbox{160pt}{This text is
|
|
typeset inside of a box.} % two arguments
|
|
</pre>
|
|
|
|
<p>The number of arguments passed to a command is fixed. However, some
|
|
commands accept optional parameters. These are passed within square brackets
|
|
(``<code>[</code>'', ``<code>]</code>'') and usually precede the arguments
|
|
just as the options precede the arguments in most UN*X utility programs.</p>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre>
|
|
\parbox[t]{10cm}{I am a top-aligned
|
|
paragraph.} % one option, two arguments
|
|
</pre>
|
|
|
|
<p>Here <code>t</code> is the optional parameter.</p>
|
|
|
|
<p>Spaces that follow a type 1 command name without arguments (like the
|
|
second ``<code>\raggedleft</code>'' above) are ``eaten''; they are not passed
|
|
on to the output.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Environments">Environments</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Environments are pairs in the form
|
|
|
|
<p><code>\begin{</code><em>environment</em><code>}</code></p>
|
|
|
|
<p><em>Text within the environment.</em></p>
|
|
|
|
<p><code>\end{</code><em>environment</em><code>}</code></p>
|
|
|
|
<p>An environment changes the appearance of the text within it. Environments
|
|
control the alignment, the width of the margins and many other things. Some
|
|
predefined environments are: <code>center</code>, <code>description</code>,
|
|
<code>enumerate</code>, <code>flushleft</code>, <code>flushright</code>,
|
|
<code>itemize</code>, <code>list</code>, <code>minipage</code>, <code>
|
|
quotation</code>, <code>quote</code>, <code>tabbing</code>, <code>
|
|
table</code>, <code>tabular</code>, <code>verbatim</code>, and <code>
|
|
verse</code>.</p>
|
|
|
|
<p>Environments do nest. For example, to get a quotation typeset flush against
|
|
the right margin, use the <code>flushright</code> environment and the <code>
|
|
quotation</code> environment.</p>
|
|
|
|
<pre>
|
|
\begin{flushright}
|
|
\begin{quotation}
|
|
Letters are things, \\
|
|
not pictures of things. \\
|
|
-- Eric Gill
|
|
\end{quotation}
|
|
\end{flushright}
|
|
</pre>
|
|
|
|
<p>An environment only affects text inside of it; it encapsulates all changes,
|
|
like a different indentation occurring within the environment. (Well -- unless
|
|
you happen to change a global variable, but I won't tell you how to do that,
|
|
so you're safe.)</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="sectioning">Sectioning</a></h4>
|
|
|
|
<p>LaTeX knows three or four heading levels depending on the <em>
|
|
documentclass</em>. Class <code>article</code> has three section levels,
|
|
whereas classes <code>book</code> and <code>report</code> feature
|
|
chapters as a fourth and topmost heading level.</p>
|
|
|
|
<p><code>\chapter{</code><em>heading</em><code>}</code> % only for class
|
|
<code>book</code> and <code>report</code></p>
|
|
|
|
<p><code>\section{</code><em>heading</em><code>}</code></p>
|
|
|
|
<p><code>\subsection{</code><em>heading</em><code>}</code></p>
|
|
|
|
<p><code>\subsubsection{</code><em>heading</em><code>}</code></p>
|
|
|
|
<p>Note that as in POD, discussed in <a href=
|
|
"http://www.linuxgazette.com/issue73/spiel.html">Part I</a>, sectioning
|
|
commands act as separators. They do not group together text with a start
|
|
marker and an end marker, but their mere appearance groups the text. This will
|
|
be different in DocBook, as I shall show in next month's article.</p>
|
|
|
|
<h4><a name="lists">Lists</a></h4>
|
|
|
|
<p>LaTeX ships with three kinds of list-generating environments:</p>
|
|
|
|
<ul>
|
|
<li>itemized lists (sometimes also called ``bulleted lists''),</li>
|
|
|
|
<li>enumerated lists, and</li>
|
|
|
|
<li>description lists.</li>
|
|
</ul>
|
|
|
|
<p>They correspond to unnumbered lists, numbered lists, and definition lists
|
|
in HTML, or <code>=item *</code>, <code>=item 1</code>, <code>
|
|
=item</code> <em>term</em> lists in POD.</p>
|
|
|
|
<p>The items themselves are introduced with ``<code>\item</code>''. An item
|
|
can consist of more than one paragraph.</p>
|
|
|
|
<p>For description lists the optional parameter given to
|
|
``<code>\item</code>'' as in
|
|
``<code>\item[</code><em>term</em><code>]</code>'' specifies the <em>
|
|
term</em>. The text following
|
|
``<code>\item[</code><em>term</em><code>]</code>'' is <em>term</em>'s
|
|
definition.</p>
|
|
|
|
<p>Examples:</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Itemized_List">Itemized List</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
What emacs can do for you:
|
|
\begin{itemize}
|
|
\item Cut and paste blocks of text
|
|
\item Fill or justify paragraphs
|
|
\item Spell check documents
|
|
\end{itemize}
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Enumerated_List">Enumerated List</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
Starting emacs for the first time
|
|
\begin{enumerate}
|
|
\item Start emacs from the command line:
|
|
</pre>
|
|
|
|
<pre>
|
|
\texttt{\$ emacs}
|
|
</pre>
|
|
|
|
<pre>
|
|
emacs will show you its startup screen and soon switch to a
|
|
buffer called \texttt{*scratch*}.
|
|
</pre>
|
|
|
|
<pre>
|
|
\item Hold down the Control~key and press~H. You see a prompt
|
|
at the bottom of the screen (or emacs window).
|
|
</pre>
|
|
|
|
<pre>
|
|
\texttt{C-h (Type ? for further options)-}
|
|
</pre>
|
|
|
|
<pre>
|
|
\item Press~T to start the emacs tutorial.
|
|
\end{enumerate}
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Description_List">Description List</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
Some emacs commands:
|
|
\begin{description}
|
|
\item[C-x C-c] Quit emacs.
|
|
\item[C-x f] Open a file.
|
|
\item[C-x r k]
|
|
Kill rectangle defined by mark and point, this is, by the
|
|
active region.
|
|
\end{description}
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="crossreferences">Cross-References</a></h4>
|
|
|
|
<p>All cross references need two parts: a pointer (the link) and a pointee
|
|
(the anchor). Anchors in LaTeX are inserted with <code>
|
|
\label{</code><em>anchor-name</em><code>}</code>. Every anchor is located in a
|
|
particular section and on a particular page. These two pieces of information
|
|
are retrieved with <code>\ref{</code><em>anchor-name</em><code>}</code> and
|
|
<code>\pageref{</code><em>anchor-name</em><code>}</code> at any place in the
|
|
document.</p>
|
|
|
|
<p>Example use of <code>\ref</code>:</p>
|
|
|
|
<pre>
|
|
\section{Setup}\label{section:setup}
|
|
...
|
|
</pre>
|
|
|
|
<pre>
|
|
\section{Summary}\label{section:summary}
|
|
As has been pointed out in section~\ref{section:setup} `Setup', ...
|
|
</pre>
|
|
|
|
<p>Example use of <code>\pageref</code>:</p>
|
|
|
|
<pre>
|
|
\section{Setup}\label{section:setup}
|
|
The steel used in the sample chamber is alloyed with Ti (0.5\%),
|
|
Cr (0.1\%), and Mn (0.1\%).\label{definition:chamber-alloy}
|
|
</pre>
|
|
|
|
<pre>
|
|
\section{Experiments}\label{section:experiments}
|
|
For sample chamber is made of stainless steel (see
|
|
page~\pageref{definition:chamber-alloy} for the exact
|
|
metallurgical composition), ...
|
|
</pre>
|
|
|
|
<h4><a name="defining your own commands and environments">Defining Your Own
|
|
Commands and Environments</a></h4>
|
|
|
|
<p>One of the major advantages of the LaTeX typesetting system is to allow the
|
|
user to define her own commands and environments. Say you want to mark up all
|
|
replaceable parameters in the description of a UN*X utility, like in</p>
|
|
|
|
<pre>
|
|
cd directory
|
|
</pre>
|
|
|
|
<p>to be rendered as, for example,</p>
|
|
|
|
<p><strong>cd</strong> <em>directory</em></p>
|
|
|
|
<p>Here, <code>cd</code> is the utility's name, and <code>directory</code> is
|
|
the replaceable parameter.</p>
|
|
|
|
<p>Often utility names are typeset in bold face, and replaceable parameters in
|
|
italics. Thus, a good solution would be to write</p>
|
|
|
|
<pre>
|
|
\utilityname{cd} \replaceable{directory}
|
|
</pre>
|
|
|
|
<p>where <code>\utilityname</code> and <code>\replaceable</code> switch fonts
|
|
to bold face and italics respectively. With the help of <code>
|
|
\utilityname</code> and <code>\replaceable</code> we can consistently mark up
|
|
further command lines:</p>
|
|
|
|
<pre>
|
|
\utilityname{pushd} \replaceable{directory}
|
|
\utilityname{ls} \replaceable{filename}
|
|
</pre>
|
|
|
|
<p>To define a new LaTeX command, use</p>
|
|
|
|
<p><code>
|
|
\newcommand{</code><em>command-name</em><code>}[</code><em>number-of-arguments</em><code>
|
|
]{</code><em>command-sequence</em><code>}</code></p>
|
|
|
|
<p>where <em>command-name</em> is the new command's name, <em>
|
|
number-of-arguments</em> is the number of arguments the new command takes (it
|
|
defaults to 0 if omitted), and <em>command-sequence</em> are the LaTeX
|
|
commands to execute when <em>command-name</em> is called.</p>
|
|
|
|
<p>For our example, define <code>\utilityname</code> and <code>
|
|
\replaceable</code> as:</p>
|
|
|
|
<pre>
|
|
\newcommand{\utilityname}[1]{\textbf{#1}}
|
|
\newcommand{\replaceable}[1]{\textit{#1}}
|
|
</pre>
|
|
|
|
<p>The predefined commands <code>\textbf</code> and <code>\textit</code>
|
|
switch fonts to text bold face (in contrary to math bold face) and text
|
|
italic. Arguments are referred to by <code>#</code><em>digit</em>, where <em>
|
|
digit</em> takes on values from 1 to 9.</p>
|
|
|
|
<p>To give you an impression of the usefulness of our newly defined commands,
|
|
suppose we would like to generate an index entry for each utility that is
|
|
mentioned in the text. Command <code>\index{</code><em>term</em><code>}</code>
|
|
puts <em>term</em> in the index. We only need to modify the definition of
|
|
<code>\utilityname</code> to</p>
|
|
|
|
<pre>
|
|
\newcommand{\utilityname}[1]{\textbf{#1}\index{#1}}
|
|
</pre>
|
|
|
|
<p>and are done. (For the curious: index levels are separated with vertical
|
|
bars. So, we probably would prefer <code>\index{utility|#1}</code> as it
|
|
neatly groups all utilities together. See the documentation of <strong>
|
|
makeindex</strong> for details.)</p>
|
|
|
|
<p>New environments are defined with</p>
|
|
|
|
<p><code>
|
|
\newenvironment{</code><em>environment-name</em><code>}[</code><em>number-of-arguments</em><code>
|
|
]{</code><em>starting-sequence</em><code>}{</code><em>ending-sequence</em><code>
|
|
}</code></p>
|
|
|
|
<p>the only difference being that <code>\newenvironment</code> requires two
|
|
command sequences: one to open the environment, <em>starting-sequence</em>,
|
|
and one to close it, <em>ending-sequence</em>. Continuing the example of a
|
|
quotation typeset flush left against the page's margin, we define our own own
|
|
quotation environment:</p>
|
|
|
|
<pre>
|
|
\newenvironment{myquotation}% Note: "%" masks newline
|
|
{\begin{flushright}\begin{quotation}}%
|
|
{\end{quotation}\end{flushright}}
|
|
</pre>
|
|
|
|
<p>which is then used like this:</p>
|
|
|
|
<pre>
|
|
\begin{myquotation}
|
|
Letters are things, \\
|
|
not pictures of things. \\
|
|
-- Eric Gill
|
|
\end{myquotation}
|
|
</pre>
|
|
|
|
<p>Neither commands, nor environments can be defined multiple times with
|
|
<code>\newcommand</code> or <code>\newenvironment</code>. These commands only
|
|
serve first time definition. Redefinitions are done with <code>
|
|
\renewcommand</code> and <code>\renewenvironment</code>, which take on the
|
|
same arguments as their first-time cousins.</p>
|
|
|
|
<h4><a name="inline markup">Inline Markup</a></h4>
|
|
|
|
<p>LaTeX offers an extremely rich set of inline markup. I restrict the
|
|
discussion to the same three inline markup changes which I discussed for
|
|
Perl's plain old documentation format: emphasis, italics, bold face, and
|
|
typewrite (code) font.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Emphasis_and_Italics">Emphasis and
|
|
Italics</a></strong><br>
|
|
</dt>
|
|
|
|
<dd><code>\textit{</code><em>argument</em><code>}</code> -- Typeset <em>
|
|
argument</em> in text italics.
|
|
|
|
<p><code>\emph{</code><em>argument</em><code>}</code> -- Emphasize <em>
|
|
argument</em>. The default configuration switches to and from italics
|
|
depending on the current font setting. If the current font is upright, <code>
|
|
\emph</code> uses italics; if the current font is italics, it uses an upright
|
|
font. This way the emphasized parts of text always stand out.</p>
|
|
|
|
<p>Why have <code>\textit</code> and at the same time <code>\emph</code>? The
|
|
commands express different requests. <code>\textit</code> unconditionally
|
|
demands the argument to be typeset using an italics font. Period.
|
|
<code>\emph</code> on the other hand asks for emphasizing its argument, however
|
|
the emphasizing may look like. The default uses an italics font as explained
|
|
above, but <code>\emph</code> can be redefined to use a bold font, underlining,
|
|
or anything else the writer imagines for her preferred method of emphasizing.
|
|
The command name <code>emph</code> always catches the concept of emphasis and
|
|
hides the implementation.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Bold_Face">Bold Face</a></strong><br>
|
|
</dt>
|
|
|
|
<dd><code>\textbf{</code><em>argument</em><code>}</code> -- Typeset <em>
|
|
argument</em> in text bold face.
|
|
|
|
<p>Based on <code>\textbf</code>, we can define our own logical markup
|
|
commands, like for example</p>
|
|
|
|
<pre>
|
|
\newcommand{\important}[1]{\textbf{#1}}
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Typewriter_Font">Typewriter Font</a></strong><br>
|
|
</dt>
|
|
|
|
<dd><code>\texttt{</code><em>argument</em><code>}</code> -- Typeset <em>
|
|
argument</em> in text typewriter font.
|
|
|
|
<p>As with <code>\textbf</code>, <code>\texttt</code> can be wrapped into
|
|
user-defined commands:</p>
|
|
|
|
<pre>
|
|
\newcommand{\sourcecode}[1]{\texttt{#1}}
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="latex tool chain">LaTeX Tool Chain</a></h4>
|
|
|
|
<p>LaTeX files usually carry the extension <em>tex</em>. LaTeX translates
|
|
these <em>tex</em>-files into so called device independent (<em>dvi</em>)
|
|
files. <em>dvi</em> files are a binary representation of the source. They can
|
|
be previewed to <strong>dvisvga</strong> on the console (given the terminal
|
|
supports high-resolution graphics), or, for example, <strong>xdvi</strong>
|
|
under the X11 windowing system. Often <em>dvi</em> files are converted to
|
|
Postscript with the <strong>dvips</strong> tool. If Portable Document Format
|
|
is desired, <strong>pdflatex</strong> transforms <em>tex</em> files into <em>
|
|
pdf</em> files in a single step.</p>
|
|
|
|
<h3><a name="latex2html">latex2html</a></h3>
|
|
|
|
<p>So far so good. LaTeX makes wonderfully looking Postscript documents, and
|
|
its <em>pdf</em> sibling does the same, but outputs Portable Document Format
|
|
files. Didn't we say we want HTML, too? Sure, we did! But LaTeX cannot help us
|
|
here; we need another tool: <strong>latex2html</strong>. This tool transforms
|
|
a LaTeX source file into a set of html files that are properly linked together
|
|
according to the source file's structure.</p>
|
|
|
|
<p>latex2html has a home page at <a href="http://www.latex2html.org">
|
|
http://www.latex2html.org</a> where it is available for download. It can also
|
|
be obtained from <a href="http://www.ctan.org">http://www.ctan.org</a> or
|
|
better one of its many mirrors. To see whether it is installed on your Linux
|
|
system, try</p>
|
|
|
|
<pre>
|
|
latex2html --version
|
|
</pre>
|
|
|
|
<p>and you should get an answer like</p>
|
|
|
|
<pre>
|
|
This is LaTeX2HTML Version 2K.1beta (1.57)
|
|
by Nikos Drakos, Computer Based Learning Unit, University of Leeds.
|
|
</pre>
|
|
|
|
<p>What do I have to change to make my LaTeX document translatable with
|
|
latex2html? -- Good news: almost nothing! Just ensure that the packages <code>
|
|
html</code> and <code>makeindex</code> are referenced in the document's
|
|
preamble, this is, at least add</p>
|
|
|
|
<pre>
|
|
\usepackage{html,makeidx}
|
|
</pre>
|
|
|
|
<p>to it. Now file <em>my_document.tex</em> can be translated to HTML
|
|
with the call</p>
|
|
|
|
<pre>
|
|
latex2html my_document.tex
|
|
</pre>
|
|
|
|
<h4><a name="references revisited">References Revisited</a></h4>
|
|
|
|
<p>latex2html takes care of almost all issues that arise when a LaTeX file is
|
|
translated into a set of html files. However, references to other parts in the
|
|
document or other documents are conceptually different in printed
|
|
documentation and HTML. Consider the LaTeX snippet</p>
|
|
|
|
<pre>
|
|
In the following, we summarize the findings
|
|
using a cylindrical coordinate system. See
|
|
page~\pageref{definition:coordinate-system}
|
|
for the definition of the coordinate system.
|
|
</pre>
|
|
|
|
<p>where LaTeX dutifully replaces <code>
|
|
\pageref{definition:coordinate-system}</code> with the page number on which
|
|
<code>\label{definition:coordinate-system}</code>, the anchor of the page
|
|
reference, occurs. Where is the problem? First, a set of html pages does not
|
|
have a rigid notion of a ``page number''. Second, latex2html does replace
|
|
<code>\pageref{definition:coordinate-system}</code> with a hyper-link to the
|
|
spot where <code>\label{definition:coordinate-system}</code> is rendered. The
|
|
link is a dark square for graphical browser or the marker ``<code>[*]</code>''
|
|
for text browsers. But the whole construct looks awkward -- almost distracting
|
|
and this is not latex2html's fault:</p>
|
|
|
|
<blockquote>In the following, we will summarize the findings using a
|
|
cylindrical coordinate system. See page <a href="#hyperreferences">
|
|
[*]</a> for the definition of the coordinate system.</blockquote>
|
|
|
|
<p>Latex2html needs our help! The paragraph, which contains the reference,
|
|
ought to be rephrased for the on-screen version, for example to:</p>
|
|
|
|
<pre>
|
|
In the following, we will summarize the
|
|
findings using a <a>cylindrical coordinate
|
|
system</a>.
|
|
</pre>
|
|
|
|
<p>where I have indicated the hyperlink with HTML anchor tags. To allow for
|
|
two different versions depending on the output format, latex2html defines the
|
|
<code>\hyperref</code> command.</p>
|
|
|
|
<p><code>\hyperref[</code><em>reference-type</em><code>]{</code><em>text for
|
|
html version</em><code>}{</code><em>pre-reference text for LaTeX
|
|
version</em><code>}{</code><em>post-reference text for LaTeX
|
|
version</em><code>}</code></p>
|
|
|
|
<p>The optional parameter <em>reference-type</em> selects the counter the
|
|
reference refers to:</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_%22ref%22">``<code>ref</code>''</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Cross reference to a section number like <code>\ref</code> does. The
|
|
reference text is the section number (``4'', ``1.5.2'', ``3.4.2.1'',
|
|
etc.).</dd>
|
|
|
|
<dt><strong><a name="item_%22page%22_or_%22pageref%22">``<code>page</code>''
|
|
or ``<code>pageref</code>''</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Reference to a page number like <code>\pageref</code> does. The reference
|
|
text is a page number (``25'', ``xxiii'', etc.).</dd>
|
|
</dl>
|
|
|
|
<p>Rewritten with <code>\hyperref</code> our example looks like this</p>
|
|
|
|
<pre>
|
|
In the following, we will summarize the
|
|
findings using a \hyperref[pageref]%
|
|
{cylindrical coordinate system}% for HTML
|
|
{cylindrical coordinate system. See page~}% for LaTeX
|
|
{ for the definition of the coordinate system}% trailing text for LaTeX
|
|
{definition:coordinate-system}.% label the reference refers to
|
|
</pre>
|
|
|
|
<p>LaTeX renders it to</p>
|
|
|
|
<blockquote>In the following, we will summarize the findings using a
|
|
cylindrical coordinate system. See page 97 for the definition of the
|
|
coordinate system.</blockquote>
|
|
|
|
<p>and latex2html produces</p>
|
|
|
|
<blockquote>In the following, we will summarize the findings using a <a href=
|
|
"#hyperreferences">cylindrical coordinate system</a>.</blockquote>
|
|
|
|
<p>from it.</p>
|
|
|
|
<h4><a name="hyperlinks">Hyperlinks</a></h4>
|
|
|
|
<p>A problem related to the one we have just encountered with references
|
|
happens when hyperlinks come into play. In the HTML version of the document
|
|
hyperlinks are essential; in the printed version, they are of little use:
|
|
Compare ``Click here'' with ``Press your pencil against this letter''?
|
|
Sometimes, however, the author really wants to include the target of the
|
|
hyperlink, an universal resource locator (URL), in the printed text.
|
|
latex2html defines two commands that exactly cater these needs.</p>
|
|
|
|
<p><code>\htmladdnormallink{</code><em>link
|
|
text</em><code>}{</code><em>universal resource locator</em><code>}</code></p>
|
|
|
|
<p><code>\htmladdnormallinkfoot{</code><em>link
|
|
text</em><code>}{</code><em>universal resource locator</em><code>}</code></p>
|
|
|
|
<p>Both commands generate the hyperlink <a href = "<em>universal resource
|
|
locator</em>"><em>link text</em></a> in the HTML version. The first
|
|
only renders <em>link text</em> in the LaTeX version, suppressing <em>
|
|
universal resource locator</em> completely. The second adds a footnote
|
|
containing <em>universal resource locator</em>. The typical usage of these
|
|
commands is</p>
|
|
|
|
<blockquote>The text of this article can be downloaded from our
|
|
\htmladdnormallink{web site}{http://www.linux-gazette.org}.</blockquote>
|
|
|
|
<p>and</p>
|
|
|
|
<blockquote>The text of this article can be downloaded from our
|
|
\htmladdnormallinkfoot{web site}{http://www.linux-gazette.org}.</blockquote>
|
|
|
|
<p>where the LaTeX result of the first looks like this</p>
|
|
|
|
<blockquote>The text of this article can be downloaded from our web
|
|
site.</blockquote>
|
|
|
|
<p>for the second <code>web site</code> gets a footnote marker and a footnote
|
|
with the URL is placed at the bottom of the page. The HTML output will show up
|
|
both times as</p>
|
|
|
|
<blockquote>The text of this article can be downloaded from our <a href=
|
|
"http://www.linux-gazette.org">web site</a>.</blockquote>
|
|
|
|
<h4><a name="format specific commands">Format Specific Commands</a></h4>
|
|
|
|
<p>As a last resort several commands and environments enable the writer to
|
|
divert her text between LaTeX and HTML versions of the document:</p>
|
|
|
|
<ul>
|
|
<li><code>\latex{</code><em>short text for LaTeX only</em><code>}</code></li>
|
|
|
|
<li><code>\html{</code><em>short text for HTML only</em><code>}</code></li>
|
|
|
|
<li><code>\latexhtml{</code><em>short text for LaTeX only</em> <code>
|
|
}{</code><em>short text for HTML only</em><code>}</code></li>
|
|
|
|
<li><code>\begin{latexonly}</code> <em>text for LaTeX only</em> <code>
|
|
\end{latexonly}</code></li>
|
|
|
|
<li><code>\begin{htmlonly}</code> <em>text for HTML only</em> <code>
|
|
\end{htmlonly}</code></li>
|
|
</ul>
|
|
|
|
<p>I recommend to use diversion of output only if no more specialized
|
|
latex2html command or environment can produce the desired markup, for
|
|
splitting always requires to keep both branches in sync.</p>
|
|
|
|
<h3><a name="pros and cons">latex2html Pros and Cons</a></h3>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Pros">Pros</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>Completely configurable through user-defined LaTeX commands and
|
|
environments</li>
|
|
|
|
<li>Extremely high-quality printed output</li>
|
|
|
|
<li>Handles tables and graphics (not shown in this article)</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Cons">Cons</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>``Impedance mismatch'' between LaTeX and HTML not completely compensated
|
|
by latex2html</li>
|
|
|
|
<li>Flat learning curve of LaTeX</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="further reading">Further Reading</a></h3>
|
|
|
|
<ul>
|
|
<li>Tobias Oetiker, Hubert Partl, Irene Hyna, and Elisabeth Schlegl, <em>The
|
|
Not So Short Introduction to LaTeX</em>. Search for <code>lshort</code> on
|
|
your local Linux system, or use the search facilities at
|
|
<A HREF="http://www.ctan.org/">www.ctan.org</A> for find
|
|
a mirror close to you.</li>
|
|
|
|
<li>Leslie Lamport, <em>LaTeX -- User's Guide and Reference Manual</em>,
|
|
Addison Wesley.</li>
|
|
|
|
<li>Donald E. Knuth, <em>The TeXbook</em>, Addison Wesley.</li>
|
|
|
|
<li>If you are lucky, your LaTeX comes bundled with a hypertext help pages,
|
|
<em>Hypertext Help with LaTeX</em>. My S.u.S.E. distribution has the entry
|
|
point installed at file:///usr/share/texmf/doc/latex/latex2e-html/ltx-2.html
|
|
|
|
<p>For a beginner the hypertext pages can neither replace the <em>Short
|
|
Introduction</em>, nor Lamport's book. For the intermediate LaTeX user,
|
|
however, they are a valuable help in case printed documentation is out of
|
|
reach.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Next month: DocBook</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 74 of <i>Linux Gazette</i>, January 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="qubism.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/issue74/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="tougher.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 ============================================================-->
|