autodoc.pl: Enhance apidoc_section feature

This feature allows documentation destined for perlapi or perlintern to
be split into sections of related functions, no matter where the
documentation source is.  Prior to this commit the line had to contain
the exact text of the title of the section.  Now it can be a $variable
name that autodoc.pl expands to the title. It still has to be an exact
match for the variable in autodoc, but now, the expanded text can be
changed in autodoc alone, without other files needing to be updated at
the same time.

27 files changed, 152 insertions, 141 deletions

diff --git a/XSUB.h b/XSUB.h
index 82b0f8d1e5..616d813840 100644
--- a/XSUB.h
+++ b/XSUB.h
@@ -14,7 +14,7 @@
 /* first, some documentation for xsubpp-generated items */
 
 /*
-=for apidoc_section XS
+=for apidoc_section $XS
 
 F<xsubpp> compiles XS code into C.  See L<perlutil/xsubpp>.
 
@@ -215,7 +215,7 @@ is a lexical C<$_> in scope.
 /* Typically used to return values from XS functions.       */
 
 /*
-=for apidoc_section Stack Manipulation Macros
+=for apidoc_section $stack
 
 =for apidoc Am|void|XST_mIV|int pos|IV iv
 Place an integer into the specified position C<pos> on the stack.  The
@@ -291,7 +291,7 @@ C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
 Macro to verify that the perl api version an XS module has been compiled against
 matches the api version of the perl interpreter it's being loaded into.
 
-=for apidoc_section Exception Handling (simple) Macros
+=for apidoc_section $exceptions
 
 =for apidoc Amns||dXCPT
 Set up necessary local variables for exception handling.
diff --git a/autodoc.pl b/autodoc.pl
index 0e13945483..31f98bd9af 100644
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -24,15 +24,21 @@ use Text::Tabs;
 # Throughout the files read by this script are lines like
 #
 # =for apidoc_section Section Name
+# =for apidoc_section $section_name_variable
 #
 # "Section Name" (after having been stripped of leading space) must be one of
-# the legal section names, or an error is thrown.  All API elements defined
-# between this line and the next 'apidoc_section' line will go into the
-# section "Section Name", sorted by dictionary order within it.  perlintern
-# and perlapi are parallel documents, each potentially with a section "Section
-# Name".  Each element is marked as to which document it goes into.  If there
-# are none for a particular section in perlapi, that section is
-# omitted.
+# the legal section names, or an error is thrown.  $section_name_variable must
+# be one of the legal section name variables defined below; these expand to
+# legal section names.  This form is used so that minor wording changes in
+# these titles can be confied to this file.  All the names of the variables
+# end in '_scn'; this suffix is optional in the apidoc_section lines.
+#
+# All API elements defined between this line and the next 'apidoc_section'
+# line will go into the section "Section Name" (or $section_name_variable),
+# sorted by dictionary order within it.  perlintern and perlapi are parallel
+# documents, each potentially with a section "Section Name".  Each element is
+# marked as to which document it goes into.  If there are none for a
+# particular section in perlapi, that section is omitted.
 #
 # Also, in .[ch] files, there may be
 #
@@ -44,7 +50,7 @@ use Text::Tabs;
 # are used as a heading for section "Section Name" (in both perlintern and
 # perlapi).  This includes any =head[2-5].  If more than one '=head1 Section
 # Name' line has content, they appear in the generated pod in an undefined
-# order.
+# order.  Note that you can't use a $section_name_variable in =head1 lines
 #
 # The next =head1, =for apidoc_section, or file end terminates what goes into
 # the current section
@@ -407,6 +413,11 @@ sub autodoc ($$) { # parse a file and extract documentation info
         if ($in=~ /^ = (?: for [ ]+ apidoc_section | head1 ) [ ]+ (.*) /x) {
 
             $section = $1;
+            if ($section =~ / ^ \$ /x) {
+                $section .= '_scn' unless $section =~ / _scn $ /;
+                $section = eval "$section";
+                die "Unknown \$section variable '$section' in $file: $@" if $@;
+            }
             die "Unknown section name '$section' in $file near line $.\n"
                                     unless defined $valid_sections{$section};
 
diff --git a/cop.h b/cop.h
index c811eb0ec4..b675370d54 100644
--- a/cop.h
+++ b/cop.h
@@ -166,7 +166,7 @@ typedef struct jmpenv JMPENV;
     } STMT_END
 
 /*
-=for apidoc_section COP Hint Hashes
+=for apidoc_section $COP
 */
 
 typedef struct refcounted_he COPHH;
@@ -1083,7 +1083,7 @@ typedef struct stackinfo PERL_SI;
     } STMT_END
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 =for apidoc Amn|bool|IN_PERL_COMPILETIME
 Returns 1 if this macro is being called during the compilation phase of the
 program; otherwise 0;
