svn commit: r43808 - head/en_US.ISO8859-1/books/porters-handbook

[Warren Block]

Author: wblock
Date: Thu Feb  6 17:43:17 2014
New Revision: 43808
URL: http://svnweb.freebsd.org/changeset/doc/43808

Log:
  Improve this section grammatically and systematically.
  
  Reviewed by:	bapt, mat (in slightly earlier forms)

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 17:42:21 2014	(r43807)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Thu Feb  6 17:43:17 2014	(r43808)
@@ -804,10 +804,10 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	<filename>patch-src-freeglut__joystick.c</filename>.</para>
 
       <para>Please only use characters
-	<literal>[-+._a-zA-Z0-9]</literal> for naming your patches.
+	<literal>[-+._a-zA-Z0-9]</literal> for naming patches.
 	Do not use any other characters besides them.  Do not name
-	your patches like <filename>patch-aa</filename> or
-	<filename>patch-ab</filename> etc, always mention the path and
+	patches like <filename>patch-aa</filename> or
+	<filename>patch-ab</filename>, always mention the path and
 	file name in patch names.</para>
 
       <para>There is an alternate, easier method for creating patches to existing files.
@@ -845,8 +845,8 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
       <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
+	base, but obey different style and indenting rules.  When
+	taking a working piece of functionality from one project to fix
 	similar areas in another, please be careful: the resulting
 	line patch may be full of non-functional changes.  It not only
 	increases the size of the
@@ -854,35 +854,39 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	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
+      <para>If a file must be deleted, do it in the
 	<buildtarget>post-extract</buildtarget> target rather than as
 	part of the patch.</para>
 
       <para>Simple replacements can be performed directly from the
 	port <filename>Makefile</filename> using the in-place mode of
-	&man.sed.1;.  This is very useful when you need to patch in a
-	variable value.  Example:</para>
+	&man.sed.1;.  This is useful when changes use the value of a variable:</para>
 
       <programlisting>post-patch:
 	@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
 
       <para>Quite often, software being ported uses the CR/LF
-	convention for its source files.  This may cause problems with
-	further patching, compiler warnings, scripts execution (e.g.,
-	<command>/bin/sh^M</command> not found.) To quickly convert
-	all files from CR/LF to just LF, add
-	<literal>USES=dos2unix</literal> to the port
-	<filename>Makefile</filename>.  A list of files to convert can
-	be specified:</para>
-
-      <programlisting>DOS2UNIX_FILES=	util.c util.h</programlisting>
-
-      <para>If you want to convert a group of files across
-	subdirectories, <varname>DOS2UNIX_REGEX</varname> can be used.
-	Its argument is a <command>find</command> compatible regular
+	convention in source files.  This may cause problems with
+	further patching, compiler warnings, or script execution (like
+	<literal>/bin/sh^M not found</literal>.) To quickly convert
+	all files from CR/LF to just LF, add this entry
+	to the port
+	<filename>Makefile</filename>:</para>
+
+      <programlisting>USES=	dos2unix</programlisting>
+
+      <para>A list of specific files to convert can
+	be given:</para>
+
+      <programlisting>USES=	dos2unix
+DOS2UNIX_FILES=	util.c util.h</programlisting>
+
+      <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
+	of files across subdirectories.
+	Its argument is a &man.find.1;-compatible regular
 	expression.  More on the format is in &man.re.format.7;.  This
 	option is useful for converting all files of a given
-	extension, for example all source code files leaving binary
+	extension.  For example, convert all source code files, leaving binary
 	files intact:</para>
 
       <programlisting>USES=	dos2unix