Add some documentation to the heads of the various *.pl build scripts

diff --git a/autodoc.pl b/autodoc.pl
index 325d778..042131e 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -1,4 +1,20 @@
 #!/usr/bin/perl -w
+# 
+# Unconditionally regenerate:
+#
+#    pod/perlintern.pod
+#    pod/perlapi.pod
+#
+# from information stored in
+#
+#    embed.fnc
+#    plus all the .c and .h files listed in MANIFEST
+#
+# Has an optional arg, which is the directory to chdir to before reading
+# MANIFEST and *.[ch].
+#
+# This script is normally invoked as part of 'make all', but is also
+# called from from regen.pl.
 
 use strict;
 

diff --git a/embed.pl b/embed.pl
index f85c5a3..50da232 100755 (executable)
--- a/embed.pl
+++ b/embed.pl
@@ -1,4 +1,26 @@
 #!/usr/bin/perl -w
+# 
+# Regenerate (overwriting only if changed):
+#
+#    embed.h
+#    embedvar.h
+#    global.sym
+#    perlapi.c
+#    perlapi.h
+#    proto.h
+#
+# from information stored in
+#
+#    embed.fnc
+#    intrpvar.h
+#    perlvars.h
+#    pp.sym     (which has been generated by opcode.pl)
+#
+# plus from the values hardcoded into this script in @extvars.
+#
+# Accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
 
 require 5.003; # keep this compatible, an old perl is all we may have before
                 # we build the new one

diff --git a/keywords.pl b/keywords.pl
index 6ede805..7ce010e 100755 (executable)
--- a/keywords.pl
+++ b/keywords.pl
@@ -1,4 +1,15 @@
 #!/usr/bin/perl -w
+# 
+# Regenerate (overwriting only if changed):
+#
+#    keywords.h
+#
+# from information stored in the DATA section of this file.
+#
+# Accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
+
 use strict;
 
 require 'regen_lib.pl';

diff --git a/opcode.pl b/opcode.pl
index 1656893..2cc242f 100755 (executable)
--- a/opcode.pl
+++ b/opcode.pl
@@ -1,4 +1,19 @@
 #!/usr/bin/perl -w
+# 
+# Regenerate (overwriting only if changed):
+#
+#    opcode.h
+#    opnames.h
+#    pp_proto.h
+#    pp.sym
+#
+# from information stored in the DATA section of this file, plus the
+# values hardcoded into this script in @raw_alias.
+#
+# Accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
+
 use strict;
 
 BEGIN {

diff --git a/overload.pl b/overload.pl
index 38331cb..b9c5cc6 100644 (file)
--- a/overload.pl
+++ b/overload.pl
@@ -1,9 +1,18 @@
 #!/usr/bin/perl -w
-
 #
-# Generate overload.h
+# Unconditionally regenerate:
+#
+#    overload.h
+#    overload.c
+#    lib/overload/numbers.pm
+#
+# from information stored in the DATA section of this file.
+#
 # This allows the order of overloading constants to be changed.
-# 
+#
+# Accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
 
 BEGIN {
     # Get function prototypes

diff --git a/reentr.pl b/reentr.pl
index 2fb9ff0..b90c61d 100644 (file)
--- a/reentr.pl
+++ b/reentr.pl
@@ -1,9 +1,20 @@
 #!/usr/bin/perl -w
-
-#
-# Generate the reentr.c and reentr.h,
-# and optionally also the relevant metaconfig units (-U option).
 # 
+# Regenerate (overwriting only if changed):
+#
+#    reentr.h
+#    reentr.c
+#
+# from information stored in the DATA section of this file.
+#
+# With the -U option, it also unconditionally regenerates the relevant
+# metaconfig units:
+#
+#    d_${func}_r.U
+#
+# Also accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
 
 BEGIN {
     # Get function prototypes

diff --git a/regcomp.pl b/regcomp.pl
index 239787a..d4e9402 100644 (file)
--- a/regcomp.pl
+++ b/regcomp.pl
@@ -1,3 +1,18 @@
+#!/usr/bin/perl
+# 
+# Regenerate (overwriting only if changed):
+#
+#    regnodes.h
+#
+# from information stored in
+#
+#    regcomp.sym
+#    regexp.h
+#
+# Accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
+
 BEGIN {
     # Get function prototypes
     require 'regen_lib.pl';

diff --git a/warnings.pl b/warnings.pl
index 2f987c5..c5cdaa8 100644 (file)
--- a/warnings.pl
+++ b/warnings.pl
@@ -1,4 +1,17 @@
 #!/usr/bin/perl
+# 
+# Regenerate (overwriting only if changed):
+#
+#    lib/warnings.pm
+#    warnings.h
+#
+# from information hardcoded into this script (the $tree hash), plus the
+# template for warnings.pm in the DATA section.
+#
+# With an argument of 'tree', just dump the contents of $tree and exits.
+# Also accepts the standard regen_lib -q and -v args.
+#
+# This script is normally invoked from regen.pl.
 
 $VERSION = '1.02_02';