848 lines
26 KiB
HTML
848 lines
26 KiB
HTML
<!--startcut ==============================================-->
|
|
<!-- *** BEGIN HTML header *** -->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
|
<HTML><HEAD>
|
|
<title>Writing Documentation - Part 1: POD LG #73</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="padala.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/issue73/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="zhaoway.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 1: POD</font></H1>
|
|
<H4>By <a href="mailto:cspiel@hydra.hammersmith-consulting.com">Christoph Spiel</a></H4>
|
|
</center>
|
|
<P> <HR> <P>
|
|
|
|
<!-- END header -->
|
|
|
|
|
|
|
|
|
|
<a name="writing documentation"></a>
|
|
|
|
<p>The title, <em>Writing Documentation</em>, sounds somewhat formal. However,
|
|
in this article I refer to documentation a broad sense, not only to
|
|
documentation accompanying a particular piece of software, but to any related
|
|
textual pieces of information. This textual information could be as short as a
|
|
few lines and, for example, describe how to to start a program with all of its
|
|
command line options and environment variables set correctly. On the other
|
|
hand, the text could be several tens of thousands lines long, elaborating all
|
|
the tricks a group of users has learned over the years while using a large
|
|
software system.</p>
|
|
|
|
<h2><a name="introduction">Introduction</a></h2>
|
|
|
|
<p>With today's GNU/Linux distributions, the aspiring documentation writer
|
|
immediately finds herself in fat city: there are several systems to chose from!
|
|
Three documentation systems will be introduced in this article series. Here, I
|
|
start with POD. Next month I'll address LaTeX in conjunction with <strong>
|
|
latex2html</strong>, and in part 3 DocBook.</p>
|
|
|
|
<p>The systems cater different documentation needs and all have their highs
|
|
and lows. But before assessing the pros and cons of the different systems, let
|
|
me put up some requirements, which I want to impose on the documentation
|
|
systems.</p>
|
|
|
|
<p>The sources of the documentation should be:</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Portable">Portable</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>As of December 2001, writing a "portable" file almost implies using
|
|
7-bit ASCII to encode characters. Today, 7-bit ASCII is the only
|
|
encoding that works on a huge number of computers. In the future, hopefully,
|
|
it will mean <a href="http://www.unicode.org/">Unicode</a>. Unicode can
|
|
represent many more characters than ASCII does and will be as portable.
|
|
|
|
<p>Requiring portability ensures that the texts' sources can be read and
|
|
modified on a wide variety of computer systems, thereby making the
|
|
documentation accessible to other programmers, which is what Open Source
|
|
Software is all about.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Searchable">Searchable</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Data on a computer is only as good as the access to it. -- Sounds like a
|
|
commonplace, but we easily forget that documentation ought to be maintained
|
|
just like source code is. We want to be able to search existing documentation
|
|
for, say, a particular term or identifier. Therefore, the source of the
|
|
documentation should at least be amenable to standard searching tools like,
|
|
for example, the grep family (<strong>grep</strong>, <strong>agrep</strong>,
|
|
<strong>rgrep</strong>, <strong>sgrep</strong>) of tools.</dd>
|
|
|
|
<dt><strong><a name="item_Modular">Modular</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Unless we write a short note, it is desirable that the document sources
|
|
can be split into logical parts, for example sections, and the collection of
|
|
all the source files is still processed as a whole by the documentation
|
|
system.</dd>
|
|
|
|
<dt><strong><a name="item_Easy_to_Read">Easy to Read</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>For documentation to be ``open'' (as in ``Open Source''), the source
|
|
should be easy to read, and the system to generate the final output should be
|
|
simple to learn. A documentation system will be better accepted if the writer
|
|
-- and later possibly the maintainer -- can concentrate on contents rather
|
|
than syntactic quirks or obscure tool chains.</dd>
|
|
</dl>
|
|
|
|
<p>Just as I require certain features in the documentation's source format, so I do
|
|
with the output.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Multiple_Output_Formats">Multiple Output
|
|
Formats</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>The documentation system must be capable of producing different output
|
|
formats -- the more formats the better. At least HTML and PostScript (some
|
|
users prefer PDF) must be supported, one for on-screen reading, the other for
|
|
print outs.
|
|
|
|
<p>HTML support in turn requires ``hyperlinks'', this is, references between
|
|
documents or parts thereof that can be followed in a convenient way.
|
|
References also help to implement the <em>Modular Requirement</em> in my list
|
|
of source format features.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Automatic_Reference_Generation">Automatic
|
|
Reference Generation</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>All references should be resolved automatically as far as this is
|
|
possible. For example, the system should resolve cross references within in
|
|
the document and should allow for footnotes or sidenotes to be placed and
|
|
numbered without the help of the writer. The index and bibliography also
|
|
should be generated automatically.</dd>
|
|
</dl>
|
|
|
|
<p>Let us now look at a particularly easy to use format: Perl's Plain Old
|
|
Documentation.</p>
|
|
|
|
<h2><a name="perl's plain old documentation (pod)">Perl's Plain Old
|
|
Documentation (POD)</a></h2>
|
|
|
|
<p>The ``Plain Old Documentation'' system that ships with every Perl
|
|
distribution is simplest documentation system in my selection. It is simple to
|
|
learn, simple to use, but -- and I hesitate to write therefore -- also the
|
|
most limited of the three. Anyhow, the article you are currently reading (yes
|
|
this one!) has been prepared with POD. If it is good for the goose, it can't
|
|
be bad for the gander...</p>
|
|
|
|
<p>The big advantages of POD are</p>
|
|
|
|
<ul>
|
|
<li>It comes with Perl. So you probably already have it on your Linux box. Try
|
|
|
|
|
|
<pre>
|
|
pod2man --help
|
|
</pre>
|
|
|
|
<p>to see if it is installed.</p>
|
|
</li>
|
|
|
|
<li>It offers a small and well-though-out set of document structuring and
|
|
markup instructions.</li>
|
|
|
|
<li>The POD translation tools render at least four different output formats:
|
|
HTML, UN*X manual pages, LaTeX (which serves as base for a further translation
|
|
into PostScript), and plain ASCII text.</li>
|
|
</ul>
|
|
|
|
<h3><a name="syntax">Syntax</a></h3>
|
|
|
|
<p>The POD format defines three different kinds of paragraphs. Paragraphs are
|
|
separated from each other by one or more <EM>completely (!)</EM> empty
|
|
lines.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Ordinary_Paragraph">Ordinary
|
|
Paragraph.</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Any line that does not start with at least four spaces or an equal sign is
|
|
considered ordinary text. Paragraphs are separated by one or more empty lines.
|
|
This means, the documenter simply writes one paragraph after the other with at
|
|
least one blank line between each pair.
|
|
|
|
<p>Ordinary paragraphs will be filled and justified (if the output format
|
|
allows for justification) when output.
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Verbatim_Paragraph">Verbatim
|
|
Paragraph.</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Lines indented by four or more spaces are considered verbatim text. They
|
|
are output exactly as typed. All formatting instructions that we will see
|
|
later, are disabled in verbatim paragraphs.</dd>
|
|
|
|
<dt><strong><a name="item_Command_Paragraph">Command
|
|
Paragraph.</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Command paragraphs start with an equal sign ``<code>=</code>'' in column
|
|
zero, immediately followed by an identifier. Usually, command paragraphs
|
|
consist of single lines. Yet they are syntactically paragraphs, because they
|
|
are separated by blank lines before and after them.</dd>
|
|
</dl>
|
|
|
|
<h4><a name="sectioning">Sectioning</a></h4>
|
|
|
|
<p>Text is sectioned by <code>=head</code><em>N</em> commands, like</p>
|
|
|
|
<p><code>=head1</code> <em>primary_heading</em></p>
|
|
|
|
<p><code>=head2</code> <em>secondary_heading</em></p>
|
|
|
|
<p><code>=head3</code> <em>tertiary_heading</em></p>
|
|
|
|
<p>which also define the section headings <em>primary_heading</em>, etc.. How
|
|
many heading levels (this is largest <em>N</em> permitted) actually are
|
|
accepted, depends on the POD-to-something converter. For example, <strong>
|
|
pod2man</strong> allows only two levels, <strong>pod2html</strong> allows up
|
|
to six levels.</p>
|
|
|
|
<p>I have added line and column numbers to the source of the examples. The
|
|
line numbers do not appear in the real source. They are included here to point
|
|
out the empty lines that must separate the command paragraphs, this is, those
|
|
starting with an equal sign in column 0. Additionally, I have added a
|
|
column-number ruler at the beginning of the next example to clarify where
|
|
column 0 starts.</p>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre>
|
|
1 2 3 4 5
|
|
0123456789012345678901234567890123456789001234567890
|
|
1 =head1 Hardware
|
|
2
|
|
3 The physical parts of your computer are called "hardware".
|
|
4
|
|
5 =head1 CPU
|
|
6
|
|
7 The CPU is the most important part of your computer.
|
|
8
|
|
9 =head1 Mass Storage
|
|
10
|
|
11 Mass storage devices store data permanently.
|
|
12
|
|
13 =head2 Hard Disk Drives
|
|
14
|
|
15 Hard disk drives provide fast random access to data.
|
|
16
|
|
17 =head2 Magnetic Tapes
|
|
18
|
|
19 Magnetic tapes provide slow sequential access to data.
|
|
20
|
|
21 =head1 Software
|
|
22
|
|
23 This is where the trouble starts ...
|
|
</pre>
|
|
|
|
<h4><a name="lists">Lists</a></h4>
|
|
|
|
<p>Itemized, enumerated or description lists are produced with</p>
|
|
|
|
<p><code>=over</code> <em>N</em></p>
|
|
|
|
<p><code>=item</code> <em>label</em></p>
|
|
|
|
<p><code>=item</code> <em>label</em></p>
|
|
|
|
<p>...</p>
|
|
|
|
<p><code>=back</code></p>
|
|
|
|
<p>where <code>=over</code> <em>N</em> starts a list that is indented at
|
|
least <em>N</em> spaces, and extends until <code>=back</code>. Depending on
|
|
the first <em>label</em> the POD-to-something translators generate an itemized
|
|
list (<em>label</em> = <code>*</code>), a numbered list (<em>label</em> =
|
|
<code>1</code>) or a description list (<em>label</em> starts with a
|
|
letter).</p>
|
|
|
|
<p><strong>Example:</strong> itemized list</p>
|
|
|
|
<p>Again, I have added line numbers to alert the reader of the (many) empty
|
|
lines used for separating the command paragraphs.</p>
|
|
|
|
<p>Source</p>
|
|
|
|
<pre>
|
|
1 =over 4
|
|
2
|
|
3 =item *
|
|
4
|
|
5 Fruit, particularly non-imported fruit like ...
|
|
6
|
|
7 =item *
|
|
8
|
|
9 Though not tasty, vegetables should make up a large part of your
|
|
10 daily diet.
|
|
11
|
|
12 =item *
|
|
13
|
|
14 Fish is much easier digestible than meat. Therefore, ...
|
|
15
|
|
16 =back
|
|
</pre>
|
|
|
|
<p>Result</p>
|
|
|
|
<ul>
|
|
<li>Fruit, particularly non-imported fruit like ...</li>
|
|
|
|
<li>Though not tasty, vegetables should make up a large part of your daily
|
|
diet.</li>
|
|
|
|
<li>Fish is much easier digestible than meat. Therefore, ...</li>
|
|
</ul>
|
|
|
|
<p><strong>Example:</strong> enumerated list</p>
|
|
|
|
<p>Source</p>
|
|
|
|
<pre>
|
|
1 =over 4
|
|
2
|
|
3 =item 1.
|
|
4
|
|
5 Ensure that the power switch is in position "OFF".
|
|
6
|
|
7 =item 2.
|
|
8
|
|
9 Plug in the power cord.
|
|
10
|
|
11 =item 3.
|
|
12
|
|
13 Switch the power switch in position "ON".
|
|
14
|
|
15 =back
|
|
</pre>
|
|
|
|
<p>Result</p>
|
|
|
|
<ol>
|
|
<li>Ensure that the power switch is in position ``OFF''.</li>
|
|
|
|
<li>Plug in the power cord.</li>
|
|
|
|
<li>Switch the power switch in position ``ON''.</li>
|
|
</ol>
|
|
|
|
<p><strong>Example:</strong> description list</p>
|
|
|
|
<p>Source</p>
|
|
|
|
<pre>
|
|
1 =over 8
|
|
2
|
|
3 =item Robert
|
|
4
|
|
5 Lead singer
|
|
6
|
|
7 =item Jimmy
|
|
8
|
|
9 Lead guitar
|
|
10
|
|
11 =item John-Paul
|
|
12
|
|
13 Bass guitar
|
|
14
|
|
15 =item John
|
|
16
|
|
17 Drums and percussion
|
|
18
|
|
19 =back
|
|
</pre>
|
|
|
|
<p>Result</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Robert">Robert</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Lead singer</dd>
|
|
|
|
<dt><strong><a name="item_Jimmy">Jimmy</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Lead guitar</dd>
|
|
|
|
<dt><strong><a name="item_John_Paul">John-Paul</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Base guitar</dd>
|
|
|
|
<dt><strong><a name="item_John">John</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Drums and percussion</dd>
|
|
</dl>
|
|
|
|
<h4><a name="inline markup commands">Inline Markup Commands</a></h4>
|
|
|
|
<p>Within Ordinary Text, several markup commands are recognized. All markup
|
|
commands start with a single capital letter and enclose their argument within
|
|
angle brackets: <em>LETTER</em><<em>argument</em>>. The argument can
|
|
consist of multiple words, which can span more than one line.</p>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_I_argument">
|
|
I<<em>argument</em>></a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Render argument in italics. <code>I</code> corresponds to the HTML
|
|
tags <code>em</code> and <code>var</code>, thus it is primarily used for
|
|
emphasizing words or marking up variables.
|
|
|
|
<p>Examples:</p>
|
|
|
|
<ul>
|
|
<li>Do <em>not</em> remove your Linux kernel!
|
|
|
|
<p>is produced by</p>
|
|
|
|
<pre>
|
|
Do I<not> remove your Linux kernel!
|
|
</pre>
|
|
</li>
|
|
|
|
<li>Use <strong>cd</strong> <em>directory</em> to change your working
|
|
directory to <em>directory</em>.
|
|
|
|
<p>is generated with</p>
|
|
|
|
<pre>
|
|
Use B<cd> I<directory> to change your
|
|
working directory to I<directory>.
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_B_argument">
|
|
B<<em>argument</em>></a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Render argument bold. <code>B</code> corresponds to the HTML
|
|
tag <code>b</code>. It is used to emphasize in text and to mark up
|
|
program names or switches.
|
|
|
|
<p>Examples:</p>
|
|
|
|
<ul>
|
|
<li><strong>Always</strong> shut down your machine before switching it off.
|
|
|
|
<p>comes from</p>
|
|
|
|
<pre>
|
|
B<Always> shut down your machine before switching it off.
|
|
</pre>
|
|
</li>
|
|
|
|
<li><strong>podchecker</strong> accepts the options <strong>-warnings</strong>
|
|
and <strong>-nowarnings</strong>.
|
|
|
|
<p>is the result of</p>
|
|
|
|
<pre>
|
|
B<podchecker> accepts the options B<-warnings>
|
|
and B<-nowarnings>.
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_C_argument">
|
|
C<<em>argument</em>></a></strong><br>
|
|
</dt>
|
|
|
|
<dd><code>C</code> marks up code or anything else which is to be taken
|
|
literally. The corresponding HTML tags is are <code>code</code>, <code>
|
|
samp</code>, and <code>tt</code>.
|
|
|
|
<p>Examples:</p>
|
|
|
|
<ul>
|
|
<li>Every C-program must have a function called <code>main</code>.
|
|
|
|
<p>is generated by</p>
|
|
|
|
<pre>
|
|
Every C-program must have a function
|
|
called C<main>.
|
|
</pre>
|
|
</li>
|
|
|
|
<li>Boolean false is represented by <code>[1 1 0]</code>, and boolean true by
|
|
<code>[1 1 1]</code>.
|
|
|
|
<p>is produced by</p>
|
|
|
|
<pre>
|
|
Boolean false is represented by C<[1 1 0]>,
|
|
and boolean true by C<[1 1 1]>.
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_L_reference_or_L_description_reference">
|
|
L<<em>reference</em>> or
|
|
L<<em>description</em>|<em>reference</em>></a></strong><br>
|
|
</dt>
|
|
|
|
<dd>Link to an existing <em>reference</em>. If <em>description</em> is
|
|
omitted, the link's text is <em>reference</em>, otherwise it is <em>
|
|
description</em>. Using <code>L</code> is a bit tricky. Therefore, I
|
|
have devoted the next section to it.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="cross references">Cross References</a></h4>
|
|
|
|
The <code>L</code>-command is distantly related to HTML's
|
|
<a href = "<em>reference</em>"><em>description</em></a>, however,
|
|
in POD, <em>reference</em> is not a general unified resource locator (URL).
|
|
|
|
<p><em>reference</em> can only refer to (automatically by the POD-to-something
|
|
translator) generated labels. These labels are inserted for every <code>
|
|
=head</code> and <code>=item</code>. The label associated with <code>
|
|
=head</code> <em>heading</em> is <em>heading</em> downcased, but otherwise
|
|
unchanged, e.g.</p>
|
|
|
|
<pre>
|
|
=head1 A Multi-Word Heading (MWH)
|
|
</pre>
|
|
|
|
<p>automatically gets assigned the label</p>
|
|
|
|
<pre>
|
|
a multi-word heading (mwh)
|
|
</pre>
|
|
|
|
<p>The labels of <code>=item</code>s are prefixed by <code>item_</code>,
|
|
spaces are replaced by underscores, and non-alphanumeric characters are
|
|
replaced by their hexadecimal ASCII code prefixed by a percent sign. Anybody
|
|
expected an easy rule? So, one of the items in this article,</p>
|
|
|
|
<pre>
|
|
=item Automatic Reference Generation.
|
|
</pre>
|
|
|
|
<p>has the label</p>
|
|
|
|
<pre>
|
|
item_Automatic_Reference_Generation%2E
|
|
</pre>
|
|
|
|
<p>because the ASCII number of the period is 46 in decimal or 2e in
|
|
hexadecimal.</p>
|
|
|
|
<p>Example:</p>
|
|
|
|
<p>Source</p>
|
|
|
|
<pre>
|
|
=head1 Introduction
|
|
</pre>
|
|
|
|
<pre>
|
|
Section L<"concepts"> introduces the basics of the field.
|
|
</pre>
|
|
|
|
<pre>
|
|
=head1 Concepts
|
|
</pre>
|
|
|
|
<pre>
|
|
...
|
|
</pre>
|
|
|
|
<pre>
|
|
=head1 Synchronization
|
|
</pre>
|
|
|
|
<pre>
|
|
=over 4
|
|
</pre>
|
|
|
|
<pre>
|
|
=item Deadlocks
|
|
</pre>
|
|
|
|
<pre>
|
|
=item Race Conditions
|
|
</pre>
|
|
|
|
<pre>
|
|
=item Recovering from Deadlocks
|
|
</pre>
|
|
|
|
<pre>
|
|
=back
|
|
</pre>
|
|
|
|
<pre>
|
|
How to cope with deadlocks was already discussed in
|
|
L<Deadlocks|"item_Deadlocks">, and L<Recovering from
|
|
Deadlocks|"item_Recovering_from_Deadlocks">.
|
|
</pre>
|
|
|
|
<p>Result</p>
|
|
|
|
<blockquote>
|
|
<h1>Introduction</h1>
|
|
|
|
<p>Section <a href="#concepts">concepts</a> introduces the basics of the
|
|
field.</p>
|
|
|
|
<hr>
|
|
<h1><a name="concepts">Concepts</a></h1>
|
|
|
|
<p>...</p>
|
|
|
|
<hr>
|
|
<h1><a name="synchronization">Synchronization</a></h1>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Deadlocks">Deadlocks</a></strong><br>
|
|
</dt>
|
|
|
|
<dt><strong><a name="item_Race_Conditions">Race Conditions</a></strong><br>
|
|
</dt>
|
|
|
|
<dt><strong><a name="item_Recovering_from_Deadlocks">Recovering from
|
|
Deadlocks</a></strong><br>
|
|
</dt>
|
|
</dl>
|
|
|
|
<p>How to cope with deadlocks was discussed in <a href="#item_deadlocks">
|
|
Deadlocks</a>, and <a href="#item_recovering_from_deadlocks">Recovering from
|
|
Deadlocks</a>.</p>
|
|
</blockquote>
|
|
|
|
<p>The <code>L</code>-command is very limited in its use, for the writer
|
|
cannot insert places to refer to with an <code>L</code>-command; HTML-like
|
|
``anchors'' are missing.</p>
|
|
|
|
<p>A second limiting factor are some POD translators trying to be smart and
|
|
decorate link with additional text. For example, <strong>pod2latex</strong>
|
|
mangles both references to items in the above example:</p>
|
|
|
|
<blockquote>How to cope with deadlocks was discussed in <u>the</u>
|
|
\textsf{Deadlocks<u>$|$"item\_Deadlocks"</u>} <u>entry elsewhere in this
|
|
document</u>, and <u>the</u> \textsf{Recovering from
|
|
Deadlocks<u>$|$"item\_Recovering\_from\_Deadlocks"</u>} <u>entry elsewhere in
|
|
this document</u>.</blockquote>
|
|
|
|
<p>where I have underlined the words added by <strong>pod2latex</strong>.
|
|
Clearly, we want a better mechanism. The mechanism exists in format-specific
|
|
paragraphs.</p>
|
|
|
|
<h2><a name="formatspecific paragraphs">Format-Specific Paragraphs</a></h2>
|
|
|
|
<p>We have just seen that the <code>L</code>-command is somewhat difficult to
|
|
control. Why can't we simply use a HTML-reference? The terse answer, ``because
|
|
POD is not HTML'', leads to the solution. If we had a way to say ``this text
|
|
is for HTML, this line is for LaTeX, and this paragraph is for ''SnaFoo``, we
|
|
could use the specific markup provided by these formats.</p>
|
|
|
|
<p>The special command</p>
|
|
|
|
<p><code>=for</code> <em>format</em> <em>paragraph_of_text</em></p>
|
|
|
|
<p>tells a translator to look at <em>format</em> before processing <em>
|
|
paragraph_of_text</em>. If the translator feels responsible for handling <em>
|
|
format</em>, it transforms <em>paragraph_of_text</em> according to its own
|
|
rules, otherwise it completely ignores the paragraph. The second part of the
|
|
translator's name usually specifies which format it takes care of. For
|
|
example, <strong>pod2man</strong> transforms <code>=for man</code> paragraphs,
|
|
<strong>pod2html</strong> processes <code>=for html</code> paragraphs, and so
|
|
on.</p>
|
|
|
|
<p>As all command paragraphs, a <code>=for</code> <em>format</em>
|
|
paragraph ends at the first completly empty line that follows the introducing
|
|
<code>=for</code>.</p>
|
|
|
|
<p>A consistent document structure will show ``forks'' whenever specific
|
|
formats are used, because a <code>=for</code> <em>format</em> clause
|
|
ought to appear for each desired output format, otherwise we punch a logical
|
|
holes into the document.</p>
|
|
|
|
<pre>
|
|
This is an ordinary paragraph, which is processed by all
|
|
translators.
|
|
</pre>
|
|
|
|
<pre>
|
|
=for html <p>This paragraph only appears if the file is processed
|
|
with <b>pod2html</b>.</p>
|
|
</pre>
|
|
|
|
<pre>
|
|
=for latex This very paragraph is only treated by {\bf pod2latex}.
|
|
</pre>
|
|
|
|
<pre>
|
|
=for text I am a paragraph for the *pod2text* formatter.
|
|
</pre>
|
|
|
|
<pre>
|
|
We now continue with the ordinary text for all formatters.
|
|
</pre>
|
|
|
|
<p>The translators ignore unknown <em>format</em>s, which means we can invent
|
|
special paragraphs for our own purposes! For example, to ``comment out'' a
|
|
paragraph, write</p>
|
|
|
|
<pre>
|
|
=for comment Can someone clarify the next section?
|
|
</pre>
|
|
|
|
<p>Another popular use is the <code>emacs</code> format :-) To switch <strong>
|
|
emacs</strong> into text-mode when preparing a POD-file, start the file
|
|
with</p>
|
|
|
|
<pre>
|
|
=for emacs -*- text -*-
|
|
</pre>
|
|
|
|
<p>or end it with</p>
|
|
|
|
<pre>
|
|
=for emacs
|
|
Local Variables:
|
|
mode: text
|
|
End:
|
|
</pre>
|
|
|
|
<p>The emacs-users who are using the <a href=
|
|
"http://sourceforge.net/projects/hyperbole/">hyperbole</a> add-on can convert
|
|
their "dumb" POD-files into hyper-linked collections (well -- hyperbole can do
|
|
a lot more than that, but hyperlinks are a beginning) of files with</p>
|
|
|
|
<pre>
|
|
=for hyperbole <(std-reference)>
|
|
</pre>
|
|
|
|
<p>where <code><(std-reference)></code> is a hyperbole button taking you
|
|
to another file which holds the reference documentation of <code>std</code>
|
|
when you click the button in emacs.</p>
|
|
|
|
<h3><a name="programs that work with pod">Programs That Work With POD</a></h3>
|
|
|
|
<ul>
|
|
<li><strong>pod2html</strong>, <strong>pod2man</strong>, <strong>
|
|
pod2latex</strong>, <strong>pod2text</strong>
|
|
|
|
<p>Translators from POD to HTML, UN*X manual pages, LaTeX and plain text
|
|
respectively.</p>
|
|
</li>
|
|
|
|
<li><strong>podchecker</strong>
|
|
|
|
<p>Simple syntax checker for POD files.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3><a name="pros and cons of pod">Pros And Cons of POD</a></h3>
|
|
|
|
<dl>
|
|
<dt><strong><a name="item_Pro">Pro</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>Simplicity</li>
|
|
|
|
<li>Conversion speed</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_Cons">Cons</a></strong><br>
|
|
</dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>Lack of tables</li>
|
|
|
|
<li>No program to generate an index supplied by default</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="further reading">Further Reading</a></h3>
|
|
|
|
<p>Manual pages of perlpod(1), pod2man(1), pod2html(1), pod2latex(1),
|
|
pod2text(1), and podchecker(1).</p>
|
|
|
|
<p>Next month: LaTeX in conjuction with <strong>latex2html</strong>.</p>
|
|
</body>
|
|
</html>
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *** 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 © 2001, Christoph Spiel.<BR>
|
|
Copying license <A HREF="../copying.html">http://www.linuxgazette.com/copying.html</A><BR>
|
|
Published in Issue 73 of <i>Linux Gazette</i>, December 2001</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="padala.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/issue73/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="zhaoway.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 ============================================================-->
|