This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Change some =head1 to apidoc_section lines
authorKarl Williamson <khw@cpan.org>
Wed, 26 Aug 2020 23:40:28 +0000 (17:40 -0600)
committerKarl Williamson <khw@cpan.org>
Fri, 4 Sep 2020 22:13:25 +0000 (16:13 -0600)
apidoc_section is slightly favored over head1, as it is known only to
autodoc, and can't be confused with real pod.

22 files changed:
XSUB.h
av.h
cop.h
dump.c
handy.h
inline.h
intrpvar.h
op.c
op.h
pad.c
pad.h
perl.c
perl.h
pp.h
pp_pack.c
regen/unicode_constants.pl
regexec.c
regexp.h
scope.h
sv.c
sv.h
unicode_constants.h

diff --git a/XSUB.h b/XSUB.h
index 5f17a5a..d62dc6c 100644 (file)
--- a/XSUB.h
+++ b/XSUB.h
@@ -200,7 +200,7 @@ is a lexical C<$_> in scope.
 /* Typically used to return values from XS functions.       */
 
 /*
-=head1 Stack Manipulation Macros
+=for apidoc_section Stack Manipulation Macros
 
 =for apidoc Am|void|XST_mIV|int pos|IV iv
 Place an integer into the specified position C<pos> on the stack.  The
@@ -278,7 +278,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 Exception Handling (simple) Macros
+=for apidoc_section Exception Handling (simple) Macros
 
 =for apidoc Amns||dXCPT
 Set up necessary local variables for exception handling.
diff --git a/av.h b/av.h
index 90ebfff..ff954b8 100644 (file)
--- a/av.h
+++ b/av.h
@@ -37,7 +37,7 @@ struct xpvav {
  */
 
 /*
-=head1 Handy Values
+=for apidoc_section AV Handling
 
 =for apidoc ADmnU||Nullav
 Null AV pointer.
diff --git a/cop.h b/cop.h
index cc6e795..d75da94 100644 (file)
--- a/cop.h
+++ b/cop.h
@@ -166,7 +166,7 @@ typedef struct jmpenv JMPENV;
     } STMT_END
 
 /*
-=head1 COP Hint Hashes
+=for apidoc_section COP Hint Hashes
 */
 
 typedef struct refcounted_he COPHH;
@@ -1126,7 +1126,7 @@ typedef struct stackinfo PERL_SI;
 
 
 /*
-=head1 Multicall Functions
+=for apidoc_section Multicall Functions
 
 =for apidoc Amns||dMULTICALL
 Declare local variables for a multicall.  See L<perlcall/LIGHTWEIGHT CALLBACKS>.
diff --git a/dump.c b/dump.c
index 7936008..3134049 100644 (file)
--- a/dump.c
+++ b/dump.c
@@ -21,7 +21,7 @@
  *
  * It also holds the debugging version of the  runops function.
 
-=head1 Display and Dump functions
+=for apidoc_section Display and Dump functions
  */
 
 #include "EXTERN.h"
diff --git a/handy.h b/handy.h
index ff818cc..07aa210 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -369,7 +369,7 @@ Like C<hv_store>, but takes a literal string instead of a
 string/length pair
 and omits the hash parameter.
 
-=head1 Lexer interface
+=for apidoc_section Lexer interface
 
 =for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags
 
@@ -2444,7 +2444,7 @@ typedef U32 line_t;
 #define isALPHA_FOLD_NE(c1, c2) (! isALPHA_FOLD_EQ((c1), (c2)))
 
 /*
-=head1 Memory Management
+=for apidoc_section Memory Management
 
 =for apidoc Am|void|Newx|void* ptr|int nitems|type
 The XSUB-writer's interface to the C C<malloc> function.
index 29ad5a2..41bb4c5 100644 (file)
--- a/inline.h
+++ b/inline.h
@@ -303,7 +303,7 @@ S_sv_or_pv_pos_u2b(pTHX_ SV *sv, const char *pv, STRLEN pos, STRLEN *lenp)
 /* ------------------------------- utf8.h ------------------------------- */
 
 /*
-=head1 Unicode Support
+=for apidoc_section Unicode Support
 */
 
 PERL_STATIC_INLINE void
