branch master updated: * contrib/perldoc-all, doc/texinfo.texi (Invoking @command{pod2texi}): comment out the paragraph on contrib/perldoc-all as there are issues with cross Pod links, because the Perldoc Browser adds an additional anchor with the first word.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new c2a7f649c7 * contrib/perldoc-all, doc/texinfo.texi (Invoking 
@command{pod2texi}): comment out the paragraph on contrib/perldoc-all as there 
are issues with cross Pod links, because the Perldoc Browser adds an additional 
anchor with the first word.
c2a7f649c7 is described below

commit c2a7f649c7c878e30c5010e51d25d2536f86e08f
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Feb 8 22:11:52 2022 +0100

    * contrib/perldoc-all, doc/texinfo.texi (Invoking @command{pod2texi}):
    comment out the paragraph on contrib/perldoc-all as there are issues with
    cross Pod links, because the Perldoc Browser adds an additional anchor
    with the first word.
---
 ChangeLog                            |  7 +++++++
 Pod-Simple-Texinfo/pod2texi.pl       |  9 +++++++++
 contrib/perldoc-all/GNUmakefile      | 11 ++++++++---
 contrib/perldoc-all/README           |  6 ++++++
 contrib/perldoc-all/perldoc-all.texi |  4 ++--
 doc/texinfo.texi                     | 11 +++++++----
 man/pod2texi.1                       |  4 ++--
 7 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8f9f556f8b..c375f00b6e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-02-08  Patrice Dumas  <pertusus@free.fr>
+
+       * contrib/perldoc-all, doc/texinfo.texi (Invoking @command{pod2texi}): 
+       comment out the paragraph on contrib/perldoc-all as there are issues 
with
+       cross Pod links, because the Perldoc Browser adds an additional anchor
+       with the first word.
+
 2022-02-08  Patrice Dumas  <pertusus@free.fr>
 
        * Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm (_convert_pod)
diff --git a/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index 9668371988..37daa792e6 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -529,6 +529,15 @@ and all the C<@include> is generated.
 
 =head1 OPTIONS
 
+=begin comment
+
+This style used for command line options is a style often seen in
+Pods.  Also often seen is simple =item, or a verbatim block with --help
+output.  More rarely =head2, very rare use of C<>.  Use of C<> would
+have been more in line with Texinfo @option.
+
+=end comment
+
 =over
 
 =item B<--appendix-sections>
diff --git a/contrib/perldoc-all/GNUmakefile b/contrib/perldoc-all/GNUmakefile
index f7fdde69a4..2b056b963e 100644
--- a/contrib/perldoc-all/GNUmakefile
+++ b/contrib/perldoc-all/GNUmakefile
@@ -22,10 +22,14 @@ pod2texi_args  = --base-level=section
 pod2texi_args += --preamble=''  # we want our own
 pod2texi_args += --subdir=$(texi_pod_subdir)
 
-# Unfortunately have to use --no-validate since not all the names and
-# L<references> match up.  Split HTML by chapter is the natural thing here.
 gendocs_args  = --email bug-texinfo@gnu.org
+# Unfortunately have to use --no-validate since not all the names and
+# L<references> match up.  The main issue with missing links is because
+# Pod::Simple::Role::XHTML::WithLinkMappings which formats the Perldoc Browser
+# does not follow the Pod specification and adds anchors:
+#   "a link will be generated using the first word of the target."
 gendocs_args += --common "--no-warn --no-validate"
+# Split HTML by chapter is the natural thing here.
 gendocs_args += --split chapter
 gendocs_args += --no-ascii
 gendocs_args += --source $(texi_pod_subdir)
@@ -51,7 +55,8 @@ $(texi_pod_doc_incl): $(perl_pod_subdir)/*.pod
 # searching (and take tons of time and space to process).
 # 
 # We also omit perlunicook, since it necessarily has many binary Unicode
-# characters, and processing the whole thing in UTF-8 makes it less useful. 
+# characters, and processing the whole thing with UTF-8 not handled
+# by texi2pdf is not useful.
 #
 # Because we start from the source directory, we also lose all the
 # generated .pods, such as perluniprops.  We would not want
diff --git a/contrib/perldoc-all/README b/contrib/perldoc-all/README
index 81db92c660..32adc6d167 100644
--- a/contrib/perldoc-all/README
+++ b/contrib/perldoc-all/README
@@ -16,3 +16,9 @@ and run (GNU) make.  Aside from the result hopefully being 
useful in
 itself (just copy the .info file to an Info directory), it also serves
 as a nontrivial example of using pod2texi.
 
+Note that a main issue with the generated files is that many internal
+links are missing because the links do not follow the Pod specification
+as Pod::Simple::Role::XHTML::WithLinkMappings which formats the Perldoc
+Browser adds anchors:
+  "a link will be generated using the first word of the target."
+
diff --git a/contrib/perldoc-all/perldoc-all.texi 
b/contrib/perldoc-all/perldoc-all.texi
index 6b38bd51cb..ccdd737207 100644
--- a/contrib/perldoc-all/perldoc-all.texi
+++ b/contrib/perldoc-all/perldoc-all.texi
@@ -1,7 +1,7 @@
 \input texinfo
 @c This top-level file is so trivial, it has to be public domain.
 @setfilename perldoc-all.info
-@settitle Perl pod documentation
+@settitle Perl Pod documentation
 @finalout
 @tex
 \global\hfuzz=\maxdimen
@@ -16,7 +16,7 @@
 @top Perl pod documentation
 
 This translation of the Perl documentation
-(@url{http://perldoc.perl.org}) from POD to Texinfo is not official,
+(@url{http://perldoc.perl.org}) from Pod to Texinfo is not official,
 and not endorsed by the Perl developers (indeed, they haven't seen
 it).  It was created by the GNU Texinfo developers because they found
 it useful to have the Perl documentation available in Info and other
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 0f3d8d3474..5bf77482f1 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -17140,10 +17140,13 @@ version on the web
 included below.  The version included in the manual is also an example of
 @command{pod2texi} use, as it is converted from Pod using @command{pod2texi}.
 
-For an example of using @command{pod2texi} to make Texinfo out of the
-Perl documentation itself, see
-@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
-@file{contrib/perldoc-all}} in the Texinfo source distribution.
+@c there are issue with the perldoc-all generated files, as the perl 
documentation
+@c does not follows the Pod specification, there are anchors added
+@c using the first word in addition to the regular anchors.
+@c For an example of using @command{pod2texi} to make Texinfo out of the
+@c Perl documentation itself, see
+@c 
@url{http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo,
+@c @file{contrib/perldoc-all}} in the Texinfo source distribution.
 
 @menu
 * pod2texi manual page::      @command{pod2texi} invokation in a manual page 
format
diff --git a/man/pod2texi.1 b/man/pod2texi.1
index 17fb07a8c1..903a821074 100644
--- a/man/pod2texi.1
+++ b/man/pod2texi.1
@@ -226,8 +226,8 @@ Display version information and exit.
 .IX Header "SEE ALSO"
 Pod::Simple::Texinfo.  perlpod.  The Texinfo manual.
 Texinfo home page: <http://www.gnu.org/software/texinfo/>
-.SH "COPYRIGHT"
-.IX Header "COPYRIGHT"
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
 Copyright 2012\-2022 Free Software Foundation, Inc.
 .PP
 This program is free software; you can redistribute it and/or modify