Document Types

The refentry 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 NAME and SYNOPSIS sections. To accommodate this, Pod::DocBook performs extra processing on the Pod source when the doctype is set to refentry. 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 NAME and SYNOPSIS headers are both =head1s, that "NAME" and "SYNOPSIS" are both uppercase, and that =head1 NAME is the first line of Pod source.

Ordinary Paragraphs

For example, given this Pod paragraph:

  Here is some text with I<italics> & an ampersand.

Pod::DocBook would produce DocBook markup similar to this:

  <para>
    Here is some text with <emphasis role="italic">italics</emphasis>
    &amp; an ampersand.
  </para>

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::DocBook offers a convenient mechanism for handling double quotes in ordinary paragraphs and letting your SGML toolchain manage their presentation: the fix_double_quotes option to "new()". If this option is set to a true value, Pod::DocBook will replace pairs of double quotes in ordinary paragraphs (and only in ordinary paragraphs) with <quote> and </quote>.

For example, given this Pod paragraph:

  Here is some text with I<italics> & an "ampersand".

Pod::DocBook, with fix_double_quotes set, would produce DocBook markup similar to this:

  <para>
    Here is some text with <emphasis role="italic">italics</emphasis>
    &amp; an <quote>ampersand</quote>.
  </para>

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 E<quot>, and Pod::DocBook should be able to give you the output you expect. Also, if you have any =begin docbook ... =end docbook regions (see "Embedded DocBook Markup") in your Pod, you are responsible for managing your own quotes in those regions.

Verbatim Paragraphs

For example, given this verbatim paragraph (imagine there's leading whitespace in the source):

  my $i = 10;
  while (<> && $i--) {
      print "$i: $_";
  }

Pod::DocBook would produce DocBook markup similar to this:

  <screen><![CDATA[my $i = 10;
  while (<> && $i--) {
      print "$i: $_";
  }]] ></screen>

Multiple contiguous verbatim paragraphs are treated as a single screen element, with blank lines separating the paragraphs, as dictated by perlpodspec.

Command Paragraphs

"=head1 Heading Text"

"=head2 Heading Text"

"=head3 Heading Text"

"=head4 Heading Text"

All of the Pod heading commands produce DocBook section elements, with the heading text as titles. Pod::DocBook (perlpod) only allows for 4 heading levels, but DocBook allows arbitrary nesting; see "Embedded DocBook Markup" if you need more than 4 levels. Pod::DocBook only looks at relative heading levels to determine nesting. For example, this bit of Pod:

  =head1 1

  Contents of section 1

  =head2 1.1

  Contents of section 1.1
    

and this bit of Pod:

  =head1 1

  Contents of section 1

  =head3 1.1

  Contents of section 1.1
    

both produce the same DocBook markup, which will look something like this:

  <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>
    

Note that Pod::DocBook automatically generates section identifiers from your doctype, document title and section title. It does the same when you make internal links (see "Formatting Codes", ensuring that if you supply the same link text as you did for the section title, the resulting identifiers will be the same.

"=over indentlevel"

"=item stuff..."

"=back"

"=over" ... "=back" regions are somewhat complex, in that they can lead to a variety of DocBook constructs. In every case, indentlevel is ignored by Pod::DocBook, since that's best left to your stylesheets.

An "=over" ... "=back" region with no "=item"s represents indented text and maps directly to a DocBook blockquote element. Given this source:

  =over 4

  This text should be indented.

  =back
    

Pod::DocBook will produce DocBook markup similar to this:

  <blockquote>
    <para>
      This text should be indented.
    </para>
  </blockquote>
    

Inside an "=over" ... "=back" region, "=item" commands generate lists. The text that follows the first "=item" determines the type of list that will be output:

"=pod"

"=cut"

Pod::Parser recognizes these commands, and, therefore, so does Pod::DocBook, but they don't produce any output.

"=begin formatname"

"=end formatname"

"=for formatname text..."

Pod::DocBook supports two formats: docbook, explained in "Embedded DocBook Markup", and table, explained in "Simple Tables".

"=encoding encodingname"

This command is currently not supported. If Pod::DocBook encounters a document that contains "=encoding", it will ignore the command and report an error ("unknown command `%s' at line %d in file %s").

Embedded DocBook Markup

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 =begin docbook ... =end docbook or =for docbook .... Pod::DocBook will directly output whatever text you provide, unprocessed, so it's up to you to ensure that it's valid DocBook.

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:

  =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

Pod::DocBook will generate DocBook markup similar to this:

    <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>

Simple Tables

Pod::DocBook also provides a mechanism for generating basic tables with =begin table and =end docbook. If you have simple tabular data or a CSV file exported from some application, Pod::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::DocBook produces, you can rapidly produce some markup which you can hand-edit and then embed directly in your Pod with =begin docbook ... =end docbook. Each table definition spans multiple lines, so there is no equivalent =for table command.

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 left, center or right. 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).

Here's an example:

  =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

And here's what Pod::DocBook would do with it:

  <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>

Formatting Codes

• "I<text>"

    <emphasis role="italic">text</emphasis>
      

• "B<text>"

    <emphasis role="bold">text</emphasis>
      

• "C<code>"

    <literal role="code"><![CDATA[code]] ></literal>
      

• "L<name>"

    <citerefentry><refentrytitle>name</refentrytitle></citerefentry>
      

• "L<name(n)>"

    <citerefentry><refentrytitle>name</refentrytitle>
    <manvolnum>n</manvolnum></citerefentry>
      

• "L<name/"sec">" or "L<name/sec>"

    <quote>sec</quote> in <citerefentry>
    <refentrytitle>name</refentrytitle></citerefentry>
      

• "L<name(n)/"sec">" or "L<name(n)/sec>"

    <quote>sec</quote> in <citerefentry>
    <refentrytitle>name</refentrytitle><manvolnum>n</manvolnum>
    </citerefentry>
      

• "L</"sec">" or "L</sec>" or "L<"sec">"

    <link linkend="article-My-Article-sec"><quote>sec</quote></link>
      

• "L<text|name>"

    text
      

• "L<text|name/"sec">" or "L<text|name/sec>"

    text
      

• "L<text|/"sec">" or "L<text|/sec>" or "L<text|"sec">"

    <link linkend="article-My-Article-sec"><quote>text</quote></link>
      

• "L<scheme:...>"

    <ulink url="scheme:...">scheme:...</ulink>
      

• "E<verbar>"

    |
      

• "E<sol>"

    /
      

• "E<number>"

    &#number;
      

• any other "E<escape>"

    &escape;
      

• "F<filename>"

  <filename>filename</filename>

• "S<text with spaces>"

   text with spaces
      

• "X<topic name>"

  <indexterm><primary>topic name</primary></indexterm>