Update the slow-porting chapter.

Sponsored by:	Absolight

en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml

@@ -99,10 +99,19 @@
 	  installed.</para>
       </step>
 
+      <step>
+	<para>The <buildtarget>package</buildtarget> target is run.
+	  This creates a package using the files from the temporary
+	  directory created during the
+	  <buildtarget>stage</buildtarget> target and the port's
+	  <filename>pkg-plist</filename>.</para>
+      </step>
+
       <step>
 	<para>The <buildtarget>install</buildtarget> target is run.
-	  This copies the files listed in the port's pkg-plist to the
+	  This install the package created during the
-	  host system.</para>
+	  <buildtarget>package</buildtarget> target into the host
+	  system.</para>
       </step>
     </procedure>
 
@@ -255,9 +264,23 @@
 
     <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
 
+    <sect2>
+      <title>Automatic Patch Generation</title>
+
+      <para>When all the files have been modified, use <command>make
+	  makepatch</command> from the port directory to write updated
+	patch files to the <filename>files</filename> directory of the
+	port.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Manual Patch Generation</title>
+
       <para>Patches are saved into files named
-      <filename>patch-*</filename> where <replaceable>*</replaceable>
+	<filename>patch-*</filename> where
-      indicates the pathname of the file that is patched, such as
+	<replaceable>*</replaceable> indicates the pathname of the
+	file that is patched, such as
 	<filename>patch-Imakefile</filename> or
 	<filename>patch-src-config.h</filename>.</para>
 
@@ -280,30 +303,24 @@
 	where they will be automatically applied.  All patches must be
 	relative to <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, avoid having
+	build is done).  To make fixes and upgrades easier, avoid
-      more than one patch fix the same file (that is,
+	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>).  Note that if the path of
+	<filename>WRKSRC/foobar.c</filename>).  Note that in the path
-      a patched file contains an underscore (<literal>_</literal>)
+	of a patched file the <literal>/</literal> are to be replaced
-      character, the patch needs to have two underscores instead in
+	with two underscores <literal>__</literal>.  For example, to
-      its name.  For example, to patch a file named
+	patch a file named
-      <filename>src/freeglut_joystick.c</filename>, the corresponding
+	<filename>src/freeglut_joystick.c</filename>, the
-      patch should be named
+	corresponding patch should be named
-      <filename>patch-src-freeglut__joystick.c</filename>.</para>
+	<filename>patch-src__freeglut_joystick.c</filename>.</para>
 
       <para>Please only use characters
 	<literal>[-+._a-zA-Z0-9]</literal> for naming patches.  Do not
-      use any other characters besides them.  Do not name patches like
+	use any other characters besides them.  Do not name patches
-      <filename>patch-aa</filename> or <filename>patch-ab</filename>,
+	like <filename>patch-aa</filename> or
-      always mention the path and file name in patch names.</para>
+	<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.  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
@@ -315,9 +332,9 @@
 	<literal>&dollar;RCS</literal>.</para>
 
       <para>Using the recurse (<option>-r</option>) option to
-      &man.diff.1; to generate patches is fine, but please look at the
+	&man.diff.1; to generate patches is fine, but please look at
-      resulting patches to make sure there is no unnecessary junk in
+	the resulting patches to make sure there is no unnecessary
-      there.  In particular, diffs between two backup files,
+	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 it was
@@ -326,37 +343,47 @@
 	<command>configure</command>, do not take the diffs of
 	<command>configure</command> (it often grows to a few thousand
 	lines!).  Instead, define
-      <literal>USE_AUTOTOOLS=autoconf:261</literal> and take the diffs
+	<literal>USE_AUTOTOOLS=autoconf:261</literal> and take the
-      of <filename>configure.in</filename>.</para>
+	diffs of <filename>configure.in</filename>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>General Rules for Patching</title>
 
       <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.  When taking a working
-      piece of functionality from one project to fix similar areas in
+	piece of functionality from one project to fix similar areas
-      another, please be careful: the resulting line patch may be full
+	in another, please be careful: the resulting line patch may be
-      of non-functional changes.  It not only increases the size of
+	full of non-functional changes.  It not only increases the
-      the <application>Subversion</application> repository but makes
+	size of the <application>Subversion</application> repository
-      it hard to find out what exactly caused the problem and what was
+	but makes it hard to find out what exactly caused the problem
-      changed at all.</para>
+	and what was changed at all.</para>
 
       <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
+    </sect2>
-      <filename>Makefile</filename> using the in-place mode of
+
+    <sect2>
+      <title>Simple Automatic Replacements</title>
+
+      <para>Simple replacements can be performed directly from the
+	port <filename>Makefile</filename> using the in-place mode of
 	&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
+      <para>Quite often, software being ported uses the CR/LF
-      in source files.  This may cause problems with further patching,
+	convention in source files.  This may cause problems with
-      compiler warnings, or script execution (like
+	further patching, compiler warnings, or script execution (like
-      <literal>/bin/sh^M not found</literal>.)  To quickly convert all
+	<literal>/bin/sh^M not found</literal>.)  To quickly convert
-      files from CR/LF to just LF, add this entry to the port
+	all files from CR/LF to just LF, add this entry to the port
 	<filename>Makefile</filename>:</para>
 
       <programlisting>USES=	dos2unix</programlisting>
@@ -366,22 +393,24 @@
       <programlisting>USES=	dos2unix
 DOS2UNIX_FILES=	util.c util.h</programlisting>
 
-    <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
+      <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
-      files across subdirectories.  Its argument is a
+	of files across subdirectories.  Its argument is a
-      &man.find.1;-compatible regular expression.  More on the format
+	&man.find.1;-compatible regular expression.  More on the
-      is in &man.re.format.7;.  This option is useful for converting
+	format is in &man.re.format.7;.  This option is useful for
-      all files of a given extension.  For example, convert all source
+	converting all files of a given extension.  For example,
-      code files, leaving binary files intact:</para>
+	convert all source code files, leaving binary files
+	intact:</para>
 
       <programlisting>USES=	dos2unix
 DOS2UNIX_REGEX=	.*\.([ch]|cpp)</programlisting>
 
-    <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
+      <para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
-      invokes <command>find</command> for each element listed in
+	which invokes <command>find</command> for each element listed
-      it.</para>
+	in it.</para>
 
       <programlisting>USES=	dos2unix
 DOS2UNIX_GLOB=	*.c *.cpp *.h</programlisting>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="slow-configure">