[PATCH: perl@7613] updates to Porting/pumpkin.pod

Here are a few (mostly VMS specific) updates to Porting/pumpkin.pod.
We have been wondering: how likely is it that `make regen_all` will
be done as part of kit assembly (I did not see it mentioned in a quick
look through makerel)?  Thanks.

--- pumpkin.pod.orig	Sun Oct 22 14:35:13 2000
+++ pumpkin.pod	Wed Nov  8 23:04:36 2000
@@ -58,7 +58,7 @@
 
 For compatibility with the older numbering scheme the composite floating
 point version number continues to be available as the magic variable $],
-and amounts to C<$revision + $version/1000 + $subversion/1000000>.  This
+and amounts to C<$revision + $version/1000 + $subversion/100000>.  This
 can still be used in comparisons.
 
 	print "You've got an old perl\n" if $] < 5.005_03;
@@ -112,7 +112,7 @@
 
 =head2 Why is it called the patch pumpkin?
 
-Chip Salzenberg gets credit for that, with a nod to his cow orker,
+Chip Salzenberg gets credit for that, with a nod to his coworker,
 David Croy.  We had passed around various names (baton, token, hot
 potato) but none caught on.  Then, Chip asked:
 
@@ -210,7 +210,7 @@
 line options and possibly existing config.sh and Policy.sh files from
 previous Configure runs.
 
-The extension hints are written Perl (by the time they are used
+The extension hints are written in Perl (by the time they are used
 miniperl has been built) and control the building of their respective
 extensions.  They can be used to for example manipulate compilation
 and linking flags.
@@ -252,7 +252,8 @@
 A file called F<README.youros> at the top level that explains things
 like how to install perl at this platform, where to get any possibly
 required additional software, and for example what test suite errors
-to expect, is nice too.
+to expect, is nice too.  Such files are in the process of being written
+in pod format and will eventually be renamed F<INSTALL.youros>.
 
 You may also want to write a separate F<.pod> file for your operating
 system to tell about existing mailing lists, os-specific modules,
@@ -449,7 +450,9 @@
 to config.sh and then propoagate them to a canned 'config.h' by any
 number of means, including a perl script in win32/ or carrying 
 config.sh and config_h.SH to a Unix system and running sh
-config_h.SH.)
+config_h.SH.)  Vms uses configure.com to generate its own config.sh
+and config.h.  If you want to add a new variable to config.sh check
+with vms folk how to add it to configure.com too.
 XXX]
 
 The Porting/config.sh and Porting/config_H files are provided to
@@ -460,7 +463,7 @@
 Simply edit the existing config_H file; keep the first few explanatory
 lines and then copy your new config.h below.
 
-It may also be necessary to update win32/config.?c, vms/config.vms and
+It may also be necessary to update win32/config.?c, and
 plan9/config.plan9, though you should be quite careful in doing so if
 you are not familiar with those systems.  You might want to issue your
 patch with a promise to quickly issue a follow-up that handles those
@@ -481,8 +484,10 @@
 started to fix F<perly.fixer> to detect this, but I never completed the
 task.
 
-If C<perly.c> changes, make sure you run C<perl vms/vms_yfix.pl> to
-update the corresponding VMS files.  See L<VMS-specific updates>.
+If C<perly.c> or C<perly.h> changes, make sure you run C<perl vms/vms_yfix.pl> 
+to update the corresponding VMS files.  This could be taken care of by 
+the regen_all target in the Unix Makefile.  See also 
+L<VMS-specific updates>.
 
 Some additional notes from Larry on this:
 
@@ -507,6 +512,11 @@
 
 Larry
 
+=head2 make regen_all
+
+This target takes care of the PERLYVMS, regen_headers, and regen_pods
+targets.
+
 =head2 make regen_headers
 
 The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically
@@ -532,6 +542,10 @@
 than answering all the questions and complaints about the failing
 command.
 
+=head2 make regen_pods
+
+Will run `make regen_pods` in the pod directory for indexing. 
+
 =head2 global.sym, interp.sym and perlio.sym
 
 Make sure these files are up-to-date.  Read the comments in these
@@ -541,7 +555,7 @@
 
 If you do change F<global.sym> or F<interp.sym>, think carefully about
 what you are doing.  To the extent reasonable, we'd like to maintain
-souce and binary compatibility with older releases of perl.  That way,
+source and binary compatibility with older releases of perl.  That way,
 extensions built under one version of perl will continue to work with
 new versions of perl.
 
@@ -594,11 +608,11 @@
 =head2 VMS-specific updates
 
 If you have changed F<perly.y> or F<perly.c>, then you most probably want
-to update F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>.
+to update F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>, or
+by running `make regen_all` which will run that script for you.
 
-The Perl version number appears in several places under F<vms>.
-It is courteous to update these versions.  For example, if you are
-making 5.004_42, replace "5.00441" with "5.00442".
+The Perl revision number appears as "perl5" in configure.com.
+It is courteous to update that if necessary.
 
 =head2 Making the new distribution
 
@@ -1353,7 +1367,8 @@
 =item File locking
 
 Somehow, straighten out, document, and implement lockf(), flock(),
-and/or fcntl() file locking.  It's a mess.
+and/or fcntl() file locking.  It's a mess.  See $d_fcntl_can_lock
+in recent config.sh files though.
 
 =back
 
End of Patch.

Peter Prymmer

• [PATCH: perl@7613] updates to Porting/pumpkin.pod by Prymmer/Kahn
• Re: [PATCH: perl@7613] updates to Porting/pumpkin.pod by Jarkko Hietaniemi
• Re: [PATCH: perl@7613] updates to Porting/pumpkin.pod by Prymmer/Kahn