texinfo-commits
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[no subject]


From: Patrice Dumas
Date: Sun, 27 Oct 2024 11:22:28 -0400 (EDT)

branch: master
commit 6c41c1044323f965771d8494bd7a9723eea938e1
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Oct 27 17:22:16 2024 +0100

    pod2texi: Use an @url to convert L<...> referring to external modules
    
    * Pod-Simple-Texinfo/Makefile.PL (WriteMakefile),
    Pod-Simple-Texinfo/README, configure.ac (POD_SIMPLE_TEXINFO_TESTS)
    (BUILD_PERL_API_TEXI): document/add Pod::Simple::XHTML dependence.
    
    * Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm (_accessorize),
    ($pod_links_html_parser, new, _texinfo_handle_element_start)
    (_texinfo_handle_element_end): add texinfo_external_pod_as_url
    configuration, set to 1 in the default case.  Pass $manual_text
    and $section_text to L tag formatting.  If texinfo_external_pod_as_url
    is set, format L to external Pod as an @url, using idify and
    perldoc_url_prefix from Pod::Simple::XHTML, mimicking
    Pod::Simple::XHTML resolve_pod_page_link, but without url protection,
    as it is already done in Texinfo::Convert::HTML.
    
    * Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t (run_test)
    (index in head node, protected characters, link to external module)
    (protected -, end of line in L, empty head2): modify run_test to
    pass $external_pod_as_url as first optional argument, to be able to
    set texinfo_external_pod_as_url to a different value as the default.
    
    * Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t
    (link to external module external pod as url)
    (protected - external pod as url)
    (end of line in L external pod as url): tests using the same Pod as
    other tests, but with texinfo_external_pod_as_url left to the default
    value.
---
 ChangeLog                                    | 31 +++++++++++
 Pod-Simple-Texinfo/Makefile.PL               |  1 +
 Pod-Simple-Texinfo/README                    |  2 +-
 Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm | 52 +++++++++++++-----
 Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t    | 80 +++++++++++++++++++++-------
 configure.ac                                 |  4 +-
 doc/pod2texi.texi                            |  2 +-
 doc/tp_api/api_includes/Texinfo-Common.texi  |  4 +-
 8 files changed, 137 insertions(+), 39 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4b4eff57cd..ffc391f0aa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,34 @@
+2024-10-27  Patrice Dumas  <pertusus@free.fr>
+
+       pod2texi: Use an @url to convert L<...> referring to external modules
+
+       * Pod-Simple-Texinfo/Makefile.PL (WriteMakefile),
+       Pod-Simple-Texinfo/README, configure.ac (POD_SIMPLE_TEXINFO_TESTS)
+       (BUILD_PERL_API_TEXI): document/add Pod::Simple::XHTML dependence.
+
+       * Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm (_accessorize),
+       ($pod_links_html_parser, new, _texinfo_handle_element_start)
+       (_texinfo_handle_element_end): add texinfo_external_pod_as_url
+       configuration, set to 1 in the default case.  Pass $manual_text
+       and $section_text to L tag formatting.  If texinfo_external_pod_as_url
+       is set, format L to external Pod as an @url, using idify and
+       perldoc_url_prefix from Pod::Simple::XHTML, mimicking
+       Pod::Simple::XHTML resolve_pod_page_link, but without url protection,
+       as it is already done in Texinfo::Convert::HTML.
+
+       * Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t (run_test)
+       (index in head node, protected characters, link to external module)
+       (protected -, end of line in L, empty head2): modify run_test to
+       pass $external_pod_as_url as first optional argument, to be able to
+       set texinfo_external_pod_as_url to a different value as the default.
+
+       * Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t
+       (link to external module external pod as url)
+       (protected - external pod as url)
+       (end of line in L external pod as url): tests using the same Pod as
+       other tests, but with texinfo_external_pod_as_url left to the default
+       value.
+
 2024-10-27  Patrice Dumas  <pertusus@free.fr>
 
        * tp/texi2any.pl (@texinfo_language_config_dirs): when calling