index 07133dd..f6d8609 100644 (file)
@@ -11,7 +11,7 @@
 #include "handy.h"
 
 /*
-=head1 Per-Interpreter Variables
+=for apidoc_section Per-Interpreter Variables
 */
 
 /* These variables are per-interpreter in threaded/multiplicity builds,
diff --git a/op.c b/op.c
index 8482c80..b27eb0b 100644 (file)
--- a/op.c
+++ b/op.c
@@ -789,7 +789,7 @@ Perl_allocmy(pTHX_ const char *const name, const STRLEN len, const U32 flags)
 }
 
 /*
-=head1 Optree Manipulation Functions
+=for apidoc_section Optree Manipulation Functions
 
 =for apidoc alloccopstash
 
@@ -5789,7 +5789,7 @@ Perl_block_end(pTHX_ I32 floor, OP *seq)
 }
 
 /*
-=head1 Compile-time scope hooks
+=for apidoc_section Compile-time scope hooks
 
 =for apidoc blockhook_register
 
@@ -6336,7 +6336,7 @@ S_gen_constant_list(pTHX_ OP *o)
 }
 
 /*
-=head1 Optree Manipulation Functions
+=for apidoc_section Optree Manipulation Functions
 */
 
 /* List constructors */
@@ -6508,7 +6508,7 @@ Perl_op_convert_list(pTHX_ I32 type, I32 flags, OP *o)
 
 
 /*
-=head1 Optree construction
+=for apidoc_section Optree construction
 
 =for apidoc newNULLLIST
 
@@ -9022,7 +9022,7 @@ Perl_dofile(pTHX_ OP *term, I32 force_builtin)
 }
 
 /*
-=head1 Optree construction
+=for apidoc_section Optree construction
 
 =for apidoc newSLICEOP
 
@@ -10610,7 +10610,7 @@ static void const_av_xsub(pTHX_ CV* cv);
 
 /*
 
-=head1 Optree Manipulation Functions
+=for apidoc_section Optree Manipulation Functions
 
 =for apidoc cv_const_sv
 
@@ -17982,7 +17982,7 @@ Perl_peep(pTHX_ OP *o)
 }
 
 /*
-=head1 Custom Operators
+=for apidoc_section Custom Operators
 
 =for apidoc Perl_custom_op_xop
 Return the XOP structure for a given custom op.  This macro should be
@@ -18386,7 +18386,7 @@ Perl_report_redefined_cv(pTHX_ const SV *name, const CV *old_cv,
 }
 
 /*
-=head1 Hook manipulation
+=for apidoc_section Hook manipulation
 
 These functions provide convenient and thread-safe means of manipulating
 hook variables.
diff --git a/op.h b/op.h
index d660c84..30f808b 100644 (file)
--- a/op.h
+++ b/op.h
@@ -639,7 +639,7 @@ typedef struct {
 
 
 /*
-=head1 Optree Manipulation Functions
+=for apidoc_section Optree Manipulation Functions
 
 =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 {
 };
 
 /*
-=head1 Compile-time scope hooks
+=for apidoc_section Compile-time scope hooks
 
 =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
 
 /*
-=head1 Custom Operators
+=for apidoc_section Custom Operators
 
 =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)
 
 /*
-=head1 Optree Manipulation Functions
+=for apidoc_section Optree Manipulation Functions
 
 =for apidoc Am|const char *|OP_NAME|OP *o
 Return the name of the provided OP.  For core ops this looks up the name
@@ -1060,7 +1060,7 @@ C<sib> is non-null. For a higher-level interface, see C<L</op_sibling_splice>>.
 #define newSUB(f, o, p, b)     newATTRSUB((f), (o), (p), NULL, (b))
 
 /*
-=head1 Hook manipulation
+=for apidoc_section Hook manipulation
 */
 
 #ifdef USE_ITHREADS
diff --git a/pad.c b/pad.c
index cd23fa8..8bcb8b3 100644 (file)
--- a/pad.c
+++ b/pad.c
@@ -19,7 +19,7 @@
  */
 
 /*
-=head1 Pad Data Structures
+=for apidoc_section Pad Data Structures
 
 =for apidoc Amx|PADLIST *|CvPADLIST|CV *cv
 
diff --git a/pad.h b/pad.h
index ac7f528..7ccbdd2 100644 (file)
--- a/pad.h
+++ b/pad.h
@@ -12,7 +12,7 @@
  */
 
 /*
-=head1 Pad Data Structures
+=for apidoc_section Pad Data Structures
 */
 
 
