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

7 files changed, 186 insertions, 13 deletions

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<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(
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<Pod::Html> were moved to new package L<Pod::Html::Util> in
+Perl 5.36.  While they remain importable from L<Pod::Html> in Perl 5.36, as of
+Perl 5.38 they will only be importable, on request, from L<Pod::Html::Util>.
+
 =head2 Perl 5.34
 
 There are no deprecations or fatalizations scheduled for Perl 5.34.