From 68327975be0888d6cf8425ec1fb62510c1321310 Mon Sep 17 00:00:00 2001 From: James E Keenan Date: Tue, 3 Aug 2021 17:29:29 +0000 Subject: 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 --- MANIFEST | 1 + ext/Pod-Html/lib/Pod/Html.pm | 34 +++++++++-- ext/Pod-Html/lib/Pod/Html/Util.pm | 21 +++++-- ext/Pod-Html/t/anchorify-536.t | 116 ++++++++++++++++++++++++++++++++++++++ ext/Pod-Html/t/anchorify.t | 16 +++++- ext/Pod-Html/t/lib/Testing.pm | 2 +- pod/perldeprecation.pod | 9 +++ 7 files changed, 186 insertions(+), 13 deletions(-) create mode 100644 ext/Pod-Html/t/anchorify-536.t diff --git a/MANIFEST b/MANIFEST index 99677f7ba6..72f8c69d61 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4360,6 +4360,7 @@ ext/Pod-Html/corpus/perlvar-copy.pod ext/Pod-Html/lib/Pod/Html.pm Convert POD data to HTML ext/Pod-Html/lib/Pod/Html/Util.pm Helper functions for Pod-Html ext/Pod-Html/t/anchorify.t +ext/Pod-Html/t/anchorify-536.t Test Pod-Html utility functions during perl-5.36 ext/Pod-Html/t/cache.pod ext/Pod-Html/t/cache.t ext/Pod-Html/t/crossref.pod 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, either by default or on request: + +=over 4 + +=item * C (by default) + +=item * C (upon request) + +=item * C (upon request) + +=back + +The definition and documentation of these functions have been moved to +F, viewable via C. + +In perl-5.36, these functions will be importable from either F or +F. However, beginning with perl-5.38 they will only be +importable, upon request, from F. 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 - -TK +B While these functions are importable on request from +F, they are specifically intended for use within (a) the +F distribution (modules and test programs) shipped as part of the +Perl 5 core and (b) other parts of the core such as the F +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 -TK +Display customary Pod::Html usage information. =cut @@ -149,7 +157,8 @@ END_OF_USAGE =head2 C -TK +Ensure that F'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 = ; +} + +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 + +=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( diff --git a/pod/perldeprecation.pod b/pod/perldeprecation.pod index 4faa9a8527..f6422724ea 100644 --- a/pod/perldeprecation.pod +++ b/pod/perldeprecation.pod @@ -14,6 +14,15 @@ features are available. The deprecated features will be grouped by the version of Perl in which they will be removed. +=head2 Perl 5.38 + +=head3 Pod::Html utility functions + +The definition and documentation of three utility functions previously +importable from L were moved to new package L in +Perl 5.36. While they remain importable from L in Perl 5.36, as of +Perl 5.38 they will only be importable, on request, from L. + =head2 Perl 5.34 There are no deprecations or fatalizations scheduled for Perl 5.34. -- cgit v1.2.1