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

[Mathieu Arnold]

Author: mat (ports committer)
Date: Fri Apr 18 12:06:38 2014
New Revision: 44602
URL: http://svnweb.freebsd.org/changeset/doc/44602

Log:
  Document the new @sample keyword, and move the old way in a note below.
  
  Sponsored by:	Absolight

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

Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Thu Apr 17 20:33:55 2014	(r44601)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Fri Apr 18 12:06:38 2014	(r44602)
@@ -189,46 +189,19 @@ lib/X11/oneko/sounds/cat.au
       edited by the user, and a re-installation will wipe them
       out.</para>
 
-    <para>Instead, install sample file(s) with a
-      <filename><replaceable>filename</replaceable>.sample</filename> suffix.  Then copy the
-      sample file to the real configuration file name, if it does not
-      already exist.  On deinstall delete the configuration file, but
-      only if it is identical to the <filename>.sample</filename>
-      file.  You need to handle this in the
+    <para>Instead, install sample file(s) as
+      <filename><replaceable>filename</replaceable>.sample</filename>,
+      and for each sample file, add this line to your
       <filename>pkg-plist</filename>.</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
- at exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>
-
-    <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.8; for more information on
-      <literal>%D</literal> and related substitution markers.</para>
+    <programlisting>@sample etc/orbit.conf.sample</programlisting>
 
     <para>If there is a very good reason not to install a working
-      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 must copy and edit the file before the software will
+      configuration file by default, only list the sample filename in
+      <filename>pkg-plist</filename>, without the <literal>@sample
+	</literal> part, and add a <link
+	linkend="porting-message">message</link> pointing out that the
+      user must copy and edit the file before the software will
       work.</para>
 
     <tip>
@@ -241,6 +214,36 @@ etc/orbit.conf.sample
 	<literal>%%ETCDIR%%</literal> macro should be used in its
 	stead in the <filename>pkg-plist</filename> file.</para>
     </tip>
+
+    <note>
+      <para>The sample configuration files should always have the
+	<filename>.sample</filename> suffix.  If for some historical
+	reason you cannot use the standard suffix, you can still use
+	this construct:</para>
+
+      <programlisting>@unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
+etc/orbit.conf-dist
+ at exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>
+
+      <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.8; for more information on
+	<literal>%D</literal> and related substitution markers.</para>
+    </note>
   </sect1>
 
   <sect1 xml:id="plist-dynamic">