ch26_01.htm

编程珍珠,里面很多好用的代码,大家可以参考学习呵呵,

<tt class="literal">=end</tt> let you include special sections to be passed
through unaltered, but only to particular formatters. Formatters that
recognize their own names, or aliases for their names, in
<em class="replaceable">TRANSLATOR</em> pay attention to that directive;
any others completely ignore them.  The directive
<tt class="literal">=for</tt> specifies that just the rest of this
paragraph is destined <em class="emphasis">for</em> a particular
translator.
<blockquote>
<pre class="programlisting">=for html
&lt;p&gt; This is a &lt;flash&gt;raw&lt;/flash&gt; &lt;small&gt;HTML&lt;/small&gt; paragraph &lt;/p&gt;</pre>
</blockquote>

The paired <tt class="literal">=begin</tt> and <tt class="literal">=end</tt>
directives work similarly to <tt class="literal">=for</tt>, but instead of
accepting a single paragraph only, they treat all text between matched
<tt class="literal">=begin</tt> and <tt class="literal">=end</tt> as destined for
a particular translator.  Some examples:
<blockquote>
<pre class="programlisting">=begin html

&lt;br&gt;Figure 1.&lt;IMG SRC="figure1.png"&gt;&lt;br&gt;

=end html

=begin text

  ---------------
  |  foo        |
  |        bar  |
  ---------------

^^^^ Figure 1. ^^^^

=end text</pre>
</blockquote>

Values of <em class="replaceable">TRANSLATOR</em> commonly accepted by
formatters include <tt class="literal">roff</tt>, <tt class="literal">man</tt>,
<tt class="literal">troff</tt>, <tt class="literal">nroff</tt>,
<tt class="literal">tbl</tt>, <tt class="literal">eqn</tt>,
<tt class="literal">latex</tt>, <tt class="literal">tex</tt>,
<tt class="literal">html</tt>, and <tt class="literal">text</tt>.  Some formatters
will accept some of these as synonyms.  No translator accepts
<tt class="literal">comment</tt>--that's just the customary word for
something to be ignored by everybody. Any unrecognized word would
serve the same purpose. While writing this book, we often left notes
for ourselves under the directive <tt class="literal">=for later</tt>.</p>

<p>Note that <tt class="literal">=begin</tt> and <tt class="literal">=end</tt> do
nest, but only in the sense that the outermost matched set causes
everything in the middle to be treated as nonpod, even if it happens
to contain other <em class="replaceable">=word</em> directives.  That
is, as soon as any translator sees <tt class="literal">=begin foo</tt>, it
will either ignore or process <em class="emphasis">everything</em> down to
the corresponding <tt class="literal">=end foo</tt>.</p>
</dd>

</dl>






<h3 class="sect2">26.1.3. Pod Sequences</h3>

<p>The third type of paragraph is simply "flowed" text.  That is, if a
paragraph doesn't start with either whitespace or an equals sign, it's
taken as a plain paragraph: regular text that's typed in with as few
frills as possible.  Newlines are treated as equivalent to spaces.
It's largely up to the translator to make it look nice, because
programmers have more important things to do.  It is assumed that
translators will apply certain common heuristics--see the section "Pod Translators
and Modules" later in this chapter.</p>

<p>You can do some things explicitly, however.  Inside either
ordinary paragraphs or heading/item directives (but not in verbatim
paragraphs), you may use special sequences to adjust the formatting.
These sequences always start with a single capital letter followed by a
left angle bracket, and extend through the matching (not necessarily
the next) right angle bracket.  Sequences may contain other sequences.</p>

<p>Here are the sequences defined by pod:</p>

<dl>
<dt>
<b><tt class="literal">I&lt;</tt><em class="replaceable">text</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Italicized text, used for emphasis, book titles, names of
ships, and manpage references such as "<em class="emphasis">perlpod</em>(1)".</p>
</dd>


