/ 
Pod-2-DocBook-0.03
River stage zero No dependents
/ doc/Pod-2-DocBook.html

1.1

Contents of section 1.1</pre><p> and this bit of Pod: </p><pre class="screen">=head1 1

Contents of section 1

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">&lt;section id="article-My-Article-1"&gt;&lt;title&gt;1&lt;/title&gt; &lt;para&gt; Contents of section 1 &lt;/para&gt; &lt;section id="article-My-Article-1-1"&gt;&lt;title&gt;1.1&lt;/title&gt; &lt;para&gt; Contents of section 1.1 &lt;/para&gt; &lt;/section&gt; &lt;/section&gt;</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">&#8220;<span class="quote">Formatting Codes</span>&#8221;</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">&lt;blockquote&gt; &lt;para&gt; This text should be indented. &lt;/para&gt; &lt;/blockquote&gt;</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>&lt;itemizedlist&gt;</strong></span> </p></li><li><p> "1" or "1." produces <span class="bold"><strong>&lt;orderedlist numeration="arabic"&gt;</strong></span> </p></li><li><p> "a" or "a." produces <span class="bold"><strong>&lt;orderedlist numeration="loweralpha"&gt;</strong></span> </p></li><li><p> "A" or "A." produces <span class="bold"><strong>&lt;orderedlist numeration="upperalpha"&gt;</strong></span> </p></li><li><p> "i" or "i." produces <span class="bold"><strong>&lt;orderedlist numeration="lowerroman"&gt;</strong></span> </p></li><li><p> "I" or "I." produces <span class="bold"><strong>&lt;orderedlist numeration="upperroman"&gt;</strong></span> </p></li><li><p> anything else produces <span class="bold"><strong>&lt;variablelist&gt;</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">&#8220;<span class="quote">Embedded DocBook Markup</span>&#8221;</a>, and <span class="bold"><strong>table</strong></span>, explained in <a class="link" href="#ID-b46a76f311a349310b340a24793584ee" title="Simple Tables">&#8220;<span class="quote">Simple Tables</span>&#8221;</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">&#8220;<span class="quote">unknown command `%s' at line %d in file %s</span>&#8221;</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

1.1

This is Section 1.1

1.1.1

This is Section 1.1.1

1.1.1.1

This is Section 1.1.1.1

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 287:

Non-ASCII character seen before =encoding in 'class="bold"><strong>&lt;orderedlist numeration="arabic"&gt;</strong></span>'. Assuming CP1252

Around line 351:

'=end docbook</pre><p> Pod::2::DocBook will generate DocBook markup similar to this: </p><pre class="screen">' is invalid. (Stack: =begin docbook)

Around line 413:

'=end table</pre><p> And here's what Pod::2::DocBook would do with it: </p><pre class="screen">&lt;table&gt; &lt;title&gt;Sample Table&lt;/title&gt; &lt;tgroup cols="3"&gt; &lt;colspec align="left"&gt; &lt;colspec align="center"&gt; &lt;colspec align="right"&gt; &lt;thead&gt; &lt;row&gt; &lt;entry&gt;Powers of Ten&lt;/entry&gt; &lt;entry&gt;Planets&lt;/entry&gt; &lt;entry&gt;Dollars&lt;/entry&gt; &lt;/row&gt; &lt;/thead&gt; &lt;tbody&gt; &lt;row&gt; &lt;entry&gt;10&lt;/entry&gt; &lt;entry&gt;Earth&lt;/entry&gt; &lt;entry&gt;$1&lt;/entry&gt; &lt;/row&gt; &lt;row&gt; &lt;entry&gt;100&lt;/entry&gt; &lt;entry&gt;Mercury&lt;/entry&gt; &lt;entry&gt;$5&lt;/entry&gt; &lt;/row&gt; &lt;row&gt; &lt;entry&gt;1000&lt;/entry&gt; &lt;entry&gt;Mars&lt;/entry&gt; &lt;entry&gt;$10&lt;/entry&gt; &lt;/row&gt; &lt;row&gt; &lt;entry&gt;10000&lt;/entry&gt; &lt;entry&gt;Venus&lt;/entry&gt; &lt;entry&gt;$20&lt;/entry&gt; &lt;/row&gt; &lt;row&gt; &lt;entry&gt;100000&lt;/entry&gt; &lt;entry&gt;Jupiter, Saturn&lt;/entry&gt; &lt;entry&gt;$50&lt;/entry&gt; &lt;/row&gt; &lt;/tbody&gt; &lt;/tgroup&gt; &lt;/table&gt;</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&lt;text&gt;</code> </p><pre class="screen">&lt;emphasis role="italic"&gt;text&lt;/emphasis&gt;</pre></li><li><p> <code class="literal">B&lt;text&gt;</code> </p><pre class="screen">&lt;emphasis role="bold"&gt;text&lt;/emphasis&gt;</pre></li><li><p> <code class="literal">C&lt;code&gt;</code> </p><pre class="screen">&lt;literal role="code"&gt;&lt;![CDATA[code]] &gt;&lt;/literal&gt;</pre></li><li><p> <code class="literal">L&lt;name&gt;</code> </p><pre class="screen">&lt;citerefentry&gt;&lt;refentrytitle&gt;name&lt;/refentrytitle&gt;&lt;/citerefentry&gt;</pre></li><li><p> <code class="literal">L&lt;name(n)&gt;</code> </p><pre class="screen">&lt;citerefentry&gt;&lt;refentrytitle&gt;name&lt;/refentrytitle&gt; &lt;manvolnum&gt;n&lt;/manvolnum&gt;&lt;/citerefentry&gt;' is invalid. (Stack: =begin docbook)