From owner-svn-doc-all@freebsd.org Thu Oct 1 14:34:15 2015 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 3962DA0C183; Thu, 1 Oct 2015 14:34:15 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org (repo.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 2972B14A7; Thu, 1 Oct 2015 14:34:15 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.70]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t91EYF75026632; Thu, 1 Oct 2015 14:34:15 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t91EYFF6026631; Thu, 1 Oct 2015 14:34:15 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201510011434.t91EYFF6026631@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Thu, 1 Oct 2015 14:34:15 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47465 - 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-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 Oct 2015 14:34:15 -0000 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 " The sample configuration files should always have the .sample 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: - @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. + @sample etc/orbit.conf-dist etc/orbit.conf - See &man.pkg-create.8; for more information on - %D and related substitution markers. + or + + @sample %%EXAMPLESDIR%%/orbit.conf etc/orbit.conf + + The format is @sample + sample-file + actual-config-file. @@ -408,17 +396,21 @@ etc/orbit.conf-dist <literal>@sample</literal> - <replaceable>file</replaceable> - - Add the file passed as argument to the plist. + file + [file] - On installation, check for a real file with - just the base name (the name without the - .sample 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 for more - information. + This is used to handle installation of configuration + files, through example files bundled with the package. The + actual, non-sample, file is either the second + filename, if present, or the first filename without the + .sample extension. + + 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 for more information.