<dt>
<b><tt class="literal">B&lt;</tt><em class="replaceable">text</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Emboldened text, used almost exclusively for command-line switches
and sometimes for names of programs.</p>
</dd>


<dt>
<b><tt class="literal">C&lt;</tt><em class="replaceable">text</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Literal code, probably in a fixed-width font like Courier.  Not
needed on simple items that the translator should be able to infer
as code, but you should put it anyway.</p>
</dd>


<dt>
<b><tt class="literal">S&lt;</tt><em class="replaceable">text</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Text with nonbreaking spaces.  Often surrounds other sequences.</p>
</dd>


<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">name</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>A cross reference (link) to a name:</p>

<dl>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">name</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Manual page</p>
</dd>


<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">name/ident</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Item in manual page</p>
</dd>


<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">name/"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Section in other manual page</p>
</dd>


<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Section in this manual page (the quotes are optional)</p>
</dd>


<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">/"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Ditto</p>
</dd>

</dl>

<p>The next five sequences are the same as those above, but the output will be
only <em class="replaceable">text</em>, with the link information hidden as in
HTML:</p>

<dl>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">text</em><tt class="literal">|</tt><em class="replaceable">name</em><tt class="literal">&gt;</tt></b>
</dt>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">text</em><tt class="literal">|</tt><em class="replaceable">name</em><tt class="literal">/</tt><em class="replaceable">ident</em><tt class="literal">&gt;</tt></b>
</dt>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">text</em><tt class="literal">|</tt><em class="replaceable">name</em><tt class="literal">/</tt><em class="replaceable">"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">text</em><tt class="literal">|</tt><em class="replaceable">"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dt>
<b><tt class="literal">L&lt;</tt><em class="replaceable">text</em><tt class="literal">|/</tt><em class="replaceable">"sec"</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>The <em class="replaceable">text</em> cannot contain the characters <tt class="literal">/</tt> and <tt class="literal">|</tt>, and should
contain <tt class="literal">&lt;</tt> or <tt class="literal">&gt;</tt> only in matched pairs.</p>
</dd>

</dl>
</dd>


<dt>
<b><tt class="literal">F&lt;</tt><em class="replaceable">pathname</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>Used for filenames.  This is traditionally rendered the same as <tt class="literal">I</tt>.</p>
</dd>


<dt>
<b><tt class="literal">X&lt;</tt><em class="replaceable">entry</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>An index entry of some sort.  As always, it's up to the translator to decide what to do.
The pod specification doesn't dictate that.</p>
</dd>


<dt>
<b><tt class="literal">E&lt;</tt><em class="replaceable">escape</em><tt class="literal">&gt;</tt></b>
</dt>
<dd>
<p>A named character, similar to HTML escapes:</p>
</dd>


<dt>
<b><tt class="literal">Z&lt;&gt;</tt></b>
</dt>
<dd>
<p>A zero-width character.  This is nice for putting in front of sequences
that might confuse something.  For example, if you had a line
in regular prose that had to start with an equals sign, you could write
that as:
<blockquote>
<pre class="programlisting">Z&lt;&gt;=can you see</pre>
</blockquote>

or for something with a "From" in it, so the mailer doesn't put a <tt class="literal">&gt;</tt> in front:
<blockquote>
<pre class="programlisting">Z&lt;&gt;From here on out...</pre>
</blockquote>
</p>
</dd>

</dl>

