Reorganize perlapi

This uses a new organization of sections that I came up with.  I asked
for comments on p5p, but there were none.

44 files changed, 148 insertions, 103 deletions

diff --git a/XSUB.h b/XSUB.h
index d62dc6c6d6..eb59d549fc 100644
--- a/XSUB.h
+++ b/XSUB.h
@@ -14,7 +14,7 @@
 /* first, some documentation for xsubpp-generated items */
 
 /*
-=head1 C<xsubpp> variables and internal functions
+=for apidoc_section XS
 
 =for apidoc Amn|char*|CLASS
 Variable which is setup by C<xsubpp> to indicate the 
@@ -258,8 +258,6 @@ Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
 =for apidoc Amns||XSRETURN_EMPTY
 Return an empty list from an XSUB immediately.
 
-=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
-
 =for apidoc AmU||newXSproto|char* name|XSUBADDR_t f|char* filename|const char *proto
 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
 the subs.
diff --git a/av.c b/av.c
index b5ddacaf4f..6fc129471a 100644
--- a/av.c
+++ b/av.c
@@ -16,7 +16,7 @@
  */
 
 /*
-=head1 Array Manipulation Functions
+=for apidoc_section AV Handling
 */
 
 #include "EXTERN.h"
diff --git a/av.h b/av.h
index ff954b868a..d7281e8cb8 100644
--- a/av.h
+++ b/av.h
@@ -44,8 +44,6 @@ Null AV pointer.
 
 (deprecated - use C<(AV *)NULL> instead)
 
-=head1 Array Manipulation Functions
-
 =for apidoc Am|int|AvFILL|AV* av
 Same as C<av_top_index()> or C<av_tindex()>.
 
