perlpodspec.pod

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

=head1 About LE<lt>...E<gt> Codes

As you can tell from a glance at L<perlpod|perlpod>, the LE<lt>...>
code is the most complex of the Pod formatting codes.  The points below
will hopefully clarify what it means and how processors should deal
with it.

=over

=item *

In parsing an LE<lt>...> code, Pod parsers must distinguish at least
four attributes:

=over

=item First:

The link-text.  If there is none, this must be undef.  (E.g., in
"LE<lt>Perl Functions|perlfunc>", the link-text is "Perl Functions".
In "LE<lt>Time::HiRes>" and even "LE<lt>|Time::HiRes>", there is no
link text.  Note that link text may contain formatting.)

=item Second:

The possibly inferred link-text -- i.e., if there was no real link
text, then this is the text that we'll infer in its place.  (E.g., for
"LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".)

=item Third:

The name or URL, or undef if none.  (E.g., in "LE<lt>Perl
Functions|perlfunc>", the name -- also sometimes called the page --
is "perlfunc".  In "LE<lt>/CAVEATS>", the name is undef.)

=item Fourth:

The section (AKA "item" in older perlpods), or undef if none.  E.g.,
in "LE<lt>Getopt::Std/DESCRIPTIONE<gt>", "DESCRIPTION" is the section.  (Note
that this is not the same as a manpage section like the "5" in "man 5
crontab".  "Section Foo" in the Pod sense means the part of the text
that's introduced by the heading or item whose text is "Foo".)

=back

Pod parsers may also note additional attributes including:

=over

=item Fifth:

A flag for whether item 3 (if present) is a URL (like
"http://lists.perl.org" is), in which case there should be no section
attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or
possibly a man page name (like "crontab(5)" is).

=item Sixth:

The raw original LE<lt>...> content, before text is split on
"|", "/", etc, and before EE<lt>...> codes are expanded.

=back

(The above were numbered only for concise reference below.  It is not
a requirement that these be passed as an actual list or array.)

For example:

  L<Foo::Bar>
    =>  undef,                          # link text
        "Foo::Bar",                     # possibly inferred link text
        "Foo::Bar",                     # name
        undef,                          # section
        'pod',                          # what sort of link
        "Foo::Bar"                      # original content

  L<Perlport's section on NL's|perlport/Newlines>
    =>  "Perlport's section on NL's",   # link text
        "Perlport's section on NL's",   # possibly inferred link text
        "perlport",                     # name
        "Newlines",                     # section
        'pod',                          # what sort of link
        "Perlport's section on NL's|perlport/Newlines" # orig. content

  L<perlport/Newlines>
    =>  undef,                          # link text
        '"Newlines" in perlport',       # possibly inferred link text
        "perlport",                     # name
        "Newlines",                     # section
        'pod',                          # what sort of link
        "perlport/Newlines"             # original content

  L<crontab(5)/"DESCRIPTION">
    =>  undef,                          # link text
        '"DESCRIPTION" in crontab(5)',  # possibly inferred link text
        "crontab(5)",                   # name
        "DESCRIPTION",                  # section
        'man',                          # what sort of link
        'crontab(5)/"DESCRIPTION"'      # original content

  L</Object Attributes>
    =>  undef,                          # link text
        '"Object Attributes"',          # possibly inferred link text
        undef,                          # name
        "Object Attributes",            # section
        'pod',                          # 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
        'url',                          # what sort of link
        "http://www.perl.org/"          # original content

Note that you can distinguish URL-links from anything else by the
fact that they match C<m/\A\w+:[^:\s]\S*\z/>.  So
C<LE<lt>http://www.perl.comE<gt>> is a URL, but
C<LE<lt>HTTP::ResponseE<gt>> isn't.

=item *

In case of LE<lt>...> codes with no "text|" part in them,
older formatters have exhibited great variation in actually displaying
the link or cross reference.  For example, LE<lt>crontab(5)> would render
as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage"
or just "C<crontab(5)>".

Pod processors must now treat "text|"-less links as follows:

  L<name>         =>  L<name|name>
  L</section>     =>  L<"section"|/section>
  L<name/section> =>  L<"section" in name|name/section>

=item *

Note that section names might contain markup.  I.e., if a section
starts with:

  =head2 About the C<-M> Operator

or with:

  =item About the C<-M> Operator

then a link to it would look like this:

  L<somedoc/About the C<-M> Operator>

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:

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

=item *

Previous versions of perlpod distinguished C<LE<lt>name/"section"E<gt>>
links from C<LE<lt>name/itemE<gt>> links (and their targets).  These
have been merged syntactically and semantically in the current
specification, and I<section> can refer either to a "=headI<n> Heading
Content" command or to a "=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 I<section> identifier (e.g., in HTML, several things all producing
the same I<anchorname> in <a name="I<anchorname>">...</a>
elements).  Where Pod processors can control this behavior, they should
use the first such anchor.  That is, C<LE<lt>Foo/BarE<gt>> refers to the
I<first> "Bar" section in Foo.

But for some processors/formats this cannot be easily controlled; as
with the HTML example, the behavior of multiple ambiguous
<a name="I<anchorname>">...</a> is most easily just left up to
browsers to decide.

=item *

Authors wanting to link to a particular (absolute) URL, must do so
only with "LE<lt>scheme:...>" codes (like
LE<lt>http://www.perl.org>), and must not attempt "LE<lt>Some Site
Name|scheme:...>" codes.  This restriction avoids many problems
in parsing and rendering LE<lt>...> codes.

=item *

In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
for formatting or for EE<lt>...> escapes, as in:

  L<B<ummE<234>stuff>|...>

For C<LE<lt>...E<gt>> codes without a "name|" part, only
C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur -- no
other formatting codes.  That is, authors should not use
"C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>".

Note, however, that formatting codes and ZE<lt>>'s can occur in any
and all parts of an LE<lt>...> (i.e., in I<name>, I<section>, I<text>,
and I<url>).

Authors must not nest LE<lt>...> codes.  For example, "LE<lt>The
LE<lt>Foo::Bar> man page>" should be treated as an error.

=item *

Note that Pod authors may use formatting codes inside the "text"
part of "LE<lt>text|name>" (and so on for LE<lt>text|/"sec">).

In other words, this is valid:

  Go read L<the docs on C<$.>|perlvar/"$.">

Some output formats that do allow rendering "LE<lt>...>" codes as
hypertext, might not allow the link-text to be formatted; in
that case, formatters will have to just ignore that formatting.

=item *

At time of writing, C<LE<lt>nameE<gt>> values are of two types:
either the name of a Pod page like C<LE<lt>Foo::BarE<gt>> (which
might be a real Perl module or program in an @INC / PATH
directory, or a .pod file in those places); or the name of a UNIX
man page, like C<LE<lt>crontab(5)E<gt>>.  In theory, C<LE<lt>chmodE<gt>>
in ambiguous between a Pod page called "chmod", or the Unix man page
"chmod" (in whatever man-section).  However, the presence of a string
in parens, as in "crontab(5)", is sufficient to signal that what
is being discussed is not a Pod page, and so is presumably a
UNIX 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 C<LE<lt>fooE<gt>> code.

=item *

Previous versions of perlpod allowed for a C<LE<lt>sectionE<gt>> syntax
(as in C<LE<lt>Object AttributesE<gt>>), which was not easily distinguishable
from C<LE<lt>nameE<gt>> syntax.  This syntax is no longer in the
specification, and has been replaced by the C<LE<lt>"section"E<gt>> syntax
(where the quotes were formerly optional).  Pod parsers should tolerate
the C<LE<lt>sectionE<gt>> syntax, for a while at least.  The suggested
heuristic for distinguishing C<LE<lt>sectionE<gt>> from C<LE<lt>nameE<gt>>
is that if it contains any whitespace, it's a I<section>.  Pod processors
may warn about this being deprecated syntax.

=back

=head1 About =over...=back Regions

"=over"..."=back" regions are used for various kinds of list-like
structures.  (I use the term "region" here simply as a collective
term for everything from the "=over" to the matching "=back".)

=over

=item *

The non-zero numeric I<indentlevel> in "=over I<indentlevel>" ...
"=back" is used for giving the formatter a clue as to how many
"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 I<indentlevel> parameter is
equivalent to an I<indentlevel> value of 4.  Pod processors may
complain if I<indentlevel> is present but is not a positive number
matching C<m/\A(\d*\.)?\d+\z/>.

=item *

Authors of Pod formatters are reminded that "=over" ... "=back" 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, "=item" can map to <li> or
<dt>.

=item *

Each "=over" ... "=back" region should be one of the following:

=over

=item *

An "=over" ... "=back" region containing only "=item *" commands,
each followed by some number of ordinary/verbatim paragraphs, other
nested "=over" ... "=back" regions, "=for..." paragraphs, and
"=begin"..."=end" regions.

(Pod processors must tolerate a bare "=item" as if it were "=item
*".)  Whether "*" is rendered as a literal asterisk, an "o", or as
some kind of real bullet character, is left up to the Pod formatter,
and may depend on the level of nesting.

=item *

An "=over" ... "=back" region containing only
C<m/\A=item\s+\d+\.?\s*\z/> paragraphs, each one (or each group of them)
followed by some number of ordinary/verbatim paragraphs, other nested
"=over" ... "=back" regions, "=for..." paragraphs, and/or
"=begin"..."=end" codes.  Note that the numbers must start at 1
in each section, and must proceed in order and without skipping
numbers.

(Pod processors must tolerate lines like "=item 1" as if they were
"=item 1.", with the period.)

=item *

An "=over" ... "=back" region containing only "=item [text]"
commands, each one (or each group of them) followed by some number of
ordinary/verbatim paragraphs, other nested "=over" ... "=back"
regions, or "=for..." paragraphs, and "=begin"..."=end" regions.

The "=item [text]" paragraph should not match
C<m/\A=item\s+\d+\.?\s*\z/> or C<m/\A=item\s+\*\s*\z/>, nor should it
match just C<m/\A=item\s*\z/>.

=item *

An "=over" ... "=back" region containing no "=item" paragraphs at
all, and containing only some number of 
ordinary/verbatim paragraphs, and possibly also some nested "=over"
... "=back" regions, "=for..." paragraphs, and "=begin"..."=end"
regions.  Such an itemless "=over" ... "=back" region in Pod is
equivalent in meaning to a "<blockquote>...</blockquote>" element in
HTML.

=back

Note that with all the above cases, you can determine which type of
"=over" ... "=back" you have, by examining the first (non-"=cut", 
non-"=pod") Pod paragraph after the "=over" command.

=item *

Pod formatters I<must> tolerate arbitrarily large amounts of text
in the "=item I<text...>" paragraph.  In practice, most such
paragraphs are short, as in:

  =item For cutting off our trade with all parts of the world

But they may be arbitrarily long:

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

=item *

Pod processors should tolerate "=item *" / "=item I<number>" commands