perlpodspec.1

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

paragraphs that they surround from being parsed as data or verbatim
paragraphs, if \fIidentifier\fR doesn't begin with a colon.  This
is discussed in detail in the section
\&\*(L"About Data Paragraphs and \*(R"=begin/=end\*(L" Regions\*(R".
.SH "Pod Commands"
.IX Header "Pod Commands"
This section is intended to supplement and clarify the discussion in
\&\*(L"Command Paragraph\*(R" in perlpod.  These are the currently recognized
Pod commands:
.ie n .IP """=head1"", ""=head2"", ""=head3"", ""=head4""" 4
.el .IP "``=head1'', ``=head2'', ``=head3'', ``=head4''" 4
.IX Item "=head1, =head2, =head3, =head4"
This command indicates that the text in the remainder of the paragraph
is a heading.  That text may contain formatting codes.  Examples:
.Sp
.Vb 1
\&  =head1 Object Attributes
\&
\&  =head3 What B<Not> to Do!
.Ve
.ie n .IP """=pod""" 4
.el .IP "``=pod''" 4
.IX Item "=pod"
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 \*(L"=pod\*(R",
it must be ignored.  Examples:
.Sp
.Vb 1
\&  =pod
\&
\&  This is a plain Pod paragraph.
\&
\&  =pod This text is ignored.
.Ve
.ie n .IP """=cut""" 4
.el .IP "``=cut''" 4
.IX Item "=cut"
This command indicates that this line is the end of this previously
started Pod block.  If there is any text after \*(L"=cut\*(R" on the line, it must be
ignored.  Examples:
.Sp
.Vb 1
\&  =cut
\&
\&  =cut The documentation ends here.
\&
\&  =cut
\&  # This is the first line of program text.
\&  sub foo { # This is the second.
.Ve
.Sp
It is an error to try to \fIstart\fR a Pod block with a \*(L"=cut\*(R" command.  In
that case, the Pod processor must halt parsing of the input file, and
must by default emit a warning.
.ie n .IP """=over""" 4
.el .IP "``=over''" 4
.IX Item "=over"
This command indicates that this is the start of a list/indent
region.  If there is any text following the \*(L"=over\*(R", it must consist
of only a nonzero positive numeral.  The semantics of this numeral is
explained in the \*(L"About =over...=back Regions\*(R" section, further
below.  Formatting codes are not expanded.  Examples:
.Sp
.Vb 1
\&  =over 3
\&
\&  =over 3.5
\&
\&  =over
.Ve
.ie n .IP """=item""" 4
.el .IP "``=item''" 4
.IX Item "=item"
This command indicates that an item in a list begins here.  Formatting
codes are processed.  The semantics of the (optional) text in the
remainder of this paragraph are
explained in the \*(L"About =over...=back Regions\*(R" section, further
below.  Examples:
.Sp
.Vb 1
\&  =item
\&
\&  =item *
\&
\&  =item      *    
\&
\&  =item 14
\&
\&  =item   3.
\&
\&  =item C<< $thing\->stuff(I<dodad>) >>
\&
\&  =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
.ie n .IP """=back""" 4
.el .IP "``=back''" 4
.IX Item "=back"
This command indicates that this is the end of the region begun
by the most recent \*(L"=over\*(R" command.  It permits no text after the
\&\*(L"=back\*(R" command.
.ie n .IP """=begin formatname""" 4
.el .IP "``=begin formatname''" 4
.IX Item "=begin formatname"
This marks the following paragraphs (until the matching \*(L"=end
formatname\*(R") as being for some special kind of processing.  Unless
\&\*(L"formatname\*(R" begins with a colon, the contained non-command
paragraphs are data paragraphs.  But if \*(L"formatname\*(R" \fIdoes\fR begin
with a colon, then non-command paragraphs are ordinary paragraphs
or data paragraphs.  This is discussed in detail in the section
\&\*(L"About Data Paragraphs and \*(R"=begin/=end\*(L" Regions\*(R".
.Sp
It is advised that formatnames match the regexp
\&\f(CW\*(C`m/\eA:?[\-a\-zA\-Z0\-9_]+\ez/\*(C'\fR.  Implementors should anticipate future
expansion in the semantics and syntax of the first parameter
to \*(L"=begin\*(R"/\*(L"=end\*(R"/\*(L"=for\*(R".
.ie n .IP """=end formatname""" 4
.el .IP "``=end formatname''" 4
.IX Item "=end formatname"
This marks the end of the region opened by the matching
\&\*(L"=begin formatname\*(R" region.  If \*(L"formatname\*(R" is not the formatname
of the most recent open \*(L"=begin formatname\*(R" region, then this
is an error, and must generate an error message.  This
is discussed in detail in the section
\&\*(L"About Data Paragraphs and \*(R"=begin/=end\*(L" Regions\*(R".
.ie n .IP """=for formatname text...""" 4
.el .IP "``=for formatname text...''" 4
.IX Item "=for formatname text..."
This is synonymous with:
.Sp
.Vb 1
\&     =begin formatname
\&
\&     text...
\&
\&     =end formatname
.Ve
.Sp
That is, it creates a region consisting of a single paragraph; that
paragraph is to be treated as a normal paragraph if \*(L"formatname\*(R"
begins with a \*(L":\*(R"; if \*(L"formatname\*(R" \fIdoesn't\fR begin with a colon,
then \*(L"text...\*(R" will constitute a data paragraph.  There is no way
to use \*(L"=for formatname text...\*(R" to express \*(L"text...\*(R" as a verbatim
paragraph.
.ie n .IP """=encoding encodingname""" 4
.el .IP "``=encoding encodingname''" 4
.IX Item "=encoding encodingname"
This command, which should occur early in the document (at least
before any non-US-ASCII data!), declares that this document is
encoded in the encoding \fIencodingname\fR, which must be
an encoding name that Encoding recognizes.  (Encoding's list
of supported encodings, in Encoding::Supported, is useful here.)
If the Pod parser cannot decode the declared encoding, it 
should emit a warning and may abort parsing the document
altogether.
.Sp
A document having more than one \*(L"=encoding\*(R" line should be
considered an error.  Pod processors may silently tolerate this if
the not-first \*(L"=encoding\*(R" lines are just duplicates of the
first one (e.g., if there's a \*(L"=use utf8\*(R" line, and later on
another \*(L"=use utf8\*(R" line).  But Pod processors should complain if
there are contradictory \*(L"=encoding\*(R" lines in the same document
(e.g., if there is a \*(L"=encoding utf8\*(R" early in the document and
\&\*(L"=encoding big5\*(R" later).  Pod processors that recognize BOMs
may also complain if they see an \*(L"=encoding\*(R" line
that contradicts the \s-1BOM\s0 (e.g., if a document with a \s-1UTF\-16LE\s0
\&\s-1BOM\s0 has an \*(L"=encoding shiftjis\*(R" line).
.PP
If a Pod processor sees any command other than the ones listed
above (like \*(L"=head\*(R", or \*(L"=haed1\*(R", or \*(L"=stuff\*(R", or \*(L"=cuttlefish\*(R",
or \*(L"=w123\*(R"), that processor must by default treat this as an
error.  It must not process the paragraph beginning with that
command, must by default warn of this as an error, and may
abort the parse.  A Pod parser may allow a way for particular
applications to add to the above list of known commands, and to
stipulate, for each additional command, whether formatting
codes should be processed.
.PP
Future versions of this specification may add additional
commands.
.SH "Pod Formatting Codes"
.IX Header "Pod Formatting Codes"
(Note that in previous drafts of this document and of perlpod,
formatting codes were referred to as \*(L"interior sequences\*(R", and
this term may still be found in the documentation for Pod parsers,
and in error messages from Pod processors.)
.PP
There are two syntaxes for formatting codes:
.IP "\(bu" 4
A formatting code starts with a capital letter (just US-ASCII [A\-Z])
followed by a \*(L"<\*(R", any number of characters, and ending with the first
matching \*(L">\*(R".  Examples:
.Sp
.Vb 1
\&    That\*(Aqs what I<you> think!
\&
\&    What\*(Aqs C<dump()> for?
\&
\&    X<C<chmod> and C<unlink()> Under Different Operating Systems>
.Ve
.IP "\(bu" 4
A formatting code starts with a capital letter (just US-ASCII [A\-Z])
followed by two or more \*(L"<\*(R"'s, one or more whitespace characters,
any number of characters, one or more whitespace characters,
and ending with the first matching sequence of two or more \*(L">\*(R"'s, where
the number of \*(L">\*(R"'s equals the number of \*(L"<\*(R"'s in the opening of this
formatting code.  Examples:
.Sp
.Vb 1
\&    That\*(Aqs what I<< you >> think!
\&
\&    C<<< open(X, ">>thing.dat") || die $! >>>
\&
\&    B<< $foo\->bar(); >>
.Ve
.Sp
With this syntax, the whitespace character(s) after the \*(L"C<<<\*(R"
and before the \*(L">>\*(R" (or whatever letter) are \fInot\fR renderable \*(-- they
do not signify whitespace, are merely part of the formatting codes
themselves.  That is, these are all synonymous:
.Sp
.Vb 7
\&    C<thing>
\&    C<< thing >>
\&    C<<           thing     >>
\&    C<<<   thing >>>
\&    C<<<<
\&    thing
\&               >>>>
.Ve
.Sp
and so on.
.PP
In parsing Pod, a notably tricky part is the correct parsing of
(potentially nested!) formatting codes.  Implementors should
consult the code in the \f(CW\*(C`parse_text\*(C'\fR routine in Pod::Parser as an
example of a correct implementation.
.ie n .IP """I<text>"" \*(-- italic text" 4
.el .IP "\f(CWI<text>\fR \*(-- italic text" 4
.IX Item "I<text>  italic text"
See the brief discussion in \*(L"Formatting Codes\*(R" in perlpod.
.ie n .IP """B<text>"" \*(-- bold text" 4
.el .IP "\f(CWB<text>\fR \*(-- bold text" 4
.IX Item "B<text>  bold text"
See the brief discussion in \*(L"Formatting Codes\*(R" in perlpod.
.ie n .IP """C<code>"" \*(-- code text" 4
.el .IP "\f(CWC<code>\fR \*(-- code text" 4
.IX Item "C<code>  code text"
See the brief discussion in \*(L"Formatting Codes\*(R" in perlpod.
.ie n .IP """F<filename>"" \*(-- style for filenames" 4
.el .IP "\f(CWF<filename>\fR \*(-- style for filenames" 4
.IX Item "F<filename>  style for filenames"
See the brief discussion in \*(L"Formatting Codes\*(R" in perlpod.
.ie n .IP """X<topic name>"" \*(-- an index entry" 4
.el .IP "\f(CWX<topic name>\fR \*(-- an index entry" 4
.IX Item "X<topic name>  an index entry"
See the brief discussion in \*(L"Formatting Codes\*(R" in perlpod.
.Sp
This code is unusual in that most formatters completely discard
this code and its content.  Other formatters will render it with
invisible codes that can be used in building an index of
the current document.
.ie n .IP """Z<>"" \*(-- a null (zero-effect) formatting code" 4
.el .IP "\f(CWZ<>\fR \*(-- a null (zero-effect) formatting code" 4
.IX Item "Z<>  a null (zero-effect) formatting code"
Discussed briefly in \*(L"Formatting Codes\*(R" in perlpod.
.Sp
This code is unusual is that it should have no content.  That is,
a processor may complain if it sees \f(CW\*(C`Z<potatoes>\*(C'\fR.  Whether
or not it complains, the \fIpotatoes\fR text should ignored.
.ie n .IP """L<name>"" \*(-- a hyperlink" 4
.el .IP "\f(CWL<name>\fR \*(-- a hyperlink" 4
.IX Item "L<name>  a hyperlink"
The complicated syntaxes of this code are discussed at length in
\&\*(L"Formatting Codes\*(R" in perlpod, and implementation details are
discussed below, in \*(L"About L<...> Codes\*(R".  Parsing the
contents of L<content> is tricky.  Notably, the content has to be
checked for whether it looks like a \s-1URL\s0, or whether it has to be split
on literal \*(L"|\*(R" and/or \*(L"/\*(R" (in the right order!), and so on,
\&\fIbefore\fR E<...> codes are resolved.
.ie n .IP """E<escape>"" \*(-- a character escape" 4
.el .IP "\f(CWE<escape>\fR \*(-- a character escape" 4
.IX Item "E<escape>  a character escape"
See \*(L"Formatting Codes\*(R" in perlpod, and several points in
\&\*(L"Notes on Implementing Pod Processors\*(R".
.ie n .IP """S<text>"" \*(-- text contains non-breaking spaces" 4
.el .IP "\f(CWS<text>\fR \*(-- text contains non-breaking spaces" 4
.IX Item "S<text>  text contains non-breaking spaces"
This formatting code is syntactically simple, but semantically
complex.  What it means is that each space in the printable
content of this code signifies a non-breaking space.