diff --git a/cop.h b/cop.h
index d75da949cb..d7c42aae0e 100644
--- a/cop.h
+++ b/cop.h
@@ -481,10 +481,6 @@ struct cop {
 #define CopHINTHASH_set(c,h)	((c)->cop_hints_hash = (h))
 
 /*
-=head1 COP Hint Reading
-*/
-
-/*
 =for apidoc Am|SV *|cop_hints_fetch_pvn|const COP *cop|const char *keypv|STRLEN keylen|U32 hash|U32 flags
 
 Look up the hint entry in the cop C<cop> with the key specified by
@@ -942,10 +938,6 @@ struct context {
 #define CXINC (cxstack_ix < cxstack_max ? ++cxstack_ix : (cxstack_ix = cxinc()))
 
 /*
-=head1 "Gimme" Values
-*/
-
-/*
 =for apidoc AmnU||G_SCALAR
 Used to indicate scalar context.  See C<L</GIMME_V>>, C<L</GIMME>>, and
 L<perlcall>.
diff --git a/cv.h b/cv.h
index 9a169e865c..3ed80aca6a 100644
--- a/cv.h
+++ b/cv.h
@@ -16,18 +16,16 @@ struct xpvcv {
 };
 
 /*
-=head1 Handy Values
+=head1 CV Handling
+
+This section documents functions to manipulate CVs which are code-values,
+meaning subroutines.  For more information, see L<perlguts>.
 
 =for apidoc ADmnU||Nullcv
 Null CV pointer.
 
 (deprecated - use C<(CV *)NULL> instead)
 
-=head1 CV Manipulation Functions
-
-This section documents functions to manipulate CVs which are code-values,
-or subroutines.  For more information, see L<perlguts>.
-
 =for apidoc Am|HV*|CvSTASH|CV* cv
 Returns the stash of the CV.  A stash is the symbol table hash, containing
 the package-scoped variables in the package where the subroutine was defined.
@@ -255,7 +253,6 @@ CvNAME_HEK(CV *sv)
     )
 
 /*
-=head1 CV reference counts and CvOUTSIDE
 
 =for apidoc m|bool|CvWEAKOUTSIDE|CV *cv
 
diff --git a/doio.c b/doio.c
index b07750960d..b4103e15b2 100644
--- a/doio.c
+++ b/doio.c
@@ -3252,7 +3252,7 @@ Perl_do_shmio(pTHX_ I32 optype, SV **mark, SV **sp)
 #endif /* SYSV IPC */
 
 /*
-=head1 IO Functions
+=for apidoc_section Input/Output
 
 =for apidoc start_glob
 
diff --git a/dump.c b/dump.c
index 3134049379..d0b64aa017 100644
--- a/dump.c
+++ b/dump.c
@@ -528,10 +528,6 @@ Perl_sv_peek(pTHX_ SV *sv)
     return SvPV_nolen(t);
 }
 
-/*
-=head1 Debugging Utilities
-*/
-
 void
 Perl_dump_indent(pTHX_ I32 level, PerlIO *file, const char* pat, ...)
 {
diff --git a/gv.c b/gv.c
index f3ff7930fd..bf64b5e793 100644
--- a/gv.c
+++ b/gv.c
@@ -20,7 +20,7 @@
  */
 
 /*
-=head1 GV Functions
+=head1 GV Handling
 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
 It is a structure that holds a pointer to a scalar, an array, a hash etc,
 corresponding to $foo, @foo, %foo.
diff --git a/gv.h b/gv.h
index 488f2cc87f..4d7e758566 100644
--- a/gv.h
+++ b/gv.h
@@ -72,7 +72,7 @@ struct gp {
 #define GvNAMELEN(gv)	GvNAMELEN_get(gv)
 
 /*
-=head1 GV Functions
+=for apidoc_section GV Handling
 
 =for apidoc Am|SV*|GvSV|GV* gv
 
diff --git a/handy.h b/handy.h
index 07aa210a02..f435e4e450 100644
--- a/handy.h
+++ b/handy.h
@@ -18,16 +18,40 @@
 #  define Null(type) ((type)NULL)
 
 /*
-=head1 Handy Values
-
+=for apidoc_section String Handling
 =for apidoc AmnU||Nullch
 Null character pointer.  (No longer available when C<PERL_CORE> is
 defined.)
 
+=for apidoc_section SV Handling
 =for apidoc AmnU||Nullsv
 Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
 
 =cut
+
+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 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 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
+
+=for apidoc_section String Handling
+=for apidoc Am|token|CAT2|token x|token y
+=for apidoc Am|string|STRINGIFY|token x
+
+=for apidoc_section Numeric Functions
+=for apidoc Am|double|Drand01|double x
+=for apidoc Am|void|seedDrand01|Rand_seed_t x
+=for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b
+
+=cut
 */
 
 #  define Nullch Null(char*)
@@ -98,6 +122,7 @@ Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
 #endif
 
 /*
+=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:
@@ -279,6 +304,7 @@ typedef U64TYPE U64;
 #define nBIT_UMAX(n)  nBIT_MASK(n)
 
 /*
+=for apidoc_section Compiler directives
 =for apidoc Am|void|__ASSERT_|bool expr
 
 This is a helper macro to avoid preprocessor issues, replaced by nothing
@@ -300,7 +326,7 @@ detects that and gets all excited. */
 #endif
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc Ama|SV*|newSVpvs|"literal string"
 Like C<newSVpvn>, but takes a literal string instead of a
@@ -342,7 +368,7 @@ string/length pair.
 Like C<sv_setref_pvn>, but takes a literal string instead of
 a string/length pair.
 
-=head1 Memory Management
+=for apidoc_section String Handling
 
 =for apidoc Ama|char*|savepvs|"literal string"
 Like C<savepvn>, but takes a literal string instead of a
@@ -352,13 +378,13 @@ string/length pair.
 A version of C<savepvs()> which allocates the duplicate string in memory
 which is shared between threads.
 
-=head1 GV Functions
+=for apidoc_section GV Handling
 
 =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
 Like C<gv_stashpvn>, but takes a literal string instead of a
 string/length pair.
 
-=head1 Hash Manipulation Functions
+=for apidoc_section HV Handling
 
 =for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval
 Like C<hv_fetch>, but takes a literal string instead of a
@@ -380,7 +406,7 @@ a string/length pair.
 */
 
 /*
-=head1 Handy Values
+=for apidoc_section String Handling
 
 =for apidoc Amu|pair|STR_WITH_LEN|"literal string"
 
@@ -455,6 +481,7 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used.
                                                         PERL_VERSION_PATCH)
 
 /*
+=for apidoc_section Versioning
 =for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch
 
 Returns whether or not the perl currently being compiled has the specified
@@ -529,7 +556,7 @@ becomes
 # define PERL_VERSION_GT(j,n,p) (! PERL_VERSION_LE(j,n,p))
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section String Handling
 
 =for apidoc Am|bool|strNE|char* s1|char* s2
 Test two C<NUL>-terminated strings to see if they are different.  Returns true
@@ -1153,7 +1180,7 @@ C<isIDCONT_LC_utf8>, and C<isIDCONT_LC_utf8_safe>.
 =for apidoc Amh|bool|isIDCONT_LC_uvchr|int ch
 =for apidoc Amh|bool|isIDCONT_LC_utf8_safe|U8 * s| U8 *end
 
-=head1 Miscellaneous Functions
+=for apidoc_section Numeric Functions
 
 =for apidoc Am|U8|READ_XDIGIT|char str*
 Returns the value of an ASCII-range hex digit and advances the string pointer.
@@ -1340,6 +1367,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 AmnU|void|WIDEST_UTYPE
 
 Yields the widest unsigned integer type on the platform, currently either
@@ -2485,6 +2513,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 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
@@ -2517,6 +2546,7 @@ Like C<Zero> but returns dest.  Useful
 for encouraging compilers to tail-call
 optimise.
 
+=for apidoc_section Utility Functions
 =for apidoc Am|void|StructCopy|type *src|type *dest|type
 This is an architecture-independent macro to copy one structure to another.
 
@@ -2731,7 +2761,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)))
 
 /*
-=head1 Handy Values
+=for apidoc_section Utility Functions
 
 =for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a
 
diff --git a/hv.c b/hv.c
index e44e75e81e..f4c819cb80 100644
--- a/hv.c
+++ b/hv.c
@@ -17,7 +17,7 @@
  */
 
 /* 
-=head1 Hash Manipulation Functions
+=head1 HV Handling
 A HV structure represents a Perl hash.  It consists mainly of an array
 of pointers, each of which points to a linked list of HE structures.  The
 array is indexed by the hash function of the key, so each linked list
@@ -3731,6 +3731,7 @@ Perl_refcounted_he_inc(pTHX_ struct refcounted_he *he)
 }
 
 /*
+=for apidoc_section COP Hint Hashes
 =for apidoc cop_fetch_label
 
 Returns the label attached to a cop, and stores its length in bytes into
@@ -3810,6 +3811,7 @@ Perl_cop_store_label(pTHX_ COP *const cop, const char *label, STRLEN len,
 }
 
 /*
+=for apidoc_section HV Handling
 =for apidoc hv_assert
 
 Check that a hash is in an internally consistent state.
diff --git a/hv.h b/hv.h
index 607152c840..8e71e124e8 100644
--- a/hv.h
+++ b/hv.h
@@ -140,22 +140,18 @@ struct xpvhv {
 };
 
 /*
-=head1 Hash Manipulation Functions
+=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
 is to be expected.  (For information only--not to be used).
 
-=head1 Handy Values
-
 =for apidoc ADmnU||Nullhv
 Null HV pointer.
 
 (deprecated - use C<(HV *)NULL> instead)
 
-=head1 Hash Manipulation Functions
-
 =for apidoc Am|char*|HvNAME|HV* stash
 Returns the package name of a stash, or C<NULL> if C<stash> isn't a stash.
 See C<L</SvSTASH>>, C<L</CvSTASH>>.
diff --git a/inline.h b/inline.h
index 41bb4c5dbf..d0e119a41a 100644
--- a/inline.h
+++ b/inline.h
@@ -40,6 +40,7 @@ SOFTWARE.
 /* ------------------------------- av.h ------------------------------- */
 
 /*
+=for apidoc_section AV Handling
 =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
@@ -1876,7 +1877,7 @@ Perl_utf8_to_uvchr_buf_helper(pTHX_ const U8 *s, const U8 *send, STRLEN *retlen)
 /* ------------------------------- perl.h ----------------------------- */
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Utility Functions
 
 =for apidoc is_safe_syscall
 
@@ -2449,7 +2450,7 @@ Perl_cx_popgiven(pTHX_ PERL_CONTEXT *cx)
 /* ------------------ util.h ------------------------------------------- */
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section String Handling
 
 =for apidoc foldEQ
 
@@ -2505,6 +2506,7 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len)
 }
 
 /*
+=for apidoc_section Locales
 =for apidoc foldEQ_locale
 
 Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the
@@ -2532,6 +2534,7 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len)
 }
 
 /*
+=for apidoc_section String Handling
 =for apidoc my_strnlen
 
 The C library C<strnlen> if available, or a Perl implementation of it.
diff --git a/locale.c b/locale.c
index d1806beca1..5d6566f8f2 100644
--- a/locale.c
+++ b/locale.c
@@ -2281,7 +2281,7 @@ S_win32_setlocale(pTHX_ int category, const char* locale)
 
 /*
 
-=head1 Locale-related functions and macros
+=for apidoc_section Locales
 
 =for apidoc Perl_setlocale
 
diff --git a/malloc.c b/malloc.c
index 01e84bfc19..f69d45028f 100644
--- a/malloc.c
+++ b/malloc.c
@@ -1225,6 +1225,7 @@ 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/mathoms.c b/mathoms.c
index 5149bd731c..caed40171a 100644
--- a/mathoms.c
+++ b/mathoms.c
@@ -50,7 +50,7 @@
  *
  * Some blurb for perlapi.pod:
 
-=head1 Obsolete backwards compatibility functions
+ head1 Obsolete backwards compatibility functions
 
 Some of these are also deprecated.  You can exclude these from
 your compiled Perl by adding this option to Configure:
@@ -85,6 +85,7 @@ Perl_ref(pTHX_ OP *o, I32 type)
 }
 
 /*
+=for apidoc_section SV Handling
 =for apidoc sv_unref
 
 Unsets the RV status of the SV, and decrements the reference count of
@@ -605,6 +606,7 @@ Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
 }
 
 /*
+=for apidoc_section GV Handling
 =for apidoc gv_fetchmethod
 
 See L</gv_fetchmethod_autoload>.
@@ -702,6 +704,7 @@ Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep)
 }
 
 /*
+=for apidoc_section SV Handling
 =for apidoc sv_nolocking
 
 Dummy routine which "locks" an SV when there is no locking module present.
@@ -819,6 +822,7 @@ Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len)
 }
 
 /*
+=for apidoc_section Pack and Unpack
 =for apidoc unpack_str
 
 The engine implementing C<unpack()> Perl function.  Note: parameters C<strbeg>,
@@ -1115,6 +1119,7 @@ Perl_sv_2bool(pTHX_ SV *const sv)
 
 
 /*
+=for apidoc_section Custom Operators
 =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
@@ -1177,6 +1182,7 @@ ASCII_TO_NEED(const UV enc, const UV ch)
 }
 
 /*
+=for apidoc_section Unicode Support
 =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 16b72bf1f4..3708bd50fe 100644
--- a/mg.c
+++ b/mg.c
@@ -16,7 +16,7 @@
  */
 
 /*
-=head1 Magical Functions
+=head1 Magic
 "Magic" is special data attached to SV structures in order to give them
 "magical" properties.  When any Perl code tries to read from, or assign to,
 an SV marked as magical, it calls the 'get' or 'set' function associated
@@ -846,6 +846,7 @@ S_fixup_errno_string(pTHX_ SV* sv)
 }
 
 /*
+=for apidoc_section Errno
 =for apidoc sv_string_from_errnum
 
 Generates the message string describing an OS error and returns it as
@@ -1909,6 +1910,7 @@ Perl_magic_setnkeys(pTHX_ SV *sv, MAGIC *mg)
 }
 
 /*
+=for apidoc_section Magic
 =for apidoc magic_methcall
 
 Invoke a magic method (like FETCH).
@@ -3639,6 +3641,7 @@ S_unwind_handler_stack(pTHX_ const void *p)
 }
 
 /*
+=for apidoc_section Magic
 =for apidoc magic_sethint
 
 Triggered by a store to C<%^H>, records the key/value pair to
diff --git a/mro_core.c b/mro_core.c
index 1fc7c7ca9d..378c738c7a 100644
--- a/mro_core.c
+++ b/mro_core.c
@@ -19,7 +19,7 @@
  */
 
 /*
-=head1 MRO Functions
+=head1 MRO
 These functions are related to the method resolution order of perl classes
 Also see L<perlmroapi>.
 
diff --git a/numeric.c b/numeric.c
index 8920afc7dd..a476881cf9 100644
--- a/numeric.c
+++ b/numeric.c
@@ -16,7 +16,7 @@
  */
 
 /*
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =cut
 
diff --git a/op.c b/op.c
index b27eb0b009..c0879017bc 100644
--- a/op.c
+++ b/op.c
@@ -8877,7 +8877,7 @@ Perl_utilize(pTHX_ int aver, I32 floor, OP *version, OP *idop, OP *arg)
 }
 
 /*
-=head1 Embedding Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc load_module
 
diff --git a/op.h b/op.h
index 30f808bf40..12d359529d 100644
--- a/op.h
+++ b/op.h
@@ -70,7 +70,7 @@ typedef PERL_BITFIELD16 Optype;
 #define OP_GIMME_REVERSE(flags)	((flags) & G_WANT)
 
 /*
-=head1 "Gimme" Values
+=for apidoc_section Callback Functions
 
 =for apidoc Amn|U32|GIMME_V
 The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
diff --git a/pad.c b/pad.c
index 8bcb8b313e..7e5e2365f7 100644
--- a/pad.c
+++ b/pad.c
@@ -272,7 +272,7 @@ Perl_pad_new(pTHX_ int flags)
 
 
 /*
-=head1 Embedding Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc cv_undef
 
diff --git a/patchlevel.h b/patchlevel.h
index a8e3319eff..452605c586 100644
--- a/patchlevel.h
+++ b/patchlevel.h
@@ -9,7 +9,7 @@
  */
 
 /*
-=head1 Handy Values
+=for apidoc_section Versioning
 
 =for apidoc AmDnU|U8|PERL_REVISION
 The major number component of the perl interpreter currently being compiled or
diff --git a/perl.c b/perl.c
index f32686b982..f54dc6025f 100644
--- a/perl.c
+++ b/perl.c
@@ -177,7 +177,7 @@ perl_alloc_using(struct IPerlMem* ipM, struct IPerlMem* ipMS,
 #else
 
 /*
-=head1 Embedding Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc perl_alloc
 
@@ -2742,7 +2742,7 @@ S_run_body(pTHX_ I32 oldscope)
 }
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc get_sv
 
@@ -2768,7 +2768,7 @@ Perl_get_sv(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=head1 Array Manipulation Functions
+=for apidoc_section AV Handling
 
 =for apidoc get_av
 
@@ -2798,7 +2798,7 @@ Perl_get_av(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=head1 Hash Manipulation Functions
+=for apidoc_section HV Handling
 
 =for apidoc get_hv
 
@@ -2825,7 +2825,7 @@ Perl_get_hv(pTHX_ const char *name, I32 flags)
 }
 
 /*
-=head1 CV Manipulation Functions
+=for apidoc_section CV Handling
 
 =for apidoc get_cvn_flags
 
@@ -3271,7 +3271,7 @@ Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
 /* Require a module. */
 
 /*
-=head1 Embedding Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc require_pv
 
diff --git a/perl.h b/perl.h
index edeb4eb7b7..615ab3027a 100644
--- a/perl.h
+++ b/perl.h
@@ -84,6 +84,7 @@
 /* <--- here ends the logic shared by perl.h and makedef.pl */
 
 /*
+=for apidoc_section Compiler 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
@@ -408,8 +409,6 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>.
  * but we cannot quite get rid of, such as "ax" in PPCODE+noargs xsubs,
  * or variables/arguments that are used only in certain configurations.
 
-=head1 Miscellaneous Functions
-
 =for apidoc Am||PERL_UNUSED_ARG|void x
 This is used to suppress compiler warnings that a parameter to a function is
 not used.  This situation can arise, for example, when a parameter is needed
@@ -633,8 +632,7 @@ __typeof__ and nothing else.
 #endif
 
 /*
-=head1 Miscellaneous Functions
-
+=for apidoc_section Compiler directives
 =for apidoc AmnUu|void|STMT_START
 
  STMT_START { statements; } STMT_END;
@@ -1076,6 +1074,7 @@ EXTERN_C int usleep(unsigned int);
 #  endif
 
 /*
+=for apidoc_section Integer configuration values
 =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
@@ -1585,6 +1584,7 @@ any magic.
 #endif
 
 /*
+=for apidoc_section SV Handling
 =for apidoc Amn|SV *|DEFSV
 Returns the SV associated with C<$_>
 
@@ -1806,8 +1806,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.
 
-=head1 Miscellaneous Functions
-
+=for apidoc_section String Handling
 =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
@@ -2631,7 +2630,7 @@ extern long double Perl_my_frexpl(long double x, int *e);
 #endif
 
 /*
-=head1 Numeric functions
+=for apidoc_section Integer configuration values
 
 =for apidoc AmnUh||PERL_INT_MIN
 =for apidoc AmnUh||PERL_LONG_MAX
@@ -2650,6 +2649,8 @@ extern long double Perl_my_frexpl(long double x, int *e);
 =for apidoc AmnUh||PERL_USHORT_MAX
 =for apidoc AmnUh||PERL_USHORT_MIN
 =for apidoc AmnUh||PERL_QUAD_MIN
+=for apidoc_section Floating point configuration values
+
 =for apidoc AmnU||PERL_INT_MAX
 This and
 C<PERL_INT_MIN>,
@@ -3068,7 +3069,7 @@ typedef struct padname PADNAME;
 #endif
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv
 Provides system-specific tune up of the C runtime environment necessary to
@@ -3668,7 +3669,7 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex)
 #endif
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Compiler directives
 
 =for apidoc AmU|bool|LIKELY|const bool expr
 
@@ -6192,7 +6193,7 @@ typedef struct am_table_short AMTS;
                         cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL))
 
 /*
-=head1 Locale-related functions and macros
+=for apidoc_section Locales
 
 =for apidoc Amn|bool|IN_LOCALE
 
@@ -6460,7 +6461,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.)
 
-=head1 Locale-related functions and macros
+=for apidoc_section Locales
 
 =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION
 
@@ -6753,7 +6754,7 @@ cannot have changed since the precalculation.
 
 /*
 
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e
 
@@ -7081,7 +7082,7 @@ EXTERN_C int flock(int fd, int op);
 #define IS_NUMBER_TRAILING            0x40 /* number has trailing trash */
 
 /*
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send
 
@@ -7190,6 +7191,7 @@ extern void moncontrol(int);
 #define PERL_UNICODE_UTF8CACHEASSERT		'a'
 
 /*
+=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
@@ -7200,7 +7202,7 @@ unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
 #define PERL_SIGNALS_UNSAFE_FLAG	0x0001
 
 /*
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc Am|int|PERL_ABS|int
 
@@ -7232,7 +7234,7 @@ so no C<x++>.
 
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Utility Functions
 
 =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/perlio.h b/perlio.h
index ee16ab8774..c0bd7ea645 100644
--- a/perlio.h
+++ b/perlio.h
@@ -63,6 +63,10 @@ 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 f7509009bb..66add53e4d 100644
--- a/pod/perlapio.pod
+++ b/pod/perlapio.pod
@@ -68,6 +68,8 @@ perlapio - perl's IO abstraction interface.
                                                     const char *layers);
   void    PerlIO_debug(const char *fmt,...);
 
+=for apidoc_section Input/Output
+
 =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
 =for apidoc ATmh|int    |PerlIO_canset_cnt|PerlIO *f
diff --git a/pod/perlcall.pod b/pod/perlcall.pod
index c340716653..089c39785f 100644
--- a/pod/perlcall.pod
+++ b/pod/perlcall.pod
@@ -121,6 +121,8 @@ been warned.
 
 =head1 FLAG VALUES
 
+=for apidoc_section Callback Functions
+
 The C<flags> parameter in all the I<call_*> functions is one of G_VOID,
 G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together
 with a bit mask of any combination of the other G_* symbols defined below.
@@ -993,6 +995,7 @@ 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 Amnh|GV *|PL_errgv
 
 =item 3.
diff --git a/pod/perlfilter.pod b/pod/perlfilter.pod
index 0744e29f8d..6b15eccf95 100644
--- a/pod/perlfilter.pod
+++ b/pod/perlfilter.pod
@@ -294,6 +294,7 @@ becomes M.)
 
    1;
 
+=for apidoc_section Source Filters
 =for apidoc filter_add
 =for apidoc filter_read
 
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 3b1b9d5421..4af6067882 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -548,6 +548,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 Amh|void|PERL_HASH|U32 hash|char *key|STRLEN klen
 
 =head2 Hash API Extensions
@@ -2408,6 +2409,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 Amnh||aTHX
 =for apidoc Amnh||aTHX_
 =for apidoc Amnh||dTHX
@@ -2663,6 +2665,7 @@ following macros for portability
         NVff            NV %f-like
         NVgf            NV %g-like
 
+=for apidoc_section Formats
 =for apidoc Amnh||IVdf
 =for apidoc Amnh||UVuf
 =for apidoc Amnh||UVof
@@ -2750,6 +2753,9 @@ 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
+=cut
+
 =head2 Formatted Printing of C<Size_t> and C<SSize_t>
 
 The most general way to do this is to cast them to a UV or IV, and
@@ -2779,6 +2785,7 @@ use the follow macros to do it right.
         PTR2NV(pointer)
         INT2PTR(pointertotype, integer)
 
+=for apidoc_section Casting
 =for apidoc Amh|void *|INT2PTR|type|int value
 =for apidoc Amh|UV|PTR2UV|void *
 =for apidoc Amh|IV|PTR2IV|void *
diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod
index 7f412e4afa..769c2f6714 100644
--- a/pod/perlhacktips.pod
+++ b/pod/perlhacktips.pod
@@ -671,7 +671,7 @@ library functions instead.  In this case C<memchr> can be used to see if
 C<c> is in C<"list"> and works even if C<c> is C<NUL>.  These functions
 need an additional parameter to give the string length.
 In the case of literal string parameters, perl has defined macros that
-calculate the length for you.  See L<perlapi/Miscellaneous Functions>.
+calculate the length for you.  See L<perlapi/String Handling>.
 
 =item *
 
diff --git a/pod/perlmroapi.pod b/pod/perlmroapi.pod
index c585441fc9..e2dbefd94e 100644
--- a/pod/perlmroapi.pod
+++ b/pod/perlmroapi.pod
@@ -79,6 +79,7 @@ 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
 
 To set your private value, call C<Perl_mro_set_private_data()>:
diff --git a/pp_ctl.c b/pp_ctl.c
index cc244d7ba7..6fcaaef563 100644
--- a/pp_ctl.c
+++ b/pp_ctl.c
@@ -1846,7 +1846,7 @@ PP(pp_xor)
 
 /*
 
-=head1 CV Manipulation Functions
+=for apidoc_section CV Handling
 
 =for apidoc caller_cx
 
diff --git a/pp_sort.c b/pp_sort.c
index a3a7352aac..94c6a02e85 100644
--- a/pp_sort.c
+++ b/pp_sort.c
@@ -541,7 +541,7 @@ S_sortsv_flags_impl(pTHX_ gptr *base, size_t nmemb, SVCOMPARE_t cmp, U32 flags)
 }
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc sortsv_flags
 
@@ -669,7 +669,6 @@ sortsv_cmp_locale_desc(pTHX_ gptr *base, size_t nmemb, U32 flags)
 #endif
 
 /*
-=head1 Array Manipulation Functions
 
 =for apidoc sortsv
 
diff --git a/pp_sys.c b/pp_sys.c
index 2727456b6c..0ab64e75d7 100644
--- a/pp_sys.c
+++ b/pp_sys.c
@@ -1293,7 +1293,7 @@ PP(pp_sselect)
 
 /*
 
-=head1 GV Functions
+=for apidoc_section GV Handling
 
 =for apidoc setdefout
 
diff --git a/regcomp.c b/regcomp.c
index 64488994fa..124ea5b90b 100644
--- a/regcomp.c
+++ b/regcomp.c
@@ -21859,6 +21859,7 @@ 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/scope.c b/scope.c
index 5b4fe1131c..d9b51f7826 100644
--- a/scope.c
+++ b/scope.c
@@ -316,7 +316,7 @@ Perl_save_set_svflags(pTHX_ SV* sv, U32 mask, U32 val)
 
 /*
 
-=head1 GV Functions
+=for apidoc_section GV Handling
 
 =for apidoc save_gp
 
diff --git a/sv.c b/sv.c
index ebee0221e5..a268002dac 100644
--- a/sv.c
+++ b/sv.c
@@ -130,8 +130,7 @@ static const char S_destroy[] = "DESTROY";
 
 /* ============================================================================
 
-=head1 Allocation and deallocation of SVs.
-
+=for apidoc_section SV Handling
 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
@@ -409,7 +408,7 @@ S_del_sv(pTHX_ SV *p)
 
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc sv_add_arena
 
@@ -13486,7 +13485,7 @@ Perl_sv_vcatpvfn_flags(pTHX_ SV *const sv, const char *const pat, const STRLEN p
 
 /* =========================================================================
 
-=head1 Cloning an interpreter
+=for apidoc_section Embedding and Interpreter Cloning
 
 =cut
 
@@ -16345,6 +16344,7 @@ Perl_varname(pTHX_ const GV *const gv, const char gvtype, PADOFFSET targ,
 
 
 /*
+=apidoc_section Warning and Dieing
 =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 fc1bad21de..b97ca21431 100644
--- a/sv.h
+++ b/sv.h
@@ -269,7 +269,7 @@ struct p5rx {
 #undef _SV_HEAD_UNION		/* ensure no pollution */
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc Am|U32|SvREFCNT|SV* sv
 Returns the value of the object's reference count. Exposed
