perlpodspec.1

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

.Sp
Consider:
.Sp
.Vb 1
\&    C<$x ? $y    :  $z>
\&
\&    S<C<$x ? $y     :  $z>>
.Ve
.Sp
Both signify the monospace (c[ode] style) text consisting of
\&\*(L"$x\*(R", one space, \*(L"?\*(R", one space, \*(L":\*(R", one space, \*(L"$z\*(R".  The
difference is that in the latter, with the S code, those spaces
are not \*(L"normal\*(R" spaces, but instead are non-breaking spaces.
.PP
If a Pod processor sees any formatting code other than the ones
listed above (as in \*(L"N<...>\*(R", or \*(L"Q<...>\*(R", etc.), that
processor must by default treat this as an error.
A Pod parser may allow a way for particular
applications to add to the above list of known formatting codes;
a Pod parser might even allow a way to stipulate, for each additional
command, whether it requires some form of special processing, as
L<...> does.
.PP
Future versions of this specification may add additional
formatting codes.
.PP
Historical note:  A few older Pod processors would not see a \*(L">\*(R" as
closing a \*(L"C<\*(R" code, if the \*(L">\*(R" was immediately preceded by
a \*(L"\-\*(R".  This was so that this:
.PP
.Vb 1
\&    C<$foo\->bar>
.Ve
.PP
would parse as equivalent to this:
.PP
.Vb 1
\&    C<$foo\-E<gt>bar>
.Ve
.PP
instead of as equivalent to a \*(L"C\*(R" formatting code containing 
only \*(L"$foo\-\*(R", and then a \*(L"bar>\*(R" outside the \*(L"C\*(R" formatting code.  This
problem has since been solved by the addition of syntaxes like this:
.PP
.Vb 1
\&    C<< $foo\->bar >>
.Ve
.PP
Compliant parsers must not treat \*(L"\->\*(R" as special.
.PP
Formatting codes absolutely cannot span paragraphs.  If a code is
opened in one paragraph, and no closing code is found by the end of
that paragraph, the Pod parser must close that formatting code,
and should complain (as in \*(L"Unterminated I code in the paragraph
starting at line 123: 'Time objects are not...'\*(R").  So these
two paragraphs:
.PP
.Vb 1
\&  I<I told you not to do this!
\&
\&  Don\*(Aqt make me say it again!>
.Ve
.PP
\&...must \fInot\fR be parsed as two paragraphs in italics (with the I
code starting in one paragraph and starting in another.)  Instead,
the first paragraph should generate a warning, but that aside, the
above code must parse as if it were:
.PP
.Vb 1
\&  I<I told you not to do this!>
\&
\&  Don\*(Aqt make me say it again!E<gt>
.Ve
.PP
(In SGMLish jargon, all Pod commands are like block-level
elements, whereas all Pod formatting codes are like inline-level
elements.)
.SH "Notes on Implementing Pod Processors"
.IX Header "Notes on Implementing Pod Processors"
The following is a long section of miscellaneous requirements
and suggestions to do with Pod processing.
.IP "\(bu" 4
Pod formatters should tolerate lines in verbatim blocks that are of
any length, even if that means having to break them (possibly several
times, for very long lines) to avoid text running off the side of the
page.  Pod formatters may warn of such line-breaking.  Such warnings
are particularly appropriate for lines are over 100 characters long, which
are usually not intentional.
.IP "\(bu" 4
Pod parsers must recognize \fIall\fR of the three well-known newline
formats: \s-1CR\s0, \s-1LF\s0, and \s-1CRLF\s0.  See perlport.
.IP "\(bu" 4
Pod parsers should accept input lines that are of any length.
.IP "\(bu" 4
Since Perl recognizes a Unicode Byte Order Mark at the start of files
as signaling that the file is Unicode encoded as in \s-1UTF\-16\s0 (whether
big-endian or little-endian) or \s-1UTF\-8\s0, Pod parsers should do the
same.  Otherwise, the character encoding should be understood as
being \s-1UTF\-8\s0 if the first highbit byte sequence in the file seems
valid as a \s-1UTF\-8\s0 sequence, or otherwise as Latin\-1.
.Sp
Future versions of this specification may specify
how Pod can accept other encodings.  Presumably treatment of other
encodings in Pod parsing would be as in \s-1XML\s0 parsing: whatever the
encoding declared by a particular Pod file, content is to be
stored in memory as Unicode characters.
.IP "\(bu" 4
The well known Unicode Byte Order Marks are as follows:  if the
file begins with the two literal byte values 0xFE 0xFF, this is
the \s-1BOM\s0 for big-endian \s-1UTF\-16\s0.  If the file begins with the two
literal byte value 0xFF 0xFE, this is the \s-1BOM\s0 for little-endian
\&\s-1UTF\-16\s0.  If the file begins with the three literal byte values
0xEF 0xBB 0xBF, this is the \s-1BOM\s0 for \s-1UTF\-8\s0.
.IP "\(bu" 4
A naive but sufficient heuristic for testing the first highbit
byte-sequence in a BOM-less file (whether in code or in Pod!), to see
whether that sequence is valid as \s-1UTF\-8\s0 (\s-1RFC\s0 2279) is to check whether
that the first byte in the sequence is in the range 0xC0 \- 0xFD
\&\fIand\fR whether the next byte is in the range
0x80 \- 0xBF.  If so, the parser may conclude that this file is in
\&\s-1UTF\-8\s0, and all highbit sequences in the file should be assumed to
be \s-1UTF\-8\s0.  Otherwise the parser should treat the file as being
in Latin\-1.  In the unlikely circumstance that the first highbit
sequence in a truly non\-UTF\-8 file happens to appear to be \s-1UTF\-8\s0, one
can cater to our heuristic (as well as any more intelligent heuristic)
by prefacing that line with a comment line containing a highbit
sequence that is clearly \fInot\fR valid as \s-1UTF\-8\s0.  A line consisting
of simply \*(L"#\*(R", an e\-acute, and any non-highbit byte,
is sufficient to establish this file's encoding.
.IP "\(bu" 4
This document's requirements and suggestions about encodings
do not apply to Pod processors running on non-ASCII platforms,
notably \s-1EBCDIC\s0 platforms.
.IP "\(bu" 4
Pod processors must treat a \*(L"=for [label] [content...]\*(R" paragraph as
meaning the same thing as a \*(L"=begin [label]\*(R" paragraph, content, and
an \*(L"=end [label]\*(R" paragraph.  (The parser may conflate these two
constructs, or may leave them distinct, in the expectation that the
formatter will nevertheless treat them the same.)
.IP "\(bu" 4
When rendering Pod to a format that allows comments (i.e., to nearly
any format other than plaintext), a Pod formatter must insert comment
text identifying its name and version number, and the name and
version numbers of any modules it might be using to process the Pod.
Minimal examples:
.Sp
.Vb 1
\&  %% POD::Pod2PS v3.14159, using POD::Parser v1.92
\&
\&  <!\-\- Pod::HTML v3.14159, using POD::Parser v1.92 \-\->
\&
\&  {\edoccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
\&
\&  .\e" Pod::Man version 3.14159, using POD::Parser version 1.92
.Ve
.Sp
Formatters may also insert additional comments, including: the
release date of the Pod formatter program, the contact address for
the author(s) of the formatter, the current time, the name of input
file, the formatting options in effect, version of Perl used, etc.
.Sp
Formatters may also choose to note errors/warnings as comments,
besides or instead of emitting them otherwise (as in messages to
\&\s-1STDERR\s0, or \f(CW\*(C`die\*(C'\fRing).
.IP "\(bu" 4
Pod parsers \fImay\fR emit warnings or error messages (\*(L"Unknown E code
E<zslig>!\*(R") to \s-1STDERR\s0 (whether through printing to \s-1STDERR\s0, or
\&\f(CW\*(C`warn\*(C'\fRing/\f(CW\*(C`carp\*(C'\fRing, or \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing), but \fImust\fR allow
suppressing all such \s-1STDERR\s0 output, and instead allow an option for
reporting errors/warnings
in some other way, whether by triggering a callback, or noting errors
in some attribute of the document object, or some similarly unobtrusive
mechanism \*(-- or even by appending a \*(L"Pod Errors\*(R" section to the end of
the parsed form of the document.
.IP "\(bu" 4
In cases of exceptionally aberrant documents, Pod parsers may abort the
parse.  Even then, using \f(CW\*(C`die\*(C'\fRing/\f(CW\*(C`croak\*(C'\fRing is to be avoided; where
possible, the parser library may simply close the input file
and add text like \*(L"*** Formatting Aborted ***\*(R" to the end of the
(partial) in-memory document.
.IP "\(bu" 4
In paragraphs where formatting codes (like E<...>, B<...>)
are understood (i.e., \fInot\fR verbatim paragraphs, but \fIincluding\fR
ordinary paragraphs, and command paragraphs that produce renderable
text, like \*(L"=head1\*(R"), literal whitespace should generally be considered
\&\*(L"insignificant\*(R", in that one literal space has the same meaning as any
(nonzero) number of literal spaces, literal newlines, and literal tabs
(as long as this produces no blank lines, since those would terminate
the paragraph).  Pod parsers should compact literal whitespace in each
processed paragraph, but may provide an option for overriding this
(since some processing tasks do not require it), or may follow
additional special rules (for example, specially treating
period-space-space or period-newline sequences).
.IP "\(bu" 4
Pod parsers should not, by default, try to coerce apostrophe (') and
quote (\*(L") into smart quotes (little 9's, 66's, 99's, etc), nor try to
turn backtick (`) into anything else but a single backtick character
(distinct from an open quote character!), nor \*(R"\-\-" into anything but
two minus signs.  They \fImust never\fR do any of those things to text
in C<...> formatting codes, and never \fIever\fR to text in verbatim
paragraphs.
.IP "\(bu" 4
When rendering Pod to a format that has two kinds of hyphens (\-), one
that's a non-breaking hyphen, and another that's a breakable hyphen
(as in \*(L"object-oriented\*(R", which can be split across lines as
\&\*(L"object\-\*(R", newline, \*(L"oriented\*(R"), formatters are encouraged to
generally translate \*(L"\-\*(R" to non-breaking hyphen, but may apply
heuristics to convert some of these to breaking hyphens.
.IP "\(bu" 4
Pod formatters should make reasonable efforts to keep words of Perl
code from being broken across lines.  For example, \*(L"Foo::Bar\*(R" in some
formatting systems is seen as eligible for being broken across lines
as \*(L"Foo::\*(R" newline \*(L"Bar\*(R" or even \*(L"Foo::\-\*(R" newline \*(L"Bar\*(R".  This should
be avoided where possible, either by disabling all line-breaking in
mid-word, or by wrapping particular words with internal punctuation
in \*(L"don't break this across lines\*(R" codes (which in some formats may
not be a single code, but might be a matter of inserting non-breaking
zero-width spaces between every pair of characters in a word.)
.IP "\(bu" 4
Pod parsers should, by default, expand tabs in verbatim paragraphs as
they are processed, before passing them to the formatter or other
processor.  Parsers may also allow an option for overriding this.
.IP "\(bu" 4
Pod parsers should, by default, remove newlines from the end of
ordinary and verbatim paragraphs before passing them to the
formatter.  For example, while the paragraph you're reading now
could be considered, in Pod source, to end with (and contain)
the newline(s) that end it, it should be processed as ending with
(and containing) the period character that ends this sentence.
.IP "\(bu" 4
Pod parsers, when reporting errors, should make some effort to report
an approximate line number (\*(L"Nested E<>'s in Paragraph #52, near
line 633 of Thing/Foo.pm!\*(R"), instead of merely noting the paragraph
number (\*(L"Nested E<>'s in Paragraph #52 of Thing/Foo.pm!\*(R").  Where
this is problematic, the paragraph number should at least be
accompanied by an excerpt from the paragraph (\*(L"Nested E<>'s in
Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for
the C<interest rate> attribute...'\*(R").
.IP "\(bu" 4
Pod parsers, when processing a series of verbatim paragraphs one
after another, should consider them to be one large verbatim
paragraph that happens to contain blank lines.  I.e., these two
lines, which have a blank line between them:
.Sp
.Vb 1
\&        use Foo;
\&
\&        print Foo\->VERSION
.Ve
.Sp
should be unified into one paragraph (\*(L"\etuse Foo;\en\en\etprint
Foo\->\s-1VERSION\s0\*(R") before being passed to the formatter or other
processor.  Parsers may also allow an option for overriding this.
.Sp
While this might be too cumbersome to implement in event-based Pod
parsers, it is straightforward for parsers that return parse trees.
.IP "\(bu" 4
Pod formatters, where feasible, are advised to avoid splitting short
verbatim paragraphs (under twelve lines, say) across pages.
.IP "\(bu" 4
Pod parsers must treat a line with only spaces and/or tabs on it as a
\&\*(L"blank line\*(R" such as separates paragraphs.  (Some older parsers
recognized only two adjacent newlines as a \*(L"blank line\*(R" but would not
recognize a newline, a space, and a newline, as a blank line.  This
is noncompliant behavior.)
.IP "\(bu" 4
Authors of Pod formatters/processors should make every effort to
avoid writing their own Pod parser.  There are already several in
\&\s-1CPAN\s0, with a wide range of interface styles \*(-- and one of them,
Pod::Parser, comes with modern versions of Perl.
.IP "\(bu" 4
Characters in Pod documents may be conveyed either as literals, or by
number in E<n> codes, or by an equivalent mnemonic, as in
E<eacute> which is exactly equivalent to E<233>.
.Sp
Characters in the range 32\-126 refer to those well known US-ASCII
characters (also defined there by Unicode, with the same meaning),
which all Pod formatters must render faithfully.  Characters
in the ranges 0\-31 and 127\-159 should not be used (neither as
literals, nor as E<number> codes), except for the
literal byte-sequences for newline (13, 13 10, or 10), and tab (9).
.Sp
Characters in the range 160\-255 refer to Latin\-1 characters (also
defined there by Unicode, with the same meaning).  Characters above
255 should be understood to refer to Unicode characters.
.IP "\(bu" 4
Be warned
that some formatters cannot reliably render characters outside 32\-126;
and many are able to handle 32\-126 and 160\-255, but nothing above
255.
.IP "\(bu" 4
Besides the well-known \*(L"E<lt>\*(R" and \*(L"E<gt>\*(R" codes for
less-than and greater-than, Pod parsers must understand \*(L"E<sol>\*(R"
for \*(L"/\*(R" (solidus, slash), and \*(L"E<verbar>\*(R" for \*(L"|\*(R" (vertical bar,
pipe).  Pod parsers should also understand \*(L"E<lchevron>\*(R" and
\&\*(L"E<rchevron>\*(R" as legacy codes for characters 171 and 187, i.e.,
\&\*(L"left-pointing double angle quotation mark\*(R" = \*(L"left pointing
guillemet\*(R" and \*(L"right-pointing double angle quotation mark\*(R" = \*(L"right