~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

      <h2>Links:</h2>

      <ul>

        <li><a href="http://search.cpan.org">CPAN</a></li>

        <li><a href="http://www.perl.com">Perl.com</a></li>

        <li><a href="http://www.pm.org">Perl Mongers</a></li>

        <li><a href="http://www.perlmonks.org">Perl Monks</a></li>

        <li><a href="http://planet.perl.org">Planet Perl</a></li>

      <ul>

        <li>Site maintained by<br><a href="http://perl.jonallen.info">Jon Allen</a>

            (<a href="http://perl.jonallen.info">JJ</a>)</li>

        <li class="spaced">See the <a href="http://perl.jonallen.info/projects/perldoc">project page</a> for

        more details</li>

      </ul>

    <div id="centerContent">

      <div id="contentHeader">

        <div id="contentHeaderLeft"><a href="#" onClick="showLeft()">Show navigation</a></div>

        <div id="contentHeaderRight"><a href="#" onClick="showRight()">Show toolbar</a></div>

      </div>

      <div id="breadCrumbs"><a href="index.html">Home</a> &gt; <a href="index-language.html">Language reference</a> &gt; perlpod</div>

      <script language="JavaScript">fromSearch();</script>

 

 </h1>

<p>perlpod - the Plain Old Documentation format</p>

<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>

<a href="#Ordinary-Paragraph">ordinary</a>,

<a href="#Verbatim-Paragraph">verbatim</a>, and 

<a href="#Command-Paragraph">command</a>.</p>

</h2>

<p>Most paragraphs in your documentation will be ordinary blocks

of text, like this one.  You can simply type in your text without

like being rewrapped, probably put into a proportionally spaced

font, and maybe even justified.</p>

<p>You can use formatting codes in ordinary paragraphs, for <b>bold</b>,

, <a href="perlfaq.html">hyperlinks</a>, and more.  Such

codes are explained in the "<a href="#Formatting-Codes">Formatting Codes</a>"

section, below.</p>

 </h2>

<p>Verbatim paragraphs are usually used for presenting a codeblock or

other text which does not require any special parsing or formatting,

be on 8-column boundaries.  There are no special formatting codes,

so you can't italicize or anything like that.  A \ means \, and

nothing else.</p>

</h2>

<p>A command paragraph is used for special treatment of whole chunks

of text, usually as headings or parts of lists.</p>

    =encoding type

    =cut</pre><p>To explain them each in detail:</p>

<ul>

 

   

   </b>

</li>

</b>

<p>Head1 through head4 produce headings, head1 being the highest

level.  The text in the rest of this paragraph is the content of the

heading.  For example:</p>

<p>The text "Object Attributes" comprises the heading there.  (Note that

head3 and head4 are recent additions, not supported in older Pod

translators.)  The text in these heading commands can use

formatting codes, as seen here:</p>

<p>Such commands are explained in the

"<a href="#Formatting-Codes">Formatting Codes</a>" section, below.</p>

</li>

 

     </b>

</li>

</b>

</li>

<li><a name="'%3dback'"></a><b><code class="inline"><span class="pd">=back</span></code>

one em is the width of an "M" in the document's base font) or roughly

comparable units; if there is no <i>indentlevel</i> option, it defaults