@@ -2095,7 +2095,7 @@ incremented.
 /* the following macros update any magic values this C<sv> is associated with */
 
 /*
-=head1 Magical Functions
+=head1 Magic
 
 =for apidoc Am|void|SvGETMAGIC|SV* sv
 Invokes C<mg_get> on an SV if it has 'get' magic.  For example, this
@@ -2134,7 +2134,7 @@ has been loaded.
 Releases a mutual exclusion lock on C<sv> if a suitable module
 has been loaded.
 
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =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/t/porting/customized.dat b/t/porting/customized.dat
index 125430347f..395dc639e0 100644
--- a/t/porting/customized.dat
+++ b/t/porting/customized.dat
@@ -8,7 +8,7 @@ Digest::MD5 cpan/Digest-MD5/MD5.pm df5f0663f0f755be7eda6e3d2f008f2629246b19
 Digest::MD5 cpan/Digest-MD5/MD5.xs 249bed648232192ce018f7f894ad127c3a639831
 Digest::MD5 cpan/Digest-MD5/t/files.t e987329d2411ff60ad9a2bdf93fdf5f6943467e8
 ExtUtils::Constant cpan/ExtUtils-Constant/t/Constant.t d5c75c41d6736a0c5897130f534af0896a7d6f4d
-Filter::Util::Call pod/perlfilter.pod e9833bf4ebc51087dfee5c553e0f8a5eef67212d
+Filter::Util::Call pod/perlfilter.pod 67d1ea264f5fe88e9422976e2a903bf3d1671f6d
 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
@@ -31,4 +31,4 @@ Win32API::File cpan/Win32API-File/File.pm 8fd212857f821cb26648878b96e57f13bf21b9
 Win32API::File cpan/Win32API-File/File.xs beb870fed4490d2faa547b4a8576b8d64d1d27c5
 experimental cpan/experimental/t/basic.t cb9da8dd05b854375809872a05dd32637508d5da
 version cpan/version/lib/version.pm 7ef9219d1d5f1d71f08a79f3b0577df138b21b12
-version vutil.c 601cc57bbc0070ae33eab7fd2d667f20efbe15f8
+version vutil.c 7a416b6630a498e737aae03891d0873aaeb066f0
diff --git a/universal.c b/universal.c
index 6797b9fb53..0cc6363b0a 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
 }
 
 /*
-=head1 SV Manipulation Functions
+=for apidoc_section SV Handling
 
 =for apidoc sv_derived_from_pvn
 
diff --git a/util.c b/util.c
index 87ad3a8bfe..401b0cf9fd 100644
--- a/util.c
+++ b/util.c
@@ -573,6 +573,7 @@ S_delimcpy_intern(char *to, const char *toend, const char *from,
 
 
 /*
+=for apidoc_section String Handling
 =for apidoc delimcpy_no_escape
 
 Copy a source buffer to a destination buffer, stopping at (but not including)
@@ -635,8 +636,6 @@ Perl_delimcpy(char *to, const char *toend, const char *from, const char *fromend
 }
 
 /*
-=head1 Miscellaneous Functions
-
 =for apidoc ninstr
 
 Find the first (leftmost) occurrence of a sequence of bytes within another
@@ -705,8 +704,6 @@ Perl_ninstr(const char *big, const char *bigend, const char *little, const char
 }
 
 /*
-=head1 Miscellaneous Functions
-
 =for apidoc rninstr
 
 Like C<L</ninstr>>, but instead finds the final (rightmost) occurrence of a
@@ -818,7 +815,6 @@ Perl_rninstr(const char *big, const char *bigend, const char *little, const char
    If FBMcf_TAIL, the table is created as if the string has a trailing \n. */
 
 /*
-=head1 Miscellaneous Functions
 
 =for apidoc fbm_compile
 
@@ -1165,8 +1161,7 @@ Perl_cntrl_to_mnemonic(const U8 c)
 /* copy a string to a safe spot */
 
 /*
-=head1 Memory Management
-
+=for apidoc_section String Handling
 =for apidoc savepv
 
 Perl's version of C<strdup()>.  Returns a pointer to a newly allocated
@@ -1373,7 +1368,7 @@ Perl_form_nocontext(const char* pat, ...)
 #endif /* PERL_IMPLICIT_CONTEXT */
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Display and Dump functions
 =for apidoc form
 
 Takes a sprintf-style format pattern and conventional