@@ -1098,7 +1098,7 @@ program; otherwise 0;
 #define IN_PERL_RUNTIME         cBOOL(PL_curcop != &PL_compiling)
 
 /*
-=for apidoc_section Multicall Functions
+=for apidoc_section $multicall
 
 =for apidoc Amns||dMULTICALL
 Declare local variables for a multicall.  See L<perlcall/LIGHTWEIGHT CALLBACKS>.
diff --git a/handy.h b/handy.h
index 8704c773de..62fc08c1cd 100644
--- a/handy.h
+++ b/handy.h
@@ -18,12 +18,12 @@
 #  define Null(type) ((type)NULL)
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc AmnU||Nullch
 Null character pointer.  (No longer available when C<PERL_CORE> is
 defined.)
 
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc AmnU||Nullsv
 Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
 
@@ -32,21 +32,21 @@ Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
 Below are signatures of functions from config.h which can't easily be gleaned
 from it, and are very unlikely to change
 
-=for apidoc_section Signals
+=for apidoc_section $signals
 =for apidoc Am|int|Sigsetjmp|jmp_buf env|int savesigs
 =for apidoc Am|void|Siglongjmp|jmp_buf env|int val
 
-=for apidoc_section Filesystem configuration values
+=for apidoc_section $filesystem
 =for apidoc Am|void *|FILE_ptr|FILE * f
 =for apidoc Am|Size_t|FILE_cnt|FILE * f
 =for apidoc Am|void *|FILE_base|FILE * f
 =for apidoc Am|Size_t|FILE_bufsiz|FILE *f
 
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc Amu|token|CAT2|token x|token y
 =for apidoc Amu|string|STRINGIFY|token x
 
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 =for apidoc Am|double|Drand01
 =for apidoc Am|void|seedDrand01|Rand_seed_t x
 =for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b
@@ -69,7 +69,7 @@ from it, and are very unlikely to change
 #define FALSE (0)
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc Am|void *|MUTABLE_PTR|void * p
 =for apidoc_item |AV *|MUTABLE_AV|AV * p
 =for apidoc_item |CV *|MUTABLE_CV|CV * p
@@ -138,7 +138,7 @@ already-built-in ones return pointers to what their names indicate.
 #endif
 
 /*
-=for apidoc_section Casting
+=for apidoc_section $casting
 =for apidoc Am|bool|cBOOL|bool expr
 
 Cast-to-bool.  A simple S<C<(bool) I<expr>>> cast may not do the right thing:
@@ -320,7 +320,7 @@ typedef U64TYPE U64;
 #define nBIT_UMAX(n)  nBIT_MASK(n)
 
 /*
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 =for apidoc Am||__ASSERT_|bool expr
 
 This is a helper macro to avoid preprocessor issues, replaced by nothing
@@ -342,7 +342,7 @@ detects that and gets all excited. */
 #endif
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc Ama|SV*|newSVpvs|"literal string"
 Like C<newSVpvn>, but takes a literal string instead of a
@@ -384,7 +384,7 @@ string/length pair.
 Like C<sv_setref_pvn>, but takes a literal string instead of
 a string/length pair.
 
-=for apidoc_section String Handling
+=for apidoc_section $string
 
 =for apidoc Ama|char*|savepvs|"literal string"
 Like C<savepvn>, but takes a literal string instead of a
@@ -394,13 +394,13 @@ string/length pair.
 A version of C<savepvs()> which allocates the duplicate string in memory
 which is shared between threads.
 
-=for apidoc_section GV Handling
+=for apidoc_section $GV
 
 =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
 Like C<gv_stashpvn>, but takes a literal string instead of a
 string/length pair.
 
-=for apidoc_section HV Handling
+=for apidoc_section $HV
 
 =for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval
 Like C<hv_fetch>, but takes a literal string instead of a
@@ -411,7 +411,7 @@ Like C<hv_store>, but takes a literal string instead of a
 string/length pair
 and omits the hash parameter.
 
-=for apidoc_section Lexer interface
+=for apidoc_section $lexer
 
 =for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags
 
@@ -422,7 +422,7 @@ a string/length pair.
 */
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 
 =for apidoc Amu|pair|STR_WITH_LEN|"literal string"
 
