From c010f57674665ac1af72bebad8ecac860e5b15ab Mon Sep 17 00:00:00 2001
From: Warren Block <wblock@FreeBSD.org>
Date: Mon, 2 Apr 2012 20:31:56 +0000
Subject: [PATCH] Clarify the configuration files section.

PR:		docs/166541
Submitted by:	Mel Flynn
---
 .../books/porters-handbook/book.sgml          | 31 +++++++++++++++----
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index b9eda982de..318fa575c5 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -9378,20 +9378,39 @@ lib/X11/oneko/sounds/cat.au
 		${CP} -p ${PREFIX}/etc/orbit.conf.sample ${PREFIX}/etc/orbit.conf ; \
 	fi</programlisting>
 
-      <para>Example of the <filename>pkg-plist</filename> part:</para>
+      <para>For each configuration file, create the following three
+	lines in <filename>pkg-plist</filename>:</para>
 
       <programlisting>@unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
 etc/orbit.conf.sample
 @exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>
 
-      <para>For information on the above variables see
-	&man.pkg.create.1;</para>
+      <para>The order of these lines is important.  On deinstallation,
+	the sample file is compared to the actual configuration file.
+	If these files are identical, no changes have been made by the
+	user and the actual file can be safely deleted.  Because the
+	sample file must still exist for the comparison, the
+	<literal>@unexec</literal> line comes before the sample
+	configuration file name.  On installation, if an actual
+	configuration file is not already present, the sample file is
+	copied to the actual file.  The sample file must be present
+	before it can be copied, so the <literal>@exec</literal> line
+	comes after the sample configuration file name.</para>
+
+      <para>To debug any issues, temporarily remove the
+	<literal>-s</literal> flag to &man.cmp.1; for more
+	output.</para>
+
+      <para>See &man.pkg.create.1; for more information on
+	<literal>%D</literal> and related substitution markers.</para>
 
       <para>If there is a very good reason not to install a working
-	configuration file by default, use a <link
+	configuration file by default, leave the
+	<literal>@exec</literal> line out of
+	<filename>pkg-plist</filename> and add a <link
 	  linkend="porting-message">message</link> pointing out that
-	the user has to copy and edit the file before the software can
-	be made to work.</para>
+	the user must copy and edit the file before the software will
+	work.</para>
     </sect1>
 
     <sect1 id="plist-dynamic">