The enclosed patch to perlpod.pod and perlpodspec.pod explains my proposed
syntax for attributes in L<>.
(e.g. L< p<perlfunc> s<print> the print function>)
Here's a quick summary of my proposal, as it currently stands:
Lowercase letters are used to indicate attribute codes. Attribute codes
can only appear within formatting codes. Attribute codes can appear
anywhere within the formatting code, in any order. Whitespace immediately
preceeding and following an attribute code is ignored (that's just to make
the pod easier to read).
Each formatting code can have its own set of attributes, and only known
attribute codes are accepted. Right now I am only proposing attribute
codes for L<>.
The patch does not yet address exactly how URL links with display text
should be rendered. My current plan is to add a flag indicating that the
link should be rendered as 'text <target>' instead of 'text' in formats
that don't do hypertext links.
e.g.
pod: L< u<http://www.perl.com> the Perl homepage>
becomes
text: the Perl homepage <http://www.perl.com/>
HTML: <A HREF="http://www.perl.com/";>the Perl homepage</A>
This is not ideal, because it requires a special case in most renderers,
but it's the best solution I've come up with.
I searched the standard documentation for instances of a lowercase letter
followed by <. Under my proposal, these would become errors. Most of the
instances either occur within verbatim text and are not affected, or are
errors and need to be fixed anyway. These are the only two instances that
would need to be changed for my proposal:
perlop.pod:C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
could be either C<< sE<lt>foo>/bar/ >>, C<< sZ<><foo>/bar/ >>,
or C<< s{foo}/bar/ >>
perlpodspec.pod:"<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").
could be \nE<lt>hr>\n or \nZ<><hr>\n
Ronald
diff -r -x '*~' -x '*.old' -x blib -uw Pod-Simple-0.96.orig/lib/perlpod.pod
Pod-Simple-0.96/lib/perlpod.pod
--- Pod-Simple-0.96.orig/lib/perlpod.pod Wed May 14 17:21:34 2003
+++ Pod-Simple-0.96/lib/perlpod.pod Mon Jun 2 14:56:18 2003
@@ -332,73 +332,119 @@
this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
-=item C<LE<lt>nameE<gt>> -- a hyperlink
+=item C<LE<lt>...E<gt>> -- a hyperlink
-There are various syntaxes, listed below. In the syntaxes given,
-C<text>, C<name>, and C<section> cannot contain the characters
-'/' and '|'; and any '<' or '>' should be matched.
+There are two ways of specifying a link with LE<lt>...>: the traditional
+syntax and the attribute syntax.
+
+In the traditional syntax (e.g. LE<lt>text|page/section>), C<text>, C<page>,
+and C<section> cannot contain the characters '/' and '|', as those
+characters are used to separate the parts of the link.
+
+In the attribute syntax (e.g. LE<lt> pE<lt>page> sE<lt>section> text >),
+attribute codes are used to indicate the parts of the link. Attribute
+codes are like formatting codes but begin with lowercase letters instead.
+The specific attribute codes for C<LE<lt>...E<gt>> and their meanings are
+listed below. See L< s<Attribute Codes> > for a description of attribute
+codes in general.
+
+In both syntaxes, any '<' or '>' should be matched.
+
+In the following descriptions, the first example is in the traditional
+syntax, and the second example is in the attribute syntax.
=over
=item *
-C<LE<lt>nameE<gt>>
+C<LE<lt>pageE<gt>>
+
+=item *
+
+C<LE<lt> pE<lt>pageE<gt> E<gt>>
+
+Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>> or C<LE<lt>
+pE<lt>Net::PingE<gt> E<gt>>). Note that C<page> should not contain spaces.
+This syntax is also occasionally used for references to UNIX man pages, as
+in C<LE<lt>crontab(5)E<gt>> or C<LE<lt> pE<lt>crontab(5)E<gt> E<gt>>.
+
+=item *
-Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note
-that C<name> should not contain spaces. This syntax
-is also occasionally used for references to UNIX man pages, as in
-C<LE<lt>crontab(5)E<gt>>.
+C<LE<lt>page/"section"E<gt>> or C<LE<lt>page/sectionE<gt>>
=item *
-C<LE<lt>name/"sec"E<gt>> or C<LE<lt>name/secE<gt>>
+C<LE<lt> pE<lt>pageE<gt> sE<lt>sectionE<gt> E<gt>>
+
+Link to a section in another manual page. E.g.,
+C<LE<lt>perlsyn/"For Loops"E<gt>> or C<LE<lt> pE<lt>perlsynE<gt> sE<lt>For
+LoopsE<gt> E<gt>>.
+
+=item *
-Link to a section in other manual page. E.g.,
-C<LE<lt>perlsyn/"For Loops"E<gt>>
+C<LE<lt>/"section"E<gt>> or C<LE<lt>/sectionE<gt>> or C<LE<lt>"section"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> sE<lt>sectionE<gt> E<gt>>
Link to a section in this manual page. E.g.,
-C<LE<lt>/"Object Methods"E<gt>>
+C<LE<lt>/"Object Methods"E<gt>> or C<LE<lt> sE<lt>Object MethodsE<gt> E<gt>>.
=back
-A section is started by the named heading or item. For
-example, C<LE<lt>perlvar/$.E<gt>> or C<LE<lt>perlvar/"$."E<gt>> both
-link to the section started by "C<=item $.>" in perlvar. And
-C<LE<lt>perlsyn/For LoopsE<gt>> or C<LE<lt>perlsyn/"For Loops"E<gt>>
-both link to the section started by "C<=head2 For Loops>"
-in perlsyn.
-
-To control what text is used for display, you
-use "C<LE<lt>text|...E<gt>>", as in:
+A section is started by the named heading or item. For example,
+C<LE<lt>perlvar/$.E<gt>>, C<LE<lt>perlvar/"$."E<gt>>, and C<LE<lt>
+pE<lt>perlvarE<gt> sE<lt>$.E<gt> E<gt>> all link to the section started by
+"C<=item $.>" in perlvar. C<LE<lt>perlsyn/For LoopsE<gt>>,
+C<LE<lt>perlsyn/"For Loops"E<gt>>, and C<LE<lt> pE<lt>perlsynE<gt>
+sE<lt>For loopsE<gt> E<gt>> all link to the section started by "C<=head2
+For Loops>" in perlsyn.
+
+To control what text is used for display under the traditional syntax, you
+use "C<LE<lt>text|...E<gt>>". Under the attribute syntax, you simply
+specify the text in the LE<lt>...> code but outside the attributes; the
+attributes may appear before, after, or mixed in the text.
=over
=item *
-C<LE<lt>text|nameE<gt>>
+C<LE<lt>text|pageE<gt>>
+
+=item *
+
+C<LE<lt> pE<lt>pageE<gt> textE<gt>>
Link this text to that manual page. E.g.,
-C<LE<lt>Perl Error Messages|perldiagE<gt>>
+C<LE<lt>Perl Error Messages|perldiagE<gt>> or C<LE<lt> pE<lt>perldiagE<gt>
+Perl Error Messages E<gt>>.
=item *
-C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>
+C<LE<lt>text|page/"section"E<gt>> or C<LE<lt>text|page/sectionE<gt>>
+
+=item *
+
+C<LE<lt> pE<lt>pageE<gt> sE<lt>sectionE<gt> text E<gt>>
Link this text to that section in that manual page. E.g.,
C<LE<lt>SWITCH statements|perlsyn/"Basic BLOCKs and Switch
-Statements"E<gt>>
+Statements"E<gt>> or C<LE<lt> pE<lt>perlsynE<gt> sE<lt>Basic BLOCKs and
+Switch StatementsE<gt> SWITCH statmentsE<gt>>.
=item *
C<LE<lt>text|/"sec"E<gt>> or C<LE<lt>text|/secE<gt>>
or C<LE<lt>text|"sec"E<gt>>
+=item *
+
+C<LE<lt> sE<lt>sectionE<gt> text E<gt>>
+
Link this text to that section in this manual page. E.g.,
-C<LE<lt>the various attributes|/"Member Data"E<gt>>
+C<LE<lt>the various attributes|/"Member Data"E<gt>> or
+C<LE<lt> sE<lt>Member DataE<gt> the various attributesE<gt>>.
=back
@@ -410,10 +456,21 @@
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.
+=item *
+
+C<LE<lt> uE<lt>scheme:...E<gt> E<gt>>
+
+Link to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>>
+or C<LE<lt> uE<lt>http://www.perl.orgE<gt> E<gt>>.
+
+=item *
+
+C<LE<lt> uE<lt>scheme:...E<gt> text E<gt>>
+
+Link this text to that URL. For example, C<LE<lt>
+uE<lt>http://www.perl.orgE<gt> the Perl homepage E<gt>>. There is no way
+to specify display text for a URL link under the traditional syntax;
+C<LE<lt>text|scheme:...E<gt>> is not allowed for various reasons.
=back
@@ -558,6 +615,22 @@
and any other pod2xxx or Pod::Xxxx translators that use
Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
+=head2 Attribute Codes
+
+Inside certain formatting codes, various attribute codes can be used.
+Attribute codes are similar to formatting codes, but begin with a lowercase
+letter. When an attribute code is used, any whitespace immediately
+preceeding or following the code is ignored. Attribute codes may appear
+anywhere within the formatting code. E.g., the following are
+equivalent:
+
+ L<p<page>Link to the page>
+ L<Link to the page p<page> >
+ L<Link to the pa p<page> ge>
+
+Currently, the only formatting code that supports attributes is
+LE<lt>...>. See L< s<C<LE<lt>...E<gt>> -- a hyperlink> >.
+
=head2 The Intent
The intent is simplicity of use, not power of expression. Paragraphs
diff -r -x '*~' -x '*.old' -x blib -uw Pod-Simple-0.96.orig/lib/perlpodspec.pod
Pod-Simple-0.96/lib/perlpodspec.pod
--- Pod-Simple-0.96.orig/lib/perlpodspec.pod Wed May 14 17:21:34 2003
+++ Pod-Simple-0.96/lib/perlpodspec.pod Mon Jun 2 14:45:39 2003
@@ -387,9 +387,9 @@
B<< $foo->bar(); >>
-With this syntax, the whitespace character(s) after the "CE<lt><<"
-and before the ">>" (or whatever letter) are I<not> renderable -- they
-do not signify whitespace, are merely part of the formatting codes
+With this syntax, the whitespace character(s) after the "CE<lt><<" (or
+whatever letter) and before the ">>" are I<not> renderable -- they do
+not signify whitespace, are merely part of the formatting codes
themselves. That is, these are all synonymous:
C<thing>
@@ -449,10 +449,11 @@
The complicated syntaxes of this code are discussed at length in
L<perlpod/"Formatting Codes">, and implementation details are
discussed below, in L</"About LE<lt>...E<gt> Codes">. Parsing the
-contents of LE<lt>content> is tricky. Notably, the content has to be
-checked for whether it looks like a URL, or whether it has to be split
-on literal "|" and/or "/" (in the right order!), and so on,
-I<before> EE<lt>...> codes are resolved.
+contents of LE<lt>content> is tricky. Notably, if the content does
+not contain any attributes, it has to be checked for whether it looks
+like a URL, or whether it has to be split on literal "|" and/or "/"
+(in the right order!), and so on, I<before> EE<lt>...> codes are
+resolved.
=item C<EE<lt>escapeE<gt>> -- a character escape
@@ -535,6 +536,75 @@
+=head1 Pod Attribute Codes
+
+Pod attribute codes are used within Pod formatting codes, and provide
+additional information about the formatting code.
+
+Like formatting codes, there are two syntaxes for attribute codes.
+In addition to the below details, the same rules apply as for
+formatting codes.
+
+=over
+
+=item *
+
+An attribute code occurs within a formatting code. It starts with a
+lowercase letter (just US-ASCII [a-z]) followed by a "<", any number of
+characters, and ending with the first matching ">". Whitespace immediately
+preceeding the initial lowercase letter and whitespace immediately
+following the ">", if present, must be ignored. Examples:
+
+ See L< s<print> p<perlfunc> >.
+
+ Check out L< u<http://www.example.com/> my home page >!
+
+=item *
+
+An attribute code occurs within a formatting code. It starts with a
+lowercase letter (just US-ASCII [a-z]) followed by two or more "<"'s, one
+of more whitespace characters, any number of characters, one or more
+whitespace characters, and ending with the first matching sequence of two
+or more ">"'s, where the number of ">"'s equals the number of "<"'s in the
+opening of this formatting code. Whitespace immediately preceeding the
+initial lowercase letter and immediately following the ">"'s, if present,
+must be ignored. Example:
+
+ See L< p<< perlvar >> s<< $> >> >.
+
+=back
+
+Each formatting code may have its own set of accepted attributes.
+Currently, only C<LE<lt>...E<gt>> accepts attributes.
+
+=over
+
+=item C<LE<lt> pE<lt>pageE<gt> E<gt>> -- link to page
+
+See L</"About LE<lt>...E<gt> Codes">.
+
+=item C<LE<lt> sE<lt>sectionE<gt> E<gt>> -- link to section
+
+See L</"About LE<lt>...E<gt> Codes">.
+
+=item C<LE<lt> uE<lt>URLE<gt> E<gt>> -- link to URL
+
+See L</"About LE<lt>...E<gt> Codes">.
+
+=back
+
+If a Pod processor sees any attribute code within a formatting code
+other than the ones listed above (as in "LE<lt> qE<lt>...> >" or
+"BE<lt> sE<lt>...> >", 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 attribute codes.
+
+If a Pod processor sees any attribute code outside a formatting code,
+that processor must treat this as an error.
+
+Future versions of this specification may add additional attribute
+codes.
+
=head1 Notes on Implementing Pod Processors
The following is a long section of miscellaneous requirements
@@ -1081,36 +1151,44 @@
=item *
In parsing an LE<lt>...> code, Pod parsers must distinguish at least
-four attributes:
+four attributes of the link. The attributes may be specified using
+either the attribute syntax or the traditional syntax. If the
+attribute syntax is used, all text within the LE<lt>...> code that is
+not within an attribute code is part of the link text.
=over
=item First:
The link-text. If there is none, this must be undef. (E.g., in
-"LE<lt>Perl Functions|perlfunc>", the link-text is "Perl Functions".
-In "LE<lt>Time::HiRes>" and even "LE<lt>|Time::HiRes>", there is no
-link text. Note that link text may contain formatting.)
+"LE<lt>Perl Functions|perlfunc>" and "LE<lt> pE<lt>perlfunc> Perl
+Functions>", the link-text is "Perl Functions". In
+"LE<lt>Time::HiRes>", "LE<lt> pE<lt>Time::HiRes> >", and even
+"LE<lt>|Time::HiRes>", there is no link text. Note that link text may
+contain formatting.)
=item Second:
The possibly inferred link-text -- i.e., if there was no real link
text, then this is the text that we'll infer in its place. (E.g., for
-"LE<lt>Getopt::Std>", the inferred link text is "Getopt::Std".)
+"LE<lt>Getopt::Std>" and "LE<lt> pE<lt>Getop::Std>", the inferred link
+text is "Getopt::Std".)
=item Third:
The name or URL, or undef if none. (E.g., in "LE<lt>Perl
-Functions|perlfunc>", the name -- also sometimes called the page --
-is "perlfunc". In "LE<lt>/CAVEATS>", the name is undef.)
+Functions|perlfunc>" and "LE<lt> pE<lt>perlfunc> Perl Functions>", the
+name -- also sometimes called the page -- is "perlfunc". In
+"LE<lt>/CAVEATS>" and "LE<lt> sE<lt>CAVEATS> >", the name is undef.)
=item Fourth:
-The section (AKA "item" in older perlpods), or undef if none. E.g.,
-in L<Getopt::Std/DESCRIPTION>, "DESCRIPTION" is the section. (Note
-that this is not the same as a manpage section like the "5" in "man 5
-crontab". "Section Foo" in the Pod sense means the part of the text
-that's introduced by the heading or item whose text is "Foo".)
+The section (AKA "item" in older perlpods), or undef if none. (E.g.,
+in "LE<lt>Getopt::Std/DESCRIPTION>" and "LE<lt> sE<lt>DESCRIPTION>
+pE<lt>Getopt::Std> >", the section is "DESCRIPTION". [Note that this
+is not the same as a manpage section like the "5" in "man 5 crontab".
+"Section Foo" in the Pod sense means the part of the text that's
+introduced by the heading or item whose text is "Foo".])
=back
@@ -1127,8 +1205,9 @@
=item Sixth:
-The raw original LE<lt>...> content, before text is split on
-"|", "/", etc, and before EE<lt>...> codes are expanded.
+The raw original LE<lt>...> content, before attributes are parsed out
+or the text is split on "|", "/", etc., and before EE<lt>...> codes
+are expanded.
=back
@@ -1138,57 +1217,78 @@
For example:
L<Foo::Bar>
+ L< p<Foo::Bar> >
=> undef, # link text
"Foo::Bar", # possibly inferred link text
"Foo::Bar", # name
undef, # section
'pod', # what sort of link
- "Foo::Bar" # original content
+ "Foo::Bar" / " p<Foo::Bar> " # original content
L<Perlport's section on NL's|perlport/Newlines>
+ L< p<perlport> s<Newlines> Perlport's section on NL's >
=> "Perlport's section on NL's", # link text
"Perlport's section on NL's", # possibly inferred link text
"perlport", # name
"Newlines", # section
'pod', # what sort of link
- "Perlport's section on NL's|perlport/Newlines" # orig. content
+ "Perlport's section on NL's|perlport/Newlines" /
+ " p<perlport> s<Newlines> Perlport's section on NL's "
+ # original content
L<perlport/Newlines>
+ L< p<perlport> s<Newlines> >
=> undef, # link text
'"Newlines" in perlport', # possibly inferred link text
"perlport", # name
"Newlines", # section
'pod', # what sort of link
- "perlport/Newlines" # original content
+ "perlport/Newlines" / # original content
+ " p<perlport> s<Newlines> "
L<crontab(5)/"DESCRIPTION">
+ L< p<crontab(5)> s<DESCRIPTION> >
=> undef, # link text
'"DESCRIPTION" in crontab(5)', # possibly inferred link text
"crontab(5)", # name
"DESCRIPTION", # section
'man', # what sort of link
- 'crontab(5)/"DESCRIPTION"' # original content
+ 'crontab(5)/"DESCRIPTION"' / # original content
+ " p<crontab(5)> s<DESCRIPTION> "
L</Object Attributes>
+ L< s<Object Attributes> >
=> undef, # link text
'"Object Attributes"', # possibly inferred link text
undef, # name
"Object Attributes", # section
'pod', # what sort of link
- "/Object Attributes" # original content
+ "/Object Attributes" / # original content
+ " s<Object Attributes> "
L<http://www.perl.org/>
+ L< u<http://www.perl.org/> >
=> undef, # link text
"http://www.perl.org/";, # possibly inferred link text
"http://www.perl.org/";, # name
undef, # section
'url', # what sort of link
- "http://www.perl.org/"; # original content
+ "http://www.perl.org/"; / # original content
+ " u<http://www.perl.org/> "
+
+ L< u<http://www.perl.org> the Perl homepage >
+ => "the Perl homepage", # link text
+ "the Perl homepage", # possibly inferred link text
+ "http://www.perl.org";, # name
+ undef, # section
+ 'url', # what sort of link
+ "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
-C<LE<lt>HTTP::ResponseE<gt>> isn't.
+
+Note that under the traditional syntax, 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 C<LE<lt>HTTP::ResponseE<gt>> isn't.
=item *
@@ -1198,11 +1298,16 @@
as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage"
or just "C<crontab(5)>".
-Pod processors must now treat "text|"-less links as follows:
+Pod processors must now treat links without explicit link text as
+follows:
- L<name> => L<name|name>
+ L<page> => L<page|page>
L</section> => L<"section"|/section>
- L<name/section> => L<"section" in name|name/section>
+ L<page/section> => L<"section" in page|page/section>
+
+ L< p<page> > => L< p<page> page>
+ L< s<section> > => L< s<section> "section">
+ L< p<page> s<section> > => L< p<page> s<section> "section" in page>
=item *
@@ -1218,6 +1323,7 @@
then a link to it would look like this:
L<somedoc/About the C<-M> Operator>
+ L< p<page> s<About the C<-M> Operator> >
Formatters may choose to ignore the markup for purposes of resolving
the link and use only the renderable characters in the section name,
@@ -1243,7 +1349,8 @@
same I<section> identifier (e.g., in HTML, several things all producing
the same I<anchorname> in <a name="I<anchorname>">...</a>
elements). Where Pod processors can control this behavior, they should
-use the first such anchor. That is, C<LE<lt>Foo/BarE<gt>> refers to the
+use the first such anchor. That is, C<LE<lt>Foo/BarE<gt>> and
+C<LE<lt> pE<lt>FooE<gt> sE<lt>BarE<gt> E<gt>>" refer to the
I<first> "Bar" section in Foo.
But for some processors/formats this cannot be easily controlled; as
@@ -1253,22 +1360,25 @@
=item *
-Authors wanting to link to a particular (absolute) URL, must do so
-only with "LE<lt>scheme:...>" codes (like
-LE<lt>http://www.perl.org>), and must not attempt "LE<lt>Some Site
-Name|scheme:...>" codes. This restriction avoids many problems
-in parsing and rendering LE<lt>...> codes.
+Authors wanting to specify link text when linking to a particular
+(absolute) URL must do so using attribute codes (e.g. "LE<lt>
+uE<lt>http://www.perl.org> the Perl homepage>"). The traditional
+syntax does not support link text for URL links (i.e. "LE<lt>Some Site
+Name|scheme:...>" is not allowed). This restriction avoids many
+problems in parsing the traditional syntax for LE<lt>...> codes.
=item *
-In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
-for formatting or for EE<lt>...> escapes, as in:
+In a C<LE<lt>text|...E<gt>> or C<LE<lt> pE<lt>...E<gt> textE<gt>>
+code, text may contain formatting codes for formatting or for
+EE<lt>...> escapes, as in:
L<B<ummE<234>stuff>|...>
+ L< p<...> B<ummE<234>stuff> >
-For C<LE<lt>...E<gt>> codes without a "name|" part, only
-C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may occur -- no
-other formatting codes. That is, authors should not use
+For C<LE<lt>...E<gt>> codes using the traditional syntax without a
+"text|" part, only C<EE<lt>...E<gt>> and C<ZE<lt>E<gt>> codes may
+occur -- no other formatting codes. That is, authors should not use
"C<LE<lt>BE<lt>Foo::BarE<gt>E<gt>>".
Note, however, that formatting codes and ZE<lt>>'s can occur in any
@@ -1293,29 +1403,29 @@
=item *
-At time of writing, C<LE<lt>nameE<gt>> values are of two types:
-either the name of a Pod page like C<LE<lt>Foo::BarE<gt>> (which
-might be a real Perl module or program in an @INC / PATH
-directory, or a .pod file in those places); or the name of a UNIX
-man page, like C<LE<lt>crontab(5)E<gt>>. In theory, C<LE<lt>chmodE<gt>>
-in ambiguous between a Pod page called "chmod", or the Unix man page
-"chmod" (in whatever man-section). However, the presence of a string
-in parens, as in "crontab(5)", is sufficient to signal that what
-is being discussed is not a Pod page, and so is presumably a
-UNIX man page. The distinction is of no importance to many
-Pod processors, but some processors that render to hypertext formats
-may need to distinguish them in order to know how to render a
-given C<LE<lt>fooE<gt>> code.
+At time of writing, C<LE<lt>pageE<gt>> and C<LE<lt> pE<lt>pageE<gt>
+E<gt>> values are of two types: either the name of a Pod page like
+C<LE<lt>Foo::BarE<gt>> (which might be a real Perl module or program
+in an @INC / PATH directory, or a .pod file in those places); or the
+name of a UNIX man page, like C<LE<lt>crontab(5)E<gt>>. In theory,
+C<LE<lt>chmodE<gt>> is ambiguous between a Pod page called "chmod", or
+the Unix man page "chmod" (in whatever man-section). However, the
+presence of a string in parens, as in "crontab(5)", is sufficient to
+signal that what is being discussed is not a Pod page, and so is
+presumably a UNIX man page. The distinction is of no importance to
+many Pod processors, but some processors that render to hypertext
+formats may need to distinguish them in order to know how to render a
+given C<LE<lt>fooE<gt>> or C<LE<lt> pE<lt>fooE<gt> E<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
+from C<LE<lt>pageE<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>>
+heuristic for distinguishing C<LE<lt>sectionE<gt>> from C<LE<lt>pageE<gt>>
is that if it contains any whitespace, it's a I<section>. Pod processors
may warn about this being deprecated syntax.
@@ -1765,7 +1875,7 @@
"<img src='wirth_spokesmodeling_book.png'>\n"
and another consisting of "<hr>\n"), but I<should> be stored as
a single data paragraph (consisting of
-"<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").
+"<img src='wirth_spokesmodeling_book.png'>\n\nE<lt>hr>\n").
Pod processors should tolerate empty
"=begin I<something>"..."=end I<something>" regions,
