From e5711c282bd36fe4ddce6c810de5220e14ba831d Mon Sep 17 00:00:00 2001 From: Mathieu Arnold Date: Fri, 18 Apr 2014 12:06:38 +0000 Subject: [PATCH] Document the new @sample keyword, and move the old way in a note below. Sponsored by: Absolight --- .../books/porters-handbook/plist/chapter.xml | 75 ++++++++++--------- 1 file changed, 39 insertions(+), 36 deletions(-) diff --git a/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml index 71bc2a2c92..71c2807f44 100644 --- a/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml +++ b/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml @@ -189,46 +189,19 @@ lib/X11/oneko/sounds/cat.au edited by the user, and a re-installation will wipe them out. - Instead, install sample file(s) with a - filename.sample 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 .sample - file. You need to handle this in the + Instead, install sample file(s) as + filename.sample, + and for each sample file, add this line to your pkg-plist. - For each configuration file, create the following three - lines in pkg-plist: - - @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 - - 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 - @unexec 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 @exec line - comes after the sample configuration file name. - - To debug any issues, temporarily remove the - -s flag to &man.cmp.1; for more - output. - - See &man.pkg-create.8; for more information on - %D and related substitution markers. + @sample etc/orbit.conf.sample If there is a very good reason not to install a working - configuration file by default, leave the - @exec line out of - pkg-plist and add a - message 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 + pkg-plist, without the @sample + part, and add a message pointing out that the + user must copy and edit the file before the software will work. @@ -241,6 +214,36 @@ etc/orbit.conf.sample %%ETCDIR%% macro should be used in its stead in the pkg-plist file. + + + The sample configuration files should always have the + .sample suffix. If for some historical + reason you cannot use the standard suffix, you can still use + this construct: + + @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 + + 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 + @unexec 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 @exec line + comes after the sample configuration file name. + + To debug any issues, temporarily remove the + -s flag to &man.cmp.1; for more + output. + + See &man.pkg-create.8; for more information on + %D and related substitution markers. +