From nobody@FreeBSD.org  Wed Feb  5 22:50:28 2014
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
	(using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by hub.freebsd.org (Postfix) with ESMTPS id AA744AA9
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  5 Feb 2014 22:50:28 +0000 (UTC)
Received: from oldred.freebsd.org (oldred.freebsd.org [IPv6:2001:1900:2254:206a::50:4])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.freebsd.org (Postfix) with ESMTPS id 9418A1389
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  5 Feb 2014 22:50:28 +0000 (UTC)
Received: from oldred.freebsd.org ([127.0.1.6])
	by oldred.freebsd.org (8.14.5/8.14.7) with ESMTP id s15MoRrK087616
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 5 Feb 2014 22:50:27 GMT
	(envelope-from nobody@oldred.freebsd.org)
Received: (from nobody@localhost)
	by oldred.freebsd.org (8.14.5/8.14.5/Submit) id s15MoRwu087615;
	Wed, 5 Feb 2014 22:50:27 GMT
	(envelope-from nobody)
Message-Id: <201402052250.s15MoRwu087615@oldred.freebsd.org>
Date: Wed, 5 Feb 2014 22:50:27 GMT
From: Ondra Knezour <knezour@weboutsourcing.cz>
To: freebsd-gnats-submit@FreeBSD.org
Subject: The Porters Handbook - better diff description
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         186499
>Category:       docs
>Synopsis:       The Porters Handbook - better diff description
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Feb 05 23:00:00 UTC 2014
>Closed-Date:    Thu Feb 06 16:50:47 UTC 2014
>Last-Modified:  Thu Feb  6 17:00:00 UTC 2014
>Originator:     Ondra Knezour
>Release:        
>Organization:
>Environment:
>Description:
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. 
>How-To-Repeat:

>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.



>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Thu Feb 6 15:29:28 UTC 2014 
Responsible-Changed-Why:  
Take. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=186499 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Thu Feb 6 16:50:14 UTC 2014 
State-Changed-Why:  
Added examles of using diff.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=186499 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/186499: commit references a PR
Date: Thu,  6 Feb 2014 16:49:59 +0000 (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"
 
>Unformatted:
