<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Pod::2::DocBook</title><link rel="stylesheet" href="docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2477633"></a><span class="application">Pod::2::DocBook</span></h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Jozef</span> <span class="surname">Kutej</span></h3></div></div></div><div><p class="copyright">Copyright © 2008 Jozef Kutej. All rights reserved.</p></div><div><div class="legalnotice"><a name="id2502526"></a><p>
Copyright Notice: This document contains information about <span class="application">Pod::2::DocBook</span>
Perl module.
All parts of this document may be photocopied, otherwise reproduced,
or translated to another language without the prior written consent.
</p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.01</td><td align="left">2008-07-03</td><td align="left">Jozef Kutej</td></tr><tr><td align="left" colspan="3">
Initial draft started.
</td></tr><tr><td align="left">Revision 0.02</td><td align="left">2008-07-06</td><td align="left">Jozef Kutej</td></tr><tr><td align="left" colspan="3">
Added "Usage" chapter.
</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#chapter-intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro.overview">Overview</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chapter-usage">2. Usage</a></span></dt><dd><dl><dt><span class="section"><a href="#usage.installation">Instalation</a></span></dt><dt><span class="section"><a href="#id2551924">DocBook quick start guide</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chapter-dev">3. Developers documentation section</a></span></dt><dd><dl><dt><span class="section"><a href="#id2629957">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#id2629947">Modules</a></span></dt><dt><span class="section"><a href="#dev.scripts">Scripts</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chapter-appendix-a">4. Open questions</a></span></dt><dd><dl><dt><span class="section"><a href="#id2599764">some terms used in this book</a></span></dt></dl></dd></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#intro.overview">Overview</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro.overview"></a>Overview</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>This document refers to
<a class="ulink" href="http://search.cpan.org/dist/Pod-2-DocBook/" target="_top"><span class="application">Pod::2::DocBook</span></a>
version
<a class="ulink" href="http://search.cpan.org/~jkutej/Pod-2-DocBook-0.01/" target="_top">0.01</a>.
</p></td></tr></table></div><p><span class="application">Pod::2::DocBook</span> Perl module helps to convert existing pod documentation
to docbook xml format. For a full reasoning and detail description see
<a class="xref" href="#chapter-dev" title="Chapter 3. Developers documentation section">Chapter 3, <i>Developers documentation section</i></a>.
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>not complete, as any other documentation ;-)</p></td></tr></table></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-usage"></a>Chapter 2. Usage</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usage.installation">Instalation</a></span></dt><dt><span class="section"><a href="#id2551924">DocBook quick start guide</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usage.installation"></a>Instalation</h2></div></div></div><p>Installing of <span class="application">Pod::2::DocBook</span> should be as easy and streight
forward as executing <code class="code">cpan -i Pod::2::DocBook</code>. This
will add <span class="application">pod2docbook</span> script to the system.
See <a class="xref" href="#dev.scripts" title="Scripts">the section called “Scripts”</a> for description.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2551924"></a>DocBook quick start guide</h2></div></div></div><p>In folder <code class="filename">examples/pod2docbook-docbook/</code> of
<a class="ulink" href="http://search.cpan.org/dist/Pod-2-DocBook/" target="_top"><span class="application">Pod::2::DocBook</span></a>
is the source of this document. To generate the
<span class="application">HTML</span> or <span class="application">PDF</span>
version from
it you'll need: make, xmllint, xsltproc, fop and docbook xml+xsl.
</p><p>For Debian: <span class="command"><strong>apt-get install docbook-utils psutils
docbook-xml docbook-xsl xsltproc fop make</strong></span>. To have images in the
PDF you need to get
<a class="ulink" href="http://java.sun.com/products/jimi/" target="_top">jimi</a> and copy
<code class="filename">jimi.jar</code> to <code class="filename">/usr/share/java/jimi-1.0.jar</code>
</p><p>Then just do <span class="command"><strong>make</strong></span> or <span class="command"><strong>make Pod-2-DocBook.html</strong></span>
or <span class="command"><strong>make Pod-2-DocBook.pdf</strong></span> to generate this "book".
</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-dev"></a>Chapter 3. Developers documentation section</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2629957">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#id2629947">Modules</a></span></dt><dt><span class="section"><a href="#dev.scripts">Scripts</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2629957"></a>Overview</h2></div></div></div><p>It's aways nice to read some documentation but to write it's
not so fun. And to write it and sync it on two different places it's
just annoing. To make our life easy let's see how a docbook sections
generated directly for Perl module can look like.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2629947"></a>Modules</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2629910"></a>Pod-2-DocBook POD</h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-58242115eaaf2c95bbef44b2d63e2b74"></a>NAME</h5></div></div></div><p>
Pod::2::DocBook - Convert Pod data to DocBook SGML
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-51d50f687f0442c7221c18d338b95ece"></a>SYNOPSIS</h5></div></div></div><pre class="screen">use Pod::2::DocBook;
my $parser = Pod::2::DocBook->new (title => 'My Article',
doctype => 'article',
fix_double_quotes => 1,
spaces => 3);
$parser->parse_from_file ('my_article.pod', 'my_article.sgml');</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-7fca5888c7cf9b8e58f198fe9bb00892"></a>DESCRIPTION</h5></div></div></div><p>
Pod::2::DocBook is a module for translating Pod-formatted documents
to DocBook 4.2 SGML (see <a class="ulink" href="http://www.docbook.org/" target="_top">http://www.docbook.org/</a>). It
is primarily a back end for <span class="bold"><strong>pod2docbook</strong></span>, but, as a Pod::Parser subclass,
it can be used on its own. The only public extensions to the
Pod::Parser interface are options available to <code class="literal">new()</code>:
</p><p>
</p><div class="variablelist"><dl><dt><span class="term"><a name="ID-97457a93826eedeb05c02ef412ea7147"></a>doctype</span></dt><dd><p>
This option sets the output document's doctype. The
currently supported types are <span class="bold"><strong>article</strong></span>, <span class="bold"><strong>chapter</strong></span>, <span class="bold"><strong>refentry</strong></span> and <span class="bold"><strong>section</strong></span>. Special processing is
performed when the doctype is set to <span class="bold"><strong>refentry</strong></span> (see <a class="link" href="#ID-3b19848ad8becd5b034cca6ea6b57eb7" title="Document Types">“<span class="quote">Document
Types</span>”</a>). You <span class="italic">must</span> set this option in order to get
valid DocBook output.
</p></dd><dt><span class="term"><a name="ID-5cac6bd3f4fd21d5bba16d572aca5bda"></a>fix_double_quotes</span></dt><dd><p>
If this option is set to a true value, pairs of double quote
characters ('"') in ordinary paragraphs will be replaced with
<span class="bold"><strong><quote></strong></span> and <span class="bold"><strong></quote></strong></span>. See <a class="link" href="#ID-3ccb626553ea01666dc8d94204d1ed36" title="Ordinary Paragraphs">“<span class="quote">Ordinary
Paragraphs</span>”</a> for details.
</p></dd><dt><span class="term"><a name="ID-db2645470fa03b14a816600681467ea6"></a>header</span></dt><dd><p>
If this option is set to a true value, Pod::2::DocBook will
emit a DOCTYPE as the first line of output.
</p></dd><dt><span class="term"><a name="ID-081bece647d5723a268cc579c95695c9"></a>spaces</span></dt><dd><p>
Pod::2::DocBook produces pretty-printed output. This option
sets the number of spaces per level of indentation in the
output.
</p></dd><dt><span class="term"><a name="ID-1efdce179ab82fed2547288f3cb83409"></a>title</span></dt><dd><p>
This option sets the output document's title.
</p></dd></dl></div><p>
</p><p>
The rest of this document only describes issues specific to
Pod::2::DocBook; for details on invoking the parser, specifically the
<code class="literal">new()</code>, <code class="literal">parse_from_file()</code> and <code class="literal">parse_from_filehandle()</code> methods,
see <span class="citerefentry"><span class="refentrytitle">Pod::Parser</span></span>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-faea5325c66b171909c6af7991e2a31f"></a>METHODS</h5></div></div></div><pre class="screen">our @ISA = qw(Pod::Parser);</pre><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-d1724f2a982547518ebb3549b36dec25"></a>initialize()</h6></div></div></div><p>
Initialize parser.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-0e6090522fd23cecce3cb9c3cf889630"></a>begin_pod()</h6></div></div></div><p>
Output docbook header stuff.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-f439f7926feaa39e72ea057344c5f180"></a>end_pod()</h6></div></div></div><p>
Output docbook footer. Will print also errors if any in a comment
block.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-7e6511bbe86ad9e29095606006c834d8"></a>commans($command, $paragraph, $line_num)</h6></div></div></div><p>
Process POD commands.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-362d73f74172f5a0b0d893f468b9b056"></a>textblock ($paragraph, $line_num)</h6></div></div></div><p>
Process text block.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-710ee12a6f599f38ce749576d20ab53c"></a>verbatim($paragraph, $line_num)</h6></div></div></div><p>
Process verbatim text block.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-36e8760b78618aef1500bf615209c633"></a>interior_sequence($command, $argument, $seq)</h6></div></div></div><p>
Process formatting commands.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-da47f16eccd995c704463ee59f9ba1f8"></a>error_msg</h6></div></div></div><p>
Returns parser error message(s) if any occured.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-ed297956aaf9b499f9ed1f548415f708"></a>POD TO DOCBOOK TRANSLATION</h5></div></div></div><p>
Pod is a deceptively simple format; it is easy to learn and very
straightforward to use, but it is suprisingly expressive.
Nevertheless, it is not nearly as expressive or complex as DocBook.
In most cases, given some Pod, the analogous DocBook markup is
obvious, but not always. This section describes how Pod::2::DocBook
treats Pod input so that Pod authors may make informed choices. In
every case, Pod::2::DocBook strives to make easy things easy and hard
things possible.
</p><p>
The primary motivation behind Pod::2::DocBook is to facilitate
single-source publishing. That is, you should be able to generate
man pages, web pages, PDF and PostScript documents, or any other
format your SGML and/or Pod tools can produce, from the same Pod
source, without the need for hand-editing any intermediate files.
This may not always be possible, or you may simply choose to render
Pod to DocBook and use that as your single source. To satisfy the
first requirement, Pod::2::DocBook always processes the entire Pod
source and tries very hard to produce valid DocBook markup, even in
the presence of malformed Pod (see <a class="link" href="#ID-27c872f13298ab7cc42f6e59e6373302" title="DIAGNOSTICS">“<span class="quote">DIAGNOSTICS</span>”</a>).
To satisfy the second requirement (and to be a little nifty),
Pod::2::DocBook pretty-prints its output. If you're curious about
what specific output to expect, read on.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-3b19848ad8becd5b034cca6ea6b57eb7"></a>Document Types</h6></div></div></div><p>
DocBook's structure is very modular; many of its document types can
be embedded directly into other documents. Accordingly,
Pod::2::DocBook will generate four different document types:
<span class="bold"><strong>article</strong></span>, <span class="bold"><strong>chapter</strong></span>, <span class="bold"><strong>refentry</strong></span>, and <span class="bold"><strong>section</strong></span>. This makes it easy, for instance,
to write all the chapters of a book in separate Pod documents,
translate them into DocBook markup and later glue them together
before processing the entire book. You could do the same with each
section in an article, or you could write the entire article in a
single Pod document. Other document types, such as <span class="bold"><strong>book</strong></span> and <span class="bold"><strong>set</strong></span>, do not map easily from Pod, because
they require structure for which there is no Pod equivalent. But
given sections and chapters, making larger documents becomes much
simpler.
</p><p>
The <span class="bold"><strong>refentry</strong></span> document type is a
little different from the others. Sections, articles, and chapters
are essentially composed of nested sections. But a refentry has
specialized elements for the <span class="italic">NAME</span> and <span class="italic">SYNOPSIS</span> sections. To accommodate this,
Pod::2::DocBook performs extra processing on the Pod source when
the <span class="bold"><strong>doctype</strong></span> is set to <span class="bold"><strong>refentry</strong></span>. You probably don't have to do
anything to your document to assist the processing; typical man
page conventions cover the requirements. Just make sure that the
<span class="italic">NAME</span> and <span class="italic">SYNOPSIS</span> headers are both <span class="bold"><strong>=head1</strong></span>s, that "NAME" and "SYNOPSIS" are both
uppercase, and that <span class="bold"><strong>=head1 NAME</strong></span> is
the first line of Pod source.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-3ccb626553ea01666dc8d94204d1ed36"></a>Ordinary Paragraphs</h6></div></div></div><p>
Ordinary paragraphs in a Pod document translate naturally to
DocBook paragraphs. Specifically, after any formatting codes are
processed, the characters <code class="literal">&lt;</code>, <code class="literal">&gt;</code> and <code class="literal">&amp;</code> are translated to their
respective SGML character entities, and the paragraph is wrapped in
<span class="bold"><strong><para></strong></span> and <span class="bold"><strong></para></strong></span>.
</p><p>
For example, given this Pod paragraph:
</p><pre class="screen">Here is some text with I<italics> & an ampersand.</pre><p>
Pod::2::DocBook would produce DocBook markup similar to this:
</p><pre class="screen"><para>
Here is some text with <emphasis role="italic">italics</emphasis>
&amp; an ampersand.
</para></pre><p>
Depending on your final output format, you may sometimes want
double quotes in ordinary paragraphs to show up ultimately as
"smart quotes" (little 66s and 99s). Pod::2::DocBook offers a
convenient mechanism for handling double quotes in ordinary
paragraphs and letting your SGML toolchain manage their
presentation: the <span class="bold"><strong>fix_double_quotes</strong></span> option to <code class="literal">new()</code>. If this option is set to
a true value, Pod::2::DocBook will replace pairs of double quotes
in ordinary paragraphs (and <span class="italic">only</span>
in ordinary paragraphs) with <span class="bold"><strong><quote></strong></span> and <span class="bold"><strong></quote></strong></span>.
</p><p>
For example, given this Pod paragraph:
</p><pre class="screen">Here is some text with I<italics> & an "ampersand".</pre><p>
Pod::2::DocBook, with <span class="bold"><strong>fix_double_quotes</strong></span> set, would produce DocBook
markup similar to this:
</p><pre class="screen"><para>
Here is some text with <emphasis role="italic">italics</emphasis>
&amp; an <quote>ampersand</quote>.
</para></pre><p>
If you have a paragraph with an odd number of double quotes, the
last one will be left untouched, which may or may not be what you
want. If you have such a document, replace the unpaired double
quote character with <span class="bold"><strong>E<quot></strong></span>, and Pod::2::DocBook should be
able to give you the output you expect. Also, if you have any
<span class="bold"><strong>=begin docbook</strong></span> ... <span class="bold"><strong>=end docbook</strong></span> regions (see <a class="link" href="#ID-196a22a8c2df08c5124ac933228893c0" title="Embedded DocBook Markup">“<span class="quote">Embedded
DocBook Markup</span>”</a>) in your Pod, you are responsible for
managing your own quotes in those regions.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-fa07cc0bd1c6f7a9156db36b87b3f979"></a>Verbatim Paragraphs</h6></div></div></div><p>
Verbatim paragraphs translate even more naturally; <span class="citerefentry"><span class="refentrytitle">perlpodspec</span></span> mandates
that absolutely no processing should be performed on them. So
Pod::2::DocBook simply marks them as CDATA and wraps them in
<span class="bold"><strong><screen></strong></span> and <span class="bold"><strong></screen></strong></span>. They are not indented the
way ordinary paragraphs are, because they treat whitespace as
significant.
</p><p>
For example, given this verbatim paragraph (imagine there's leading
whitespace in the source):
</p><pre class="screen">my $i = 10;
while (<> && $i--) {
print "$i: $_";
}</pre><p>
Pod::2::DocBook would produce DocBook markup similar to this:
</p><pre class="screen"><screen><![CDATA[my $i = 10;
while (<> && $i--) {
print "$i: $_";
}]] ></screen></pre><p>
Multiple contiguous verbatim paragraphs are treated as a single
<span class="italic">screen</span> element, with blank lines
separating the paragraphs, as dictated by <span class="citerefentry"><span class="refentrytitle">perlpodspec</span></span>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-9b88b0d4ed55dfb1d3ad7985907bae35"></a>Command Paragraphs</h6></div></div></div><p>
</p><div class="variablelist"><dl><dt><span class="term"><a name="ID-58454906696cb2a6c87e23d686e78a68"></a><code class="literal">=head1 Heading Text</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-1335f1a114390d3beda813f4039ce34e"></a><code class="literal">=head2 Heading Text</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-e04b9a4ea3772b834795269a404ddd3e"></a><code class="literal">=head3 Heading Text</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-2519bad75ba18bc36de30ea44abbf506"></a><code class="literal">=head4 Heading Text</code></span></dt><dd><p>
All of the Pod heading commands produce DocBook <span class="italic">section</span> elements, with the heading
text as titles. Pod::2::DocBook (<span class="citerefentry"><span class="refentrytitle">perlpod</span></span>)
only allows for 4 heading levels, but DocBook allows
arbitrary nesting; see <a class="link" href="#ID-196a22a8c2df08c5124ac933228893c0" title="Embedded DocBook Markup">“<span class="quote">Embedded
DocBook Markup</span>”</a> if you need more than 4
levels. Pod::2::DocBook only looks at relative heading
levels to determine nesting. For example, this bit of Pod:
</p><pre class="screen">=head1 1
Contents of section 1
=head2 1.1
Contents of section 1.1</pre><p>
and this bit of Pod:
</p><pre class="screen">=head1 1
Contents of section 1
=head3 1.1
Contents of section 1.1</pre><p>
both produce the same DocBook markup, which will look
something like this:
</p><pre class="screen"><section id="article-My-Article-1"><title>1</title>
<para>
Contents of section 1
</para>
<section id="article-My-Article-1-1"><title>1.1</title>
<para>
Contents of section 1.1
</para>
</section>
</section></pre><p>
Note that Pod::2::DocBook automatically generates section
identifiers from your doctype, document title and section
title. It does the same when you make internal links (see
<a class="link" href="#ID-4570e0095b6f0df50bd649c88a7ea0ec" title="Formatting Codes">“<span class="quote">Formatting
Codes</span>”</a>, ensuring that if you supply the same
link text as you did for the section title, the resulting
identifiers will be the same.
</p></dd><dt><span class="term"><a name="ID-a29817cd6c532b9cf9f72ccd5a8af107"></a><code class="literal">=over indentlevel</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-b7474e185cfa92d33689733c8ce3b9a3"></a><code class="literal">=item stuff...</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-c825f1b04270d14bbc800bf886c61e69"></a><code class="literal">=back</code></span></dt><dd><p>
<code class="literal">=over</code> ...
<code class="literal">=back</code> regions
are somewhat complex, in that they can lead to a variety of
DocBook constructs. In every case, <span class="italic">indentlevel</span> is ignored by
Pod::2::DocBook, since that's best left to your
stylesheets.
</p><p>
An <code class="literal">=over</code> ...
<code class="literal">=back</code> region
with no <code class="literal">=item</code>s
represents indented text and maps directly to a DocBook
<span class="italic">blockquote</span> element.
Given this source:
</p><pre class="screen">=over 4
This text should be indented.
=back</pre><p>
Pod::2::DocBook will produce DocBook markup similar to
this:
</p><pre class="screen"><blockquote>
<para>
This text should be indented.
</para>
</blockquote></pre><p>
Inside an <code class="literal">=over</code>
... <code class="literal">=back</code>
region, <code class="literal">=item</code>
commands generate lists. The text that follows the first
<code class="literal">=item</code> determines
the type of list that will be output:
</p><p>
</p><div class="itemizedlist"><ul type="disc"><li><p>
"*" (an asterisk) produces <span class="bold"><strong><itemizedlist></strong></span>
</p></li><li><p>
"1" or "1." produces <span class="bold"><strong><orderedlist numeration="arabic"></strong></span>
</p></li><li><p>
"a" or "a." produces <span class="bold"><strong><orderedlist numeration="loweralpha"></strong></span>
</p></li><li><p>
"A" or "A." produces <span class="bold"><strong><orderedlist numeration="upperalpha"></strong></span>
</p></li><li><p>
"i" or "i." produces <span class="bold"><strong><orderedlist numeration="lowerroman"></strong></span>
</p></li><li><p>
"I" or "I." produces <span class="bold"><strong><orderedlist numeration="upperroman"></strong></span>
</p></li><li><p>
anything else produces <span class="bold"><strong><variablelist></strong></span>
</p></li></ul></div><p>
</p><p>
Since the output from each of these is relatively verbose,
the best way to see examples is to actually render some Pod
into DocBook.
</p></dd><dt><span class="term"><a name="ID-b99bd80afde7cd34dd41f6365b2c0dda"></a><code class="literal">=pod</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-e87c9217da2f3fa2056ae8e849b624e4"></a><code class="literal">=cut</code></span></dt><dd><p>
<span class="citerefentry"><span class="refentrytitle">Pod::Parser</span></span> recognizes these commands, and, therefore,
so does Pod::2::DocBook, but they don't produce any output.
</p></dd><dt><span class="term"><a name="ID-12a693bf1d5f1aed0a9c9d54fd67510c"></a><code class="literal">=begin formatname</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-2c0052b81794e3ad8d577da4effb8add"></a><code class="literal">=end formatname</code></span></dt><dd><p></p></dd><dt><span class="term"><a name="ID-370265883b52083e54361edd4d8b22c6"></a><code class="literal">=for formatname text...</code></span></dt><dd><p>
Pod::2::DocBook supports two formats: <span class="bold"><strong>docbook</strong></span>, explained in <a class="link" href="#ID-196a22a8c2df08c5124ac933228893c0" title="Embedded DocBook Markup">“<span class="quote">Embedded
DocBook Markup</span>”</a>, and <span class="bold"><strong>table</strong></span>, explained in <a class="link" href="#ID-b46a76f311a349310b340a24793584ee" title="Simple Tables">“<span class="quote">Simple
Tables</span>”</a>.
</p></dd><dt><span class="term"><a name="ID-0232a1220e1e79778e28ea38b236ea80"></a><code class="literal">=encoding encodingname</code></span></dt><dd><p>
This command is currently not supported. If
Pod::2::DocBook encounters a document that contains
<code class="literal">=encoding</code>, it
will ignore the command and report an error (<a class="link" href="#ID-06a4ed7d4d26178d25881a051e14fb93">“<span class="quote">unknown
command `%s' at line %d in file %s</span>”</a>).
</p></dd></dl></div><p>
</p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-196a22a8c2df08c5124ac933228893c0"></a>Embedded DocBook Markup</h6></div></div></div><p>
There are a wide range of DocBook structures for which there is
no Pod equivalent. For these, you will have to provide your own
markup using <span class="bold"><strong>=begin docbook</strong></span> ...
<span class="bold"><strong>=end docbook</strong></span> or <span class="bold"><strong>=for docbook ...</strong></span>. Pod::2::DocBook will
directly output whatever text you provide, unprocessed, so it's
up to you to ensure that it's valid DocBook.
</p><p>
Images, footnotes and many inline elements are obvious candidates
for embedded markup. Another possible use is nesting sections
more than four-deep. For example, given this source:
</p><pre class="screen">=head1 1
This is Section 1
=head2 1.1
This is Section 1.1
=head3 1.1.1
This is Section 1.1.1
=head4 1.1.1.1
This is Section 1.1.1.1
=begin docbook
<section>
<title>1.1.1.1.1</title>
<para>This is Section 1.1.1.1.1</para>
</section>
=end docbook</pre><p>
Pod::2::DocBook will generate DocBook markup similar to this:
</p><pre class="screen">
<section id="article-My-Article-1"><title>1</title>
<para>
This is Section 1
</para>
<section id="article-My-Article-1-1"><title>1.1</title>
<para>
This is Section 1.1
</para>
<section id="article-My-Article-1-1-1"><title>1.1.1</title>
<para>
This is Section 1.1.1
</para>
<section id="article-My-Article-1-1-1-1"><title>1.1.1.1</title>
<para>
This is Section 1.1.1.1
</para>
<section>
<title>1.1.1.1.1</title>
<para>This is Section 1.1.1.1.1</para>
</section>
</section>
</section>
</section>
</section></pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-b46a76f311a349310b340a24793584ee"></a>Simple Tables</h6></div></div></div><p>
Pod::2::DocBook also provides a mechanism for generating basic
tables with <span class="bold"><strong>=begin table</strong></span>
and <span class="bold"><strong>=end docbook</strong></span>. If you
have simple tabular data or a CSV file exported from some
application, Pod::2::DocBook makes it easy to generate a table
from your data. The syntax is intended to be simple, so
DocBook's entire table feature set is not represented, but even
if you do need more complex table markup than Pod::2::DocBook
produces, you can rapidly produce some markup which you can
hand-edit and then embed directly in your Pod with <span class="bold"><strong>=begin docbook</strong></span> ... <span class="bold"><strong>=end docbook</strong></span>. Each table definition
spans multiple lines, so there is no equivalent <span class="bold"><strong>=for table</strong></span> command.
</p><p>
The first line of a table definition gives the table's title.
The second line gives a list of comma-separated column
specifications (really just column alignments), each of which can
be <span class="bold"><strong>left</strong></span>, <span class="bold"><strong>center</strong></span> or <span class="bold"><strong>right</strong></span>. The third line is a list of
comma-separated column headings, and every subsequent line
consists of comma-separated row data. If any of your data
actually contain commas, you can enclose them in double quotes;
if they also contain double quotes, you must escape the inner
quotes with backslashes (typical CSV stuff).
</p><p>
Here's an example:
</p><pre class="screen">=begin table
Sample Table
left,center,right
Powers of Ten,Planets,Dollars
10,Earth,$1
100,Mercury,$5
1000,Mars,$10
10000,Venus,$20
100000,"Jupiter, Saturn",$50
=end table</pre><p>
And here's what Pod::2::DocBook would do with it:
</p><pre class="screen"><table>
<title>Sample Table</title>
<tgroup cols="3">
<colspec align="left">
<colspec align="center">
<colspec align="right">
<thead>
<row>
<entry>Powers of Ten</entry>
<entry>Planets</entry>
<entry>Dollars</entry>
</row>
</thead>
<tbody>
<row>
<entry>10</entry>
<entry>Earth</entry>
<entry>$1</entry>
</row>
<row>
<entry>100</entry>
<entry>Mercury</entry>
<entry>$5</entry>
</row>
<row>
<entry>1000</entry>
<entry>Mars</entry>
<entry>$10</entry>
</row>
<row>
<entry>10000</entry>
<entry>Venus</entry>
<entry>$20</entry>
</row>
<row>
<entry>100000</entry>
<entry>Jupiter, Saturn</entry>
<entry>$50</entry>
</row>
</tbody>
</tgroup>
</table></pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ID-4570e0095b6f0df50bd649c88a7ea0ec"></a>Formatting Codes</h6></div></div></div><p>
Pod formatting codes render directly into DocBook as inline
elements:
</p><p>
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">I<text></code>
</p><pre class="screen"><emphasis role="italic">text</emphasis></pre></li><li><p>
<code class="literal">B<text></code>
</p><pre class="screen"><emphasis role="bold">text</emphasis></pre></li><li><p>
<code class="literal">C<code></code>
</p><pre class="screen"><literal role="code"><![CDATA[code]] ></literal></pre></li><li><p>
<code class="literal">L<name></code>
</p><pre class="screen"><citerefentry><refentrytitle>name</refentrytitle></citerefentry></pre></li><li><p>
<code class="literal">L<name(n)></code>
</p><pre class="screen"><citerefentry><refentrytitle>name</refentrytitle>
<manvolnum>n</manvolnum></citerefentry>
</pre></li><li><p>
<code class="literal">L<name/"sec"></code> or
<code class="literal">L<name/sec></code>
</p><pre class="screen"><quote>sec</quote> in <citerefentry>
<refentrytitle>name</refentrytitle></citerefentry></pre></li><li><p>
<code class="literal">L<name(n)/"sec"></code>
or <code class="literal">L<name(n)/sec></code>
</p><pre class="screen"><quote>sec</quote> in <citerefentry>
<refentrytitle>name</refentrytitle><manvolnum>n</manvolnum>
</citerefentry></pre></li><li><p>
<code class="literal">L</"sec"></code> or
<code class="literal">L</sec></code> or
<code class="literal">L<"sec"></code>
</p><pre class="screen"><link linkend="article-My-Article-sec"><quote>sec</quote></link></pre></li><li><p>
<code class="literal">L<text|name></code>
</p><pre class="screen">text</pre></li><li><p>
<code class="literal">L<text|name/"sec"></code>
or <code class="literal">L<text|name/sec></code>
</p><pre class="screen">text</pre></li><li><p>
<code class="literal">L<text|/"sec"></code> or
<code class="literal">L<text|/sec></code> or
<code class="literal">L<text|"sec"></code>
</p><pre class="screen"><link linkend="article-My-Article-sec"><quote>text</quote></link></pre></li><li><p>
<code class="literal">L<scheme:...></code>
</p><pre class="screen"><ulink url="scheme:...">scheme:...</ulink></pre></li><li><p>
<code class="literal">E<verbar></code>
</p><pre class="screen">|</pre></li><li><p>
<code class="literal">E<sol></code>
</p><pre class="screen">/</pre></li><li><p>
<code class="literal">E<number></code>
</p><pre class="screen">&#number;</pre></li><li><p>
any other <code class="literal">E<escape></code>
</p><pre class="screen">&escape;</pre></li><li><p>
<code class="literal">F<filename></code>
</p><p>
<filename>filename</filename>
</p></li><li><p>
<code class="literal">S<text with
spaces></code>
</p><pre class="screen">text&nbsp;with&nbsp;spaces</pre></li><li><p>
<code class="literal">X<topic name></code>
</p><p>
<indexterm><primary>topic
name</primary></indexterm>
</p></li></ul></div><p>
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-27c872f13298ab7cc42f6e59e6373302"></a>DIAGNOSTICS</h5></div></div></div><p>
Pod::2::DocBook makes every possible effort to produce valid DocBook
markup, even with malformed POD source. Any processing errors will
be noted in comments at the end of the output document. Even when
errors occur, Pod::2::DocBook always reads the entire input document
and never exits with a non-zero status.
</p><pre class="screen"></pre><p>
</p><div class="variablelist"><dl><dt><span class="term"><a name="ID-06a4ed7d4d26178d25881a051e14fb93"></a>unknown command `%s' at line %d in file %s</span></dt><dd><p>
See “<span class="quote">Command Paragraph</span>” in <span class="citerefentry"><span class="refentrytitle">perlpod</span></span> for a
list of valid commands. The command referenced in the error
message was ignored.
</p></dd><dt><span class="term"><a name="ID-31e05a35ed3fb88d0fd4ebd1102beef8"></a>formatting code `%s' nested within `%s' at line %d in file %s</span></dt><dd><p>
See “<span class="quote">Formatting Codes</span>” in <span class="citerefentry"><span class="refentrytitle">perlpod</span></span> for
details on which formatting codes can be nested. The
offending code was translated into the output document as the
raw text inside its angle brackets.
</p></dd><dt><span class="term"><a name="ID-fd700e35a09475c7b3cd7fea987c59b4"></a>unknown formatting code `%s' at line in file %s</span></dt><dd><p>
The input contained a formatting code not listed in
<span class="citerefentry"><span class="refentrytitle">perlpod</span></span>; it was translated into the output document
as the raw text inside the angle brackets.
</p></dd><dt><span class="term"><a name="ID-be52c2023179b57a3ca12bfb530310a6"></a>empty L<> at line %d in file %s</span></dt><dd><p>
Self-explanatory.
</p></dd><dt><span class="term"><a name="ID-a8d63ea0972a3d6d803146eab91ef3a5"></a>invalid escape `%s' at line %d in file %s</span></dt><dd><p>
Self-explanatory; it was translated into the output document
as the raw text inside the angle brackets.
</p></dd><dt><span class="term"><a name="ID-e06be26197418681472933e1fb03680d"></a>=item must be inside an =over ... =back section at line %d in file %s</span></dt><dd><p>
Self-explanatory. The `=item' referenced in the error was
ignored.
</p></dd><dt><span class="term"><a name="ID-379e30361b6d059c44669fbda3b1751f"></a>`=end %s' found but current region opened with `=begin %s'</span></dt><dd><p>
The closest `=end' command to the referenced `=begin' didn't
match; processing continued as if the mismatched `=end'
wasn't there.
</p></dd><dt><span class="term"><a name="ID-feef62d526bd09b2ab8a40eb49c62b03"></a>no matching `=end' for `=begin %s'</span></dt><dd><p>
Pod::2::DocBook reached the end of its input without finding
an `=end' command to match the `=begin' referenced in the
error; end-of-file processing continued.
</p></dd><dt><span class="term"><a name="ID-9affd676b2db4a912b944ab88246477b"></a>unknown colspec `%s' in table at line %d in file %s</span></dt><dd><p>
See <a class="link" href="#ID-b46a76f311a349310b340a24793584ee" title="Simple Tables">“<span class="quote">Simple
Tables</span>”</a> for a list of supported column
specifications.
</p></dd><dt><span class="term"><a name="ID-81156132f37558444485f99022408011"></a>encountered unknown state `%s' (this should never happen)</span></dt><dd><p>
The state referred to is an internal variable used to
properly manage nested DocBook structures. You should indeed
never see this message, but if you do, you should contact the
module's author.
</p></dd></dl></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-d5349a6e5f4c1526564fb292de4e7d2d"></a>SEE ALSO</h5></div></div></div><p>
<span class="citerefentry"><span class="refentrytitle">pod2docbook</span></span>, <span class="citerefentry"><span class="refentrytitle">perlpod</span></span>,
<span class="citerefentry"><span class="refentrytitle">Pod::DocBook</span></span>, SVN repo - <a class="ulink" href="https://cle.sk/repos/pub/cpan/Pod-2-DocBook/" target="_top">https://cle.sk/repos/pub/cpan/Pod-2-DocBook/</a>,
<a class="ulink" href="http://www.ohloh.net/projects/pod-2-docbook" target="_top">http://www.ohloh.net/projects/pod-2-docbook</a>,
<code class="filename">doc/</code> +
<code class="filename">examples/pod2docbook-docbook/</code> for
Pod::2::DocBook DocBook documentation
</p><p>
DocBook related links: <a class="ulink" href="http://www.docbook.org/" target="_top">http://www.docbook.org/</a>, <a class="ulink" href="http://www.sagehill.net/docbookxsl/" target="_top">http://www.sagehill.net/docbookxsl/</a>,
<a class="ulink" href="http://developers.cogentrts.com/cogent/prepdoc/pd-axfrequentlyuseddocbooktags.html" target="_top">http://developers.cogentrts.com/cogent/prepdoc/pd-axfrequentlyuseddocbooktags.html</a>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-d31c735431a53065e998e51b8caaeab9"></a>AUTHOR</h5></div></div></div><p>
Alligator Descartes <descarte@symbolstone.org> wrote a module
called Pod::2::DocBook, which was later maintained by Jan Iven
<jan.iven@cern.ch>. That module was based on the original
<span class="citerefentry"><span class="refentrytitle">pod2html</span></span> by Tom Christiansen <tchrist@mox.perl.com>.
</p><p>
Nandu Shah <nandu@zvolve.com> wrote Pod::DocBook, which is
unrelated to the previous module (even though they both perform the
same function). (<a class="ulink" href="http://search.cpan.org/~nandu/Pod-DocBook-1.2/" target="_top">http://search.cpan.org/~nandu/Pod-DocBook-1.2/</a>)
</p><p>
Jozef Kutej <jkutej@cpan.org> renamed the module to
Pod::2::DocBook because Nandus version was buried in the CPAN archive
as an "UNAUTHORIZED RELEASE".
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-335792c2f7239c818aca02212dab7b2d"></a>COPYRIGHT</h5></div></div></div><p>
Copyright 2004, Nandu Shah <nandu@zvolve.com>
</p><p>
Copyright 2008, Jozef Kutej <jkutej@cpan.org>
</p><p>
This library is free software; you may redistribute it and/or modify
it under the same terms as Perl itself
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="dev.scripts"></a>Scripts</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2602238"></a>pod2docbook script</h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-3f9fd1472d4b63414628e99fbbf40a3c"></a>NAME</h5></div></div></div><p>
pod2docbook - Convert POD data to DocBook SGML
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-c570e7e6895f59333803d984bf8f72cf"></a>SYNOPSIS</h5></div></div></div><p>
pod2docbook [<span class="bold"><strong>--help</strong></span>] [<span class="bold"><strong>--doctype</strong></span>=<span class="bold"><strong>article</strong></span>|<span class="bold"><strong>chapter</strong></span>|<span class="bold"><strong>section</strong></span>|<span class="bold"><strong>refentry</strong></span>] [<span class="bold"><strong>--title</strong></span>=<span class="italic">title</span>] [<span class="bold"><strong>--spaces</strong></span>=<span class="italic"># spaces per indent level</span>]
[<span class="bold"><strong>--fix-double-quotes</strong></span>] [<span class="bold"><strong>--no-header</strong></span>] [<span class="italic">infile</span> [<span class="italic">outfile</span>]]
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-55a4467b5df1806d79641429c6a6a92d"></a>DESCRIPTION</h5></div></div></div><p>
<span class="bold"><strong>pod2docbook</strong></span> converts files from pod
format (see <span class="citerefentry"><span class="refentrytitle">perlpod</span></span>) to DocBook 4.2 SGML (see <a class="ulink" href="http://www.docbook.org/" target="_top">http://www.docbook.org/</a>). The
program itself is merely a driver for the Pod::2::DocBook class; if
you're interested in details of pod-to-SGML translation see
<span class="citerefentry"><span class="refentrytitle">Pod::2::DocBook</span></span>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-06baa79251d0ec00517751c983bf8ff6"></a>OPTIONS AND ARGUMENTS</h5></div></div></div><p>
</p><div class="variablelist"><dl><dt><span class="term"><a name="ID-a8967fcc30bb001f2350900feb7c03d9"></a>[<span class="bold"><strong>--help</strong></span>]</span></dt><dd><p>
Print usage and exit.
</p></dd><dt><span class="term"><a name="ID-3c1c62438ed457c09598171b3fe9c00b"></a>[<span class="bold"><strong>--doctype</strong></span>=<span class="bold"><strong>article</strong></span>|<span class="bold"><strong>chapter</strong></span>|<span class="bold"><strong>section</strong></span>|<span class="bold"><strong>refentry</strong></span>]</span></dt><dd><p>
Specifies the document type for the output file; the default
is <span class="bold"><strong>section</strong></span>.
</p></dd><dt><span class="term"><a name="ID-570fbc767342046eb01e3bffde2969f9"></a>[<span class="bold"><strong>--title</strong></span>=<span class="italic">title</span>]</span></dt><dd><p>
Specifies the document title. The default is <span class="italic">infile</span>, if it is supplied, or empty
string otherwise.
</p></dd><dt><span class="term"><a name="ID-8d4021783c0a96bedf39327356ca1afc"></a>[<span class="bold"><strong>--spaces</strong></span>=<span class="italic"># spaces per indent level</span>]</span></dt><dd><p>
Specifies the number of spaces per indent level in the SGML
output; the default is 2.
</p></dd><dt><span class="term"><a name="ID-d23c7a5a0ef01becc3383a41832805d7"></a>[<span class="bold"><strong>--fix-double-quotes</strong></span>]</span></dt><dd><p>
Replace pairs of double quotes in regular paragraphs with
<quote> and </quote> (see <span class="citerefentry"><span class="refentrytitle">Pod::2::DocBook</span></span> for details).
</p></dd><dt><span class="term"><a name="ID-5e06e9c0f478339bb7cbe9acc5e2b398"></a>[<span class="bold"><strong>--no-header</strong></span>]</span></dt><dd><p>
Omit the DOCTYPE line from the output.
</p></dd><dt><span class="term"><a name="ID-0d359410606c76062833b9f11b7aeff6"></a><span class="italic">infile</span></span></dt><dd><p>
The name of the file from which to read pod source; if not
supplied, STDIN is used for input.
</p></dd><dt><span class="term"><a name="ID-ecbca8badc8eb33c7394c3d1af24c5e7"></a><span class="italic">outfile</span></span></dt><dd><p>
The name of the file to which to write SGML; if not supplied,
STDOUT is used for output.
</p></dd></dl></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-19d718c30ac9b26e61d8b6bc474a80cf"></a>SEE ALSO</h5></div></div></div><p>
<span class="citerefentry"><span class="refentrytitle">perlpod</span></span>, <span class="citerefentry"><span class="refentrytitle">Pod::2::DocBook</span></span>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-a6c603fa80cf955cfb725b8e6c4e4919"></a>AUTHOR</h5></div></div></div><p>
Nandu Shah <nandu@zvolve.com>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ID-93370b077bce46e959d9811ad4c914bb"></a>COPYRIGHT</h5></div></div></div><p>
Copyright 2004, Nandu Shah <nandu@zvolve.com>
</p><p>
This program is free software; you may redistribute it and/or modify
it under the same terms as Perl itself
</p></div></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-appendix-a"></a>Chapter 4. Open questions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2599764">some terms used in this book</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2599764"></a>some terms used in this book</h2></div></div></div><div class="variablelist"><p class="title"><b>terms</b></p><dl><dt><span class="term">POD</span></dt><dd><p>
Plain Old Documentation
</p></dd><dt><span class="term">DocBook</span></dt><dd><p>
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top">--- to be done ---</td></tr></table></div><p>
</p></dd></dl></div></div></div></div></body></html>