From owner-svn-doc-head@FreeBSD.ORG Fri Apr 18 12:06:39 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 30952E1B; Fri, 18 Apr 2014 12:06:39 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 11125181A; Fri, 18 Apr 2014 12:06:39 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3IC6ccw026707; Fri, 18 Apr 2014 12:06:38 GMT (envelope-from mat@svn.freebsd.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3IC6cQh026706; Fri, 18 Apr 2014 12:06:38 GMT (envelope-from mat@svn.freebsd.org) Message-Id: <201404181206.s3IC6cQh026706@svn.freebsd.org> From: Mathieu Arnold Date: Fri, 18 Apr 2014 12:06:38 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44602 - head/en_US.ISO8859-1/books/porters-handbook/plist X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 18 Apr 2014 12:06:39 -0000 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. - 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. +