@@ -497,7 +497,7 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used.
                                                         PERL_VERSION_PATCH)
 
 /*
-=for apidoc_section Versioning
+=for apidoc_section $versioning
 =for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch
 =for apidoc_item PERL_VERSION_NE
 =for apidoc_item PERL_VERSION_LT
@@ -567,7 +567,7 @@ becomes
 # define PERL_VERSION_GT(j,n,p) (! PERL_VERSION_LE(j,n,p))
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 
 =for apidoc Am|bool|strNE|char* s1|char* s2
 Test two C<NUL>-terminated strings to see if they are different.  Returns true
@@ -1135,7 +1135,7 @@ difference is that this returns true only if the input character also matches
 L</isWORDCHAR>.  See the L<top of this section|/Character classification> for
 an explanation of the variants.
 
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 
 =for apidoc Am|U8|READ_XDIGIT|char str*
 Returns the value of an ASCII-range hex digit and advances the string pointer.
@@ -1336,7 +1336,7 @@ patched there.  The file as of this writing is cpan/Devel-PPPort/parts/inc/misc
 
 /*
    void below because that's the best fit, and works for Devel::PPPort
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 =for apidoc AyT||WIDEST_UTYPE
 
 Yields the widest unsigned integer type on the platform, currently either
@@ -2441,7 +2441,7 @@ typedef U32 line_t;
 #define isALPHA_FOLD_NE(c1, c2) (! isALPHA_FOLD_EQ((c1), (c2)))
 
 /*
-=for apidoc_section Memory Management
+=for apidoc_section $memory
 
 =for apidoc Am|void|Newx|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<malloc> function.
@@ -2482,7 +2482,7 @@ The XSUB-writer's interface to the C C<free> function.
 
 This should B<ONLY> be used on memory obtained using L</"Newx"> and friends.
 
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc Am|void|Move|void* src|void* dest|int nitems|type
 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
 source, C<dest> is the destination, C<nitems> is the number of items, and
@@ -2515,7 +2515,7 @@ Like C<Zero> but returns dest.  Useful
 for encouraging compilers to tail-call
 optimise.
 
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 =for apidoc Amu|void|StructCopy|type *src|type *dest|type
 This is an architecture-independent macro to copy one structure to another.
 
@@ -2730,7 +2730,7 @@ void Perl_mem_log_del_sv(const SV *sv, const char *filename, const int linenumbe
 #define StructCopy(s,d,t) (*((t*)(d)) = *((t*)(s)))
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 
 =for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a
 
diff --git a/hv.c b/hv.c
index f4c819cb80..43b9330260 100644
--- a/hv.c
+++ b/hv.c
@@ -3731,7 +3731,7 @@ Perl_refcounted_he_inc(pTHX_ struct refcounted_he *he)
 }
 
 /*
-=for apidoc_section COP Hint Hashes
+=for apidoc_section $COP
 =for apidoc cop_fetch_label
 
 Returns the label attached to a cop, and stores its length in bytes into
@@ -3811,7 +3811,7 @@ Perl_cop_store_label(pTHX_ COP *const cop, const char *label, STRLEN len,
 }
 
 /*
-=for apidoc_section HV Handling
+=for apidoc_section $HV
 =for apidoc hv_assert
 
 Check that a hash is in an internally consistent state.
diff --git a/inline.h b/inline.h
index 65f84212f2..96f706ed8b 100644
--- a/inline.h
+++ b/inline.h
@@ -40,7 +40,7 @@ SOFTWARE.
 /* ------------------------------- av.h ------------------------------- */
 
 /*
-=for apidoc_section AV Handling
+=for apidoc_section $AV
 =for apidoc av_count
 Returns the number of elements in the array C<av>.  This is the true length of
 the array, including any undefined elements.  It is always the same as
@@ -60,7 +60,7 @@ Perl_av_count(pTHX_ AV *av)
 /* ------------------------------- cv.h ------------------------------- */
 
 /*
-=for apidoc_section CV Handling
+=for apidoc_section $CV
 =for apidoc CvGV
 Returns the GV associated with the CV C<sv>, reifying it if necessary.
 
@@ -311,7 +311,7 @@ S_sv_or_pv_pos_u2b(pTHX_ SV *sv, const char *pv, STRLEN pos, STRLEN *lenp)
 /* ------------------------------- utf8.h ------------------------------- */
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section $unicode
 */
 
 PERL_STATIC_INLINE void
@@ -1884,7 +1884,7 @@ Perl_utf8_to_uvchr_buf_helper(pTHX_ const U8 *s, const U8 *send, STRLEN *retlen)
 /* ------------------------------- perl.h ----------------------------- */
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 
 =for apidoc is_safe_syscall
 
@@ -2457,7 +2457,7 @@ Perl_cx_popgiven(pTHX_ PERL_CONTEXT *cx)
 /* ------------------ util.h ------------------------------------------- */
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 
 =for apidoc foldEQ
 
