From ae244ac41efafec56a6f2d477f2c71549ebc4df5 Mon Sep 17 00:00:00 2001 From: James E Keenan Date: Mon, 5 Jul 2021 00:41:01 +0000 Subject: Pod-Html: rename Auxiliary.pm to Util.pm Per rjbs code review in https://github.com/Perl/perl5/pull/18950 --- MANIFEST | 2 +- ext/Pod-Html/lib/Pod/Html.pm | 8 +- ext/Pod-Html/lib/Pod/Html/Auxiliary.pm | 292 --------------------------------- ext/Pod-Html/lib/Pod/Html/Util.pm | 292 +++++++++++++++++++++++++++++++++ ext/Pod-Html/t/anchorify.t | 4 +- ext/Pod-Html/t/cache.t | 2 +- ext/Pod-Html/t/crossref2.t | 2 +- ext/Pod-Html/t/lib/Testing.pm | 2 +- 8 files changed, 302 insertions(+), 302 deletions(-) delete mode 100644 ext/Pod-Html/lib/Pod/Html/Auxiliary.pm create mode 100644 ext/Pod-Html/lib/Pod/Html/Util.pm diff --git a/MANIFEST b/MANIFEST index 60c1ee462f..c00b86265b 100644 --- a/MANIFEST +++ b/MANIFEST @@ -4324,7 +4324,7 @@ ext/Pod-Html/bin/pod2html Translator to turn pod into HTML ext/Pod-Html/corpus/perlpodspec-copy.pod 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/Auxiliary.pm Helper functions for Pod-Html +ext/Pod-Html/lib/Pod/Html/Util.pm Helper functions for Pod-Html ext/Pod-Html/t/anchorify.t ext/Pod-Html/t/cache.pod ext/Pod-Html/t/cache.t diff --git a/ext/Pod-Html/lib/Pod/Html.pm b/ext/Pod-Html/lib/Pod/Html.pm index cfaa6c81b3..e6d54b3be5 100644 --- a/ext/Pod-Html/lib/Pod/Html.pm +++ b/ext/Pod-Html/lib/Pod/Html.pm @@ -14,7 +14,7 @@ use File::Spec; use File::Spec::Unix; use Pod::Simple::Search; use Pod::Simple::SimpleTree (); -use Pod::Html::Auxiliary qw( +use Pod::Html::Util qw( html_escape htmlify parse_command_line @@ -655,15 +655,15 @@ sub resolve_pod_page_link { $path = $self->pages->{$to}; } - my $url = File::Spec::Unix->catfile(Pod::Html::Auxiliary::unixify($self->htmlroot), + my $url = File::Spec::Unix->catfile(Pod::Html::Util::unixify($self->htmlroot), $path); if ($self->htmlfileurl ne '') { # then $self->htmlroot eq '' (by definition of htmlfileurl) so # $self->htmldir needs to be prepended to link to get the absolute path # that will be relativized - $url = Pod::Html::Auxiliary::relativize_url( - File::Spec::Unix->catdir(Pod::Html::Auxiliary::unixify($self->htmldir), $url), + $url = Pod::Html::Util::relativize_url( + File::Spec::Unix->catdir(Pod::Html::Util::unixify($self->htmldir), $url), $self->htmlfileurl # already unixified ); } diff --git a/ext/Pod-Html/lib/Pod/Html/Auxiliary.pm b/ext/Pod-Html/lib/Pod/Html/Auxiliary.pm deleted file mode 100644 index 47d2054115..0000000000 --- a/ext/Pod-Html/lib/Pod/Html/Auxiliary.pm +++ /dev/null @@ -1,292 +0,0 @@ -package Pod::Html::Auxiliary; -use strict; -require Exporter; - -our $VERSION = 1.29; # Please keep in synch with lib/Pod/Html.pm -$VERSION = eval $VERSION; -our @ISA = qw(Exporter); -our @EXPORT_OK = qw( - anchorify - html_escape - htmlify - parse_command_line - relativize_url - trim_leading_whitespace - unixify - usage -); - -use Config; -use File::Spec; -use File::Spec::Unix; -use Getopt::Long; -use Pod::Simple::XHTML; -use Text::Tabs; -use locale; # make \w work right in non-ASCII lands - -=head1 NAME - -Pod::Html::Auxiliary - helper functions for Pod-Html - -=head1 SUBROUTINES - -=head2 C - -TK - -=cut - -sub parse_command_line { - my $globals = shift; - my ($opt_backlink,$opt_cachedir,$opt_css,$opt_flush,$opt_header, - $opt_help,$opt_htmldir,$opt_htmlroot,$opt_index,$opt_infile, - $opt_outfile,$opt_poderrors,$opt_podpath,$opt_podroot, - $opt_quiet,$opt_recurse,$opt_title,$opt_verbose); - - unshift @ARGV, split ' ', $Config{pod2html} if $Config{pod2html}; - my $result = GetOptions( - 'backlink!' => \$opt_backlink, - 'cachedir=s' => \$opt_cachedir, - 'css=s' => \$opt_css, - 'flush' => \$opt_flush, - 'help' => \$opt_help, - 'header!' => \$opt_header, - 'htmldir=s' => \$opt_htmldir, - 'htmlroot=s' => \$opt_htmlroot, - 'index!' => \$opt_index, - 'infile=s' => \$opt_infile, - 'outfile=s' => \$opt_outfile, - 'poderrors!' => \$opt_poderrors, - 'podpath=s' => \$opt_podpath, - 'podroot=s' => \$opt_podroot, - 'quiet!' => \$opt_quiet, - 'recurse!' => \$opt_recurse, - 'title=s' => \$opt_title, - 'verbose!' => \$opt_verbose, - ); - usage("-", "invalid parameters") if not $result; - - usage("-") if defined $opt_help; # see if the user asked for help - $opt_help = ""; # just to make -w shut-up. - - @{$globals->{Podpath}} = split(":", $opt_podpath) if defined $opt_podpath; - - $globals->{Backlink} = $opt_backlink if defined $opt_backlink; - $globals->{Cachedir} = unixify($opt_cachedir) if defined $opt_cachedir; - $globals->{Css} = $opt_css if defined $opt_css; - $globals->{Header} = $opt_header if defined $opt_header; - $globals->{Htmldir} = unixify($opt_htmldir) if defined $opt_htmldir; - $globals->{Htmlroot} = unixify($opt_htmlroot) if defined $opt_htmlroot; - $globals->{Doindex} = $opt_index if defined $opt_index; - $globals->{Podfile} = unixify($opt_infile) if defined $opt_infile; - $globals->{Htmlfile} = unixify($opt_outfile) if defined $opt_outfile; - $globals->{Poderrors} = $opt_poderrors if defined $opt_poderrors; - $globals->{Podroot} = unixify($opt_podroot) if defined $opt_podroot; - $globals->{Quiet} = $opt_quiet if defined $opt_quiet; - $globals->{Recurse} = $opt_recurse if defined $opt_recurse; - $globals->{Title} = $opt_title if defined $opt_title; - $globals->{Verbose} = $opt_verbose if defined $opt_verbose; - - warn "Flushing directory caches\n" - if $opt_verbose && defined $opt_flush; - $globals->{Dircache} = "$globals->{Cachedir}/pod2htmd.tmp"; - if (defined $opt_flush) { - 1 while unlink($globals->{Dircache}); - } - return $globals; -} - -=head2 C - -TK - -=cut - -sub usage { - my $podfile = shift; - warn "$0: $podfile: @_\n" if @_; - die < --htmlroot= - --infile= --outfile= - --podpath=:...: --podroot= - --cachedir= --flush --recurse --norecurse - --quiet --noquiet --verbose --noverbose - --index --noindex --backlink --nobacklink - --header --noheader --poderrors --nopoderrors - --css= --title= - - --[no]backlink - turn =head1 directives into links pointing to the top of - the page (off by default). - --cachedir - directory for the directory cache files. - --css - stylesheet URL - --flush - flushes the directory cache. - --[no]header - produce block header/footer (default is no headers). - --help - prints this message. - --htmldir - directory for resulting HTML files. - --htmlroot - http-server base directory from which all relative paths - in podpath stem (default is /). - --[no]index - generate an index at the top of the resulting html - (default behaviour). - --infile - filename for the pod to convert (input taken from stdin - by default). - --outfile - filename for the resulting html file (output sent to - stdout by default). - --[no]poderrors - include a POD ERRORS section in the output if there were - any POD errors in the input (default behavior). - --podpath - colon-separated list of directories containing library - pods (empty by default). - --podroot - filesystem base directory from which all relative paths - in podpath stem (default is .). - --[no]quiet - suppress some benign warning messages (default is off). - --[no]recurse - recurse on those subdirectories listed in podpath - (default behaviour). - --title - title that will appear in resulting html file. - --[no]verbose - self-explanatory (off by default). - -END_OF_USAGE - -} - -=head2 C - -TK - -=cut - -sub unixify { - my $full_path = shift; - return '' unless $full_path; - return $full_path if $full_path eq '/'; - - my ($vol, $dirs, $file) = File::Spec->splitpath($full_path); - my @dirs = $dirs eq File::Spec->curdir() - ? (File::Spec::Unix->curdir()) - : File::Spec->splitdir($dirs); - if (defined($vol) && $vol) { - $vol =~ s/:$// if $^O eq 'VMS'; - $vol = uc $vol if $^O eq 'MSWin32'; - - if( $dirs[0] ) { - unshift @dirs, $vol; - } - else { - $dirs[0] = $vol; - } - } - unshift @dirs, '' if File::Spec->file_name_is_absolute($full_path); - return $file unless scalar(@dirs); - $full_path = File::Spec::Unix->catfile(File::Spec::Unix->catdir(@dirs), - $file); - $full_path =~ s|^\/|| if $^O eq 'MSWin32'; # C:/foo works, /C:/foo doesn't - $full_path =~ s/\^\././g if $^O eq 'VMS'; # unescape dots - return $full_path; -} - -=head2 C - -Convert an absolute URL to one relative to a base URL. -Assumes both end in a filename. - -=cut - -sub relativize_url { - my ($dest, $source) = @_; - - # Remove each file from its path - my ($dest_volume, $dest_directory, $dest_file) = - File::Spec::Unix->splitpath( $dest ); - $dest = File::Spec::Unix->catpath( $dest_volume, $dest_directory, '' ); - - my ($source_volume, $source_directory, $source_file) = - File::Spec::Unix->splitpath( $source ); - $source = File::Spec::Unix->catpath( $source_volume, $source_directory, '' ); - - my $rel_path = ''; - if ($dest ne '') { - $rel_path = File::Spec::Unix->abs2rel( $dest, $source ); - } - - if ($rel_path ne '' && substr( $rel_path, -1 ) ne '/') { - $rel_path .= "/$dest_file"; - } else { - $rel_path .= "$dest_file"; - } - - return $rel_path; -} - -=head2 C - -Make text safe for HTML. - -=cut - -sub html_escape { - my $rest = $_[0]; - $rest =~ s/&/&/g; - $rest =~ s//>/g; - $rest =~ s/"/"/g; - $rest =~ s/([[:^print:]])/sprintf("&#x%x;", ord($1))/aeg; - return $rest; -} - -=head2 C - - htmlify($heading); - -Converts a pod section specification to a suitable section specification -for HTML. Note that we keep spaces and special characters except -C<", ?> (Netscape problem) and the hyphen (writer's problem...). - -=cut - -sub htmlify { - my( $heading) = @_; - return Pod::Simple::XHTML->can("idify")->(undef, $heading, 1); -} - -=head2 C - - anchorify(@heading); - -Similar to C, but turns non-alphanumerics into underscores. Note -that C is not exported by default. - -=cut - -sub anchorify { - my ($anchor) = @_; - $anchor = htmlify($anchor); - $anchor =~ s/\W/_/g; - return $anchor; -} - -=head2 C - -Remove any level of indentation (spaces or tabs) from each code block -consistently. Adapted from: -https://metacpan.org/source/HAARG/MetaCPAN-Pod-XHTML-0.002001/lib/Pod/Simple/Role/StripVerbatimIndent.pm - -=cut - -sub trim_leading_whitespace { - my ($para) = @_; - - # Start by converting tabs to spaces - @$para = Text::Tabs::expand(@$para); - - # Find the line with the least amount of indent, as that's our "base" - my @indent_levels = (sort(map { $_ =~ /^( *)./mg } @$para)); - my $indent = $indent_levels[0] || ""; - - # Remove the "base" amount of indent from each line - foreach (@$para) { - $_ =~ s/^\Q$indent//mg; - } - - return; -} - -1; - diff --git a/ext/Pod-Html/lib/Pod/Html/Util.pm b/ext/Pod-Html/lib/Pod/Html/Util.pm new file mode 100644 index 0000000000..2ecedfdc9e --- /dev/null +++ b/ext/Pod-Html/lib/Pod/Html/Util.pm @@ -0,0 +1,292 @@ +package Pod::Html::Util; +use strict; +require Exporter; + +our $VERSION = 1.29; # Please keep in synch with lib/Pod/Html.pm +$VERSION = eval $VERSION; +our @ISA = qw(Exporter); +our @EXPORT_OK = qw( + anchorify + html_escape + htmlify + parse_command_line + relativize_url + trim_leading_whitespace + unixify + usage +); + +use Config; +use File::Spec; +use File::Spec::Unix; +use Getopt::Long; +use Pod::Simple::XHTML; +use Text::Tabs; +use locale; # make \w work right in non-ASCII lands + +=head1 NAME + +Pod::Html::Util - helper functions for Pod-Html + +=head1 SUBROUTINES + +=head2 C + +TK + +=cut + +sub parse_command_line { + my $globals = shift; + my ($opt_backlink,$opt_cachedir,$opt_css,$opt_flush,$opt_header, + $opt_help,$opt_htmldir,$opt_htmlroot,$opt_index,$opt_infile, + $opt_outfile,$opt_poderrors,$opt_podpath,$opt_podroot, + $opt_quiet,$opt_recurse,$opt_title,$opt_verbose); + + unshift @ARGV, split ' ', $Config{pod2html} if $Config{pod2html}; + my $result = GetOptions( + 'backlink!' => \$opt_backlink, + 'cachedir=s' => \$opt_cachedir, + 'css=s' => \$opt_css, + 'flush' => \$opt_flush, + 'help' => \$opt_help, + 'header!' => \$opt_header, + 'htmldir=s' => \$opt_htmldir, + 'htmlroot=s' => \$opt_htmlroot, + 'index!' => \$opt_index, + 'infile=s' => \$opt_infile, + 'outfile=s' => \$opt_outfile, + 'poderrors!' => \$opt_poderrors, + 'podpath=s' => \$opt_podpath, + 'podroot=s' => \$opt_podroot, + 'quiet!' => \$opt_quiet, + 'recurse!' => \$opt_recurse, + 'title=s' => \$opt_title, + 'verbose!' => \$opt_verbose, + ); + usage("-", "invalid parameters") if not $result; + + usage("-") if defined $opt_help; # see if the user asked for help + $opt_help = ""; # just to make -w shut-up. + + @{$globals->{Podpath}} = split(":", $opt_podpath) if defined $opt_podpath; + + $globals->{Backlink} = $opt_backlink if defined $opt_backlink; + $globals->{Cachedir} = unixify($opt_cachedir) if defined $opt_cachedir; + $globals->{Css} = $opt_css if defined $opt_css; + $globals->{Header} = $opt_header if defined $opt_header; + $globals->{Htmldir} = unixify($opt_htmldir) if defined $opt_htmldir; + $globals->{Htmlroot} = unixify($opt_htmlroot) if defined $opt_htmlroot; + $globals->{Doindex} = $opt_index if defined $opt_index; + $globals->{Podfile} = unixify($opt_infile) if defined $opt_infile; + $globals->{Htmlfile} = unixify($opt_outfile) if defined $opt_outfile; + $globals->{Poderrors} = $opt_poderrors if defined $opt_poderrors; + $globals->{Podroot} = unixify($opt_podroot) if defined $opt_podroot; + $globals->{Quiet} = $opt_quiet if defined $opt_quiet; + $globals->{Recurse} = $opt_recurse if defined $opt_recurse; + $globals->{Title} = $opt_title if defined $opt_title; + $globals->{Verbose} = $opt_verbose if defined $opt_verbose; + + warn "Flushing directory caches\n" + if $opt_verbose && defined $opt_flush; + $globals->{Dircache} = "$globals->{Cachedir}/pod2htmd.tmp"; + if (defined $opt_flush) { + 1 while unlink($globals->{Dircache}); + } + return $globals; +} + +=head2 C + +TK + +=cut + +sub usage { + my $podfile = shift; + warn "$0: $podfile: @_\n" if @_; + die < --htmlroot= + --infile= --outfile= + --podpath=:...: --podroot= + --cachedir= --flush --recurse --norecurse + --quiet --noquiet --verbose --noverbose + --index --noindex --backlink --nobacklink + --header --noheader --poderrors --nopoderrors + --css= --title= + + --[no]backlink - turn =head1 directives into links pointing to the top of + the page (off by default). + --cachedir - directory for the directory cache files. + --css - stylesheet URL + --flush - flushes the directory cache. + --[no]header - produce block header/footer (default is no headers). + --help - prints this message. + --htmldir - directory for resulting HTML files. + --htmlroot - http-server base directory from which all relative paths + in podpath stem (default is /). + --[no]index - generate an index at the top of the resulting html + (default behaviour). + --infile - filename for the pod to convert (input taken from stdin + by default). + --outfile - filename for the resulting html file (output sent to + stdout by default). + --[no]poderrors - include a POD ERRORS section in the output if there were + any POD errors in the input (default behavior). + --podpath - colon-separated list of directories containing library + pods (empty by default). + --podroot - filesystem base directory from which all relative paths + in podpath stem (default is .). + --[no]quiet - suppress some benign warning messages (default is off). + --[no]recurse - recurse on those subdirectories listed in podpath + (default behaviour). + --title - title that will appear in resulting html file. + --[no]verbose - self-explanatory (off by default). + +END_OF_USAGE + +} + +=head2 C + +TK + +=cut + +sub unixify { + my $full_path = shift; + return '' unless $full_path; + return $full_path if $full_path eq '/'; + + my ($vol, $dirs, $file) = File::Spec->splitpath($full_path); + my @dirs = $dirs eq File::Spec->curdir() + ? (File::Spec::Unix->curdir()) + : File::Spec->splitdir($dirs); + if (defined($vol) && $vol) { + $vol =~ s/:$// if $^O eq 'VMS'; + $vol = uc $vol if $^O eq 'MSWin32'; + + if( $dirs[0] ) { + unshift @dirs, $vol; + } + else { + $dirs[0] = $vol; + } + } + unshift @dirs, '' if File::Spec->file_name_is_absolute($full_path); + return $file unless scalar(@dirs); + $full_path = File::Spec::Unix->catfile(File::Spec::Unix->catdir(@dirs), + $file); + $full_path =~ s|^\/|| if $^O eq 'MSWin32'; # C:/foo works, /C:/foo doesn't + $full_path =~ s/\^\././g if $^O eq 'VMS'; # unescape dots + return $full_path; +} + +=head2 C + +Convert an absolute URL to one relative to a base URL. +Assumes both end in a filename. + +=cut + +sub relativize_url { + my ($dest, $source) = @_; + + # Remove each file from its path + my ($dest_volume, $dest_directory, $dest_file) = + File::Spec::Unix->splitpath( $dest ); + $dest = File::Spec::Unix->catpath( $dest_volume, $dest_directory, '' ); + + my ($source_volume, $source_directory, $source_file) = + File::Spec::Unix->splitpath( $source ); + $source = File::Spec::Unix->catpath( $source_volume, $source_directory, '' ); + + my $rel_path = ''; + if ($dest ne '') { + $rel_path = File::Spec::Unix->abs2rel( $dest, $source ); + } + + if ($rel_path ne '' && substr( $rel_path, -1 ) ne '/') { + $rel_path .= "/$dest_file"; + } else { + $rel_path .= "$dest_file"; + } + + return $rel_path; +} + +=head2 C + +Make text safe for HTML. + +=cut + +sub html_escape { + my $rest = $_[0]; + $rest =~ s/&/&/g; + $rest =~ s//>/g; + $rest =~ s/"/"/g; + $rest =~ s/([[:^print:]])/sprintf("&#x%x;", ord($1))/aeg; + return $rest; +} + +=head2 C + + htmlify($heading); + +Converts a pod section specification to a suitable section specification +for HTML. Note that we keep spaces and special characters except +C<", ?> (Netscape problem) and the hyphen (writer's problem...). + +=cut + +sub htmlify { + my( $heading) = @_; + return Pod::Simple::XHTML->can("idify")->(undef, $heading, 1); +} + +=head2 C + + anchorify(@heading); + +Similar to C, but turns non-alphanumerics into underscores. Note +that C is not exported by default. + +=cut + +sub anchorify { + my ($anchor) = @_; + $anchor = htmlify($anchor); + $anchor =~ s/\W/_/g; + return $anchor; +} + +=head2 C + +Remove any level of indentation (spaces or tabs) from each code block +consistently. Adapted from: +https://metacpan.org/source/HAARG/MetaCPAN-Pod-XHTML-0.002001/lib/Pod/Simple/Role/StripVerbatimIndent.pm + +=cut + +sub trim_leading_whitespace { + my ($para) = @_; + + # Start by converting tabs to spaces + @$para = Text::Tabs::expand(@$para); + + # Find the line with the least amount of indent, as that's our "base" + my @indent_levels = (sort(map { $_ =~ /^( *)./mg } @$para)); + my $indent = $indent_levels[0] || ""; + + # Remove the "base" amount of indent from each line + foreach (@$para) { + $_ =~ s/^\Q$indent//mg; + } + + return; +} + +1; + diff --git a/ext/Pod-Html/t/anchorify.t b/ext/Pod-Html/t/anchorify.t index 68bc8834be..03d87f80d6 100644 --- a/ext/Pod-Html/t/anchorify.t +++ b/ext/Pod-Html/t/anchorify.t @@ -1,7 +1,7 @@ # -*- perl -*- use strict; -use Pod::Html::Auxiliary qw( anchorify ); +use Pod::Html::Util qw( anchorify ); use Test::More tests => 1; my @filedata; @@ -46,7 +46,7 @@ is_deeply( __DATA__ =head1 NAME -anchorify - Test C +anchorify - Test C =head1 DESCRIPTION diff --git a/ext/Pod-Html/t/cache.t b/ext/Pod-Html/t/cache.t index d2a48ae2f9..7a261fb4eb 100644 --- a/ext/Pod-Html/t/cache.t +++ b/ext/Pod-Html/t/cache.t @@ -11,7 +11,7 @@ use warnings; use Test::More tests => 10; use Testing qw( setup_testing_dir xconvert ); use Cwd; -use Pod::Html::Auxiliary qw( +use Pod::Html::Util qw( unixify ); diff --git a/ext/Pod-Html/t/crossref2.t b/ext/Pod-Html/t/crossref2.t index bdc801a724..9398c11f51 100644 --- a/ext/Pod-Html/t/crossref2.t +++ b/ext/Pod-Html/t/crossref2.t @@ -11,7 +11,7 @@ use warnings; use Test::More tests => 1; use Testing qw( setup_testing_dir xconvert ); use Cwd; -use Pod::Html::Auxiliary qw( +use Pod::Html::Util qw( unixify ); diff --git a/ext/Pod-Html/t/lib/Testing.pm b/ext/Pod-Html/t/lib/Testing.pm index 4b3355456b..3b993b10f2 100644 --- a/ext/Pod-Html/t/lib/Testing.pm +++ b/ext/Pod-Html/t/lib/Testing.pm @@ -19,7 +19,7 @@ use File::Path ( qw| make_path | ); use File::Spec::Functions ':ALL'; use File::Temp ( qw| tempdir | ); use Data::Dumper;$Data::Dumper::Sortkeys=1; -use Pod::Html::Auxiliary qw( +use Pod::Html::Util qw( unixify ); -- cgit v1.2.1