diff --git a/perl.c b/perl.c
index 728ab57..f32686b 100644 (file)
--- a/perl.c
+++ b/perl.c
@@ -2877,7 +2877,7 @@ Perl_get_cv(pTHX_ const char *name, I32 flags)
 
 /*
 
-=head1 Callback Functions
+=for apidoc_section Callback Functions
 
 =for apidoc call_argv
 
diff --git a/perl.h b/perl.h
index ec94327..edeb4eb 100644 (file)
--- a/perl.h
+++ b/perl.h
@@ -1404,7 +1404,7 @@ EXTERN_C char *crypt(const char *, const char *);
 #endif
 
 /*
-=head1 Errno
+=for apidoc_section Errno
 
 =for apidoc m|void|SETERRNO|int errcode|int vmserrcode
 
@@ -1507,7 +1507,7 @@ was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>.
 #endif
 
 /*
-=head1 Warning and Dieing
+=for apidoc_section Warning and Dieing
 
 =for apidoc Amn|SV *|ERRSV
 
diff --git a/pp.h b/pp.h
index 4805dfb..884343c 100644 (file)
--- a/pp.h
+++ b/pp.h
@@ -11,7 +11,7 @@
 #define PP(s) OP * Perl_##s(pTHX)
 
 /*
-=head1 Stack Manipulation Macros
+=for apidoc_section Stack Manipulation Macros
 
 =for apidoc AmnU||SP
 Stack pointer.  This is usually handled by C<xsubpp>.  See C<L</dSP>> and
index 53d63f9..195c7ea 100644 (file)
--- a/pp_pack.c
+++ b/pp_pack.c
@@ -804,7 +804,7 @@ first_symbol(const char *pat, const char *patend) {
 
 /*
 
-=head1 Pack and Unpack
+=for apidoc_section Pack and Unpack
 
 =for apidoc unpackstring
 
index b2c8c36..e5e015f 100644 (file)
@@ -29,7 +29,7 @@ print $out_fh <<END;
  *                with no additional suffix are both string constants */
 
 /*
-=head1 Unicode Support
+=for apidoc_section Unicode Support
 
 =for apidoc AmnU|const char *|BOM_UTF8
 
index e763c0a..91fb3d2 100644 (file)
--- a/regexec.c
+++ b/regexec.c
@@ -10700,7 +10700,7 @@ Perl_is_grapheme(pTHX_ const U8 * strbeg, const U8 * s, const U8 * strend, const
 }
 
 /*
-=head1 Unicode Support
+=for apidoc_section Unicode Support
 
 =for apidoc isSCRIPT_RUN
 
index e12c6a9..16fddce 100644 (file)
--- a/regexp.h
+++ b/regexp.h
@@ -252,7 +252,7 @@ typedef struct regexp_engine {
 #define RXapif_REGNAMES_COUNT  0x1000
 
 /*
-=head1 REGEXP Functions
+=for apidoc_section REGEXP Functions
 
 =for apidoc Am|REGEXP *|SvRX|SV *sv
 
diff --git a/scope.h b/scope.h
index 176ac94..3912f2a 100644 (file)
--- a/scope.h
+++ b/scope.h
 
 
 /*
-=head1 Callback Functions
+=for apidoc_section Callback Functions
 
 =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 a857412..ebee022 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -16074,7 +16074,7 @@ Perl_init_constants(pTHX)
 }
 
 /*
-=head1 Unicode Support
+=for apidoc_section Unicode Support
 
 =for apidoc sv_recode_to_utf8
 
diff --git a/sv.h b/sv.h
index c276243..fc1bad2 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -13,7 +13,7 @@
 #endif
 
 /*
-=head1 SV Flags
+=for apidoc_section SV Flags
 
 =for apidoc AmnU||svtype
 An enum of flags for Perl types.  These are found in the file F<sv.h>
index b85b0fc..e434570 100644 (file)
@@ -22,7 +22,7 @@
  *                with no additional suffix are both string constants */
 
 /*
-=head1 Unicode Support
+=for apidoc_section Unicode Support
 
 =for apidoc AmnU|const char *|BOM_UTF8