perlpodspec.pod

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

with no accompanying paragraph.  The middle item is an example:

  =over

  =item 1

  Pick up dry cleaning.

  =item 2

  =item 3

  Stop by the store.  Get Abba Zabas, Stoli, and cheap lawn chairs.

  =back

=item *

No "=over" ... "=back" region can contain headings.  Processors may
treat such a heading as an error.

=item *

Note that an "=over" ... "=back" region should have some
content.  That is, authors should not have an empty region like this:

  =over

  =back

Pod processors seeing such a contentless "=over" ... "=back" region,
may ignore it, or may report it as an error.

=item *

Processors must tolerate an "=over" list that goes off the end of the
document (i.e., which has no matching "=back"), but they may warn
about such a list.

=item *

Authors of Pod formatters should note that this construct:

  =item Neque

  =item Porro

  =item Quisquam Est

  Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci 
  velit, sed quia non numquam eius modi tempora incidunt ut
  labore et dolore magnam aliquam quaerat voluptatem.

  =item Ut Enim

is semantically ambiguous, in a way that makes formatting decisions
a bit difficult.  On the one hand, it could be mention of an item
"Neque", mention of another item "Porro", and mention of another
item "Quisquam Est", with just the last one requiring the explanatory
paragraph "Qui dolorem ipsum quia dolor..."; and then an item
"Ut Enim".  In that case, you'd want to format it like so:

  Neque

  Porro

  Quisquam Est
    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.

  Ut Enim

But it could equally well be a discussion of three (related or equivalent)
items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph
explaining them all, and then a new item "Ut Enim".  In that case, you'd
probably want to format it like so:

  Neque
  Porro
  Quisquam Est
    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.

  Ut Enim

But (for the foreseeable future), Pod does not provide any way for Pod
authors to distinguish which grouping is meant by the above
"=item"-cluster structure.  So formatters should format it like so:

  Neque

  Porro

  Quisquam Est

    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.

  Ut Enim

That is, there should be (at least roughly) equal spacing between
items as between paragraphs (although that spacing may well be less
than the full height of a line of text).  This leaves it to the reader
to use (con)textual cues to figure out whether the "Qui dolorem
ipsum..." paragraph applies to the "Quisquam Est" item or to all three
items "Neque", "Porro", and "Quisquam Est".  While not an ideal
situation, this is preferable to providing formatting cues that may
be actually contrary to the author's intent.

=back



=head1 About Data Paragraphs and "=begin/=end" Regions

Data paragraphs are typically used for inlining non-Pod data that is
to be used (typically passed through) when rendering the document to
a specific format:

  =begin rtf

  \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

  =end rtf

The exact same effect could, incidentally, be achieved with a single
"=for" paragraph:

  =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

(Although that is not formally a data paragraph, it has the same
meaning as one, and Pod parsers may parse it as one.)

Another example of a data paragraph:

  =begin html

  I like <em>PIE</em>!

  <hr>Especially pecan pie!

  =end html

If these were ordinary paragraphs, the Pod parser would try to
expand the "EE<lt>/em>" (in the first paragraph) as a formatting
code, just like "EE<lt>lt>" or "EE<lt>eacute>".  But since this
is in a "=begin I<identifier>"..."=end I<identifier>" region I<and>
the identifier "html" doesn't begin have a ":" prefix, the contents
of this region are stored as data paragraphs, instead of being
processed as ordinary paragraphs (or if they began with a spaces
and/or tabs, as verbatim paragraphs).

As a further example: At time of writing, no "biblio" identifier is
supported, but suppose some processor were written to recognize it as
a way of (say) denoting a bibliographic reference (necessarily
containing formatting codes in ordinary paragraphs).  The fact that
"biblio" paragraphs were meant for ordinary processing would be
indicated by prefacing each "biblio" identifier with a colon:

  =begin :biblio

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =end :biblio

This would signal to the parser that paragraphs in this begin...end
region are subject to normal handling as ordinary/verbatim paragraphs
(while still tagged as meant only for processors that understand the
"biblio" identifier).  The same effect could be had with:

  =for :biblio
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

