# Pod::ParseLink -- Parse an L<> formatting code in POD text.
-# $Id: ParseLink.pm,v 1.1 2001/11/15 07:58:57 eagle Exp $
#
-# Copyright 2001 by Russ Allbery <rra@stanford.edu>
+# Copyright 2001, 2008 by Russ Allbery <rra@stanford.edu>
#
# This program is free software; you may redistribute it and/or modify it
# under the same terms as Perl itself.
@ISA = qw(Exporter);
@EXPORT = qw(parselink);
-# 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.09';
##############################################################################
# Implementation
# 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
# guess that it's an old section link.
my ($page, $section) = split (/\s*\/\s*/, $link, 2);
- $section =~ s/^"\s*(.*?)\s*"$/$1/;
- if ($page =~ / / && !defined ($section)) {
+ $section =~ s/^"\s*(.*?)\s*"$/$1/ if $section;
+ if ($page && $page =~ / / && !defined ($section)) {
$section = $page;
$page = undef;
} else {
}
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);
}
}
-
##############################################################################
# Module return value and documentation
##############################################################################
=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
+
+=for stopwords
+markup Allbery URL
=head1 SYNOPSIS
=head1 DESCRIPTION
This module only provides a single function, parselink(), which takes the
-text of an LE<lt>E<gt> formatting code and parses it. It returns the anchor
-text for the link (if any was given), the anchor text possibly inferred from
-the name and section, the name or URL, the section if any, and the type of
-link. The type will be one of 'url', 'pod', or 'man', indicating a URL, a
-link to a POD page, or a link to a Unix manual page.
+text of an LE<lt>E<gt> formatting code and parses it. It returns the
+anchor text for the link (if any was given), the anchor text possibly
+inferred from the name and section, the name or URL, the section if any,
+and the type of link. The type will be one of C<url>, C<pod>, or C<man>,
+indicating a URL, a link to a POD page, or a link to a Unix manual page.
Parsing is implemented per L<perlpodspec>. For backward compatibility,
links where there is no section and name contains spaces, or links where the
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.
+
+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 backward
+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>
-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.)
+The current version of this module is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>.
=head1 AUTHOR
=head1 COPYRIGHT AND LICENSE
-Copyright 2001 by Russ Allbery <rra@stanford.edu>.
+Copyright 2001, 2008 Russ Allbery <rra@stanford.edu>.
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
projects / p5sagit/p5-mst-13.2.git / blobdiff