@@ -2513,7 +2513,7 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len)
 }
 
 /*
-=for apidoc_section Locales
+=for apidoc_section $locale
 =for apidoc foldEQ_locale
 
 Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the
@@ -2541,7 +2541,7 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len)
 }
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc my_strnlen
 
 The C library C<strnlen> if available, or a Perl implementation of it.
diff --git a/mathoms.c b/mathoms.c
index 19b0154b64..77ac0b69cb 100644
--- a/mathoms.c
+++ b/mathoms.c
@@ -85,7 +85,7 @@ Perl_ref(pTHX_ OP *o, I32 type)
 }
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc sv_unref
 
 Unsets the RV status of the SV, and decrements the reference count of
@@ -606,7 +606,7 @@ Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
 }
 
 /*
-=for apidoc_section GV Handling
+=for apidoc_section $GV
 =for apidoc gv_fetchmethod
 
 See L</gv_fetchmethod_autoload>.
@@ -704,7 +704,7 @@ Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep)
 }
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc sv_nolocking
 
 Dummy routine which "locks" an SV when there is no locking module present.
@@ -822,7 +822,7 @@ Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len)
 }
 
 /*
-=for apidoc_section Pack and Unpack
+=for apidoc_section $pack
 =for apidoc unpack_str
 
 The engine implementing C<unpack()> Perl function.  Note: parameters C<strbeg>,
@@ -1119,7 +1119,7 @@ Perl_sv_2bool(pTHX_ SV *const sv)
 
 
 /*
-=for apidoc_section Custom Operators
+=for apidoc_section $custom
 =for apidoc custom_op_name
 Return the name for a given custom op.  This was once used by the C<OP_NAME>
 macro, but is no longer: it has only been kept for compatibility, and
@@ -1182,7 +1182,7 @@ ASCII_TO_NEED(const UV enc, const UV ch)
 }
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section $unicode
 =for apidoc is_utf8_char
 
 Tests if some arbitrary number of bytes begins in a valid UTF-8
diff --git a/mg.c b/mg.c
index 32d7732bc6..8b90aa4e3f 100644
--- a/mg.c
+++ b/mg.c
@@ -842,7 +842,7 @@ S_fixup_errno_string(pTHX_ SV* sv)
 }
 
 /*
-=for apidoc_section Errno
+=for apidoc_section $errno
 =for apidoc sv_string_from_errnum
 
 Generates the message string describing an OS error and returns it as
@@ -1906,7 +1906,7 @@ Perl_magic_setnkeys(pTHX_ SV *sv, MAGIC *mg)
 }
 
 /*
-=for apidoc_section Magic
+=for apidoc_section $magic
 =for apidoc magic_methcall
 
 Invoke a magic method (like FETCH).
@@ -3353,7 +3353,7 @@ Perl_magic_set(pTHX_ SV *sv, MAGIC *mg)
 }
 
 /*
-=for apidoc_section Signals
+=for apidoc_section $signals
 =for apidoc whichsig
 =for apidoc_item whichsig_pv
 =for apidoc_item whichsig_pvn
@@ -3713,7 +3713,7 @@ S_unwind_handler_stack(pTHX_ const void *p)
 }
 
 /*
-=for apidoc_section Magic
+=for apidoc_section $magic
 =for apidoc magic_sethint
 
 Triggered by a store to C<%^H>, records the key/value pair to
diff --git a/op.c b/op.c
index 2933e2ed7d..bf3c84ea2c 100644
--- a/op.c
+++ b/op.c
@@ -789,7 +789,7 @@ Perl_allocmy(pTHX_ const char *const name, const STRLEN len, const U32 flags)
 }
 
 /*
-=for apidoc_section Optree Manipulation Functions
+=for apidoc_section $optree_manipulation
 
 =for apidoc alloccopstash
 
@@ -5789,7 +5789,7 @@ Perl_block_end(pTHX_ I32 floor, OP *seq)
 }
 
 /*
-=for apidoc_section Compile-time scope hooks
+=for apidoc_section $scope
 
 =for apidoc blockhook_register
 
@@ -6336,7 +6336,7 @@ S_gen_constant_list(pTHX_ OP *o)
 }
 
 /*
-=for apidoc_section Optree Manipulation Functions
+=for apidoc_section $optree_manipulation
 */
 
 /* List constructors */