<p>Most of the time, you'll need only a single set of angle brackets to
delimit one of these pod sequences.  Sometimes, however, you will want
to put a <tt class="literal">&lt;</tt> or <tt class="literal">&gt;</tt> inside a
sequence.  (This is particularly common when using a
<tt class="literal">C&lt;&gt;</tt> sequence to provide a constant-width font
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 represent the closing
bracket with an <tt class="literal">E</tt> sequence:
<blockquote>
<pre class="programlisting">C&lt;$a E&lt;lt&gt;=E&lt;gt&gt; $b&gt;</pre>
</blockquote>

This produces "<tt class="literal">$a &lt;=&gt; $b</tt>".</p>

<p>A more readable, and perhaps more "plain" way, is to use an alternate
set of delimiters that doesn't require the angle brackets to be escaped.
Doubled angle brackets (<tt class="literal">C&lt;&lt;</tt><em class="replaceable">stuff</em><tt class="literal">&gt;&gt;</tt>) may be used,
provided there is whitespace immediately following the opening
delimiter and immediately preceding the closing one.  For
example, the following will work:
<blockquote>
<pre class="programlisting">C&lt;&lt; $a &lt;=&gt; $b &gt;&gt;</pre>
</blockquote>

You may use as many repeated angle-brackets as you like so
long as you have the same number of them on both sides, and you make
sure that whitespace immediately follows the last <tt class="literal">&lt;</tt> of the left side
and immediately precedes the first <tt class="literal">&gt;</tt> of the right side.  So the
following will also work:
<blockquote>
<pre class="programlisting">C&lt;&lt;&lt; $a &lt;=&gt; $b &gt;&gt;&gt;
C&lt;&lt;&lt;&lt; $a &lt;=&gt; $b &gt;&gt;&gt;&gt;</pre>
</blockquote>

All these end up spitting out <tt class="literal">$a &lt;=&gt; $b</tt> in a constant-width font.</p>

<p>The extra whitespace inside on either end goes away, so you should
leave 

whitespace on the outside if you want it.  Also, the two inside
chunks of extra whitespace don't overlap, so if the first thing being
quoted is <tt class="literal">&gt;&gt;</tt>, it isn't taken as the closing delimiter:
<blockquote>
<pre class="programlisting">The C&lt;&lt; &gt;&gt; &gt;&gt; right shift operator.</pre>
</blockquote>

This produces "The <tt class="literal">&gt;&gt;</tt> right shift operator."</p>

<p>Note that pod sequences <em class="emphasis">do</em> nest.  That means you can
write "<tt class="literal">The I&lt;Santa MarE&lt;iacute&gt;a&gt; left port
already</tt>" to produce "The <em class="emphasis">Santa Mar&amp;#237;a</em>
left port already", or "<tt class="literal">B&lt;touch&gt; S&lt;B&lt;-t&gt;
I&lt;time&gt;&gt; I&lt;file&gt;</tt>" to produce
"<b class="emphasis-bold">touch -t&nbsp;</b><em class="emphasis">time</em><em class="emphasis">file</em>", and expect this to work properly.</p>








































<!-- BOTTOM NAV BAR -->

<hr width="515" align="left">
<div class="navbar">
<table width="515" border="0">
<tr>
<td align="left" valign="top" width="172"><a href="ch25_10.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0"></a></td><td align="center" valign="top" width="171"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0"></a></td><td align="right" valign="top" width="172"><a href="ch26_02.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0"></a></td>
</tr>
<tr>
<td align="left" valign="top" width="172">25.10. Style</td><td align="center" valign="top" width="171"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0"></a></td><td align="right" valign="top" width="172">26.2. Pod Translators and Modules</td>
</tr>
</table>
</div>
<hr width="515" align="left">

<!-- LIBRARY NAV BAR -->

<img src="../gifs/smnavbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links"><p>
<font size="-1"><a href="copyrght.htm">Copyright &copy; 2001</a> O'Reilly &amp; Associates. All rights reserved.</font>
</p>
<map name="library-map"> <area shape="rect" coords="2,-1,79,99" href="../index.htm"><area shape="rect" coords="84,1,157,108" href="../perlnut/index.htm"><area shape="rect" coords="162,2,248,125" href="../prog/index.htm"><area shape="rect" coords="253,2,326,130" href="../advprog/index.htm"><area shape="rect" coords="332,1,407,112" href="../cookbook/index.htm"><area shape="rect" coords="414,2,523,103" href="../sysadmin/index.htm">
</map>

<!-- END OF BODY -->

</body>
</html>