autodoc.pl: Specify scn for single-purpose files

Many of the files in perl are for one thing only, and hence their
embedded documentation will be for that one thing.  By creating a hash
here of them, those files don't have to worry about what section that
documentation goes under, and so it can be completely changed without
affecting them.

diff --git a/autodoc.pl b/autodoc.pl
index d524389..1c0a772 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -171,7 +171,14 @@ my %valid_sections = (
     $directives_scn => {},
     $concurrency_scn => {},
     $COP_scn => {},
-    $CV_scn => {},
+    $CV_scn => {
+        header => <<~'EOT',
+            This section documents functions to manipulate CVs which are
+            code-values, meaning subroutines.  For more information, see
+            L<perlguts>.
+            EOT
+    },
+
     $custom_scn => {},
     $dump_scn => {},
     $embedding_scn => {},
@@ -307,15 +314,25 @@ my %valid_sections = (
     $filters_scn => {},
     $stack_scn => {},
     $string_scn => {
-        header => <<~'EOT',
-            See also C<L</Unicode Support>>.
+        header => <<~EOT,
+            See also C<L</$unicode_scn>>.
             EOT
       },
     $SV_flags_scn => {},
     $SV_scn => {},
     $time_scn => {},
     $typedefs_scn => {},
-    $unicode_scn => {},
+    $unicode_scn => {
+        header => <<~EOT,
+            L<perlguts/Unicode Support> has an introduction to this API.
+
+            See also C<L</$classification_scn>>,
+            C<L</$casing_scn>>,
+            and C<L</$string_scn>>.
+            Various functions outside this section also work specially with
+            Unicode.  Search for the string "utf8" in this document.
+            EOT
+      },
     $utility_scn => {},
     $versioning_scn => {},
     $warning_scn => {},
@@ -385,10 +402,49 @@ sub embed_override($) {
     return ($flags, $embed_docref->{'ret_type'}, $embed_docref->{args}->@*);
 }
 
+# The section that is in effect at the beginning of the given file.  If not
+# listed here, an apidoc_section line must precede any apidoc lines.
+# This allows the files listed here that generally are single-purpose, to not
+# have to worry about the autodoc section
+my %initial_file_section = (
+                            'av.c' => $AV_scn,
+                            'av.h' => $AV_scn,
+                            'cv.h' => $CV_scn,
+                            'doio.c' => $io_scn,
+                            'gv.c' => $GV_scn,
+                            'gv.h' => $GV_scn,
+                            'hv.h' => $HV_scn,
+                            'locale.c' => $locale_scn,
+                            'malloc.c' => $memory_scn,
+                            'numeric.c' => $numeric_scn,
+                            'opnames.h' => $optree_construction_scn,
+                            'pad.h'=> $pad_scn,
+                            'patchlevel.h' => $versioning_scn,
+                            'perlio.h' => $io_scn,
+                            'pod/perlapio.pod' => $io_scn,
+                            'pod/perlcall.pod' => $callback_scn,
+                            'pod/perlembed.pod' => $embedding_scn,
+                            'pod/perlfilter.pod' => $filters_scn,
+                            'pod/perliol.pod' => $io_scn,
+                            'pod/perlmroapi.pod' => $MRO_scn,
+                            'pod/perlreguts.pod' => $regexp_scn,
+                            'pp_pack.c' => $pack_scn,
+                            'pp_sort.c' => $SV_scn,
+                            'regcomp.c' => $regexp_scn,
+                            'regexp.h' => $regexp_scn,
+                            'unicode_constants.h' => $unicode_scn,
+                            'utf8.c' => $unicode_scn,
+                            'utf8.h' => $unicode_scn,
+                            'vutil.c' => $versioning_scn,
+                           );
+
 sub autodoc ($$) { # parse a file and extract documentation info
     my($fh,$file) = @_;
     my($in, $line_num, $header, $section);
 
+    $section = $initial_file_section{$file}
+                                    if defined $initial_file_section{$file};
+
     my $file_is_C = $file =~ / \. [ch] $ /x;
 
     # Count lines easier

diff --git a/av.c b/av.c
index b0a4d8d..ed67df1 100644 (file)
--- a/av.c
+++ b/av.c
@@ -15,10 +15,6 @@
  *     [p.476 of _The Lord of the Rings_, III/iv: "Treebeard"]
  */
 
-/*
-=for apidoc_section AV Handling
-*/
-
 #include "EXTERN.h"
 #define PERL_IN_AV_C
 #include "perl.h"

diff --git a/av.h b/av.h
index 8466dc1..6903db6 100644 (file)
--- a/av.h
+++ b/av.h
@@ -37,8 +37,6 @@ struct xpvav {
  */
 
 /*
-=for apidoc_section AV Handling
-
 =for apidoc ADmnU||Nullav
 Null AV pointer.
 

diff --git a/cv.h b/cv.h
index b627fe8..5a3a25f 100644 (file)
--- a/cv.h
+++ b/cv.h
@@ -16,11 +16,6 @@ struct xpvcv {
 };
 
 /*
-=head1 CV Handling
-
-This section documents functions to manipulate CVs which are code-values,
-meaning subroutines.  For more information, see L<perlguts>.
-
 =for apidoc Ayh||CV
 
 =for apidoc ADmnU||Nullcv

diff --git a/doio.c b/doio.c
index b4103e1..2bffeea 100644 (file)
--- a/doio.c
+++ b/doio.c
@@ -3252,8 +3252,6 @@ Perl_do_shmio(pTHX_ I32 optype, SV **mark, SV **sp)
 #endif /* SYSV IPC */
 
 /*
-=for apidoc_section Input/Output
-
 =for apidoc start_glob
 
 Function called by C<do_readline> to spawn a glob (or do the glob inside

diff --git a/gv.h b/gv.h
index ddc48b9..6ac9981 100644 (file)
--- a/gv.h
+++ b/gv.h
@@ -72,8 +72,6 @@ struct gp {
 #define GvNAMELEN(gv)  GvNAMELEN_get(gv)
 
 /*
-=for apidoc_section GV Handling
-
 =for apidoc Am|SV*|GvSV|GV* gv
 
 Return the SV from the GV.

diff --git a/hv.h b/hv.h
index ebb81d1..505c28e 100644 (file)
--- a/hv.h
+++ b/hv.h
@@ -140,8 +140,6 @@ struct xpvhv {
 };
 
 /*
-=for apidoc_section HV Handling
-
 =for apidoc AmnU||HEf_SVKEY
 This flag, used in the length slot of hash entries and magic structures,
 specifies the structure contains an C<SV*> pointer where a C<char*> pointer

diff --git a/locale.c b/locale.c
index fa2c68f..4654a5b 100644 (file)
--- a/locale.c
+++ b/locale.c
@@ -2280,9 +2280,6 @@ S_win32_setlocale(pTHX_ int category, const char* locale)
 #endif
 
 /*
-
-=for apidoc_section Locales
-
 =for apidoc Perl_setlocale
 
 This is an (almost) drop-in replacement for the system L<C<setlocale(3)>>,

diff --git a/malloc.c b/malloc.c
index f69d450..01e84bf 100644 (file)
--- a/malloc.c
+++ b/malloc.c
@@ -1225,7 +1225,6 @@ S_adjust_size_and_find_bucket(size_t *nbytes_p)
 /*
 These have the same interfaces as the C lib ones, so are considered documented
 
-=for apidoc_section Memory Management
 =for apidoc malloc
 =for apidoc calloc
 =for apidoc realloc

diff --git a/numeric.c b/numeric.c
index 154830b..52c4547 100644 (file)
--- a/numeric.c
+++ b/numeric.c
@@ -16,9 +16,6 @@
  */
 
 /*
-=for apidoc_section Numeric Functions
-
-=cut
 
 This file contains all the stuff needed by perl for manipulating numeric
 values, including such things as replacements for the OS's atof() function

diff --git a/op.h b/op.h
index b97f9c7..9750717 100644 (file)
--- a/op.h
+++ b/op.h
@@ -1059,10 +1059,6 @@ C<sib> is non-null. For a higher-level interface, see C<L</op_sibling_splice>>.
 #define newATTRSUB(f, o, p, a, b) Perl_newATTRSUB_x(aTHX_  f, o, p, a, b, FALSE)
 #define newSUB(f, o, p, b)     newATTRSUB((f), (o), (p), NULL, (b))
 
-/*
-=for apidoc_section Hook manipulation
-*/
-
 #ifdef USE_ITHREADS
 #  define OP_CHECK_MUTEX_INIT          MUTEX_INIT(&PL_check_mutex)
 #  define OP_CHECK_MUTEX_LOCK          MUTEX_LOCK(&PL_check_mutex)

diff --git a/pad.h b/pad.h
index 64b7810..6636ca7 100644 (file)
--- a/pad.h
+++ b/pad.h
@@ -11,11 +11,6 @@
  * variables, op targets and constants.
  */
 
-/*
-=for apidoc_section Pad Data Structures
-*/
-
-
 /* offsets within a pad */
 
 typedef SSize_t PADOFFSET; /* signed so that -1 is a valid value */

diff --git a/patchlevel.h b/patchlevel.h
index 6e4bd14..69b9ef5 100644 (file)
--- a/patchlevel.h
+++ b/patchlevel.h
@@ -9,8 +9,6 @@
  */
 
 /*
-=for apidoc_section Versioning
-
 =for apidoc AmDnU|U8|PERL_REVISION
 The major number component of the perl interpreter currently being compiled or
 executing.  This has been C<5> from 1993 into 2020.

diff --git a/perlio.h b/perlio.h
index c0bd7ea..ee16ab8 100644 (file)
--- a/perlio.h
+++ b/perlio.h
@@ -63,10 +63,6 @@ typedef PerlIOl *PerlIO;
 #define PerlIO PerlIO
 #define PERLIO_LAYERS 1
 
-/*
-=for apidoc_section Input/Output
-=cut
-*/
 /* PERLIO_FUNCS_CONST is now on by default for efficiency, PERLIO_FUNCS_CONST
    can be removed 1 day once stable & then PerlIO vtables are permanently RO */
 #ifdef PERLIO_FUNCS_CONST

diff --git a/pod/perlapio.pod b/pod/perlapio.pod
index 66add53..fb9b8c2 100644 (file)
--- a/pod/perlapio.pod
+++ b/pod/perlapio.pod
@@ -68,7 +68,7 @@ perlapio - perl's IO abstraction interface.
                                                     const char *layers);
   void    PerlIO_debug(const char *fmt,...);
 
-=for apidoc_section Input/Output
+=for apidoc_section $io
 
 =for apidoc Amh|int     |PerlIO_apply_layers|PerlIO *f|const char *mode|const char *layers
 =for apidoc Amh|int     |PerlIO_binmode|PerlIO *f|int ptype|int imode|const char *layers

diff --git a/pod/perlcall.pod b/pod/perlcall.pod
index e7c4a76..44203e5 100644 (file)
--- a/pod/perlcall.pod
+++ b/pod/perlcall.pod
@@ -121,8 +121,6 @@ been warned.
 
 =head1 FLAG VALUES
 
-=for apidoc_section Callback Functions
-
 The C<flags> parameter in all the I<call_*> functions is one of C<G_VOID>,
 C<G_SCALAR>, or C<G_ARRAY>, which indicate the call context, OR'ed together
 with a bit mask of any combination of the other G_* symbols defined below.
@@ -1009,7 +1007,6 @@ equivalent of C<$@>.  We use a local temporary, C<err_tmp>, since
 C<ERRSV> is a macro that calls a function, and C<SvTRUE(ERRSV)> would
 end up calling that function multiple times.
 
-=for apidoc_section Callback Functions
 =for apidoc AmnUh|GV *|PL_errgv
 
 =item 3.

diff --git a/pod/perlfilter.pod b/pod/perlfilter.pod
index 959deef..c137266 100644 (file)
--- a/pod/perlfilter.pod
+++ b/pod/perlfilter.pod
@@ -294,7 +294,6 @@ becomes M.)
 
    1;
 
-=for apidoc_section Source Filters
 =for apidoc filter_add
 =for apidoc filter_read
 

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 2e816f3..2f6f801 100644 (file)
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -374,7 +374,6 @@ it is pushed above a layer which does not support the interface.
 (Perl's C<sv_gets()> does not expect the streams fast C<gets> behaviour
 to change during one "get".)
 
-=for apidoc_section Input/Output
 =for apidoc Amnh||PERLIO_F_APPEND
 =for apidoc_item || PERLIO_F_CANREAD
 =for apidoc_item ||PERLIO_F_CANWRITE

diff --git a/pod/perlmroapi.pod b/pod/perlmroapi.pod
index 3341064..e0a4f70 100644 (file)
--- a/pod/perlmroapi.pod
+++ b/pod/perlmroapi.pod
@@ -79,7 +79,6 @@ stash, and a pointer to your C<mro_alg> structure:
     meta = HvMROMETA(stash);
     private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);
 
-=for apidoc_section MRO
 =for apidoc mro_get_private_data
 =for apidoc Amh|SV*|MRO_GET_PRIVATE_DATA|struct mro_meta *const smeta|const struct mro_alg *const which
 

diff --git a/pod/perlreguts.pod b/pod/perlreguts.pod
index a5ff0b6..b0a8d8f 100644 (file)
--- a/pod/perlreguts.pod
+++ b/pod/perlreguts.pod
@@ -696,7 +696,6 @@ about what state it stores, with the result that two consecutive lines in the
 code can actually be running in totally different contexts due to the
 simulated recursion.
 
-=for apidoc_section REGEXP Functions
 =for apidoc pregcomp
 =for apidoc pregexec
 

diff --git a/pp_pack.c b/pp_pack.c
index 195c7ea..f06e8cb 100644 (file)
--- a/pp_pack.c
+++ b/pp_pack.c
@@ -804,8 +804,6 @@ first_symbol(const char *pat, const char *patend) {
 
 /*
 
-=for apidoc_section Pack and Unpack
-
 =for apidoc unpackstring
 
 The engine implementing the C<unpack()> Perl function.

diff --git a/pp_sort.c b/pp_sort.c
index 94c6a02..253c297 100644 (file)
--- a/pp_sort.c
+++ b/pp_sort.c
@@ -541,8 +541,6 @@ S_sortsv_flags_impl(pTHX_ gptr *base, size_t nmemb, SVCOMPARE_t cmp, U32 flags)
 }
 
 /*
-=for apidoc_section SV Handling
-
 =for apidoc sortsv_flags
 
 In-place sort an array of SV pointers with the given comparison routine,

diff --git a/regcomp.c b/regcomp.c
index d58f16f..308d5de 100644 (file)
--- a/regcomp.c
+++ b/regcomp.c
@@ -21853,7 +21853,6 @@ Perl_regfree_internal(pTHX_ REGEXP * const rx)
 #define SAVEPVN(p, n)  ((p) ? savepvn(p, n) : NULL)
 
 /*
-=for apidoc_section REGEXP Functions
 =for apidoc re_dup_guts
 Duplicate a regexp.
 

diff --git a/regexp.h b/regexp.h
index ac936d4..d9f1a40 100644 (file)
--- a/regexp.h
+++ b/regexp.h
@@ -252,8 +252,6 @@ typedef struct regexp_engine {
 #  define RXapif_REGNAMES_COUNT  0x1000
 
 /*
-=for apidoc_section REGEXP Functions
-
 =for apidoc Am|REGEXP *|SvRX|SV *sv
 
 Convenience macro to get the REGEXP from a SV.  This is approximately

diff --git a/t/porting/customized.dat b/t/porting/customized.dat
index 1eaf709..08acf8a 100644 (file)
--- a/t/porting/customized.dat
+++ b/t/porting/customized.dat
@@ -4,7 +4,7 @@
 Config::Perl::V cpan/Config-Perl-V/V.pm 0a0f7207e6505b78ee345a933acb0246a13579f5
 ExtUtils::Constant cpan/ExtUtils-Constant/t/Constant.t d5c75c41d6736a0c5897130f534af0896a7d6f4d
 ExtUtils::PL2Bat cpan/ExtUtils-PL2Bat/t/make_executable.t 2f58339b567d943712488812f06d99f907af46ab
-Filter::Util::Call pod/perlfilter.pod 9b4aec0d8518274ddb0dd37e3b770fe13a44dd1f
+Filter::Util::Call pod/perlfilter.pod 2d98239c4f4a930ad165444c3879629bb91f4cef
 Locale::Maketext::Simple cpan/Locale-Maketext-Simple/lib/Locale/Maketext/Simple.pm 57ed38905791a17c150210cd6f42ead22a7707b6
 Math::Complex cpan/Math-Complex/lib/Math/Complex.pm 66f28a17647e2de166909ca66e4ced26f8a0a62e
 Math::Complex cpan/Math-Complex/t/Complex.t 17039e03ee798539e770ea9a0d19a99364278306

diff --git a/utf8.c b/utf8.c
index be615e1..e9f229b 100644 (file)
--- a/utf8.c
+++ b/utf8.c
@@ -38,14 +38,11 @@ static const char unees[] =
                         "Malformed UTF-8 character (unexpected end of string)";
 
 /*
-=head1 Unicode Support
 These are various utility functions for manipulating UTF8-encoded
 strings.  For the uninitiated, this is a method of representing arbitrary
 Unicode characters as a variable number of bytes, in such a way that
 characters in the ASCII range are unmodified, and a zero byte never appears
 within non-zero characters.
-
-=cut
 */
 
 /* helper for Perl__force_out_malformed_utf8_message(). Like

diff --git a/utf8.h b/utf8.h
index 59d7df3..e254b8b 100644 (file)
--- a/utf8.h
+++ b/utf8.h
@@ -35,14 +35,6 @@
 #define FOLD_FLAGS_NOMIX_ASCII  0x4
 
 /*
-=head1 Unicode Support
-L<perlguts/Unicode Support> has an introduction to this API.
-
-See also L</Character classification>,
-and L</Character case changing>.
-Various functions outside this section also work specially with Unicode.
-Search for the string "utf8" in this document.
-
 =for apidoc is_ascii_string
 
 This is a misleadingly-named synonym for L</is_utf8_invariant_string>.