perlpodspec.1

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

\&        "Newlines",                     # section
\&        \*(Aqpod\*(Aq,                          # what sort of link
\&        "Perlport\*(Aqs section on NL\*(Aqs|perlport/Newlines" # orig. content
\&
\&  L<perlport/Newlines>
\&    =>  undef,                          # link text
\&        \*(Aq"Newlines" in perlport\*(Aq,       # possibly inferred link text
\&        "perlport",                     # name
\&        "Newlines",                     # section
\&        \*(Aqpod\*(Aq,                          # what sort of link
\&        "perlport/Newlines"             # original content
\&
\&  L<crontab(5)/"DESCRIPTION">
\&    =>  undef,                          # link text
\&        \*(Aq"DESCRIPTION" in crontab(5)\*(Aq,  # possibly inferred link text
\&        "crontab(5)",                   # name
\&        "DESCRIPTION",                  # section
\&        \*(Aqman\*(Aq,                          # what sort of link
\&        \*(Aqcrontab(5)/"DESCRIPTION"\*(Aq      # original content
\&
\&  L</Object Attributes>
\&    =>  undef,                          # link text
\&        \*(Aq"Object Attributes"\*(Aq,          # possibly inferred link text
\&        undef,                          # name
\&        "Object Attributes",            # section
\&        \*(Aqpod\*(Aq,                          # what sort of link
\&        "/Object Attributes"            # original content
\&
\&  L<http://www.perl.org/>
\&    =>  undef,                          # link text
\&        "http://www.perl.org/",         # possibly inferred link text
\&        "http://www.perl.org/",         # name
\&        undef,                          # section
\&        \*(Aqurl\*(Aq,                          # what sort of link
\&        "http://www.perl.org/"          # original content
.Ve
.Sp
Note that you can distinguish URL-links from anything else by the
fact that they match \f(CW\*(C`m/\eA\ew+:[^:\es]\eS*\ez/\*(C'\fR.  So
\&\f(CW\*(C`L<http://www.perl.com>\*(C'\fR is a \s-1URL\s0, but
\&\f(CW\*(C`L<HTTP::Response>\*(C'\fR isn't.
.RE
.IP "\(bu" 4
In case of L<...> codes with no \*(L"text|\*(R" part in them,
older formatters have exhibited great variation in actually displaying
the link or cross reference.  For example, L<\fIcrontab\fR\|(5)> would render
as "the \f(CWcrontab(5)\fR manpage\*(L", or \*(R"in the \f(CWcrontab(5)\fR manpage\*(L"
or just \*(R"\f(CWcrontab(5)\fR".
.Sp
Pod processors must now treat \*(L"text|\*(R"\-less links as follows:
.Sp
.Vb 3
\&  L<name>         =>  L<name|name>
\&  L</section>     =>  L<"section"|/section>
\&  L<name/section> =>  L<"section" in name|name/section>
.Ve
.IP "\(bu" 4
Note that section names might contain markup.  I.e., if a section
starts with:
.Sp
.Vb 1
\&  =head2 About the C<\-M> Operator
.Ve
.Sp
or with:
.Sp
.Vb 1
\&  =item About the C<\-M> Operator
.Ve
.Sp
then a link to it would look like this:
.Sp
.Vb 1
\&  L<somedoc/About the C<\-M> Operator>
.Ve
.Sp
Formatters may choose to ignore the markup for purposes of resolving
the link and use only the renderable characters in the section name,
as in:
.Sp
.Vb 2
\&  <h1><a name="About_the_\-M_Operator">About the <code>\-M</code>
\&  Operator</h1>
\&
\&  ...
\&
\&  <a href="somedoc#About_the_\-M_Operator">About the <code>\-M</code>
\&  Operator" in somedoc</a>
.Ve
.IP "\(bu" 4
Previous versions of perlpod distinguished \f(CW\*(C`L<name/"section">\*(C'\fR
links from \f(CW\*(C`L<name/item>\*(C'\fR links (and their targets).  These
have been merged syntactically and semantically in the current
specification, and \fIsection\fR can refer either to a "=head\fIn\fR Heading
Content\*(L" command or to a \*(R"=item Item Content" command.  This
specification does not specify what behavior should be in the case
of a given document having several things all seeming to produce the
same \fIsection\fR identifier (e.g., in \s-1HTML\s0, several things all producing
the same \fIanchorname\fR in <a name="\fIanchorname\fR">...</a>
elements).  Where Pod processors can control this behavior, they should
use the first such anchor.  That is, \f(CW\*(C`L<Foo/Bar>\*(C'\fR refers to the
\&\fIfirst\fR \*(L"Bar\*(R" section in Foo.
.Sp
But for some processors/formats this cannot be easily controlled; as
with the \s-1HTML\s0 example, the behavior of multiple ambiguous
<a name="\fIanchorname\fR">...</a> is most easily just left up to
browsers to decide.
.IP "\(bu" 4
Authors wanting to link to a particular (absolute) \s-1URL\s0, must do so
only with \*(L"L<scheme:...>\*(R" codes (like
L<http://www.perl.org>), and must not attempt \*(L"L<Some Site
Name|scheme:...>\*(R" codes.  This restriction avoids many problems
in parsing and rendering L<...> codes.
.IP "\(bu" 4
In a \f(CW\*(C`L<text|...>\*(C'\fR code, text may contain formatting codes
for formatting or for E<...> escapes, as in:
.Sp
.Vb 1
\&  L<B<ummE<234>stuff>|...>
.Ve
.Sp
For \f(CW\*(C`L<...>\*(C'\fR codes without a \*(L"name|\*(R" part, only
\&\f(CW\*(C`E<...>\*(C'\fR and \f(CW\*(C`Z<>\*(C'\fR codes may occur \*(-- no
other formatting codes.  That is, authors should not use
"\f(CW\*(C`L<B<Foo::Bar>>\*(C'\fR".
.Sp
Note, however, that formatting codes and Z<>'s can occur in any
and all parts of an L<...> (i.e., in \fIname\fR, \fIsection\fR, \fItext\fR,
and \fIurl\fR).
.Sp
Authors must not nest L<...> codes.  For example, \*(L"L<The
L<Foo::Bar> man page>\*(R" should be treated as an error.
.IP "\(bu" 4
Note that Pod authors may use formatting codes inside the \*(L"text\*(R"
part of \*(L"L<text|name>\*(R" (and so on for L<text|/\*(L"sec\*(R">).
.Sp
In other words, this is valid:
.Sp
.Vb 1
\&  Go read L<the docs on C<$.>|perlvar/"$.">
.Ve
.Sp
Some output formats that do allow rendering \*(L"L<...>\*(R" codes as
hypertext, might not allow the link-text to be formatted; in
that case, formatters will have to just ignore that formatting.
.IP "\(bu" 4
At time of writing, \f(CW\*(C`L<name>\*(C'\fR values are of two types:
either the name of a Pod page like \f(CW\*(C`L<Foo::Bar>\*(C'\fR (which
might be a real Perl module or program in an \f(CW@INC\fR / \s-1PATH\s0
directory, or a .pod file in those places); or the name of a \s-1UNIX\s0
man page, like \f(CW\*(C`L<crontab(5)>\*(C'\fR.  In theory, \f(CW\*(C`L<chmod>\*(C'\fR
in ambiguous between a Pod page called \*(L"chmod\*(R", or the Unix man page
\&\*(L"chmod\*(R" (in whatever man-section).  However, the presence of a string
in parens, as in \*(L"\fIcrontab\fR\|(5)\*(R", is sufficient to signal that what
is being discussed is not a Pod page, and so is presumably a
\&\s-1UNIX\s0 man page.  The distinction is of no importance to many
Pod processors, but some processors that render to hypertext formats
may need to distinguish them in order to know how to render a
given \f(CW\*(C`L<foo>\*(C'\fR code.
.IP "\(bu" 4
Previous versions of perlpod allowed for a \f(CW\*(C`L<section>\*(C'\fR syntax
(as in \f(CW\*(C`L<Object Attributes>\*(C'\fR), which was not easily distinguishable
from \f(CW\*(C`L<name>\*(C'\fR syntax.  This syntax is no longer in the
specification, and has been replaced by the \f(CW\*(C`L<"section">\*(C'\fR syntax
(where the quotes were formerly optional).  Pod parsers should tolerate
the \f(CW\*(C`L<section>\*(C'\fR syntax, for a while at least.  The suggested
heuristic for distinguishing \f(CW\*(C`L<section>\*(C'\fR from \f(CW\*(C`L<name>\*(C'\fR
is that if it contains any whitespace, it's a \fIsection\fR.  Pod processors
may warn about this being deprecated syntax.
.SH "About =over...=back Regions"
.IX Header "About =over...=back Regions"
\&\*(L"=over\*(R"...\*(L"=back\*(R" regions are used for various kinds of list-like
structures.  (I use the term \*(L"region\*(R" here simply as a collective
term for everything from the \*(L"=over\*(R" to the matching \*(L"=back\*(R".)
.IP "\(bu" 4
The non-zero numeric \fIindentlevel\fR in "=over \fIindentlevel\fR\*(L" ...
\&\*(R"=back\*(L" is used for giving the formatter a clue as to how many
\&\*(R"spaces" (ems, or roughly equivalent units) it should tab over,
although many formatters will have to convert this to an absolute
measurement that may not exactly match with the size of spaces (or M's)
in the document's base font.  Other formatters may have to completely
ignore the number.  The lack of any explicit \fIindentlevel\fR parameter is
equivalent to an \fIindentlevel\fR value of 4.  Pod processors may
complain if \fIindentlevel\fR is present but is not a positive number
matching \f(CW\*(C`m/\eA(\ed*\e.)?\ed+\ez/\*(C'\fR.
.IP "\(bu" 4
Authors of Pod formatters are reminded that \*(L"=over\*(R" ... \*(L"=back\*(R" may
map to several different constructs in your output format.  For
example, in converting Pod to (X)HTML, it can map to any of
<ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or
<blockquote>...</blockquote>.  Similarly, \*(L"=item\*(R" can map to <li> or
<dt>.
.IP "\(bu" 4
Each \*(L"=over\*(R" ... \*(L"=back\*(R" region should be one of the following:
.RS 4
.IP "\(bu" 4
An \*(L"=over\*(R" ... \*(L"=back\*(R" region containing only \*(L"=item *\*(R" commands,
each followed by some number of ordinary/verbatim paragraphs, other
nested \*(L"=over\*(R" ... \*(L"=back\*(R" regions, \*(L"=for...\*(R" paragraphs, and
\&\*(L"=begin\*(R"...\*(L"=end\*(R" regions.
.Sp
(Pod processors must tolerate a bare \*(L"=item\*(R" as if it were \*(L"=item
*\*(R".)  Whether \*(L"*\*(R" is rendered as a literal asterisk, an \*(L"o\*(R", or as
some kind of real bullet character, is left up to the Pod formatter,
and may depend on the level of nesting.
.IP "\(bu" 4
An \*(L"=over\*(R" ... \*(L"=back\*(R" region containing only
\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR paragraphs, each one (or each group of them)
followed by some number of ordinary/verbatim paragraphs, other nested
\&\*(L"=over\*(R" ... \*(L"=back\*(R" regions, \*(L"=for...\*(R" paragraphs, and/or
\&\*(L"=begin\*(R"...\*(L"=end\*(R" codes.  Note that the numbers must start at 1
in each section, and must proceed in order and without skipping
numbers.
.Sp
(Pod processors must tolerate lines like \*(L"=item 1\*(R" as if they were
\&\*(L"=item 1.\*(R", with the period.)
.IP "\(bu" 4
An \*(L"=over\*(R" ... \*(L"=back\*(R" region containing only \*(L"=item [text]\*(R"
commands, each one (or each group of them) followed by some number of
ordinary/verbatim paragraphs, other nested \*(L"=over\*(R" ... \*(L"=back\*(R"
regions, or \*(L"=for...\*(R" paragraphs, and \*(L"=begin\*(R"...\*(L"=end\*(R" regions.
.Sp
The \*(L"=item [text]\*(R" paragraph should not match
\&\f(CW\*(C`m/\eA=item\es+\ed+\e.?\es*\ez/\*(C'\fR or \f(CW\*(C`m/\eA=item\es+\e*\es*\ez/\*(C'\fR, nor should it
match just \f(CW\*(C`m/\eA=item\es*\ez/\*(C'\fR.
.IP "\(bu" 4
An \*(L"=over\*(R" ... \*(L"=back\*(R" region containing no \*(L"=item\*(R" paragraphs at
all, and containing only some number of 
ordinary/verbatim paragraphs, and possibly also some nested \*(L"=over\*(R"
\&... \*(L"=back\*(R" regions, \*(L"=for...\*(R" paragraphs, and \*(L"=begin\*(R"...\*(L"=end\*(R"
regions.  Such an itemless \*(L"=over\*(R" ... \*(L"=back\*(R" region in Pod is
equivalent in meaning to a \*(L"<blockquote>...</blockquote>\*(R" element in
\&\s-1HTML\s0.
.RE
.RS 4
.Sp
Note that with all the above cases, you can determine which type of
\&\*(L"=over\*(R" ... \*(L"=back\*(R" you have, by examining the first (non\-\*(L"=cut\*(R", 
non\-\*(L"=pod\*(R") Pod paragraph after the \*(L"=over\*(R" command.
.RE
.IP "\(bu" 4
Pod formatters \fImust\fR tolerate arbitrarily large amounts of text
in the "=item \fItext...\fR" paragraph.  In practice, most such
paragraphs are short, as in:
.Sp
.Vb 1
\&  =item For cutting off our trade with all parts of the world
.Ve
.Sp
But they may be arbitrarily long:
.Sp
.Vb 2
\&  =item For transporting us beyond seas to be tried for pretended
\&  offenses
\&
\&  =item He is at this time transporting large armies of foreign
\&  mercenaries to complete the works of death, desolation and
\&  tyranny, already begun with circumstances of cruelty and perfidy
\&  scarcely paralleled in the most barbarous ages, and totally
\&  unworthy the head of a civilized nation.
.Ve
.IP "\(bu" 4
Pod processors should tolerate \*(L"=item *\*(R" / "=item \fInumber\fR" commands
with no accompanying paragraph.  The middle item is an example:
.Sp
.Vb 1
\&  =over
\&
\&  =item 1
\&
\&  Pick up dry cleaning.
\&
\&  =item 2
\&
\&  =item 3
\&
\&  Stop by the store.  Get Abba Zabas, Stoli, and cheap lawn chairs.
\&
\&  =back
.Ve
.IP "\(bu" 4
No \*(L"=over\*(R" ... \*(L"=back\*(R" region can contain headings.  Processors may
treat such a heading as an error.
.IP "\(bu" 4
Note that an \*(L"=over\*(R" ... \*(L"=back\*(R" region should have some
content.  That is, authors should not have an empty region like this:
.Sp
.Vb 1
\&  =over
\&
\&  =back
.Ve
.Sp
Pod processors seeing such a contentless \*(L"=over\*(R" ... \*(L"=back\*(R" region,
may ignore it, or may report it as an error.
.IP "\(bu" 4
Processors must tolerate an \*(L"=over\*(R" list that