sixth attempt to silence S_emulate_eaccess compiler warning

[p5sagit/p5-mst-13.2.git] / Porting / patching.pod

diff --git a/Porting/patching.pod b/Porting/patching.pod
index 14b39e2..0b9e484 100644 (file)
--- a/Porting/patching.pod
+++ b/Porting/patching.pod
@@ -2,17 +2,10 @@
 
 patching.pod - Appropriate format for patches to the perl source tree
 
-=head2 Where to get this document
-
-The latest version of this document is available from
-     http://perrin.dimensional.com/perl/perlpatch.html
-
 =head2 How to contribute to this document
 
-You may mail corrections, additions, and suggestions to me
-at dgris@dimensional.com but the preferred method would be
-to follow the instructions set forth in this document and 
-submit a patch 8-).
+You may mail corrections, additions, and suggestions by following the
+instructions set forth in this document and submitting a patch :).
 
 =head1 Description
 
@@ -63,6 +56,10 @@ respectively, unified diffs (where the changed line appears immediately next
 to the original) and context diffs (where several lines surrounding the changes
 are included).  See the manpage for diff for more details.
 
+When GNU diff is available, the pumpkins would prefer you use C<-u -p>
+(--unified --show-c-function) as arguments for optimal control. The
+examples below will only use -u.
+
 The preferred method for creating a unified diff suitable for feeding
 to the patch program is:
 
@@ -81,19 +78,26 @@ diffs.  Some examples using GNU diff:
 
     # generate a patch for a newly added file
     % diff -u /dev/null new/file
-    
+
     # generate a patch to remove a file (patch > v2.4 will remove it cleanly)
     % diff -u old/goner /dev/null
-    
+
     # get additions, deletions along with everything else, recursively
     % diff -ruN olddir newdir
-    
+
     # ignore whitespace
     % diff -bu a/file b/file
-    
+
     # show function name in every hunk (safer, more informative)
+    % diff -u -p old/file new/file
     % diff -u -F '^[_a-zA-Z0-9]+ *(' old/file new/file
 
+    # show sub name in perl files and modules
+    % diff -u -F '^sub' old/file.pm new/file.pm
+
+    # show header in doc patches
+    % diff -u -F '^=head' old/file.pod new/file.pod
+
 =item Derived Files
 
 Many files in the distribution are derivative--avoid patching them.
@@ -140,6 +144,25 @@ you have your changes, you would run makepatch as follows:
               -diff "diff -u" \
               perl-5.7.1@8685 perl-5.7.1@8685-withfoo
 
+=item Binary Files
+
+Since the patch(1) utility cannot deal with binary files, it's important
+that you either avoid the use of binary files in your patch, generate the
+files dynamically, or that you encode any binary files using the
+F<uupacktool.pl> utility.
+
+Assuming you needed to include a gzip-encoded file for a module's test
+suite, you might do this as follows using the F<uupacktool.pl> utility:
+
+    $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
+    Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
+
+This will replace the C<t.gz> file with an encoded counterpart. During
+C<make test>, before any tests are run, perl's Makefile will restore all
+the C<.packed> files mentioned in the MANIFEST to their original name.
+This means that the test suite does not need to be aware of this packing
+scheme and will not need to be altered.
+
 =item Try it yourself
 
 Just to make sure your patch "works", be sure to apply it to the Perl
@@ -344,6 +367,11 @@ found in the headers).  This helps reconcile differing paths between
 the machine the patch was created on and the machine on which it is
 being applied.
 
+Be sure to use the Larry Wall version of patch. Some Operating Systems
+(HP-UX amongst those) have a patch command that does something completely
+different. The correct version of patch will show Larry's name several
+times when invoked as patch --version.
+
 =item Cut and paste
 
 B<Never> cut and paste a patch into your editor.  This usually clobbers
@@ -363,7 +391,7 @@ numbers and offsets in the patch, making it useless.
 If you follow these guidelines it will make everybody's life a little
 easier.  You'll have the satisfaction of having contributed to perl,
 others will have an easy time using your work, and it should be easier
-for the maintainers to coordinate the occasionally large numbers of 
+for the maintainers to coordinate the occasionally large numbers of
 patches received.
 
 Also, just because you're not a brilliant coder doesn't mean that you
@@ -381,14 +409,9 @@ hundreds of patches and that it is B<your> responsibility to integrate
 them into the source.  Obviously you'd want the patches to be as easy
 to apply as possible.  Keep that in mind.  8-)
 
-=head1 Last Modified
-
-Last modified 21 January 1999 
-Daniel Grisinger <dgris@dimensional.com>
-
 =head1 Author and Copyright Information
 
-Copyright (c) 1998, 1999 Daniel Grisinger
+Copyright (c) 1998-2002 Daniel Grisinger
 
 Adapted from a posting to perl5-porters by Tim Bunce (Tim.Bunce@ig.co.uk).