perlpodspec.html
来自「perl教程」· HTML 代码 · 共 1,304 行 · 第 1/5 页
HTML
1,304 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>perlpodspec - Plain Old Documentation: format specification and notes</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',2);</script>
<h1><a>perlpodspec - Plain Old Documentation: format specification and notes</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#pod_definitions">Pod Definitions</a></li>
<li><a href="#pod_commands">Pod Commands</a></li>
<li><a href="#pod_formatting_codes">Pod Formatting Codes</a></li>
<li><a href="#notes_on_implementing_pod_processors">Notes on Implementing Pod Processors</a></li>
<li><a href="#about_l______codes">About L<...> Codes</a></li>
<li><a href="#about__over____back_regions">About =over...=back Regions</a></li>
<li><a href="#about_data_paragraphs_and__begin__end_regions">About Data Paragraphs and "=begin/=end" Regions</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>perlpodspec - Plain Old Documentation: format specification and notes</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>This document is detailed notes on the Pod markup language. Most
people will only have to read <a href="../../lib/Pod/perlpod.html">perlpod</a> to know how to write
in Pod, but this document may answer some incidental questions to do
with parsing and rendering Pod.</p>
<p>In this document, "must" / "must not", "should" /
"should not", and "may" have their conventional (cf. RFC 2119)
meanings: "X must do Y" means that if X doesn't do Y, it's against
this specification, and should really be fixed. "X should do Y"
means that it's recommended, but X may fail to do Y, if there's a
good reason. "X may do Y" is merely a note that X can do Y at
will (although it is up to the reader to detect any connotation of
"and I think it would be <em>nice</em> if X did Y" versus "it wouldn't
really <em>bother</em> me if X did Y").</p>
<p>Notably, when I say "the parser should do Y", the
parser may fail to do Y, if the calling application explicitly
requests that the parser <em>not</em> do Y. I often phrase this as
"the parser should, by default, do Y." This doesn't <em>require</em>
the parser to provide an option for turning off whatever
feature Y is (like expanding tabs in verbatim paragraphs), although
it implicates that such an option <em>may</em> be provided.</p>
<p>
</p>
<hr />
<h1><a name="pod_definitions">Pod Definitions</a></h1>
<p>Pod is embedded in files, typically Perl source files -- although you
can write a file that's nothing but Pod.</p>
<p>A <strong>line</strong> in a file consists of zero or more non-newline characters,
terminated by either a newline or the end of the file.</p>
<p>A <strong>newline sequence</strong> is usually a platform-dependent concept, but
Pod parsers should understand it to mean any of CR (ASCII 13), LF
(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in
addition to any other system-specific meaning. The first CR/CRLF/LF
sequence in the file may be used as the basis for identifying the
newline sequence for parsing the rest of the file.</p>
<p>A <strong>blank line</strong> is a line consisting entirely of zero or more spaces
(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file.
A <strong>non-blank line</strong> is a line containing one or more characters other
than space or tab (and terminated by a newline or end-of-file).</p>
<p>(<em>Note:</em> Many older Pod parsers did not accept a line consisting of
spaces/tabs and then a newline as a blank line -- the only lines they
considered blank were lines consisting of <em>no characters at all</em>,
terminated by a newline.)</p>
<p><strong>Whitespace</strong> is used in this document as a blanket term for spaces,
tabs, and newline sequences. (By itself, this term usually refers
to literal whitespace. That is, sequences of whitespace characters
in Pod source, as opposed to "E<32>", which is a formatting
code that <em>denotes</em> a whitespace character.)</p>
<p>A <strong>Pod parser</strong> is a module meant for parsing Pod (regardless of
whether this involves calling callbacks or building a parse tree or
directly formatting it). A <strong>Pod formatter</strong> (or <strong>Pod translator</strong>)
is a module or program that converts Pod to some other format (HTML,
plaintext, TeX, PostScript, RTF). A <strong>Pod processor</strong> might be a
formatter or translator, or might be a program that does something
else with the Pod (like wordcounting it, scanning for index points,
etc.).</p>
<p>Pod content is contained in <strong>Pod blocks</strong>. A Pod block starts with a
line that matches <m/\A=[a-zA-Z]/>, and continues up to the next line
that matches <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=cut/</code></a> -- or up to the end of the file, if there is
no <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=cut/</code></a> line.</p>
<p>Within a Pod block, there are <strong>Pod paragraphs</strong>. A Pod paragraph
consists of non-blank lines of text, separated by one or more blank
lines.</p>
<p>For purposes of Pod processing, there are four types of paragraphs in
a Pod block:</p>
<ul>
<li>
<p>A command paragraph (also called a "directive"). The first line of
this paragraph must match <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=[a-zA-Z]/</code></a>. Command paragraphs are
typically one line, as in:</p>
<pre>
=head1 NOTES</pre>
<pre>
=item *</pre>
<p>But they may span several (non-blank) lines:</p>
<pre>
=for comment
Hm, I wonder what it would look like if
you tried to write a BNF for Pod from this.</pre>
<pre>
=head3 Dr. Strangelove, or: How I Learned to
Stop Worrying and Love the Bomb</pre>
<p><em>Some</em> command paragraphs allow formatting codes in their content
(i.e., after the part that matches <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=[a-zA-Z]\S*\s*/</code></a>), as in:</p>
<pre>
<span class="comment">=head1 Did You Remember to C<use strict;>?
</span>
</pre>
<p>In other words, the Pod processing handler for "head1" will apply the
same processing to "Did You Remember to C<use strict;>?" that it
would to an ordinary paragraph -- i.e., formatting codes (like
"C<...>") are parsed and presumably formatted appropriately, and
whitespace in the form of literal spaces and/or tabs is not
significant.</p>
</li>
<li>
<p>A <strong>verbatim paragraph</strong>. The first line of this paragraph must be a
literal space or tab, and this paragraph must not be inside a "=begin
<em>identifier</em>", ... "=end <em>identifier</em>" sequence unless
"<em>identifier</em>" begins with a colon (":"). That is, if a paragraph
starts with a literal space or tab, but <em>is</em> inside a
"=begin <em>identifier</em>", ... "=end <em>identifier</em>" region, then it's
a data paragraph, unless "<em>identifier</em>" begins with a colon.</p>
<p>Whitespace <em>is</em> significant in verbatim paragraphs (although, in
processing, tabs are probably expanded).</p>
</li>
<li>
<p>An <strong>ordinary paragraph</strong>. A paragraph is an ordinary paragraph
if its first line matches neither <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=[a-zA-Z]/</code></a> nor
<a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A[ \t]/</code></a>, <em>and</em> if it's not inside a "=begin <em>identifier</em>",
... "=end <em>identifier</em>" sequence unless "<em>identifier</em>" begins with
a colon (":").</p>
</li>
<li>
<p>A <strong>data paragraph</strong>. This is a paragraph that <em>is</em> inside a "=begin
<em>identifier</em>" ... "=end <em>identifier</em>" sequence where
"<em>identifier</em>" does <em>not</em> begin with a literal colon (":"). In
some sense, a data paragraph is not part of Pod at all (i.e.,
effectively it's "out-of-band"), since it's not subject to most kinds
of Pod parsing; but it is specified here, since Pod
parsers need to be able to call an event for it, or store it in some
form in a parse tree, or at least just parse <em>around</em> it.</p>
</li>
</ul>
<p>For example: consider the following paragraphs:</p>
<pre>
<span class="comment"># <- that's the 0th column</span>
</pre>
<pre>
=head1 Foo</pre>
<pre>
Stuff</pre>
<pre>
$foo->bar</pre>
<pre>
=cut</pre>
<p>Here, "=head1 Foo" and "=cut" are command paragraphs because the first
line of each matches <a href="../../lib/Pod/perlfunc.html#item_m_"><code>m/\A=[a-zA-Z]/</code></a>. "<em>[space][space]</em>$foo->bar"
is a verbatim paragraph, because its first line starts with a literal
whitespace character (and there's no "=begin"..."=end" region around).</p>
<p>The "=begin <em>identifier</em>" ... "=end <em>identifier</em>" commands stop
paragraphs that they surround from being parsed as data or verbatim
paragraphs, if <em>identifier</em> doesn't begin with a colon. This
is discussed in detail in the section
<a href="#about_data_paragraphs_and__begine_sol__end_regions">About Data Paragraphs and "=begin/=end" Regions</a>.</p>
<p>
</p>
<hr />
<h1><a name="pod_commands">Pod Commands</a></h1>
<p>This section is intended to supplement and clarify the discussion in
<a href="../../lib/Pod/perlpod.html#command_paragraph">Command Paragraph in the perlpod manpage</a>. These are the currently recognized
Pod commands:</p>
<dl>
<dt><strong><a name="item__22_3dhead1_22_2c__22_3dhead2_22_2c__22_3dhead3_22">"=head1", "=head2", "=head3", "=head4"</a></strong>
<dd>
<p>This command indicates that the text in the remainder of the paragraph
is a heading. That text may contain formatting codes. Examples:</p>
</dd>
<dd>
<pre>
=head1 Object Attributes</pre>
</dd>
<dd>
<pre>
=head3 What B<Not> to Do!</pre>
</dd>
</li>
<dt><strong><a name="item__22_3dpod_22">"=pod"</a></strong>
<dd>
<p>This command indicates that this paragraph begins a Pod block. (If we
are already in the middle of a Pod block, this command has no effect at
all.) If there is any text in this command paragraph after "=pod",
it must be ignored. Examples:</p>
</dd>
<dd>
<pre>
=pod</pre>
</dd>
<dd>
<pre>
This is a plain Pod paragraph.</pre>
</dd>
<dd>
<pre>
=pod This text is ignored.</pre>
</dd>
</li>
<dt><strong><a name="item__22_3dcut_22">"=cut"</a></strong>
<dd>
<p>This command indicates that this line is the end of this previously
started Pod block. If there is any text after "=cut" on the line, it must be
ignored. Examples:</p>
</dd>
<dd>
<pre>
=cut</pre>
</dd>
<dd>
<pre>
=cut The documentation ends here.</pre>
</dd>
<dd>
<pre>
<span class="comment">=cut
# This is the first line of program text.
sub foo { # This is the second.
</span>
</pre>
</dd>
<dd>
<p>It is an error to try to <em>start</em> a Pod block with a "=cut" command. In
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?