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.

27 files changed, 62 insertions, 70 deletions

diff --git a/autodoc.pl b/autodoc.pl
index d52438926f..1c0a77226b 100644
--- 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 b0a4d8d1cb..ed67df19de 100644
--- 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 8466dc17f4..6903db6dbf 100644
--- 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 b627fe88e5..5a3a25f8b9 100644
--- 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 b4103e15b2..2bffeea079 100644
--- 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 ddc48b9c37..6ac99814f6 100644
--- 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 ebb81d1af0..505c28e6f3 100644
--- 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 fa2c68f288..4654a5beaf 100644
--- 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 f69d45028f..01e84bfc19 100644
--- 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 154830b13a..52c454711f 100644
--- 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 b97f9c7efd..9750717562 100644
--- 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 64b7810fbb..6636ca79a0 100644
--- 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 6e4bd145de..69b9ef5364 100644
--- 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 c0bd7ea645..ee16ab8774 100644
--- 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 66add53e4d..fb9b8c261d 100644
--- 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 e7c4a76681..44203e5fa8 100644
--- 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 959deefef1..c137266292 100644
--- 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 2e816f36a5..2f6f801d9f 100644
--- 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 3341064b7e..e0a4f704dc 100644
--- 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 a5ff0b6bce..b0a8d8f922 100644
--- 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 195c7eaf77..f06e8cba1c 100644
--- 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 94c6a02e85..253c2977d0 100644
--- 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 d58f16f1c2..308d5def3c 100644
--- 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 ac936d4d55..d9f1a40909 100644
--- 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 1eaf7099a9..08acf8ae2c 100644
--- 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 be615e13f3..e9f229b83c 100644
--- 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 59d7df3b01..e254b8b053 100644
--- 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>.