In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/93592fd5aeec89ac25994a493ef54e1d7a572d65?hp=a92c0cd070f2017820463754d4257b62b59c1e05>
- Log ----------------------------------------------------------------- commit 93592fd5aeec89ac25994a493ef54e1d7a572d65 Author: Ricardo Signes <[email protected]> Date: Mon Dec 7 18:24:59 2009 -0500 legalize =begin foo bar M pod/perlpodspec.pod commit b41aadf259cf55858c5ab0386356cdbe2dc49a6b Author: Ricardo Signes <[email protected]> Date: Mon Dec 7 18:21:44 2009 -0500 more aggressively deprecate L<section> and L<"section"> M pod/perlpod.pod M pod/perlpodspec.pod commit f6e963e4dd62b8e3c01b31f4a4dd57e47e104997 Author: Ricardo Signes <[email protected]> Date: Mon Dec 7 18:19:28 2009 -0500 remove prohibition against L<text|href> M pod/perlpod.pod M pod/perlpodspec.pod ----------------------------------------------------------------------- Summary of changes: pod/perlpod.pod | 10 +++++----- pod/perlpodspec.pod | 37 +++++++++++++++++++++++++------------ 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 827548b..55ea57e 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -395,7 +395,7 @@ C<LE<lt>perlsyn/"For Loops"E<gt>> =item * -C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>> or C<LE<lt>"sec"E<gt>> +C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>> Link to a section in this manual page. E.g., C<LE<lt>/"Object Methods"E<gt>> @@ -446,10 +446,10 @@ Or you can link to a web page: C<LE<lt>scheme:...E<gt>> -Links to an absolute URL. For example, -C<LE<lt>http://www.perl.org/E<gt>>. But note -that there is no corresponding C<LE<lt>text|scheme:...E<gt>> syntax, for -various reasons. +C<LE<lt>text|scheme:...E<gt>> + +Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or +C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>. =back diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod index 8973a70..7ab5659 100644 --- a/pod/perlpodspec.pod +++ b/pod/perlpodspec.pod @@ -293,6 +293,8 @@ by the most recent "=over" command. It permits no text after the =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 @@ -302,9 +304,11 @@ or data paragraphs. This is discussed in detail in the section 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" @@ -1208,6 +1212,14 @@ For example: '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 @@ -1332,15 +1344,16 @@ given C<LE<lt>fooE<gt>> code. =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 -- Perl5 Master Repository