@@ -6508,7 +6508,7 @@ Perl_op_convert_list(pTHX_ I32 type, I32 flags, OP *o)
 
 
 /*
-=for apidoc_section Optree construction
+=for apidoc_section $optree_construction
 
 =for apidoc newNULLLIST
 
@@ -8877,7 +8877,7 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg)
 }
 
 /*
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =for apidoc load_module
 
@@ -9025,7 +9025,7 @@ Perl_dofile(pTHX_ OP *term, I32 force_builtin)
 }
 
 /*
-=for apidoc_section Optree construction
+=for apidoc_section $optree_construction
 
 =for apidoc newSLICEOP
 
@@ -10613,7 +10613,7 @@ static void const_av_xsub(pTHX_ CV* cv);
 
 /*
 
-=for apidoc_section Optree Manipulation Functions
+=for apidoc_section $optree_manipulation
 
 =for apidoc cv_const_sv
 
@@ -17996,7 +17996,7 @@ Perl_peep(pTHX_ OP *o)
 }
 
 /*
-=for apidoc_section Custom Operators
+=for apidoc_section $custom
 
 =for apidoc Perl_custom_op_xop
 Return the XOP structure for a given custom op.  This macro should be
@@ -18398,7 +18398,7 @@ Perl_report_redefined_cv(pTHX_ const SV *name, const CV *old_cv,
 }
 
 /*
-=for apidoc_section Hook manipulation
+=for apidoc_section $hook
 
 These functions provide convenient and thread-safe means of manipulating
 hook variables.
diff --git a/op.h b/op.h
index 2279edbb97..b97f9c7efd 100644
--- a/op.h
+++ b/op.h
@@ -70,7 +70,7 @@ typedef PERL_BITFIELD16 Optype;
 #define OP_GIMME_REVERSE(flags)	((flags) & G_WANT)
 
 /*
-=for apidoc_section Callback Functions
+=for apidoc_section $callback
 
 =for apidoc Amn|U32|GIMME_V
 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
@@ -639,7 +639,7 @@ typedef struct {
 
 
 /*
-=for apidoc_section Optree Manipulation Functions
+=for apidoc_section $optree_manipulation
 
 =for apidoc Am|OP*|LINKLIST|OP *o
 Given the root of an optree, link the tree in execution order using the
@@ -751,7 +751,7 @@ struct block_hooks {
 };
 
 /*
-=for apidoc_section Compile-time scope hooks
+=for apidoc_section $scope
 
 =for apidoc mx|U32|BhkFLAGS|BHK *hk
 Return the BHK's flags.
@@ -849,7 +849,7 @@ preprocessing token; the type of C<arg> depends on C<which>.
 #define OP_LVALUE_NO_CROAK 1
 
 /*
-=for apidoc_section Custom Operators
+=for apidoc_section $custom
 
 =for apidoc Am|U32|XopFLAGS|XOP *xop
 Return the XOP's flags.
@@ -945,7 +945,7 @@ typedef enum {
     (Perl_custom_op_get_field(x, XOPe_xop_ptr).xop_ptr)
 
 /*
-=for apidoc_section Optree Manipulation Functions
+=for apidoc_section $optree_manipulation
 
 =for apidoc Am|const char *|OP_NAME|OP *o
 Return the name of the provided OP.  For core ops this looks up the name
diff --git a/pad.c b/pad.c
index 7e681386f6..9283e43867 100644
--- a/pad.c
+++ b/pad.c
@@ -19,7 +19,7 @@
  */
 
 /*
-=for apidoc_section Pad Data Structures
+=for apidoc_section $pad
 
 =for apidoc Amx|PADLIST *|CvPADLIST|CV *cv
 
@@ -272,7 +272,7 @@ Perl_pad_new(pTHX_ int flags)
 
 
 /*
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =for apidoc cv_undef
 
diff --git a/perl.c b/perl.c
index 992cbc30a4..488cebcb5b 100644
--- a/perl.c
+++ b/perl.c
@@ -177,7 +177,7 @@ perl_alloc_using(struct IPerlMem* ipM, struct IPerlMem* ipMS,
 #else
 
 /*
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =for apidoc perl_alloc
 
@@ -2746,7 +2746,7 @@ S_run_body(pTHX_ I32 oldscope)
 }
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc get_sv
 
@@ -2772,7 +2772,7 @@ Perl_get_sv(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=for apidoc_section AV Handling
+=for apidoc_section $AV
 
 =for apidoc get_av
 
@@ -2802,7 +2802,7 @@ Perl_get_av(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=for apidoc_section HV Handling
+=for apidoc_section $HV
 
 =for apidoc get_hv
 
@@ -2829,7 +2829,7 @@ Perl_get_hv(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=for apidoc_section CV Handling
+=for apidoc_section $CV
 
 =for apidoc get_cvn_flags
 
@@ -2881,7 +2881,7 @@ Perl_get_cv(pTHX_ const char *name, I32 flags)
 
 /*
 
-=for apidoc_section Callback Functions
+=for apidoc_section $callback
 
 =for apidoc call_argv
 
@@ -3275,7 +3275,7 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
 /* Require a module. */
 
 /*
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =for apidoc require_pv
 
diff --git a/perl.h b/perl.h
index 3cabb15c6a..72f1b2e29e 100644
--- a/perl.h
+++ b/perl.h
@@ -84,7 +84,7 @@
 /* <--- here ends the logic shared by perl.h and makedef.pl */
 
 /*
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 =for apidoc AmnUu|void|EXTERN_C
 When not compiling using C++, expands to nothing.
 Otherwise is used in a declaration of a function to indicate the function
@@ -183,7 +183,7 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>.
  *
  * The only one Devel::PPPort handles is this; list it as deprecated
 
-=for apidoc_section Concurrency
+=for apidoc_section $concurrency
 =for apidoc AmD|void|CPERLscope|void x
 Now a no-op.
 
@@ -406,7 +406,7 @@ Now a no-op.
  * cpp macros like PERL_UNUSED_DECL cannot work for this purpose, even
  * if it were PERL_UNUSED_DECL(x), which it cannot be (see above).
 
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 =for apidoc AmnU||PERL_UNUSED_DECL
 Tells the compiler that the parameter in the function prototype just before it
 is not necessarily expected to be used in the function.  Not that many
@@ -631,7 +631,7 @@ code.
 #endif
 
 /*
-=for apidoc_section Concurrency
+=for apidoc_section $concurrency
 =for apidoc AmnU||dVAR
 This is now a synonym for dNOOP: declare nothing
 
@@ -679,7 +679,7 @@ This is now a synonym for dNOOP: declare nothing
 #endif
 
 /*
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 =for apidoc AmnUu|void|STMT_START
 =for apidoc_item ||STMT_END
 
@@ -1068,7 +1068,7 @@ EXTERN_C int usleep(unsigned int);
 /* Macros for correct constant construction.  These are in C99 <stdint.h>
  * (so they will not be available in strict C89 mode), but they are nice, so
  * let's define them if necessary.
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 =for apidoc    Am|I16|INT16_C|number
 =for apidoc_item |I32|INT32_C|number
 =for apidoc_item |I64|INT64_C|number
@@ -1158,7 +1158,7 @@ Use C<L</UINTMAX_C>> to get the largest type available on the platform.
 #  endif
 
 /*
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 =for apidoc Am||INTMAX_C|number
 Returns a token the C compiler recognizes for the constant C<number> of the
 widest integer type on the machine.  For example, if the machine has C<long
@@ -1495,7 +1495,7 @@ EXTERN_C char *crypt(const char *, const char *);
 #endif
 
 /*
-=for apidoc_section Errno
+=for apidoc_section $errno
 
 =for apidoc m|void|SETERRNO|int errcode|int vmserrcode
 
@@ -1598,7 +1598,7 @@ was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>.
 #endif
 
 /*
-=for apidoc_section Warning and Dieing
+=for apidoc_section $warning
 
 =for apidoc Amn|SV *|ERRSV
 
@@ -1676,7 +1676,7 @@ any magic.
 #endif
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc Amn|SV *|DEFSV
 Returns the SV associated with C<$_>
 
@@ -1898,7 +1898,7 @@ Localize C<$_>.  See L<perlguts/Localizing changes>.
  * longer need that. XS modules can (and do) use this name, so it must remain
  * a part of the API that's visible to modules.
 
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc ATmD|int|my_sprintf|NN char *buffer|NN const char *pat|...
 
 Do NOT use this due to the possibility of overflowing C<buffer>.  Instead use
@@ -2722,7 +2722,7 @@ extern long double Perl_my_frexpl(long double x, int *e);
 #endif
 
 /*
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 
 =for apidoc AmnU||PERL_INT_MAX
 =for apidoc_item ||PERL_INT_MIN
@@ -3142,7 +3142,7 @@ typedef struct padname PADNAME;
 #endif
 
 /*
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv
 Provides system-specific tune up of the C runtime environment necessary to
@@ -3739,7 +3739,7 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex)
 #endif
 
 /*
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 
 =for apidoc Am||LIKELY|bool expr
 
@@ -4190,7 +4190,7 @@ my_swap16(const U16 x) {
    out of range floating point values to integers *is* undefined behaviour,
    and it is starting to bite.
 
-=for apidoc_section Casting
+=for apidoc_section $casting
 =for apidoc Am|I32|I_32|NV what
 Cast an NV to I32 while avoiding undefined C behavior
 
@@ -4230,7 +4230,7 @@ Cast an NV to UV while avoiding undefined C behavior
 #define U_L(what) U_32(what)
 
 /*
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 =for apidoc Amn|IV|IV_MAX
 The largest signed integer that fits in an IV on this platform.
 
@@ -4864,7 +4864,7 @@ EXTCONST char PL_Zero[]
   INIT("0");
 
 /*
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 =for apidoc AmTuU|const char *|PL_hexdigit|U8 value
 
 This array, indexed by an integer, converts that value into the character that
@@ -6342,7 +6342,7 @@ typedef struct am_table_short AMTS;
                         cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL))
 
 /*
-=for apidoc_section Locales
+=for apidoc_section $locale
 
 =for apidoc Amn|bool|IN_LOCALE
 
@@ -6610,7 +6610,7 @@ the plain locale pragma without a parameter (S<C<use locale>>) is in effect.
  * operations used by Perl, namely the decimal point, and even the thousands
  * separator.)
 
-=for apidoc_section Locales
+=for apidoc_section $locale
 
 =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION
 
@@ -6903,7 +6903,7 @@ cannot have changed since the precalculation.
 
 /*
 
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 
 =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e
 
@@ -7231,7 +7231,7 @@ EXTERN_C int flock(int fd, int op);
 #define IS_NUMBER_TRAILING            0x40 /* number has trailing trash */
 
 /*
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 
 =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send
 
@@ -7344,7 +7344,7 @@ extern void moncontrol(int);
 #endif
 
 /*
-=for apidoc_section Signals
+=for apidoc_section $signals
 =for apidoc Amn|U32|PERL_SIGNALS_UNSAFE_FLAG
 If this bit in C<PL_signals> is set, the system is uing the pre-Perl 5.8
 unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
@@ -7355,7 +7355,7 @@ unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
 #define PERL_SIGNALS_UNSAFE_FLAG	0x0001
 
 /*
-=for apidoc_section Numeric Functions
+=for apidoc_section $numeric
 
 =for apidoc Am|int|PERL_ABS|int
 
@@ -7387,7 +7387,7 @@ so no C<x++>.
 
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 
 =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 11e5e53990..06cc207496 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -21,11 +21,11 @@ Perl has three typedefs that handle Perl's three main data types:
 
 Each typedef has specific routines that manipulate the various data types.
 
-=for apidoc_section AV Handling
+=for apidoc_section $AV
 =for apidoc Ayh||AV
-=for apidoc_section HV Handling
+=for apidoc_section $HV
 =for apidoc Ayh||HV
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 =for apidoc Ayh||SV
 
 =head2 What is an "IV"?
@@ -55,7 +55,7 @@ may not be usable in all circumstances.
 A numeric constant can be specified with L<perlapi/C<INT16_C>>,
 L<perlapi/C<UINTMAX_C>>, and similar.
 
-=for apidoc_section Integer configuration values
+=for apidoc_section $integer
 =for apidoc Ayh||I8
 =for apidoc_item ||I16
 =for apidoc_item ||I32
@@ -590,7 +590,7 @@ is only valid for the duration of a single perl process.
 See L</Understanding the Magic of Tied Hashes and Arrays> for more
 information on how to use the hash access functions on tied hashes.
 
-=for apidoc_section HV Handling
+=for apidoc_section $HV
 =for apidoc Amh|void|PERL_HASH|U32 hash|char *key|STRLEN klen
 
 =head2 Hash API Extensions
@@ -1629,7 +1629,7 @@ Inside such a I<pseudo-block> the following service is available:
 These macros arrange things to restore the value of integer variable
 C<i> at the end of the enclosing I<pseudo-block>.
 
-=for apidoc_section Stack Manipulation Macros
+=for apidoc_section $stack
 =for apidoc Amh||SAVEINT|int i
 =for apidoc Amh||SAVEIV|IV i
 =for apidoc Amh||SAVEI32|I32 i
@@ -2493,7 +2493,7 @@ function used within the Perl guts:
 STATIC becomes "static" in C, and may be #define'd to nothing in some
 configurations in the future.
 
-=for apidoc_section Compiler directives
+=for apidoc_section $directives
 =for apidoc Ayh||STATIC
 
 A public function (i.e. part of the internal API, but not necessarily
@@ -2509,7 +2509,7 @@ The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
 or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and
 their variants.
 
-=for apidoc_section Concurrency
+=for apidoc_section $concurrency
 =for apidoc Amnh||aTHX
 =for apidoc Amnh||aTHX_
 =for apidoc Amnh||dTHX
@@ -2844,7 +2844,7 @@ UTF-8 in order to get good results and avoid Wide-character warnings.
 One way to do this for typical filehandles is to invoke perl with the
 C<-C>> parameter.  (See L<perlrun/-C [numberE<sol>list]>.
 
-=for apidoc_section Formats
+=for apidoc_section $formats
 =for apidoc Amnh||UTF8f
 =for apidoc Amh||UTF8fARG|bool is_utf8|Size_t byte_len|char *str
 
@@ -2879,7 +2879,7 @@ use the follow macros to do it right.
         PTR2NV(pointer)
         INT2PTR(pointertotype, integer)
 
-=for apidoc_section Casting
+=for apidoc_section $casting
 =for apidoc Amh|type|INT2PTR|type|int value
 =for apidoc Amh|UV|PTR2UV|void * ptr
 =for apidoc Amh|IV|PTR2IV|void * ptr
diff --git a/pp.h b/pp.h
index 884343ce29..cb50dbef03 100644
--- a/pp.h
+++ b/pp.h
@@ -11,7 +11,7 @@
 #define PP(s) OP * Perl_##s(pTHX)
 
 /*
-=for apidoc_section Stack Manipulation Macros
+=for apidoc_section $stack
 
 =for apidoc AmnU||SP
 Stack pointer.  This is usually handled by C<xsubpp>.  See C<L</dSP>> and
diff --git a/pp_ctl.c b/pp_ctl.c
index d05dec3f84..5cb5a10b20 100644
--- a/pp_ctl.c
+++ b/pp_ctl.c
@@ -1846,7 +1846,7 @@ PP(pp_xor)
 
 /*
 
-=for apidoc_section CV Handling
+=for apidoc_section $CV
 
 =for apidoc caller_cx
 
diff --git a/pp_sys.c b/pp_sys.c
index 0ab64e75d7..66c5d9aade 100644
--- a/pp_sys.c
+++ b/pp_sys.c
@@ -1293,7 +1293,7 @@ PP(pp_sselect)
 
 /*
 
-=for apidoc_section GV Handling
+=for apidoc_section $GV
 
 =for apidoc setdefout
 
diff --git a/regen/unicode_constants.pl b/regen/unicode_constants.pl
index 7851e87e22..aba447ae6a 100644
--- a/regen/unicode_constants.pl
+++ b/regen/unicode_constants.pl
@@ -29,7 +29,7 @@ print $out_fh <<END;
  *                with no additional suffix are both string constants */
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section \$unicode
 
 =for apidoc AmnU|const char *|BOM_UTF8
 
