develooper Front page | perl.perl5.porters | Postings from June 2018

[perl #133296] pod/buildtoc: generates warnings and errors inpod/perltoc.pod

Thread Next
From:
James E Keenan
Date:
June 23, 2018 02:53
Subject:
[perl #133296] pod/buildtoc: generates warnings and errors inpod/perltoc.pod
Message ID:
rt-4.0.24-9995-1529722411-482.133296-75-0@perl.org
# New Ticket Created by  James E Keenan 
# Please include the string:  [perl #133296]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org/Ticket/Display.html?id=133296 >


The program 'pod/buildtoc' is nearly the last step run by 'make'.  It 
generates 'pod/perltoc.pod' from all the other .pod files in the core 
distribution.  If, however, you run the 'podchecker' utility over 
'pod/perltoc.pod', you will get both WARNINGs and ERRORs.  For example, 
in perl-5.26.0, you get:

#####
$ perldoc -l perltoc
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod

$ podchecker `perldoc -l perltoc`
*** WARNING: empty section in previous paragraph at line 20657 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 20675 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 20677 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 20815 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 20817 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 20833 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** ERROR: unresolved internal link 'Other Properties' at line 3896 in 
file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** ERROR: unresolved internal link 'runtests' at line 33191 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
*** ERROR: unresolved internal link 'summary' at line 33191 in file 
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod
/home/jkeenan/perl5/perlbrew/perls/perl-5.26.0/lib/5.26.0/pod/perltoc.pod 
has 3 pod syntax errors.
#####

I get what is effectively the same in perl-5.28.0 (so, not a regression):

#####
$ podchecker pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21226 in file 
pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21244 in file 
pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21246 in file 
pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21384 in file 
pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21386 in file 
pod/perltoc.pod
*** WARNING: empty section in previous paragraph at line 21402 in file 
pod/perltoc.pod
*** ERROR: unresolved internal link 'Other Properties' at line 3909 in 
file pod/perltoc.pod
*** ERROR: unresolved internal link 'runtests' at line 33790 in file 
pod/perltoc.pod
*** ERROR: unresolved internal link 'summary' at line 33790 in file 
pod/perltoc.pod
pod/perltoc.pod has 3 pod syntax errors.
#####

1. The unresolved link 'Other Properties' has its origin in 
pod/perlunicode.pod:

#####
1085 =head2 Unicode Regular Expression Support Level
1086
1087 The following list of Unicode supported features for regular 
expressions describes
1088 all features currently directly supported by core Perl.  The references
1089 to "Level I<N>" and the section numbers refer to
1090 L<UTS#18 "Unicode Regular 
Expressions"|http://www.unicode.org/reports/tr18>,
1091 version 13, November 2013.
1092
1093 =head3 Level 1 - Basic Unicode Support
1094
1095  RL1.1   Hex Notation                     - Done          [1]
1096  RL1.2   Properties                       - Done          [2]
1097  RL1.2a  Compatibility Properties         - Done          [3]
1098  RL1.3   Subtraction and Intersection     - Experimental  [4]
1099  RL1.4   Simple Word Boundaries           - Done          [5]
1100  RL1.5   Simple Loose Matches             - Done          [6]
1101  RL1.6   Line Boundaries                  - Partial       [7]
1102  RL1.7   Supplementary Code Points        - Done          [8]
1103
1104 =over 4
1105
1106 =item [1] C<\N{U+...}> and C<\x{...}>
1107
1108 =item [2]
1109 C<\p{...}> C<\P{...}>.  This requirement is for a minimal list of
1110 properties.  Perl supports these and all other Unicode character
1111 properties, as R2.7 asks (see L</"Unicode Character Properties"> 
above).
1112
1113 =item [3]
1114 Perl has C<\d> C<\D> C<\s> C<\S> C<\w> C<\W> C<\X> C<[:I<prop>:]>
1115 C<[:^I<prop>:]>, plus all the properties specified by
1116 L<http://www.unicode.org/reports/tr18/#Compatibility_Properties>. 
These
1117 are described above in L</Other Properties>
1118
1119 =item [4]
1120
...
#####

2. The unresolved links 'runtests' and 'summary' come from 
cpan/Test-Harness/lib/TAP/Harness.pm:

#####
1012 =head1 SUBCLASSING
1013
1014 If you can't configure C<TAP::Harness> to do exactly what you want, 
and writing
1015 a plugin isn't an option, consider extending it.  It is designed to 
be (mostly)
1016 easy to subclass, though the cases when sub-classing is necessary 
should be few
1017 and far between.
1018
1019 =head2 Methods
1020
1021 The following methods are ones you may wish to override if you want to
1022 subclass C<TAP::Harness>.
1023
1024 =over 4
1025
1026 =item L</new>
1027
1028 =item L</runtests>
1029
1030 =item L</summary>
1031
1032 =back
#####

When I run pod/perlunicode.pod and cpan/Test-Harness/lib/TAP/Harness.pm 
through the standard 'podchecker' utility, both are graded 'pod syntax 
OK'.  So something is probably amiss with the pod/buildtoc program.

Thank you very much.
Jim Keenan

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About