perlxs.pod: update: Input part, PREINIT sections

Add text for the new '=head2 The XSUB Input Part' section, and rewrite
the existing entry for the PREINIT keyword.

Author: iabyn

dist/ExtUtils-ParseXS/lib/perlxs.pod

@@ -2520,111 +2520,78 @@ stack, then replaces the items on the stack one by one.
 
 =head2 The XSUB Input Part
 
-XXX TBC
-
-XXX NB: the keywords described in L<XSUB Generic Keywords> and L<Sharing
-XSUB bodies> may also appear in this part, plus C<C_ARGS> and
-C<INTERFACE_MACRO>.
+Following an XSUB's declaration part, the body of the XSUB follows. The
+first part of the body is the I<input> part, and is mainly concerned with
+declaring auto variables and assigning to them values extracted from the
+passed parameters. The two main keywords associated with this activity are
+L<PREINIT|/The PREINIT: Keyword> and L<INPUT|/The INPUT: Keyword>. The
+first allows you to inject extra variable declaration lines, while the
+latter used to be needed to specify the type of each parameter, but is now
+mainly of historical interest. This is also the place for the rarely-used
+L<SCOPE|/The SCOPE: Keyword> keyword.
+
+Note that the keywords described in L<XSUB Generic Keywords> and L<Sharing
+XSUB bodies> may also appear in this part, plus the L<C_ARGS|/The C_ARGS:
+Keyword> and L<INTERFACE_MACRO|/The INTERFACE_MACRO: Keyword> keywords.
 
 =head3 The PREINIT: Keyword
 
-The PREINIT: keyword allows extra variables to be declared immediately
-before or after the declarations of the parameters from the INPUT: section
-are emitted.
-
-If a variable is declared inside a CODE: section it will follow any typemap
-code that is emitted for the input parameters.  This may result in the
-declaration ending up after C code, which is C syntax error.  Similar
-errors may happen with an explicit C<;>-type or C<+>-type initialization of
-parameters is used (see L<"Initializing Function Parameters">).  Declaring
-these variables in an INIT: section will not help.
-
-In such cases, to force an additional variable to be declared together
-with declarations of other variables, place the declaration into a
-PREINIT: section.  The PREINIT: keyword may be used one or more times
-within an XSUB.
-
-The following examples are equivalent, but if the code is using complex
-typemaps then the first example is safer.
+    PREINIT:
+        int i;
+        char *prog_name = get_prog_name();
+
+This keyword allows extra variables to be declared and possibly
+initialised immediately before the declarations of auto variables
+generated from any parameter declarations or C<INPUT> lines. Any lines
+following C<PREINIT> until the next keyword (except POD and XS comments)
+are copied out as-is to the C code file. Multiple C<PREINIT> keywords are
+allowed.
+
+It is sometimes needed because in traditional C, all variable
+declarations must come before any statements. While this is no longer a
+restriction in the perl interpreter source since 5.36.0, the C compiler
+flags used when compiling XS code may be different and so, depending on
+the compiler, it may still be necessary to preserve the correct ordering.
+
+Any variable declarations generated by C<INPUT> and lines from C<PREINIT>
+are output in the same order they appear in the XS source, followed by any
+variable declarations generated from the XSUB's parameter declarations.
+These may be followed by statements to initialise those those variables.
+Thus, any variable declarations in a later C<INIT> or C<CODE> block may be
+flagged as a declaration-after-statement.
+
+C<PREINIT> code shouldn't assume that any variables declared earlier have
+already been initialised; initialisation is deferred if the initialisation
+code (typically obtained from a typemap) isn't of the simple C<type var =
+init;> form, or has a default value.
 
-    bool_t
-    rpcb_gettime(timep)
-        time_t timep = NO_INIT
-      PREINIT:
-        char *host = "localhost";
-      CODE:
-        RETVAL = rpcb_gettime(host, &timep);
-      OUTPUT:
-        timep
-        RETVAL
+For example:
 
-For this particular case an INIT: keyword would generate the
-same C code as the PREINIT: keyword.  Another correct, but error-prone example:
+    void
+    foo(int i = 0)
+        PREINIT:
+            int j = 1;
+        CODE:
+            bar(i, j);
 
-    bool_t
-    rpcb_gettime(timep)
-        time_t timep = NO_INIT
-      CODE:
-        char *host = "localhost";
-        RETVAL = rpcb_gettime(host, &timep);
-      OUTPUT:
-        timep
-        RETVAL
+might be translated into C code similar to:
 
-Another way to declare C<host> is to use a C block in the CODE: section:
+    {
+        int j = 1;
+        int i;
 
-    bool_t
-    rpcb_gettime(timep)
-        time_t timep = NO_INIT
-      CODE:
-        {
-            char *host = "localhost";
-            RETVAL = rpcb_gettime(host, &timep);
+        if (items < 1)
+            i = 0;
+        else {
+            i = (int)SvIV(ST(0));
         }
-      OUTPUT:
-        timep
-        RETVAL
-
-The ability to put additional declarations before the typemap entries are
-processed is very handy in the cases when typemap conversions manipulate
-some global state:
-
-    MyObject
-    mutate(o)
-      PREINIT:
-        MyState st = global_state;
-      INPUT:
-        MyObject o;
-      CLEANUP:
-        reset_to(global_state, st);
-
-Here we suppose that conversion to C<MyObject> in the INPUT: section and from
-MyObject when processing RETVAL will modify a global variable C<global_state>.
-After these conversions are performed, we restore the old value of
-C<global_state> (to avoid memory leaks, for example).
-
-There is another way to trade clarity for compactness: INPUT sections allow
-declaration of C variables which do not appear in the parameter list of
-a subroutine.  Thus the above code for mutate() can be rewritten as
-
-    MyObject
-    mutate(o)
-        MyState st = global_state;
-        MyObject o;
-      CLEANUP:
-        reset_to(global_state, st);
-
-and the code for rpcb_gettime() can be rewritten as
+        bar(i, j);
+    }
 
-    bool_t
-    rpcb_gettime(timep)
-        time_t timep = NO_INIT
-        char *host = "localhost";
-      C_ARGS:
-        host, &timep
-      OUTPUT:
-        timep
-        RETVAL
+Usually you could dispense with C<PREINIT> by just wrapping the code in
+C<CODE> blocks in braces, but it may be necessary if the ordering of the
+variable initialisations is sensitive, e.g. if it affected by some
+changing global state.
 
 =head3 The INPUT: Keyword