perlapi: Refactor placements, headings of some functions

It is not very user friendly to list functions as
"Functions found in file FOO".  Better is to group them by purpose, as
many were already.  I went through and placed the ones that weren't
already so grouped into groups.  Patches welcome if you have a better
classification.

I changed the headings of some so that the important disctinction was
the first word so that they are placed in the file more appropriately.

And a couple of ones that I had created myself, I came up with a name
that I think is better than the original

XSUB.h

@@ -14,7 +14,7 @@
 /* first, some documentation for xsubpp-generated items */
 
 /*
-=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
+=head1 C<xsubpp> variables and internal functions
 
 =for apidoc Amn|char*|CLASS
 Variable which is setup by C<xsubpp> to indicate the 
@@ -274,7 +274,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.
 
-=head1 Simple Exception Handling Macros
+=head1 Exception Handling (simple) Macros
 
 =for apidoc Ams||dXCPT
 Set up necessary local variables for exception handling.

dump.c

@@ -20,6 +20,8 @@
  * by Devel::Peek.
  *
  * It also holds the debugging version of the  runops function.
+
+=head1 Display and Dump functions
  */
 
 #include "EXTERN.h"

handy.h

@@ -506,7 +506,7 @@ C<strncmp>).
 
 /*
 
-=head1 Character classes
+=head1 Character classification
 This section is about functions (really macros) that classify characters
 into types, such as punctuation versus alphabetic, etc.  Most of these are
 analogous to regular expression character classes.  (See
@@ -562,14 +562,16 @@ is tested.
 =for apidoc Am|bool|isALPHA|char ch
 Returns a boolean indicating whether the specified character is an
 alphabetic character, analogous to C<m/[[:alpha:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isALPHA_A>, C<isALPHA_L1>, C<isALPHA_uni>, C<isALPHA_utf8>, C<isALPHA_LC>,
 C<isALPHA_LC_uvchr>, and C<isALPHA_LC_utf8>.
 
 =for apidoc Am|bool|isALPHANUMERIC|char ch
 Returns a boolean indicating whether the specified character is a either an
 alphabetic character or decimal digit, analogous to C<m/[[:alnum:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isALPHANUMERIC_A>, C<isALPHANUMERIC_L1>, C<isALPHANUMERIC_uni>,
 C<isALPHANUMERIC_utf8>, C<isALPHANUMERIC_LC>, C<isALPHANUMERIC_LC_uvchr>, and
 C<isALPHANUMERIC_LC_utf8>.
@@ -580,7 +582,8 @@ characters in the ASCII character set, analogous to C<m/[[:ascii:]]/>.
 On non-ASCII platforms, it returns TRUE iff this
 character corresponds to an ASCII character.  Variants C<isASCII_A()> and
 C<isASCII_L1()> are identical to C<isASCII()>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isASCII_uni>, C<isASCII_utf8>, C<isASCII_LC>, C<isASCII_LC_uvchr>, and
 C<isASCII_LC_utf8>.  Note, however, that some platforms do not have the C
 library routine C<isascii()>.  In these cases, the variants whose names contain
@@ -595,7 +598,8 @@ work properly on any string encoded or not in UTF-8.
 =for apidoc Am|bool|isBLANK|char ch
 Returns a boolean indicating whether the specified character is a
 character considered to be a blank, analogous to C<m/[[:blank:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isBLANK_A>, C<isBLANK_L1>, C<isBLANK_uni>, C<isBLANK_utf8>, C<isBLANK_LC>,
 C<isBLANK_LC_uvchr>, and C<isBLANK_LC_utf8>.  Note, however, that some
 platforms do not have the C library routine C<isblank()>.  In these cases, the
@@ -605,7 +609,8 @@ without.
 =for apidoc Am|bool|isCNTRL|char ch
 Returns a boolean indicating whether the specified character is a
 control character, analogous to C<m/[[:cntrl:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isCNTRL_A>, C<isCNTRL_L1>, C<isCNTRL_uni>, C<isCNTRL_utf8>, C<isCNTRL_LC>,
 C<isCNTRL_LC_uvchr>, and C<isCNTRL_LC_utf8>
 On EBCDIC platforms, you almost always want to use the C<isCNTRL_L1> variant.
@@ -614,21 +619,24 @@ On EBCDIC platforms, you almost always want to use the C<isCNTRL_L1> variant.
 Returns a boolean indicating whether the specified character is a
 digit, analogous to C<m/[[:digit:]]/>.
 Variants C<isDIGIT_A> and C<isDIGIT_L1> are identical to C<isDIGIT>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isDIGIT_uni>, C<isDIGIT_utf8>, C<isDIGIT_LC>, C<isDIGIT_LC_uvchr>, and
 C<isDIGIT_LC_utf8>.
 
 =for apidoc Am|bool|isGRAPH|char ch
 Returns a boolean indicating whether the specified character is a
 graphic character, analogous to C<m/[[:graph:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isGRAPH_A>, C<isGRAPH_L1>, C<isGRAPH_uni>, C<isGRAPH_utf8>, C<isGRAPH_LC>,
 C<isGRAPH_LC_uvchr>, and C<isGRAPH_LC_utf8>.
 
 =for apidoc Am|bool|isLOWER|char ch
 Returns a boolean indicating whether the specified character is a
 lowercase character, analogous to C<m/[[:lower:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isLOWER_A>, C<isLOWER_L1>, C<isLOWER_uni>, C<isLOWER_utf8>, C<isLOWER_LC>,
 C<isLOWER_LC_uvchr>, and C<isLOWER_LC_utf8>.
 
@@ -644,7 +652,8 @@ punctuation character, analogous to C<m/[[:punct:]]/>.
 Note that the definition of what is punctuation isn't as
 straightforward as one might desire.  See L<perlrecharclass/POSIX Character
 Classes> for details.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isPUNCT_A>, C<isPUNCT_L1>, C<isPUNCT_uni>, C<isPUNCT_utf8>, C<isPUNCT_LC>,
 C<isPUNCT_LC_uvchr>, and C<isPUNCT_LC_utf8>.
 
@@ -659,7 +668,8 @@ locale forms of this macro (the ones with C<LC> in their names) matched
 precisely what C<m/[[:space:]]/> does.  In those releases, the only difference,
 in the non-locale variants, was that C<isSPACE()> did not match a vertical tab.
 (See L</isPSXSPC> for a macro that matches a vertical tab in all releases.)
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isSPACE_A>, C<isSPACE_L1>, C<isSPACE_uni>, C<isSPACE_utf8>, C<isSPACE_LC>,
 C<isSPACE_LC_uvchr>, and C<isSPACE_LC_utf8>.
 
@@ -675,21 +685,24 @@ non-locale forms differ from their C<isSPACE()> forms only in that the
 C<isSPACE()> forms don't match a Vertical Tab, and the C<isPSXSPC()> forms do.
 Otherwise they are identical.  Thus this macro is analogous to what
 C<m/[[:space:]]/> matches in a regular expression.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isPSXSPC_A>, C<isPSXSPC_L1>, C<isPSXSPC_uni>, C<isPSXSPC_utf8>, C<isPSXSPC_LC>,
 C<isPSXSPC_LC_uvchr>, and C<isPSXSPC_LC_utf8>.
 
 =for apidoc Am|bool|isUPPER|char ch
 Returns a boolean indicating whether the specified character is an
 uppercase character, analogous to C<m/[[:upper:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isUPPER_A>, C<isUPPER_L1>, C<isUPPER_uni>, C<isUPPER_utf8>, C<isUPPER_LC>,
 C<isUPPER_LC_uvchr>, and C<isUPPER_LC_utf8>.
 
 =for apidoc Am|bool|isPRINT|char ch
 Returns a boolean indicating whether the specified character is a
 printable character, analogous to C<m/[[:print:]]/>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isPRINT_A>, C<isPRINT_L1>, C<isPRINT_uni>, C<isPRINT_utf8>, C<isPRINT_LC>,
 C<isPRINT_LC_uvchr>, and C<isPRINT_LC_utf8>.
 
@@ -702,7 +715,8 @@ a "mark" character that attaches to one of those (like some sort of accent).
 C<isALNUM()> is a synonym provided for backward compatibility, even though a
 word character includes more than the standard C language meaning of
 alphanumeric.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isWORDCHAR_A>, C<isWORDCHAR_L1>, C<isWORDCHAR_uni>, C<isWORDCHAR_utf8>,
 C<isWORDCHAR_LC>, C<isWORDCHAR_LC_uvchr>, and C<isWORDCHAR_LC_utf8>.
 
@@ -710,7 +724,8 @@ C<isWORDCHAR_LC>, C<isWORDCHAR_LC_uvchr>, and C<isWORDCHAR_LC_utf8>.
 Returns a boolean indicating whether the specified character is a hexadecimal
 digit.  In the ASCII range these are C<[0-9A-Fa-f]>.  Variants C<isXDIGIT_A()>
 and C<isXDIGIT_L1()> are identical to C<isXDIGIT()>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isXDIGIT_uni>, C<isXDIGIT_utf8>, C<isXDIGIT_LC>, C<isXDIGIT_LC_uvchr>, and
 C<isXDIGIT_LC_utf8>.
 
@@ -719,7 +734,8 @@ Returns a boolean indicating whether the specified character can be the first
 character of an identifier.  This is very close to, but not quite the same as
 the official Unicode property C<XID_Start>.  The difference is that this
 returns true only if the input character also matches L</isWORDCHAR>.
-See the L<top of this section|/Character classes> for an explanation of variants
+See the L<top of this section|/Character classification> for an explanation of
+variants
 C<isIDFIRST_A>, C<isIDFIRST_L1>, C<isIDFIRST_uni>, C<isIDFIRST_utf8>,
 C<isIDFIRST_LC>, C<isIDFIRST_LC_uvchr>, and C<isIDFIRST_LC_utf8>.
 
@@ -728,7 +744,8 @@ Returns a boolean indicating whether the specified character can be the
 second or succeeding character of an identifier.  This is very close to, but
 not quite the same as the official Unicode property C<XID_Continue>.  The
 difference is that this returns true only if the input character also matches
-L</isWORDCHAR>.  See the L<top of this section|/Character classes> for an
+L</isWORDCHAR>.  See the L<top of this section|/Character classification> for
+an
 explanation of variants C<isIDCONT_A>, C<isIDCONT_L1>, C<isIDCONT_uni>,
 C<isIDCONT_utf8>, C<isIDCONT_LC>, C<isIDCONT_LC_uvchr>, and
 C<isIDCONT_LC_utf8>.

inline.h

@@ -252,6 +252,8 @@ S__is_utf8_char_slow(const U8 *s, const U8 *e)
 /* ------------------------------- perl.h ----------------------------- */
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc AiR|bool|is_safe_syscall|const char *pv|STRLEN len|const char *what|const char *op_name
 
 Test that the given C<pv> doesn't contain any internal C<NUL> characters.