diff --git a/regexec.c b/regexec.c
index e546e40a2b..b80c0824eb 100644
--- a/regexec.c
+++ b/regexec.c
@@ -10913,7 +10913,7 @@ Perl_is_grapheme(pTHX_ const U8 * strbeg, const U8 * s, const U8 * strend, const
 }
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section $unicode
 
 =for apidoc isSCRIPT_RUN
 
diff --git a/scope.c b/scope.c
index d9b51f7826..cea1500e6a 100644
--- a/scope.c
+++ b/scope.c
@@ -316,7 +316,7 @@ Perl_save_set_svflags(pTHX_ SV* sv, U32 mask, U32 val)
 
 /*
 
-=for apidoc_section GV Handling
+=for apidoc_section $GV
 
 =for apidoc save_gp
 
diff --git a/scope.h b/scope.h
index 3912f2a96c..5b611c2cad 100644
--- a/scope.h
+++ b/scope.h
@@ -152,7 +152,7 @@
 
 
 /*
-=for apidoc_section Callback Functions
+=for apidoc_section $callback
 
 =for apidoc Amns||SAVETMPS
 Opening bracket for temporaries on a callback.  See C<L</FREETMPS>> and
diff --git a/sv.c b/sv.c
index 57fd65a5b8..0c4b456058 100644
--- a/sv.c
+++ b/sv.c
@@ -130,7 +130,7 @@ static const char S_destroy[] = "DESTROY";
 
 /* ============================================================================
 
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 An SV (or AV, HV, etc.) is allocated in two parts: the head (struct
 sv, av, hv...) contains type and reference count information, and for
 many types, a pointer to the body (struct xrv, xpv, xpviv...), which
@@ -408,7 +408,7 @@ S_del_sv(pTHX_ SV *p)
 
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc sv_add_arena
 
@@ -13454,7 +13454,7 @@ Perl_sv_vcatpvfn_flags(pTHX_ SV *const sv, const char *const pat, const STRLEN p
 
 /* =========================================================================
 
-=for apidoc_section Embedding and Interpreter Cloning
+=for apidoc_section $embedding
 
 =cut
 
@@ -16042,7 +16042,7 @@ Perl_init_constants(pTHX)
 }
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section $unicode
 
 =for apidoc sv_recode_to_utf8
 
@@ -16313,7 +16313,7 @@ Perl_varname(pTHX_ const GV *const gv, const char gvtype, PADOFFSET targ,
 
 
 /*
-=apidoc_section Warning and Dieing
+=apidoc_section $warning
 =for apidoc find_uninit_var
 
 Find the name of the undefined variable (if any) that caused the operator
diff --git a/sv.h b/sv.h
index b946568bbc..cc3be47ef3 100644
--- a/sv.h
+++ b/sv.h
@@ -13,7 +13,7 @@
 #endif
 
 /*
-=for apidoc_section SV Flags
+=for apidoc_section $SV_flags
 
 =for apidoc Ay||svtype
 An enum of flags for Perl types.  These are found in the file F<sv.h>
@@ -269,7 +269,7 @@ struct p5rx {
 #undef _SV_HEAD_UNION		/* ensure no pollution */
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc Am|U32|SvREFCNT|SV* sv
 Returns the value of the object's reference count. Exposed