diff --git a/Pod-Simple-Texinfo/Makefile.PL b/Pod-Simple-Texinfo/Makefile.PL
index df3a02ce88..dc47de0fc3 100644
--- a/Pod-Simple-Texinfo/Makefile.PL
+++ b/Pod-Simple-Texinfo/Makefile.PL
@@ -13,6 +13,7 @@ WriteMakefile(
     VERSION_FROM      => 'lib/Pod/Simple/Texinfo.pm', # finds $VERSION
     EXE_FILES         => [ 'pod2texi' ],
     PREREQ_PM         => { "Pod::Simple::PullParser" => 0,
+                           "Pod::Simple::XHTML" => 0,
                            "Texinfo::Parser" => 0,
                            "Getopt::Long" => 0,
                            "File::Spec" => 0,
diff --git a/Pod-Simple-Texinfo/README b/Pod-Simple-Texinfo/README
index dd5a72a680..360e11be47 100644
--- a/Pod-Simple-Texinfo/README
+++ b/Pod-Simple-Texinfo/README
@@ -21,7 +21,7 @@ DEPENDENCIES
 
 This module requires these other modules and libraries:
 
-Pod::Simple::PullParser, Texinfo::Parser.  
+Pod::Simple::PullParser, Pod::Simple::XHTML, Texinfo::Parser.
 
 DISTRIBUTION SETUP
 
diff --git a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm 
b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
index 9e9b20ad81..1fbf93c699 100644
--- a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
+++ b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
@@ -33,11 +33,6 @@
 #
 # bare_output flag described in Pod::Simple::Subclassing is taken into
 # account.
-#
-#
-# TODO: it could be relevant to convert L<...> referring to external modules to
-# urls to Metacpan, or similar websites, using @url instead of @ref, which
-# is very unlikely to lead to other modules documentation.
 
 
 package Pod::Simple::Texinfo;
@@ -50,6 +45,11 @@ use Carp qw(cluck);
 #use Pod::Simple::Debug (3);
 use Pod::Simple::PullParser ();
 
+# use idify from this package to be sure that the target is set by
+# MetaCPAN::Pod::HTML as anchor.  And also take perldoc_url_prefix
+# from this package.
+use Pod::Simple::XHTML;
+
 # for parselink()
 #use Pod::ParseLink;
 
@@ -104,6 +104,7 @@ my @raw_formats = ('html', 'HTML', 'docbook', 'DocBook', 
'texinfo',
 __PACKAGE__->_accessorize(
   'texinfo_add_upper_sectioning_command',
   'texinfo_debug',
+  'texinfo_external_pod_as_url',
   'texinfo_generate_setfilename', # for standalone manuals
   'texinfo_internal_pod_manuals',
   'texinfo_man_url_prefix',
@@ -119,6 +120,8 @@ my $sectioning_style = 'numbered';
 my $sectioning_base_level = 0;
 my $man_url_prefix = 'http://man.he.net/man';
 
+my $pod_links_html_parser = Pod::Simple::XHTML->new();
+
 sub new
 {
   my $class = shift;
@@ -133,6 +136,7 @@ sub new
   $new->texinfo_man_url_prefix($man_url_prefix);
   $new->texinfo_sectioning_style($sectioning_style);
   $new->texinfo_add_upper_sectioning_command(1);
+  $new->texinfo_external_pod_as_url(1);
   return $new;
 }
 
@@ -649,9 +653,10 @@ sub _texinfo_handle_element_start($$$)
       #print STDERR "  @attrs\n";
       #my $raw_L = $attr_hash->{'raw'}.'';
       #print STDERR " $attr_hash->{'raw'}: $raw_L\n";
-      my ($url_arg, $texinfo_node, $texinfo_manual, $texinfo_section);
+      my ($url_arg, $texinfo_node, $texinfo_manual, $texinfo_section,
+          $manual_text, $section_text);
       if ($linktype eq 'man') {
-        # NOTE: the .'' is here to force the $token->attr to ba a real
+        # NOTE: the .'' is here to force the $token->attr to be a real
         # string and not an object.
         # NOTE 2: It is not clear that setting the url should be done
         # here, maybe this should be in the Texinfo HTML converter.
@@ -706,7 +711,7 @@ sub _texinfo_handle_element_start($$$)
         # same functions as the pull parser implementation.
         my $manual = $attr_hash->{'to'};
         my $section = $attr_hash->{'section'};
-        my ($section_text, $section_texi, $section_out);
+        my ($section_texi, $section_out);
         if (defined($section)) {
           # convert the section presented as tree to Texinfo
           _begin_context($self->{'texinfo_accumulated'}, 'L section');
@@ -717,7 +722,7 @@ sub _texinfo_handle_element_start($$$)
           # coerce to string
           $section_text = $section.'';
         }
-        my ($manual_text, $manual_texi, $manual_out);
+        my ($manual_texi, $manual_out);
         if (defined($manual)) {
           # convert the manual presented as tree to Texinfo
           _begin_context($self->{'texinfo_accumulated'}, 'L manual');
@@ -797,7 +802,8 @@ sub _texinfo_handle_element_start($$$)
         # section.
       }
       push @{$self->{'texinfo_stack'}}, [$linktype, $content_implicit, 
$url_arg,
-                           $texinfo_manual, $texinfo_node, $texinfo_section];
+                           $texinfo_manual, $texinfo_node, $texinfo_section,
+                           $manual_text, $section_text];
       #print STDERR join('|', @{$self->{'texinfo_stack'}->[-1]}) . "\n";
       #if (defined($to)) {
       #  print STDERR " | $to\n";
@@ -952,7 +958,8 @@ sub _texinfo_handle_element_end($$$)
     } elsif ($tagname eq 'L') {
       my $format = pop @{$self->{'texinfo_stack'}};
       my ($linktype, $content_implicit, $url_arg,
-          $texinfo_manual, $texinfo_node, $texinfo_section) = @$format;
+          $texinfo_manual, $texinfo_node, $texinfo_section,
+          $manual_text, $section_text) = @$format;
       if ($linktype ne 'man') {
         my $explanation;
         if (defined($result) and $result =~ m/\S/ and !$content_implicit) {
@@ -967,9 +974,26 @@ sub _texinfo_handle_element_end($$$)
           }
         } elsif ($linktype eq 'pod') {
           if (defined($texinfo_manual)) {
-            $explanation = '' if (!defined($explanation));
-            _output($fh, $self->{'texinfo_accumulated'},
-                     "\@ref{$texinfo_node,,$explanation, $texinfo_manual}");
+            if ($self->texinfo_external_pod_as_url) {
+              my $node_manual = _protect_comma(protect_text($manual_text));
+              if (defined($explanation)) {
+                $node_manual .= $explanation;
+              } elsif (defined($texinfo_node) and $texinfo_node ne '') {
+                $node_manual .= ' '.$texinfo_node;
+              }
+              my $href = $pod_links_html_parser->perldoc_url_prefix
+                  . $manual_text;
+              if (defined($explanation)) {
+                my $target = $pod_links_html_parser->idify($section_text, 1);
+                $href .= '#'.$target if ($target ne '');
+              }
+              _output($fh, $self->{'texinfo_accumulated'},
+               "\@url{"._protect_comma(protect_text($href)).", $node_manual}");
+            } else {
+              $explanation = '' if (!defined($explanation));
+              _output($fh, $self->{'texinfo_accumulated'},
+                    "\@ref{$texinfo_node,,$explanation, $texinfo_manual}");
+            }
           } elsif (defined($explanation)) {
             _output($fh, $self->{'texinfo_accumulated'},
                    "\@ref{$texinfo_node,,$explanation}");
diff --git a/Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t 
b/Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t
index 163640da1d..ac215412f1 100644
--- a/Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t
+++ b/Pod-Simple-Texinfo/t/Pod-Simple-Texinfo.t
@@ -7,7 +7,7 @@ use Test::More;
 use File::Spec;
 
 BEGIN {
-  plan tests => 23;
+  plan tests => 26;
 
   my $updir = File::Spec->updir();
   # To find Texinfo::ModulePath
@@ -37,18 +37,22 @@ ok(1); # If we made it this far, we're ok.
 # to run a specific test:
 my $arg_test_case = shift @ARGV;
 
-sub run_test($$$;$$)
+sub run_test($$$;$$$)
 {
   my $in = shift;
   my $out = shift;
   my $name = shift;
+  my $external_pod_as_url = shift;
   my $test_nodes = shift;
   my $sectioning_base_level = shift;
 
   return if (defined($arg_test_case) and $name ne $arg_test_case);
 
   my $parser = Pod::Simple::Texinfo->new();
+
   $parser->set_source(\$in);
+  $parser->texinfo_external_pod_as_url($external_pod_as_url)
+    if (defined($external_pod_as_url));
   $parser->texinfo_section_nodes(1)
     if ($test_nodes);
   if (defined($sectioning_base_level)) {
@@ -68,7 +72,7 @@ sub run_test($$$;$$)
   }
 }
 
-run_test ('=head1 T
+run_test('=head1 T
 X<aaa>
 ',
 '@chapter T
@@ -82,7 +86,7 @@ TODO: {
 # fixed in 3.24 2013-02-14
 local $TODO = 'Pod::Simple not ignoring correctly X<>';
 
-run_test ('=head1 NAME
+run_test('=head1 NAME
 X<aaa>
 ',
 '@node NAME
@@ -90,11 +94,11 @@ X<aaa>
 @cindex aaa
 
 ',
-, 'index in head node', 1);
+, 'index in head node', undef, 1);
 
 }
 
-run_test ('=head1 NAME
+run_test('=head1 NAME
 
 T@c
 
@@ -113,9 +117,9 @@ T@@c
 @node T@@c @@@comma{}
 @subsection @@,
 
-', 'protected characters', 1, 2);
+', 'protected characters', undef, 1, 2);
 
-run_test ('=head1 T
+run_test('=head1 T
 
 Para X<bb>
 in para X<cc>  
@@ -228,7 +232,7 @@ run_test('=over
 
 @end table
 
-', 'duplicate anchors ref');
+', 'duplicate anchors ref', 0);
 
 run_test('=head1 a, b', '@chapter a, b
 @anchor{a@comma{} b}
@@ -299,16 +303,27 @@ L</head C<extra>>
 
 ', 'code in reference');
 
-run_test('=head1 head
+my $link_to_external_module_pod = '=head1 head
 
 L<Pod::deC<code>>
 
-', '@chapter head
+';
+
+run_test($link_to_external_module_pod,
+'@chapter head
 @anchor{head}
 
 @ref{,,, Pod-decode}
 
-', 'link to external module');
+', 'link to external module', 0);
+
+run_test($link_to_external_module_pod,
+'@chapter head
+@anchor{head}
+
+@url{https://metacpan.org/pod/Pod::decode, Pod::decode}
+
+', 'link to external module external pod as url');
 
 run_test('=head1 head
 
@@ -387,33 +402,60 @@ run_test('=head1 head
 @end html
 ','cpp lines in formats');
 
-run_test('=head1 ---- -- C<--->
+my $protected_dash_pod = '=head1 ---- -- C<--->
 
 C<--- L<---|--/--->>
 
 L<F<--->|F<-->/C<--->>
 
-','@chapter @asis{}-@asis{}-@asis{}-@asis{}- @asis{}-@asis{}-@asis{} @code{---}
+';
+
+run_test($protected_dash_pod,
+'@chapter @asis{}-@asis{}-@asis{}-@asis{}- @asis{}-@asis{}-@asis{} @code{---}
 @anchor{@asis{}-@asis{}-@asis{}-@asis{}- @asis{}-@asis{}-@asis{} @code{---}}
 
 @code{--- @ref{---,, @asis{}-@asis{}-@asis{}-@asis{}, --}}
 
 @ref{@code{---},, @file{---}, --}
 
-', 'protected -');
+', 'protected -', 0);
 
-run_test('=head1 end of line in L
+run_test($protected_dash_pod,
+'@chapter @asis{}-@asis{}-@asis{}-@asis{}- @asis{}-@asis{}-@asis{} @code{---}
+@anchor{@asis{}-@asis{}-@asis{}-@asis{}- @asis{}-@asis{}-@asis{} @code{---}}
+
+@code{--- @url{https://metacpan.org/pod/@asis{}-@asis{}-@asis{}#pod, 
@asis{}-@asis{}-@asis{} @asis{}-@asis{}-@asis{}-@asis{}}}
+
+@url{https://metacpan.org/pod/@asis{}-@asis{}-@asis{}#pod, 
@asis{}-@asis{}-@asis{} @file{---}}
+
+', 'protected - external pod as url');
+
+my $end_of_line_in_L_pod = '=head1 end of line in L
 
 L<< Some::Pod
 ::Manual/with
 end of C<line>
->>','@chapter end of line in L
+>>';
+
+run_test($end_of_line_in_L_pod,
+'@chapter end of line in L
 @anchor{end of line in L}
 
 @ref{with
 end of @code{line},,, Some-Pod-Manual}
 
-', 'end of line in L');
+', 'end of line in L', 0);
+
+run_test($end_of_line_in_L_pod,
+'@chapter end of line in L
+@anchor{end of line in L}
+
+@url{https://metacpan.org/pod/Some::Pod
+::Manual, Some::Pod
+::Manual with
+end of @code{line}}
+
+', 'end of line in L external pod as url');
 
 run_test('=head1 empty head2
 
@@ -432,7 +474,7 @@ run_test('=head1 empty head2
 @node @strong{}
 @section @strong{}
 
-', 'empty head2', 1);
+', 'empty head2', undef, 1);
 
 1;
 
diff --git a/configure.ac b/configure.ac
index b998d09d8b..ce5b445246 100644
--- a/configure.ac
+++ b/configure.ac
@@ -577,7 +577,7 @@ AC_ARG_ENABLE([pod-simple-texinfo-tests],
     [
      if test "z$PROVE" = 'z' ; then
        pod_simple_texinfo_tests='no'
-     elif $PERL -e "use 5.008_001; use Encode; use Test::More; use 
Pod::Simple::PullParser;" > /dev/null 2>&AS_MESSAGE_LOG_FD;
+     elif $PERL -e "use 5.008_001; use Encode; use Test::More; use 
Pod::Simple::PullParser; use Pod::Simple::XHTML;" > /dev/null 
2>&AS_MESSAGE_LOG_FD;
      then
        pod_simple_texinfo_tests='yes'
      else
@@ -599,7 +599,7 @@ AC_ARG_ENABLE([perl-api-texi-build],
        build_perl_api_texi='yes'
      fi],
     [
-     if $PERL -e "use 5.008_001; use Encode; use Pod::Simple::PullParser;" > 
/dev/null 2>&1;
+     if $PERL -e "use 5.008_001; use Encode; use Pod::Simple::PullParser; use 
Pod::Simple::XHTML;" > /dev/null 2>&AS_MESSAGE_LOG_FD;
      then
        build_perl_api_texi='yes'
      else
diff --git a/doc/pod2texi.texi b/doc/pod2texi.texi
index 46f602470a..bf0f2d388c 100644
--- a/doc/pod2texi.texi
+++ b/doc/pod2texi.texi
@@ -155,7 +155,7 @@ Display version information and exit.
 @subsubheading pod2texi SEE ALSO
 @anchor{pod2texi SEE ALSO}
 
-@ref{,,, Pod-Simple-Texinfo}.  @ref{,,, perlpod}.  The Texinfo manual.
+@url{https://metacpan.org/pod/Pod::Simple::Texinfo, Pod::Simple::Texinfo}.  
@url{https://metacpan.org/pod/perlpod, perlpod}.  The Texinfo manual.
 Texinfo home page: @url{https://www.gnu.org/software/texinfo/}
 
 @subsubheading pod2texi COPYRIGHT AND LICENSE
diff --git a/doc/tp_api/api_includes/Texinfo-Common.texi 
b/doc/tp_api/api_includes/Texinfo-Common.texi
index 375b947ac7..484305e05d 100644
--- a/doc/tp_api/api_includes/Texinfo-Common.texi
+++ b/doc/tp_api/api_includes/Texinfo-Common.texi
@@ -188,7 +188,7 @@ only be used in user-defined code with translatable strings 
already present in
 the domain anyway.  In fact, these functions are documented mainly because they
 are automatically exported.
 
-See @ref{,,, libintl-perl},
+See @url{https://metacpan.org/pod/libintl-perl, libintl-perl},
 @url{https://www.gnu.org/software/gettext/manual/html_node/gettext.html, 
@code{gettext} C interface},
 @url{https://www.gnu.org/software/gettext/manual/html_node/Perl.html, Perl in 
GNU Gettext}.
 For translation of strings in output, see @ref{Texinfo@asis{::}Translations 
NAME,, Texinfo::Translations}.
@@ -232,7 +232,7 @@ check the element itself, in addition to the parent context.
 Encode the @emph{$file_name} text string to a binary string 
@emph{$encoded_file_name}
 based on @emph{$input_encoding}.  Also returns the @emph{$encoding} name 
actually
 used which may have undergone some normalization.  This function is mostly
-a wrapper around @ref{encode,, Encode::encode, Encode} which avoids calling 
the module if not
+a wrapper around @url{https://metacpan.org/pod/Encode#encode, Encode 
Encode::encode} which avoids calling the module if not
 needed.  Do nothing if @emph{$input_encoding} is @code{undef}.
 
 @item $text = enumerate_item_representation($specification, $number)



reply via email to

[Prev in Thread] Current Thread [Next in Thread]