whitespace character (and there's no "=begin"..."=end" region around).
The "=begin I<identifier>" ... "=end I<identifier>" commands stop
-paragraphs that they surround from being parsed as data or verbatim
+paragraphs that they surround from being parsed as ordinary or verbatim
paragraphs, if I<identifier> doesn't begin with a colon. This
is discussed in detail in the section
L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
=item "=begin formatname"
+=item "=begin formatname parameter"
+
This marks the following paragraphs (until the matching "=end
formatname") as being for some special kind of processing. Unless
"formatname" begins with a colon, the contained non-command
L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
It is advised that formatnames match the regexp
-C<m/\A:?[-a-zA-Z0-9_]+\z/>. Implementors should anticipate future
-expansion in the semantics and syntax of the first parameter
-to "=begin"/"=end"/"=for".
+C<m/\A:?[−a−zA−Z0−9_]+\z/>. Everything following whitespace after the
+formatname is a parameter that may be used by the formatter when dealing
+with this region. This parameter must not be repeated in the "=end"
+paragraph. Implementors should anticipate future expansion in the
+semantics and syntax of the first parameter to "=begin"/"=end"/"=for".
=item "=end formatname"
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 I<encodingname>, which must be
-an encoding name that L<Encoding> recognizes. (Encoding's list
-of supported encodings, in L<Encoding::Supported>, is useful here.)
+an encoding name that L<Encode> recognizes. (Encode's list
+of supported encodings, in L<Encode::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.
A document having more than one "=encoding" line should be
considered an error. Pod processors may silently tolerate this if
the not-first "=encoding" lines are just duplicates of the
-first one (e.g., if there's a "=use utf8" line, and later on
-another "=use utf8" line). But Pod processors should complain if
+first one (e.g., if there's a "=encoding utf8" line, and later on
+another "=encoding utf8" line). But Pod processors should complain if
there are contradictory "=encoding" lines in the same document
(e.g., if there is a "=encoding utf8" early in the document and
"=encoding big5" later). Pod processors that recognize BOMs
'url', # what sort of link
"http://www.perl.org/" # original content
+ L<Perl.org|http://www.perl.org/>
+ => "Perl.org", # link text
+ "http://www.perl.org/", # possibly inferred link text
+ "http://www.perl.org/", # name
+ undef, # section
+ 'url', # what sort of link
+ "Perl.org|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
=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.
+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 and for C<LE<lt>"section"E<gt>> which was only
+slightly less ambiguous. This syntax is no longer in the specification, and
+has been replaced by the C<LE<lt>/sectionE<gt>> syntax (where the slash was
+formerly optional). Pod parsers should tolerate the C<LE<lt>"section"E<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 should warn about this being
+deprecated syntax.
=back