better document Miniperl.pm, (mini)perlmain.c

ExtUtils::Miniperl is used to generate both miniperlmain.c and perlmain.c,
but in different ways (via regen and via make respectively).

Update the pod in Miniperl.pm to explain this more clearly, and
imporve the header comment it emits in miniperlmain.c and perlmain.c.

Author: iabyn

ext/ExtUtils-Miniperl/lib/ExtUtils/Miniperl.pm

@@ -8,7 +8,7 @@ use vars qw($VERSION @ISA @EXPORT);
 
 @ISA = qw(Exporter);
 @EXPORT = qw(writemain);
-$VERSION = '1.05';
+$VERSION = '1.06';
 
 # blead will run this with miniperl, hence we can't use autodie or File::Temp
 my $temp;
@@ -36,10 +36,10 @@ sub writemain{
     my(@exts) = @_;
 
     printf $fh <<'EOF!HEAD', xsi_header();
-/*    miniperlmain.c
+/*    miniperlmain.c or perlmain.c - a generated file
  *
  *    Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003,
- *    2004, 2005, 2006, 2007, by Larry Wall and others
+ *    2004, 2005, 2006, 2007, 2016 by Larry Wall and others
  *
  *    You may distribute under the terms of either the GNU General Public
  *    License or the Artistic License, as specified in the README file.
@@ -56,11 +56,18 @@ sub writemain{
 
 /* This file contains the main() function for the perl interpreter.
  * Note that miniperlmain.c contains main() for the 'miniperl' binary,
- * while perlmain.c contains main() for the 'perl' binary.
+ * while perlmain.c contains main() for the 'perl' binary. The typical
+ * difference being that the latter includes Dynaloader.
  *
  * Miniperl is like perl except that it does not support dynamic loading,
  * and in fact is used to build the dynamic modules needed for the 'real'
  * perl executable.
+ *
+ * The content of the body of this generated file is mostly contained
+ * in Miniperl.pm - edit that file if you want to change anything.
+ * miniperlmain.c is generated by running regen/miniperlmain.pl.pl, while
+ * perlmain.c is built automatically by Makefile (so the former is
+ * included in the tarball while the latter isn't).
  */
 
 #ifdef OEMVS
@@ -217,7 +224,7 @@ __END__
 
 =head1 NAME
 
-ExtUtils::Miniperl - write the C code for perlmain.c
+ExtUtils::Miniperl - write the C code for miniperlmain.c and perlmain.c
 
 =head1 SYNOPSIS
 
@@ -230,18 +237,21 @@ ExtUtils::Miniperl - write the C code for perlmain.c
 
 =head1 DESCRIPTION
 
-C<writemain()> takes an argument list of directories containing archive
+C<writemain()> takes an argument list of zero or more directories
+containing archive
 libraries that relate to perl modules and should be linked into a new
-perl binary. It writes a corresponding F<perlmain.c> file that
+perl binary. It writes a corresponding F<miniperlmain.c> or F<perlmain.c>
+file that
 is a plain C file containing all the bootstrap code to make the
 modules associated with the libraries available from within perl.
 If the first argument to C<writemain()> is a reference to a scalar it is
 used as the filename to open for output. Any other reference is used as
 the filehandle to write to. Otherwise output defaults to C<STDOUT>.
 
-The typical usage is from within a Makefile generated by
-L<ExtUtils::MakeMaker>. So under normal circumstances you won't have to
-deal with this module directly.
+The typical usage is from within perl's own Makefile (to build
+F<perlmain.c>) or from F<regen/miniperlmain.pl> (to build miniperlmain.c).
+So under normal circumstances you won't have to deal with this module
+directly.
 
 =head1 SEE ALSO
 

miniperlmain.c

@@ -4,10 +4,10 @@
    Any changes made here will be lost!
  */
 
-/*    miniperlmain.c
+/*    miniperlmain.c or perlmain.c - a generated file
  *
  *    Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003,
- *    2004, 2005, 2006, 2007, by Larry Wall and others
+ *    2004, 2005, 2006, 2007, 2016 by Larry Wall and others
  *
  *    You may distribute under the terms of either the GNU General Public
  *    License or the Artistic License, as specified in the README file.
@@ -24,11 +24,18 @@
 
 /* This file contains the main() function for the perl interpreter.
  * Note that miniperlmain.c contains main() for the 'miniperl' binary,
- * while perlmain.c contains main() for the 'perl' binary.
+ * while perlmain.c contains main() for the 'perl' binary. The typical
+ * difference being that the latter includes Dynaloader.
  *
  * Miniperl is like perl except that it does not support dynamic loading,
  * and in fact is used to build the dynamic modules needed for the 'real'
  * perl executable.
+ *
+ * The content of the body of this generated file is mostly contained
+ * in Miniperl.pm - edit that file if you want to change anything.
+ * miniperlmain.c is generated by running regen/miniperlmain.pl.pl, while
+ * perlmain.c is built automatically by Makefile (so the former is
+ * included in the tarball while the latter isn't).
  */
 
 #ifdef OEMVS