diff options
author | James E Keenan <jkeenan@cpan.org> | 2021-08-03 17:29:29 +0000 |
---|---|---|
committer | James E Keenan <jkeenan@cpan.org> | 2021-08-10 20:03:58 +0000 |
commit | 68327975be0888d6cf8425ec1fb62510c1321310 (patch) | |
tree | 8e350c0e99b62d379472ce1ee1f13559ba43b9d5 /ext/Pod-Html | |
parent | 7e18321c957fcae8d9b16428c51f22dea10040b1 (diff) | |
download | perl-68327975be0888d6cf8425ec1fb62510c1321310.tar.gz |
Pod-Html: document new location for utility functions
... along with guidance on changes in perl-5.38.
Pod::Html::Util: caution on use of these subroutines outside core. For
perl-5.36, these three utility functions will still be importable from
Pod::Html, but thereafter they will only be importable from
Pod::Html::Util. (They are simply imported and re-exported per
suggestion from Graham Knop in GH 19036.
Also, (i) add explicit tests for anchorify() and relativize_url() based
on how they are used in 'installhtml'; (ii) conduct these tests imported
from both Pod::Html::Util (permanently) and Pod::Html (during perl-5.36
only).
For: https://github.com/Perl/perl5/pull/19036
Diffstat (limited to 'ext/Pod-Html')
-rw-r--r-- | ext/Pod-Html/lib/Pod/Html.pm | 34 | ||||
-rw-r--r-- | ext/Pod-Html/lib/Pod/Html/Util.pm | 21 | ||||
-rw-r--r-- | ext/Pod-Html/t/anchorify-536.t | 116 | ||||
-rw-r--r-- | ext/Pod-Html/t/anchorify.t | 16 | ||||
-rw-r--r-- | ext/Pod-Html/t/lib/Testing.pm | 2 |
5 files changed, 176 insertions, 13 deletions
diff --git a/ext/Pod-Html/lib/Pod/Html.pm b/ext/Pod-Html/lib/Pod/Html.pm index 8d9ec45078..01f4ec8ba9 100644 --- a/ext/Pod-Html/lib/Pod/Html.pm +++ b/ext/Pod-Html/lib/Pod/Html.pm @@ -2,9 +2,10 @@ package Pod::Html; use strict; use Exporter 'import'; -our $VERSION = 1.31; +our $VERSION = 1.32; $VERSION = eval $VERSION; -our @EXPORT = qw(pod2html); +our @EXPORT = qw(pod2html htmlify); +our @EXPORT_OK = qw(anchorify relativize_url); use Config; use Cwd; @@ -15,12 +16,13 @@ use Pod::Simple::Search; use Pod::Simple::SimpleTree (); use Pod::Html::Util qw( html_escape - htmlify parse_command_line - relativize_url trim_leading_whitespace unixify usage + htmlify + anchorify + relativize_url ); use locale; # make \w work right in non-ASCII lands @@ -194,6 +196,29 @@ Display progress messages. By default, they won't be displayed. =back +=head2 Auxiliary Functions + +Prior to perl-5.36, the following three functions were exported by +F<Pod::Html>, either by default or on request: + +=over 4 + +=item * C<htmlify()> (by default) + +=item * C<anchorify()> (upon request) + +=item * C<relativize_url()> (upon request) + +=back + +The definition and documentation of these functions have been moved to +F<Pod::Html::Util>, viewable via C<perldoc Pod::Html::Util>. + +In perl-5.36, these functions will be importable from either F<Pod::Html> or +F<Pod::Html::Util>. However, beginning with perl-5.38 they will only be +importable, upon request, from F<Pod::Html::Util>. Please modify your code as +needed. + =head1 ENVIRONMENT Uses C<$Config{pod2html}> to setup default options. @@ -586,6 +611,7 @@ sub write_file { chmod 0644, $globals->{Htmlfile} unless $globals->{Htmlfile} eq '-'; } + package Pod::Simple::XHTML::LocalPodLinks; use strict; use warnings; diff --git a/ext/Pod-Html/lib/Pod/Html/Util.pm b/ext/Pod-Html/lib/Pod/Html/Util.pm index 76d7a47015..9f33bff91e 100644 --- a/ext/Pod-Html/lib/Pod/Html/Util.pm +++ b/ext/Pod-Html/lib/Pod/Html/Util.pm @@ -2,7 +2,7 @@ package Pod::Html::Util; use strict; require Exporter; -our $VERSION = 1.31; # Please keep in synch with lib/Pod/Html.pm +our $VERSION = 1.32; # Please keep in synch with lib/Pod/Html.pm $VERSION = eval $VERSION; our @ISA = qw(Exporter); our @EXPORT_OK = qw( @@ -30,12 +30,20 @@ Pod::Html::Util - helper functions for Pod-Html =head1 SUBROUTINES -=head2 C<parse_command_line()> - -TK +B<Note:> While these functions are importable on request from +F<Pod::Html::Util>, they are specifically intended for use within (a) the +F<Pod-Html> distribution (modules and test programs) shipped as part of the +Perl 5 core and (b) other parts of the core such as the F<installhtml> +program. These functions may be modified or relocated within the core +distribution -- or removed entirely therefrom -- as the core's needs evolve. +Hence, you should not rely on these functions in situations other than those +just described. =cut +# parse_command_line will be moved back to lib/Pod/Html.pm in a subsequent +# p.r. and will be documented then and there + sub parse_command_line { my $globals = shift; my ($opt_backlink,$opt_cachedir,$opt_css,$opt_flush,$opt_header, @@ -98,7 +106,7 @@ sub parse_command_line { =head2 C<usage()> -TK +Display customary Pod::Html usage information. =cut @@ -149,7 +157,8 @@ END_OF_USAGE =head2 C<unixify()> -TK +Ensure that F<Pod::Html>'s internals and tests handle paths consistently +across Unix, Windows and VMS. =cut diff --git a/ext/Pod-Html/t/anchorify-536.t b/ext/Pod-Html/t/anchorify-536.t new file mode 100644 index 0000000000..aeb34e6e81 --- /dev/null +++ b/ext/Pod-Html/t/anchorify-536.t @@ -0,0 +1,116 @@ +# -*- perl -*- + +use strict; +use Pod::Html qw( anchorify relativize_url ); +my ($revision,$version,$subversion) = split /\./, sprintf("%vd",$^V); +use Test::More; +unless ($version == 35 or $version == 36) { + plan skip_all => "Needed only during 5.36"; +} +else { + plan tests => 3; +} + +my @filedata; +{ + local $/ = ''; + @filedata = <DATA>; +} + +my (@poddata, $i, $j); +for ($i = 0, $j = -1; $i <= $#filedata; $i++) { + $j++ if ($filedata[$i] =~ /^\s*=head[1-6]/); + if ($j >= 0) { + $poddata[$j] = "" unless defined $poddata[$j]; + $poddata[$j] .= "\n$filedata[$i]" if $j >= 0; + } +} + +my %heads = (); +foreach $i (0..$#poddata) { + $heads{anchorify($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/; +} +my %expected = map { $_ => 1 } qw( + NAME + DESCRIPTION + Subroutine + Error + Method + Has_A_Wordspace + HasTrailingWordspace + HasLeadingWordspace + Has_Extra_InternalWordspace + Has_Quotes + Has_QuestionMark + Has_Hyphen_And_Space +); +is_deeply( + \%heads, + \%expected, + "Got expected POD heads" +); + +{ + # adapted from 'installhtml' + my $file = '/home/username/tmp/installhtml/pod/perlipc'; + my $capture = 'NAME'; + my $expected_url = '/home/username/tmp/installhtml/pod/perlipc/NAME.html'; + my $expected_relativized_url = 'perlipc/NAME.html'; + my $url = "$file/@{[anchorify(qq($capture))]}.html" ; + is($url, $expected_url, "anchorify() returned expected value"); + my $relativized_url = relativize_url( $url, "$file.html" ); + is($relativized_url, $expected_relativized_url, "relativize_url() returned expected value"); +} + +__DATA__ +=head1 NAME + +anchorify - Test C<Pod::Html::Util::anchorify()> + +=head1 DESCRIPTION + +alpha + +=head2 Subroutine + +beta + +=head3 Error + +gamma + +=head4 Method + +delta + +=head4 Has A Wordspace + +delta + +=head4 HasTrailingWordspace + +epsilon + +=head4 HasLeadingWordspace + +zeta + +=head4 Has Extra InternalWordspace + +eta + +=head4 Has"Quotes" + +theta + +=head4 Has?QuestionMark + +iota + +=head4 Has-Hyphen And Space + +kappa + +=cut + +__END__ diff --git a/ext/Pod-Html/t/anchorify.t b/ext/Pod-Html/t/anchorify.t index 03d87f80d6..2778cf04f6 100644 --- a/ext/Pod-Html/t/anchorify.t +++ b/ext/Pod-Html/t/anchorify.t @@ -1,8 +1,8 @@ # -*- perl -*- use strict; -use Pod::Html::Util qw( anchorify ); -use Test::More tests => 1; +use Pod::Html::Util qw( anchorify relativize_url ); +use Test::More tests => 3; my @filedata; { @@ -43,6 +43,18 @@ is_deeply( "Got expected POD heads" ); +{ + # adapted from 'installhtml' + my $file = '/home/username/tmp/installhtml/pod/perlipc'; + my $capture = 'NAME'; + my $expected_url = '/home/username/tmp/installhtml/pod/perlipc/NAME.html'; + my $expected_relativized_url = 'perlipc/NAME.html'; + my $url = "$file/@{[anchorify(qq($capture))]}.html" ; + is($url, $expected_url, "anchorify() returned expected value"); + my $relativized_url = relativize_url( $url, "$file.html" ); + is($relativized_url, $expected_relativized_url, "relativize_url() returned expected value"); +} + __DATA__ =head1 NAME diff --git a/ext/Pod-Html/t/lib/Testing.pm b/ext/Pod-Html/t/lib/Testing.pm index 12d51c2b04..71616712f2 100644 --- a/ext/Pod-Html/t/lib/Testing.pm +++ b/ext/Pod-Html/t/lib/Testing.pm @@ -2,7 +2,7 @@ package Testing; use 5.10.0; use warnings; require Exporter; -our $VERSION = 1.31; # Let's keep this same as lib/Pod/Html.pm +our $VERSION = 1.32; # Let's keep this same as lib/Pod/Html.pm $VERSION = eval $VERSION; our @ISA = qw(Exporter); our @EXPORT_OK = qw( |