# Pod::ParseLink -- Parse an L<> formatting code in POD text.
-# $Id: ParseLink.pm,v 1.1 2001/11/15 07:58:57 eagle Exp $
+# $Id: ParseLink.pm,v 1.6 2002/07/15 05:46:00 eagle Exp $
#
# Copyright 2001 by Russ Allbery <rra@stanford.edu>
#
# Don't use the CVS revision as the version, since this module is also in Perl
# core and too many things could munge CVS magic revision strings. This
# number should ideally be the same as the CVS revision in podlators, however.
-$VERSION = 1.01;
+$VERSION = 1.06;
##############################################################################
# If the whole link is enclosed in quotes, interpret it all as a section
# even if it contains a slash.
- return (undef, $1) if (/^"\s*(.*?)\s*"$/);
+ return (undef, $1) if ($link =~ /^"\s*(.*?)\s*"$/);
# Split into page and section on slash, and then clean up quoting in the
# section. If there is no section and the name contains spaces, also
}
my ($name, $section) = _parse_section ($link);
my $inferred = $text || _infer_text ($name, $section);
- my $type = ($name =~ /\(\S*\)/) ? 'man' : 'pod';
+ my $type = ($name && $name =~ /\(\S*\)/) ? 'man' : 'pod';
return ($text, $inferred, $name, $section, $type);
}
}
=head1 NAME
-Pod::ParseLink -- Parse an L<> formatting code in POD text
+Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
=head1 SYNOPSIS
The name may contain embedded EE<lt>E<gt> and ZE<lt>E<gt> formatting codes,
and the section, anchor text, and inferred anchor text may contain any
-formatting codes. Any double quotes around the name or section are removed
-as part of the parsing, as are any leading or trailing whitespace.
+formatting codes. Any double quotes around the section are removed as part
+of the parsing, as is any leading or trailing whitespace.
-No attempt is made to resolve formatting codes. The caller must be prepared
-to do that either before or after calling parselink(). (This is because
-interpretation of EE<lt>E<gt> formatting codes may vary by formatter.)
+If the text of the LE<lt>E<gt> escape is entirely enclosed in double quotes,
+it's interpreted as a link to a section for backwards compatibility.
+
+No attempt is made to resolve formatting codes. This must be done after
+calling parselink (since EE<lt>E<gt> formatting codes can be used to escape
+characters that would otherwise be significant to the parser and resolving
+them before parsing would result in an incorrect parse of a formatting code
+like:
+
+ L<verticalE<verbar>barE<sol>slash>
+
+which should be interpreted as a link to the C<vertical|bar/slash> POD page
+and not as a link to the C<slash> section of the C<bar> POD page with an
+anchor text of C<vertical>. Note that not only the anchor text will need to
+have formatting codes expanded, but so will the target of the link (to deal
+with EE<lt>E<gt> and ZE<lt>E<gt> formatting codes), and special handling of
+the section may be necessary depending on whether the translator wants to
+consider markup in sections to be significant when resolving links. See
+L<perlpodspec> for more information.
+
+=head1 SEE ALSO
+
+L<Pod::Parser>
+
+The current version of this module is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>.
=head1 AUTHOR