The ":" on these identifiers means simply "process this stuff
normally, even though the result will be for some special target".
I suggest that parser APIs report "biblio" as the target identifier,
but also report that it had a ":" prefix.  (And similarly, with the
above "html", report "html" as the target identifier, and note the
I<lack> of a ":" prefix.)

Note that a "=begin I<identifier>"..."=end I<identifier>" region where
I<identifier> begins with a colon, I<can> contain commands.  For example:

  =begin :biblio

  Wirth's classic is available in several editions, including:

  =for comment
   hm, check abebooks.com for how much used copies cost.

  =over

  =item

  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]

  =item

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =back

  =end :biblio

Note, however, a "=begin I<identifier>"..."=end I<identifier>"
region where I<identifier> does I<not> begin with a colon, should not
directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back",
nor "=item".  For example, this may be considered invalid:

  =begin somedata

  This is a data paragraph.

  =head1 Don't do this!

  This is a data paragraph too.

  =end somedata

A Pod processor may signal that the above (specifically the "=head1"
paragraph) is an error.  Note, however, that the following should
I<not> be treated as an error:

  =begin somedata

  This is a data paragraph.

  =cut

  # Yup, this isn't Pod anymore.
  sub excl { (rand() > .5) ? "hoo!" : "hah!" }

  =pod

  This is a data paragraph too.

  =end somedata

And this too is valid:

  =begin someformat

  This is a data paragraph.

    And this is a data paragraph.

  =begin someotherformat

  This is a data paragraph too.

    And this is a data paragraph too.

  =begin :yetanotherformat

  =head2 This is a command paragraph!

  This is an ordinary paragraph!

    And this is a verbatim paragraph!

  =end :yetanotherformat

  =end someotherformat

  Another data paragraph!

  =end someformat

The contents of the above "=begin :yetanotherformat" ...
"=end :yetanotherformat" region I<aren't> data paragraphs, because
the immediately containing region's identifier (":yetanotherformat")
begins with a colon.  In practice, most regions that contain
data paragraphs will contain I<only> data paragraphs; however, 
the above nesting is syntactically valid as Pod, even if it is
rare.  However, the handlers for some formats, like "html",
will accept only data paragraphs, not nested regions; and they may
complain if they see (targeted for them) nested regions, or commands,
other than "=end", "=pod", and "=cut".

Also consider this valid structure:

  =begin :biblio

  Wirth's classic is available in several editions, including:

  =over

  =item

  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]

  =item

  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

  =back

  Buy buy buy!

  =begin html

  <img src='wirth_spokesmodeling_book.png'>

  <hr>

  =end html

  Now now now!

  =end :biblio

There, the "=begin html"..."=end html" region is nested inside
the larger "=begin :biblio"..."=end :biblio" region.  Note that the
content of the "=begin html"..."=end html" region is data
paragraph(s), because the immediately containing region's identifier
("html") I<doesn't> begin with a colon.

Pod parsers, when processing a series of data paragraphs one
after another (within a single region), should consider them to
be one large data paragraph that happens to contain blank lines.  So
the content of the above "=begin html"..."=end html" I<may> be stored
as two data paragraphs (one consisting of
"<img src='wirth_spokesmodeling_book.png'>\n"
and another consisting of "<hr>\n"), but I<should> be stored as
a single data paragraph (consisting of 
"<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").

Pod processors should tolerate empty
"=begin I<something>"..."=end I<something>" regions,
empty "=begin :I<something>"..."=end :I<something>" regions, and
contentless "=for I<something>" and "=for :I<something>"
paragraphs.  I.e., these should be tolerated:

  =for html

  =begin html

  =end html

  =begin :biblio

  =end :biblio

Incidentally, note that there's no easy way to express a data
paragraph starting with something that looks like a command.  Consider:

  =begin stuff

  =shazbot

  =end stuff

There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
paragraph "=shazbot\n".  However, you can exp