@@ -2103,7 +2103,7 @@ incremented.
 /* the following macros update any magic values this C<sv> is associated with */
 
 /*
-=head1 Magic
+=for apidoc_section $magic
 
 =for apidoc Am|void|SvGETMAGIC|SV* sv
 Invokes C<L</mg_get>> on an SV if it has 'get' magic.  For example, this
@@ -2142,7 +2142,7 @@ has been loaded.
 Releases a mutual exclusion lock on C<sv> if a suitable module
 has been loaded.
 
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc Am|char *|SvGROW|SV* sv|STRLEN len
 Expands the character buffer in the SV so that it has room for the
diff --git a/unicode_constants.h b/unicode_constants.h
index 332307e853..232f18c464 100644
--- a/unicode_constants.h
+++ b/unicode_constants.h
@@ -22,7 +22,7 @@
  *                with no additional suffix are both string constants */
 
 /*
-=for apidoc_section Unicode Support
+=for apidoc_section $unicode
 
 =for apidoc AmnU|const char *|BOM_UTF8
 
diff --git a/universal.c b/universal.c
index 0cc6363b0a..9c49cd8327 100644
--- a/universal.c
+++ b/universal.c
@@ -120,7 +120,7 @@ S_sv_derived_from_svpvn(pTHX_ SV *sv, SV *namesv, const char * name, const STRLE
 }
 
 /*
-=for apidoc_section SV Handling
+=for apidoc_section $SV
 
 =for apidoc sv_derived_from_pvn
 
diff --git a/util.c b/util.c
index b25a696c4e..c1a441c2cc 100644
--- a/util.c
+++ b/util.c
@@ -542,7 +542,7 @@ Free_t   Perl_mfree (Malloc_t where)
 #define DELIMCPY_OUT_OF_BOUNDS_RET  I32_MAX
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc delimcpy_no_escape
 
 Copy a source buffer to a destination buffer, stopping at (but not including)
@@ -1301,7 +1301,7 @@ Perl_cntrl_to_mnemonic(const U8 c)
 /* copy a string to a safe spot */
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc savepv
 
 Perl's version of C<strdup()>.  Returns a pointer to a newly allocated
