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

[Mathieu Arnold]

Author: mat
Date: Thu Oct  1 14:34:14 2015
New Revision: 47465
URL: https://svnweb.freebsd.org/changeset/doc/47465

Log:
  The @sample keyword can now take two arguments.
  
  Reviewed by:	brd, wblock
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D3755

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 Oct  1 14:34:08 2015	(r47464)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Thu Oct  1 14:34:14 2015	(r47465)
@@ -211,31 +211,19 @@ PLIST_SUB+=	X11I386="@comment "
     <note>
       <para>The sample configuration files should always have the
 	<filename>.sample</filename> suffix.  If for some historical
-	reason using the standard suffix is not possible, use
+	reason using the standard suffix is not possible, or if the
+	sample files come from some other directory, 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>
+      <programlisting>@sample etc/orbit.conf-dist etc/orbit.conf</programlisting>
 
-      <para>See &man.pkg-create.8; for more information on
-	<literal>%D</literal> and related substitution markers.</para>
+      <para>or</para>
+
+      <programlisting>@sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf</programlisting>
+
+      <para>The format is <literal>@sample
+	  <replaceable>sample-file</replaceable>
+	  <replaceable>actual-config-file</replaceable></literal>.</para>
     </note>
   </sect1>
 
@@ -408,17 +396,21 @@ etc/orbit.conf-dist
 
     <sect2 xml:id="plist-keywords-sample">
       <title><literal>@sample</literal>
-	<replaceable>file</replaceable></title>
-
-      <para>Add the file passed as argument to the plist.</para>
+	<replaceable>file</replaceable>
+	[<replaceable>file</replaceable>]</title>
 
-      <para>On installation, check for a <quote>real</quote> file with
-	just the base name (the name without the
-	<filename>.sample</filename> extension).  If the real file is
-	not found, copy the sample file to the base file name.  On
-	deinstallation, remove the configuration file if it has not
-	been modified.  See <xref linkend="plist-config"/> for more
-	information.</para>
+      <para>This is used to handle installation of configuration
+	files, through example files bundled with the package.  The
+	<quote>actual</quote>, non-sample, file is either the second
+	filename, if present, or the first filename without the
+	<filename>.sample</filename> extension.</para>
+
+      <para>This does three things.  First, add the first file passed
+	as argument, the sample file, to the plist.  Then, on
+	installation, if the actual file is not found, copy the sample
+	file to the actual file.  And finally, on deinstallation,
+	remove the actual file if it has not been modified.  See <xref
+	  linkend="plist-config"/> for more information.</para>
     </sect2>
 
     <sect2 xml:id="plist-keywords-shared-mime-info">