@@ -1661,7 +1656,7 @@ Perl_write_to_stderr(pTHX_ SV* msv)
 }
 
 /*
-=head1 Warning and Dieing
+=for apidoc_section Warning and Dieing
 */
 
 /* Common code used in dieing and warning */
@@ -2260,6 +2255,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 my_setenv
 
 A wrapper for the C library L<setenv(3)>.  Don't use the latter, as the perl
@@ -2846,6 +2842,7 @@ dup2(int oldfd, int newfd)
 #ifdef HAS_SIGACTION
 
 /*
+=for apidoc_section Signals
 =for apidoc rsignal
 
 A wrapper for the C library L<signal(2)>.  Don't use the latter, as the Perl
@@ -3952,6 +3949,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 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
@@ -4060,7 +4058,7 @@ mini_mktime() overwrites them
 	(dp->d_name[1] == '.' && dp->d_name[2] == '\0')))
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Utility Functions
 
 =for apidoc getcwd_sv
 
@@ -4968,6 +4966,7 @@ Perl_mem_log_del_sv(const SV *sv,
 #endif /* PERL_MEM_LOG */
 
 /*
+=for apidoc_section String Handling
 =for apidoc quadmath_format_valid
 
 C<quadmath_snprintf()> is very strict about its C<format> string and will
@@ -6144,6 +6143,7 @@ static void atos_symbolize(atos_context* ctx,
 #endif /* #ifdef PERL_DARWIN */
 
 /*
+=for apidoc_section Display and Dump functions
 =for apidoc get_c_backtrace
 
 Collects the backtrace (aka "stacktrace") into a single linear
@@ -6395,6 +6395,7 @@ Deallocates a backtrace received from get_c_bracktrace.
 */
 
 /*
+=for apidoc_section Display and Dump functions
 =for apidoc get_c_backtrace_dump
 
 Returns a SV containing a dump of C<depth> frames of the call stack, skipping
diff --git a/util.h b/util.h
index 12dfea8106..7d06feaa03 100644
--- a/util.h
+++ b/util.h
@@ -37,7 +37,7 @@
 #endif
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section String Handling
 
 =for apidoc ibcmp
 
diff --git a/vutil.c b/vutil.c
index 23627bea78..9a1cbbd327 100644
--- a/vutil.c
+++ b/vutil.c
@@ -8,6 +8,8 @@
 #define VERSION_MAX 0x7FFFFFFF
 
 /*
+=for apidoc_section Versioning
+
 =for apidoc prescan_version
 
 Validate that a given string can be parsed as a version object, but doesn't