to four.  (And some formatters may just ignore whatever <i>indentlevel</i>

, you may

use formatting codes, as seen here:</p>

<p>Such commands are explained in the

"<a href="#Formatting-Codes">Formatting Codes</a>" section, below.</p>

<p>Note also that there are some basic rules to using "=over" ...

</li>

</ul>

</li>

 

 </b>

<p>To end a Pod block, use a blank line,

this is where Perl code is resuming.  (The blank line before the "=cut"

is not technically necessary, but many older Pod processors require it.)</p>

</li>

 

 </b>

<p>The "=pod" command by itself doesn't do much of anything, but it

Pod block starts with <i>any</i> command paragraph, so a "=pod" command is

usually used just when you want to start a Pod block with an ordinary

paragraph or a verbatim paragraph.  For example:</p>

<pre class="verbatim"><a name="stuff"></a>  sub <span class="m">stuff</span> <span class="s">{</span>

    ...

  <span class="s">}</span></pre>

<pre class="verbatim">  Remember to check its return value, as in:</pre><pre class="verbatim">    <span class="i">stuff</span><span class="s">(</span><span class="s">)</span> || <a class="l_k" href="functions/die.html">die</a> <span class="q">&quot;Couldn&#39;t do stuff!&quot;</span><span class="sc">;</span></pre>

</li>

 

     </b>

</li>

</b>

</li>

</b>

<p>For, begin, and end will let you have regions of text/code/data that

are not generally interpreted as normal Pod text, but are passed

formatter that can use that format will use the region, otherwise it

will be completely ignored.</p>

<p>A command "=begin <i>formatname</i>", some paragraphs, and a

is meant for formatters that understand the special format

called <i>formatname</i>.  For example,</p>

<pre class="verbatim">  &lt;hr&gt; &lt;img src="thang.png"&gt;

<p>The command "=for <i>formatname</i> <i>text...</i>"

specifies that the remainder of just this paragraph (starting

<pre class="verbatim">  =for html &lt;hr&gt; &lt;img src="thang.png"&gt;

  &lt;p&gt; This is a raw HTML paragraph &lt;/p&gt;</pre><p>This means the same thing as the above "=begin html" ... "=end html"

region.</p>

after the "=begin" command and a blank line before the "=end"

command.</p>

<p>Here are some examples of how to use these:</p>

<pre class="verbatim">    ---------------

    |  foo        |

    |        bar  |

<p>Some format names that formatters currently are known to accept

include "roff", "man", "latex", "tex", "text", and "html".  (Some

formatters will treat some of these as synonyms.)</p>

<p>A format name of "comment" is common for just making notes (presumably

to yourself) that won't appear in any formatted version of the Pod

document:</p>

<p>Some <i>formatnames</i> will require a leading colon (as in

<code class="inline"><span class="q">&quot;=for :formatname&quot;</span></code>

, or

normal formatting (e.g., may not be a normal-use paragraph, but might

be for formatting as a footnote).</p>

</li>

 

 </b>

<p>This command is used for declaring the encoding of a document.  Most

users won't need this; but if your encoding isn't US-ASCII or Latin-1,

 command early in the document so

that pod formatters will know how to decode the document.  For

<i>encodingname</i>, use a name recognized by the <a href="Encode/Supported.html">Encode::Supported</a>

module.  Examples:</p>

</li>

</ul>

<p>And don't forget, when using any command, that the command lasts up

examples below, you can see that every command needs the blank

line after it, to end its paragraph.</p>

<p>Some examples of lists include:</p>

 

 </h2>

<p>In ordinary paragraphs and in some command paragraphs, various

formatting codes (a.k.a. "interior sequences") can be used:</p>

<ul>

 -- italic text

   </b>

") and parameters

("<code class="inline"><a class="l_k" href="functions/redo.html">redo</a> <span class="j">I</span><span class="q">&lt;LABEL&gt;</span></code>

")</p>

</li>

 -- bold text

   </b>

"), programs

"),

"), and so on

").</p>

</li>

 -- code text

   </b>

<p>Renders code in a typewriter font, or gives some other indication that

") or some other

").</p>

</li>

 -- a hyperlink

   </b>

<p>There are various syntaxes, listed below.  In the syntaxes given,

 cannot contain the characters

'/' and '|'; and any '&lt;' or '&gt;' should be matched.</p>

<ul>

<li>

</p>

).  Note

 should not contain spaces.  This syntax

is also occasionally used for references to UNIX man pages, as in

.</p>

</li>

<li>

</p>

<p>Link to a section in other manual page.  E.g.,

</p>

</li>

<li>

</p>

<p>Link to a section in this manual page.  E.g.,

</p>

</li>

</ul>

<p>A section is started by the named heading or item.  For

 both

link to the section started by "<code class="inline"><span class="pd">=item $.</span></code>

" in perlvar.  And

 

both link to the section started by "<code class="inline"><span class="pd">=head2 For Loops</span></code>

"

use "<code class="inline">L&lt;text|...&gt;</code>", as in:</p>

<ul>

<li>

</p>

<p>Link this text to that manual page.  E.g.,

</p>

</li>

<li>

</p>

<p>Link this text to that section in that manual page.  E.g.,

</li>

<li>

<p><code class="inline">L&lt;text|/"sec"&gt;</code> or <code class="inline">L&lt;text|/sec&gt;</code>

</p>

<p>Link this text to that section in this manual page.  E.g.,

<code class="inline">L&lt;the various attributes|/"Member Data"&gt;</code></p>

<p>Or you can link to a web page:</p>

<ul>

<li>

</p>

<p>Links to an absolute URL.  For example,

that there is no corresponding <code class="inline">L&lt;text|scheme:...&gt;</code> syntax, for

various reasons.</p>

</li>

</ul>

</li>

 -- a character escape

   </b>

<ul>

<li>

 -- a literal &lt; (less than)</p>

</li>

<li>

 -- a literal &gt; (greater than)</p>

</li>

<li>

 -- a literal | (<i>ver</i>tical <i>bar</i>)</p>

</li>

<li>

 = a literal / (<i>sol</i>idus)</p>

<p>The above four are optional except in other formatting codes,

, and when preceded by a

capital letter.</p>

</li>

<li>

</p>

,

meaning the same thing as <code class="inline"><span class="i">&amp;eacute</span><span class="sc">;</span></code>

 in HTML -- i.e., a lowercase

e with an acute (/-shaped) accent.</p>

</li>

<li>

</p>

<p>The ASCII/Latin-1/Unicode character with that number.  A

leading "0x" means that <i>number</i> is hex, as in

.  A leading "0" means that <i>number</i> is octal,

.  Otherwise <i>number</i> is interpreted as being

.</p>

<p>Note that older Pod formatters might not recognize octal or

hex numeric escapes, and that many formatters cannot reliably

render characters above 255.  (Some formatters may even have

to use compromised renderings of Latin-1 characters, like

 as just a plain "e".)</p>

</li>

</ul>

</li>

 -- used for filenames

   </b>

"</p>

</li>

 -- text contains non-breaking spaces

   

</b>

<p>This means that the words in <i>text</i> should not be broken

</li>

 -- an index entry

   </b>

<p>This is ignored by most formatters, but some may use it for building

indexes.  It always renders as empty-string.

</p>

</li>

 -- a null (zero-effect) formatting code

   </b>

<p>This is rarely used.  It's one way to get around using an

E&lt;...&gt; code sometimes.  For example, instead of

"<code class="inline">NE&lt;lt&gt;3</code>" (for "N&lt;3") you could write

" (the "Z&lt;&gt;" breaks up the "N" and

the "&lt;" so they can't be considered

the part of a (fictitious) "N&lt;...&gt;" code.</p>

common when using a formatting code to provide a different font-type for a

snippet of code.  As with all things in Perl, there is more than

one way to do it.  One way is to simply escape the closing bracket

 code:</p>

<pre class="verbatim">    C&lt;$a E&lt;lt&gt;=E&lt;gt&gt; $b&gt;</pre><p>This will produce: "<code class="inline"><span class="i">$a</span> &lt;=&gt; <span class="i">$b</span></code>

"</p>

before the closing delimiter!</i>  For example, the following will

do the trick:

</p>

<p>In fact, you can use as many repeated angle-brackets as you like so

long as you have the same number of them in the opening and closing

delimiters, and make sure that whitespace immediately follows the last

of the closing delimiter.  (The whitespace is ignored.)  So the

following will also work:

</p>

<pre class="verbatim">    C&lt;$a E&lt;lt&gt;=E&lt;gt&gt; $b&gt;</pre><p>As a further example, this means that if you wanted to put these bits of

 (code) style:</p>

<pre class="verbatim">    open(X, "&gt;&gt;thing.dat") || die $!

    $foo-&gt;bar();</pre><p>you could do it like so:</p>

<pre class="verbatim">    C&lt;open(X, "E&lt;gt&gt;E&lt;gt&gt;thing.dat") || die $!&gt;

    C&lt;$foo-E&lt;gt&gt;bar();&gt;</pre><p>This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),

and any other pod2xxx or Pod::Xxxx translators that use

Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.</p>

</h2>

<p>The intent is simplicity of use, not power of expression.  Paragraphs

look like paragraphs (block format), so that they stand out

 easily to reformat

them (that's F7 in my version of <b>vi</b>, or Esc Q in my version of

<b>emacs</b>).  I wanted the translator to always leave the <code class="inline">'</code> and <code class="inline">`</code> and

documentation.  Translators exist for <b>pod2text</b>, <b>pod2html</b>,

<b>pod2man</b> (that's for nroff(1) and troff(1)), <b>pod2latex</b>, and

<b>pod2fm</b>.  Various others are available in CPAN.</p>

</h2>

<p>You can embed Pod documentation in your Perl modules and scripts.

Start your documentation with an empty line, a "=head1" command at the

you're using an __END__ or __DATA__ cut mark, make sure to put an

empty line there before the first Pod command.</p>

<pre class="verbatim"><a name="__END__"></a>  __END__</pre>

<pre class="verbatim">  Time::Local - efficiently compute time from local and GMT time</pre><p>Without that empty line before the "=head1", many translators wouldn't

have recognized the "=head1" as starting a Pod block.</p>

<a name="Hints-for-Writing-Pod"></a><h2>Hints for Writing Pod</h2>

command and after every Pod command (including "=cut"!) to be a blank

line.  Having something like this:</p>

<pre class="verbatim"> <span class="c"># - - - - - - - - - - - -</span>

<pre class="verbatim"> This noisily detonates the firecracker object.

 =cut

 sub boom {

at all.</p>

<p>Instead, have it like this:</p>

<pre class="verbatim"> <span class="c"># - - - - - - - - - - - -</span></pre>

<pre class="verbatim"> sub boom {

 ...</pre></li>

<li>

</li>

<li>

<p>Older translators might add wording around an L&lt;&gt; link, so that

 may become "the Foo::Bar manpage", for example.

So you shouldn't write things like <code class="inline">the L&lt;foo&gt;

documentation</code>, if you want the translated document to read sensibly

 or

, to control how the

link comes out.</p>

</li>

          <!--<select name="r"><option value="1" selected>Go to top result<option value="0">Show results list</select>-->

        </form>

      </p>

      <h2>Labels:</h2>

      <p>

        <a href="#" onClick="addLabel('perlpod','perlpod.html')">Add this page</a>