mathoms.c

@@ -28,8 +28,16 @@
  *
  * The compilation of this file can be suppressed; see INSTALL
  *
+=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:
+C<-Accflags='-DNO_MATHOMS'>
+
+=cut
+
  */
 
+
 #include "EXTERN.h"
 #define PERL_IN_MATHOMS_C
 #include "perl.h"

op.c

@@ -643,6 +643,8 @@ Perl_allocmy(pTHX_ const char *const name, const STRLEN len, const U32 flags)
 }
 
 /*
+=head1 Optree Manipulation Functions
+
 =for apidoc alloccopstash
 
 Available only under threaded builds, this function allocates an entry in
@@ -1084,7 +1086,6 @@ Perl_op_contextualize(pTHX_ OP *o, I32 context)
 }
 
 /*
-=head1 Optree Manipulation Functions
 
 =for apidoc Am|OP*|op_linklist|OP *o
 This function is the implementation of the L</LINKLIST> macro.  It should
@@ -12351,9 +12352,9 @@ Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr, const XOP *xop)
 }
 
 /*
-=head1 Functions in file op.c
 
 =for apidoc core_prototype
+
 This function assigns the prototype of the named core function to C<sv>, or
 to a new mortal SV if C<sv> is NULL.  It returns the modified C<sv>, or
 NULL if the core function has no prototype.  C<code> is a code as returned

perl.h

@@ -2582,6 +2582,8 @@ typedef SV PADNAME;
 #endif
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv
 Provides system-specific tune up of the C runtime environment necessary to
 run Perl interpreters.  This should be called only once, before creating

pod/perlclib.pod

@@ -154,7 +154,7 @@ There are several types of character class tests that Perl implements.
 The only ones described here are those that directly correspond to C
 library functions that operate on 8-bit characters, but there are
 equivalents that operate on wide characters, and UTF-8 encoded strings.
-All are more fully described in L<perlapi/Character classes> and
+All are more fully described in L<perlapi/Character classification> and
 L<perlapi/Character case changing>.
 
 The C library routines listed in the table below return values based on

pp_ctl.c

@@ -1711,6 +1711,9 @@ PP(pp_xor)
 }
 
 /*
+
+=head1 CV Manipulation Functions
+
 =for apidoc caller_cx
 
 The XSUB-writer's equivalent of L<caller()|perlfunc/caller>.  The

pp_pack.c

@@ -810,6 +810,9 @@ first_symbol(const char *pat, const char *patend) {
 }
 
 /*
+
+=head1 Pack and Unpack
+
 =for apidoc unpackstring
 
 The engine implementing the unpack() Perl function.

pp_sys.c

@@ -1247,6 +1247,9 @@ PP(pp_sselect)
 }
 
 /*
+
+=head1 GV Functions
+
 =for apidoc setdefout
 
 Sets PL_defoutgv, the default file handle for output, to the passed in

t/porting/customized.dat

@@ -16,5 +16,5 @@ autodie cpan/autodie/t/utf8_open.t 5295851351c49f939008c5aca6a798742b1e503d
 podlators cpan/podlators/scripts/pod2man.PL f81acf53f3ff46cdcc5ebdd661c5d13eb35d20d6
 podlators cpan/podlators/scripts/pod2text.PL b4693fcfe4a0a1b38a215cfb8985a65d5d025d69
 version cpan/version/lib/version.pm fa9931d4db05aff9a0a6ef558610b1a472d9306e
-version vutil.c 0d8c72b682eb8a5582d5c50ad4d821ef01e368c1
+version vutil.c abd88f59a6e0cfe7b4e45b1859f414042ea254aa
 version vxs.inc 9064aacbdfe42bb584a068f62b505dd11dbb4dc4

utf8.h

@@ -62,13 +62,6 @@
 #define FOLDEQ_S1_ALREADY_FOLDED  (1 << 2)
 #define FOLDEQ_S2_ALREADY_FOLDED  (1 << 3)
 
-/*
-=for apidoc ibcmp_utf8
-
-This is a synonym for (! foldEQ_utf8())
-
-=cut
-*/
 #define ibcmp_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2) \
 		    cBOOL(! foldEQ_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2))
 

util.h

@@ -39,6 +39,8 @@
 #endif		/* VMS */
 
 /*
+=head1 Miscellaneous Functions
+
 =for apidoc ibcmp
 
 This is a synonym for (! foldEQ())

vutil.c

@@ -18,6 +18,8 @@
 #define VERSION_MAX 0x7FFFFFFF
 
 /*
+=head1 Versioning
+
 =for apidoc prescan_version
 
 Validate that a given string can be parsed as a version object, but doesn't