svn commit: r44602 - head/en_US.ISO8859-1/books/porters-handbook/plist
Mathieu Arnold
mat at FreeBSD.org
Fri Apr 18 12:06:39 UTC 2014
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">
More information about the svn-doc-head
mailing list