perlpodspec.pod

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

in CE<lt>...> formatting codes, and never I<ever> to text in verbatim
paragraphs.

=item *

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 "object-oriented", which can be split across lines as
"object-", newline, "oriented"), formatters are encouraged to
generally translate "-" to non-breaking hyphen, but may apply
heuristics to convert some of these to breaking hyphens.

=item *

Pod formatters should make reasonable efforts to keep words of Perl
code from being broken across lines.  For example, "Foo::Bar" in some
formatting systems is seen as eligible for being broken across lines
as "Foo::" newline "Bar" or even "Foo::-" newline "Bar".  This should
be avoided where possible, either by disabling all line-breaking in
mid-word, or by wrapping particular words with internal punctuation
in "don't break this across lines" 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.)

=item *

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.

=item *

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.

=item *

Pod parsers, when reporting errors, should make some effort to report
an approximate line number ("Nested EE<lt>>'s in Paragraph #52, near
line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph
number ("Nested EE<lt>>'s in Paragraph #52 of Thing/Foo.pm!").  Where
this is problematic, the paragraph number should at least be
accompanied by an excerpt from the paragraph ("Nested EE<lt>>'s in
Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for
the CE<lt>interest rate> attribute...'").

=item *

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:

	use Foo;

	print Foo->VERSION

should be unified into one paragraph ("\tuse Foo;\n\n\tprint
Foo->VERSION") before being passed to the formatter or other
processor.  Parsers may also allow an option for overriding this.

While this might be too cumbersome to implement in event-based Pod
parsers, it is straightforward for parsers that return parse trees.

=item *

Pod formatters, where feasible, are advised to avoid splitting short
verbatim paragraphs (under twelve lines, say) across pages.

=item *

Pod parsers must treat a line with only spaces and/or tabs on it as a
"blank line" such as separates paragraphs.  (Some older parsers
recognized only two adjacent newlines as a "blank line" but would not
recognize a newline, a space, and a newline, as a blank line.  This
is noncompliant behavior.)

=item *

Authors of Pod formatters/processors should make every effort to
avoid writing their own Pod parser.  There are already several in
CPAN, with a wide range of interface styles -- and one of them,
Pod::Parser, comes with modern versions of Perl.

=item *

Characters in Pod documents may be conveyed either as literals, or by
number in EE<lt>n> codes, or by an equivalent mnemonic, as in
EE<lt>eacute> which is exactly equivalent to EE<lt>233>.

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 EE<lt>number> codes), except for the
literal byte-sequences for newline (13, 13 10, or 10), and tab (9).

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.

=item *

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.

=item *

Besides the well-known "EE<lt>lt>" and "EE<lt>gt>" codes for
less-than and greater-than, Pod parsers must understand "EE<lt>sol>"
for "/" (solidus, slash), and "EE<lt>verbar>" for "|" (vertical bar,
pipe).  Pod parsers should also understand "EE<lt>lchevron>" and
"EE<lt>rchevron>" as legacy codes for characters 171 and 187, i.e.,
"left-pointing double angle quotation mark" = "left pointing
guillemet" and "right-pointing double angle quotation mark" = "right
pointing guillemet".  (These look like little "<<" and ">>", and they
are now preferably expressed with the HTML/XHTML codes "EE<lt>laquo>"
and "EE<lt>raquo>".)

=item *

Pod parsers should understand all "EE<lt>html>" codes as defined
in the entity declarations in the most recent XHTML specification at
C<www.W3.org>.  Pod parsers must understand at least the entities
that define characters in the range 160-255 (Latin-1).  Pod parsers,
when faced with some unknown "EE<lt>I<identifier>>" code,
shouldn't simply replace it with nullstring (by default, at least),
but may pass it through as a string consisting of the literal characters
E, less-than, I<identifier>, greater-than.  Or Pod parsers may offer the
alternative option of processing such unknown
"EE<lt>I<identifier>>" codes by firing an event especially
for such codes, or by adding a special node-type to the in-memory
document tree.  Such "EE<lt>I<identifier>>" may have special meaning
to some processors, or some processors may choose to add them to
a special error report.

=item *

Pod parsers must also support the XHTML codes "EE<lt>quot>" for
character 34 (doublequote, "), "EE<lt>amp>" for character 38
(ampersand, &), and "EE<lt>apos>" for character 39 (apostrophe, ').

=item *

Note that in all cases of "EE<lt>whatever>", I<whatever> (whether
an htmlname, or a number in any base) must consist only of
alphanumeric characters -- that is, I<whatever> must watch
C<m/\A\w+\z/>.  So "EE<lt> 0 1 2 3 >" is invalid, because
it contains spaces, which aren't alphanumeric characters.  This
presumably does not I<need> special treatment by a Pod processor;
" 0 1 2 3 " doesn't look like a number in any base, so it would
presumably be looked up in the table of HTML-like names.  Since
there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ",
this will be treated as an error.  However, Pod processors may
treat "EE<lt> 0 1 2 3 >" or "EE<lt>e-acute>" as I<syntactically>
invalid, potentially earning a different error message than the
error message (or warning, or event) generated by a merely unknown
(but theoretically valid) htmlname, as in "EE<lt>qacute>"
[sic].  However, Pod parsers are not required to make this
distinction.

=item *

Note that EE<lt>number> I<must not> be interpreted as simply
"codepoint I<number> in the current/native character set".  It always
means only "the character represented by codepoint I<number> in
Unicode."  (This is identical to the semantics of &#I<number>; in XML.)

This will likely require many formatters to have tables mapping from
treatable Unicode codepoints (such as the "\xE9" for the e-acute
character) to the escape sequences or codes necessary for conveying
such sequences in the target output format.  A converter to *roff
would, for example know that "\xE9" (whether conveyed literally, or via
a EE<lt>...> sequence) is to be conveyed as "e\\*'".
Similarly, a program rendering Pod in a Mac OS application window, would
presumably need to know that "\xE9" maps to codepoint 142 in MacRoman
encoding that (at time of writing) is native for Mac OS.  Such
Unicode2whatever mappings are presumably already widely available for
common output formats.  (Such mappings may be incomplete!  Implementers
are not expected to bend over backwards in an attempt to render
Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
of the other weird things that Unicode can encode.)  And
if a Pod document uses a character not found in such a mapping, the
formatter should consider it an unrenderable character.

=item *

If, surprisingly, the implementor of a Pod formatter can't find a
satisfactory pre-existing table mapping from Unicode characters to
escapes in the target format (e.g., a decent table of Unicode
characters to *roff escapes), it will be necessary to build such a
table.  If you are in this circumstance, you should begin with the
characters in the range 0x00A0 - 0x00FF, which is mostly the heavily
used accented characters.  Then proceed (as patience permits and
fastidiousness compels) through the characters that the (X)HTML
standards groups judged important enough to merit mnemonics
for.  These are declared in the (X)HTML specifications at the
www.W3.org site.  At time of writing (September 2001), the most recent
entity declaration files are:

  http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
  http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
  http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

Then you can progress through any remaining notable Unicode characters
in the range 0x2000-0x204D (consult the character tables at
www.unicode.org), and whatever else strikes your fancy.  For example,
in F<xhtml-symbol.ent>, there is the entry:

  <!ENTITY infin    "&#8734;"> <!-- infinity, U+221E ISOtech -->

While the mapping "infin" to the character "\x{221E}" will (hopefully)
have been already handled by the Pod parser, the presence of the
character in this file means that it's reasonably important enough to
include in a formatter's table that maps from notable Unicode characters
to the codes necessary for rendering them.  So for a Unicode-to-*roff
mapping, for example, this would merit the entry:

  "\x{221E}" => '\(in',

It is eagerly hoped that in the future, increasing numbers of formats
(and formatters) will support Unicode characters directly (as (X)HTML
does with C<&infin;>, C<&#8734;>, or C<&#x221E;>), reducing the need
for idiosyncratic mappings of Unicode-to-I<my_escapes>.

=item *

It is up to individual Pod formatter to display good judgement when
confronted with an unrenderable character (which is distinct from an
unknown EE<lt>thing> sequence that the parser couldn't resolve to
anything, renderable or not).  It is good practice to map Latin letters
with diacritics (like "EE<lt>eacute>"/"EE<lt>233>") to the corresponding
unaccented US-ASCII letters (like a simple character 101, "e"), but
clearly this is often not feasible, and an unrenderable character may
be represented as "?", or the like.  In attempting a sane fallback
(as from EE<lt>233> to "e"), Pod formatters may use the
%Latin1Code_to_fallback table in L<Pod::Escapes|Pod::Escapes>, or
L<Text::Unidecode|Text::Unidecode>, if available.

For example, this Pod text:

  magic is enabled if you set C<$Currency> to 'E<euro>'.

may be rendered as:
"magic is enabled if you set C<$Currency> to 'I<?>'" or as
"magic is enabled if you set C<$Currency> to 'B<[euro]>'", or as
"magic is enabled if you set C<$Currency> to '[x20AC]', etc.

A Pod formatter may also note, in a comment or warning, a list of what
unrenderable characters were encountered.

=item *

EE<lt>...> may freely appear in any formatting code (other than
in another EE<lt>...> or in an ZE<lt>>).  That is, "XE<lt>The
EE<lt>euro>1,000,000 Solution>" is valid, as is "LE<lt>The
EE<lt>euro>1,000,000 Solution|Million::Euros>".

=item *

Some Pod formatters output to formats that implement non-breaking
spaces as an individual character (which I'll call "NBSP"), and
others output to formats that implement non-breaking spaces just as
spaces wrapped in a "don't break this across lines" code.  Note that
at the level of Pod, both sorts of codes can occur: Pod can contain a
NBSP character (whether as a literal, or as a "EE<lt>160>" or
"EE<lt>nbsp>" code); and Pod can contain "SE<lt>foo
IE<lt>barE<gt> baz>" codes, where "mere spaces" (character 32) in
such codes are taken to represent non-breaking spaces.  Pod
parsers should consider supporting the optional parsing of "SE<lt>foo
IE<lt>barE<gt> baz>" as if it were
"fooI<NBSP>IE<lt>barE<gt>I<NBSP>baz", and, going the other way, the
optional parsing of groups of words joined by NBSP's as if each group
were in a SE<lt>...> code, so that formatters may use the
representation that maps best to what the output format demands.

=item *

Some processors may find that the C<SE<lt>...E<gt>> code is easiest to
implement by replacing each space in the parse tree under the content
of the S, with an NBSP.  But note: the replacement should apply I<not> to
spaces in I<all> text, but I<only> to spaces in I<printable> text.  (This
distinction may or may not be evident in the particular tree/event
model implemented by the Pod parser.)  For example, consider this
unusual case:

   S<L</Autoloaded Functions>>

This means that the space in the middle of the visible link text must
not be broken across lines.  In other words, it's the same as this:

   L<"AutoloadedE<160>Functions"/Autoloaded Functions>

However, a misapplied space-to-NBSP replacement could (wrongly)
produce something equivalent to this:

   L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>

...which is almost definitely not going to work as a hyperlink (assuming
this formatter outputs a format supporting hypertext).

Formatters may choose to just not support the S format code,
especially in cases where the output format simply has no NBSP
character/code and no code for "don't break this stuff across lines".

=item *

Besides the NBSP character discussed above, implementors are reminded
of the existence of the other "special" character in Latin-1, the
"soft hyphen" character, also known as "discretionary hyphen",
i.e. C<EE<lt>173E<gt>> = C<EE<lt>0xADE<gt>> =
C<EE<lt>shyE<gt>>).  This character expresses an optional hyphenation
point.  That is, it normally renders as nothing, but may render as a
"-" if a formatter breaks the word at that point.  Pod formatters
should, as appropriate, do one of the following:  1) render this with
a code with the same meaning (e.g., "\-" in RTF), 2) pass it through
in the expectation that the formatter understands this character as
such, or 3) delete it.

For example:

  sigE<shy>action
  manuE<shy>script
  JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi

These signal to a formatter that if it is to hyphenate "sigaction"
or "manuscript", then it should be done as
"sig-I<[linebreak]>action" or "manu-I<[linebreak]>script"
(and if it doesn't hyphenate it, then the C<EE<lt>shyE<gt>> doesn't
show up at all).  And if it is
to hyphenate "Jarkko" and/or "Hietaniemi", it can do
so only at the points where there is a C<EE<lt>shyE<gt>> code.

In practice, it is anticipated that this character will not be used
often, but formatters should either support it, or delete it.

=item *

If you think that you want to add a new command to Pod (like, say, a
"=biblio" command), consider whether you could get the same
effect with a for or begin/end sequence: "=for biblio ..." or "=begin
biblio" ... "=end biblio".  Pod processors that don't understand
"=for biblio", etc, will simply ignore it, whereas they may complain
loudly if they see "=biblio".

=item *

Throughout this document, "Pod" has been the preferred spelling for
the name of the documentation format.  One may also use "POD" or
"pod".  For the documentation that is (typically) in the Pod
format, you may use "pod", or "Pod", or "POD".  Understanding these
distinctions is useful; but obsessing over how to spell them, usually
is not.

=back