Bug 186499

Summary:	The Porters Handbook - better diff description
Product:	Documentation	Reporter:	knezour
Component:	Books & Articles	Assignee:	Warren Block <wblock>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description knezour 2014-02-05 23:00:00 UTC

In the 4.4 Patching section of the Porters Handbook first sentence reads as "In the preparation of the port, files that have been added or changed can be picked up with a diff(1) for later feeding to patch(1)."

Inexperienced porter who just started trying may not know which diff options should be used (tested on myself) and default output of diff file new_file can not be used because paths of the files are missing.

Fix: 

Someone better in both the english and ports maintaining than me may suggest change describing appropriate diff usage. I, as inexperienced person, would consider useful something like:

Before changing file make copy of it. Later you can produce patch with command 

diff [-some-magic-options-here] file.original file.changed > patch.file

which can be placed to PATCHDIR to be later fed to patch.

Comment 1 Warren Block freebsd_committer

2014-02-06 15:29:28 UTC

Responsible Changed
From-To: freebsd-doc->wblock

Take.

Comment 2 dfilter service freebsd_committer

2014-02-06 16:49:59 UTC

Author: wblock
Date: Thu Feb  6 16:49:50 2014
New Revision: 43805
URL: http://svnweb.freebsd.org/changeset/doc/43805

Log:
  Add examples of using diff(1), move mention of makepatch into that
  section.
  
  PR:		docs/186499
  Submitted by:	Ondra Knezour <knezour@weboutsourcing.cz>

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml	Thu Feb  6 16:03:48 2014	(r43804)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Thu Feb  6 16:49:50 2014	(r43805)
@@ -756,21 +756,43 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
       <title>Patching</title>
 
       <para>In the preparation of the port, files that have been added
-	or changed can be picked up with a &man.diff.1; for later
-	feeding to &man.patch.1;.  Each patch you wish to apply should
-	be saved into a file named
+	or changed can be recorded with &man.diff.1; for later
+	feeding to &man.patch.1;.  Doing this with a typical file
+	involves saving a copy of the original file before making any
+	changes.</para>
+
+      <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
+
+      <para>Patches are
+	saved into files named
 	<filename>patch-*</filename> where
 	<replaceable>*</replaceable> indicates the pathname of the
 	file that is patched, such as
 	<filename>patch-Imakefile</filename> or
-	<filename>patch-src-config.h</filename>.  These files should
-	be stored in <varname>PATCHDIR</varname> (usually
-	<filename>files/</filename>, from where they will be
+	<filename>patch-src-config.h</filename>.</para>
+
+      <para>After the file has been modified, &man.diff.1; is used to
+	record the differences between the original and the modified
+	version.  <option>-u</option> causes &man.diff.1; to produce
+	<quote>unified</quote> diffs, the preferred form.</para>
+
+      <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> &gt; patch-<replaceable>pathname-file</replaceable></userinput></screen>
+
+      <para>When generating patches for new, added files,
+	<option>-N</option> is added to tell &man.diff.1; to treat the
+	non-existent original file as if it existed but was
+	empty:</para>
+
+      <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> &gt; patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
+
+      <para>Patch files are
+	stored in <varname>PATCHDIR</varname> (usually
+	<filename class="directory">files/</filename>, from where they will be
 	automatically applied.  All patches must be relative to
-	<varname>WRKSRC</varname> (generally the directory your port's
+	<varname>WRKSRC</varname> (generally the directory the port's
 	tarball unpacks itself into, that being where the build is
-	done).  To make fixes and upgrades easier, you should avoid
-	having more than one patch fix the same file (e.g.,
+	done).  To make fixes and upgrades easier, avoid
+	having more than one patch fix the same file (that is,
 	<filename>patch-file</filename> and
 	<filename>patch-file2</filename> both changing
 	<filename>WRKSRC/foobar.c</filename>).
@@ -788,6 +810,13 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	<filename>patch-ab</filename> etc, always mention the path and
 	file name in patch names.</para>
 
+      <para>There is an alternate, easier method for creating patches to existing files.
+	The first steps are the same, make a copy of the unmodified file with an
+	<filename>.orig</filename> extension, then make modifications.
+	Then use <command>make makepatch</command>
+	to write updated patch files to the
+	<filename>files</filename> directory of the port.</para>
+
       <para>Do not put RCS strings in patches.
 	<application>Subversion</application> will mangle them when we
 	put the files into the ports tree, and when we check them out
@@ -798,23 +827,23 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	<literal>&dollar;RCS</literal>.</para>
 
       <para>Using the recurse (<option>-r</option>) option to
-	&man.diff.1; to generate patches is fine, but please take a
-	look at the resulting patches to make sure you do not have any
+	&man.diff.1; to generate patches is fine, but please
+	look at the resulting patches to make sure there is no
 	unnecessary junk in there.  In particular, diffs between two
 	backup files, <filename>Makefile</filename>s when the port
 	uses <command>Imake</command> or GNU
 	<command>configure</command>, etc., are unnecessary and should
-	be deleted.  If you had to edit
+	be deleted.  If it was necessary to edit
 	<filename>configure.in</filename> and run
 	<command>autoconf</command> to regenerate
 	<command>configure</command>, do not take the diffs of
 	<command>configure</command> (it often grows to a few thousand
-	lines!); define <literal>USE_AUTOTOOLS=autoconf:261</literal>
+	lines!).  Instead, define <literal>USE_AUTOTOOLS=autoconf:261</literal>
 	and take the diffs of
 	<filename>configure.in</filename>.</para>
 
-      <para>Also, try to minimize the amount of non-functional
-	whitespace changes in your patches.  It is common in the Open
+      <para>Try to minimize the amount of non-functional
+	whitespace changes in patches.  It is common in the Open
 	Source world for projects to share large amounts of a code
 	base, but obey different style and indenting rules.  If you
 	take a working piece of functionality from one project to fix
@@ -822,7 +851,7 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	line patch may be full of non-functional changes.  It not only
 	increases the size of the
 	<application>Subversion</application> repository but makes it
-	hard to find out what exactly caused the problem and what you
+	hard to find out what exactly caused the problem and what was
 	changed at all.</para>
 
       <para>If you had to delete a file, then you can do it in the
@@ -865,13 +894,6 @@ DOS2UNIX_REGEX=	.*\.([ch]|cpp)</programl
 
       <programlisting>USES=	dos2unix
 DOS2UNIX_GLOB=	*.c *.cpp *.h</programlisting>
-
-      <para>If you want to create a patch file based off of an
-	existing file, you can copy it with an
-	<filename>.orig</filename> extension, and then modify the
-	original one.  The <buildtarget>makepatch</buildtarget> target
-	will write out an appropriate patch file to the
-	<filename>files</filename> directory of the port.</para>
     </sect1>
 
     <sect1 xml:id="slow-configure">
_______________________________________________
svn-doc-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"

Comment 3 Warren Block freebsd_committer

2014-02-06 16:50:14 UTC

State Changed
From-To: open->closed

Added examles of using diff.  Thanks!