os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Document the new @sample keyword, and move the old way in a note below.

Browse source 
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-04-18 12:06:38 +00:00
parent 9f6c3b13b1
commit e5711c282b
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44602
1 changed files with 39 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
View file

@ -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
@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
@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">