@@ -1796,7 +1796,7 @@ Perl_write_to_stderr(pTHX_ SV* msv)
 }
 
 /*
-=for apidoc_section Warning and Dieing
+=for apidoc_section $warning
 */
 
 /* Common code used in dieing and warning */
@@ -2448,7 +2448,7 @@ S_env_alloc(void *current, Size_t l1, Size_t l2, Size_t l3, Size_t size)
 #  if !defined(WIN32) && !defined(NETWARE)
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 =for apidoc my_setenv
 
 A wrapper for the C library L<setenv(3)>.  Don't use the latter, as the perl
@@ -3035,7 +3035,7 @@ dup2(int oldfd, int newfd)
 #ifdef HAS_SIGACTION
 
 /*
-=for apidoc_section Signals
+=for apidoc_section $signals
 =for apidoc rsignal
 
 A wrapper for the C library L<signal(2)>.  Don't use the latter, as the Perl
@@ -3946,7 +3946,7 @@ Perl_init_tm(pTHX_ struct tm *ptm)	/* see mktime, strftime and asctime */
 }
 
 /*
-=for apidoc_section Time
+=for apidoc_section $time
 =for apidoc mini_mktime
 normalise S<C<struct tm>> values without the localtime() semantics (and
 overhead) of mktime().
@@ -4146,7 +4146,7 @@ Perl_my_strftime(pTHX_ const char *fmt, int sec, int min, int hour, int mday, in
 #ifdef HAS_STRFTIME
 
 /*
-=for apidoc_section Time
+=for apidoc_section $time
 =for apidoc my_strftime
 strftime(), but with a different API so that the return value is a pointer
 to the formatted result (which MUST be arranged to be FREED BY THE
@@ -4255,7 +4255,7 @@ mini_mktime() overwrites them
 	(dp->d_name[1] == '.' && dp->d_name[2] == '\0')))
 
 /*
-=for apidoc_section Utility Functions
+=for apidoc_section $utility
 
 =for apidoc getcwd_sv
 
@@ -5163,7 +5163,7 @@ Perl_mem_log_del_sv(const SV *sv,
 #endif /* PERL_MEM_LOG */
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 =for apidoc quadmath_format_valid
 
 C<quadmath_snprintf()> is very strict about its C<format> string and will
diff --git a/util.h b/util.h
index df0c7ad348..3edcec64ef 100644
--- a/util.h
+++ b/util.h
@@ -37,7 +37,7 @@
 #endif
 
 /*
-=for apidoc_section String Handling
+=for apidoc_section $string
 
 =for apidoc ibcmp