Add documentation to dh_configpackage.

[geofft@mit.edu: Rename divert/remove to displace/hide, and mention
what happens if transform scripts fail]

Author: jdreed

dh_configpackage

@@ -34,19 +34,164 @@ use Dpkg::Path qw(get_control_path);
 
 =head1 SYNOPSIS
 
-B<dh_configpackage> [S<I<debhelper options>>] [B<-n>]
+B<dh_configpackage> [B<--displace> I<path>] [B<--hide> I<path>] [B<--undisplace> I<path>] [B<--unhide> I<file>] [B<--transform> I<transformation>] [S<I<debhelper options>>] [B<-n>]
 
 =head1 DESCRIPTION
 
-B<dh_configpackage> needs more docs.
+B<dh_configpackage> is a debhelper program to create "configuration
+packages".  These packages provide an ideal way to distribute
+configurations to target systems while still affording local system
+administrators a degree of control over their workstations.  The
+motivation and philosophy behind this style of packaging is described
+in detail on the config-package-dev website.  Configuration packages
+make use of dpkg diversions and maintainer script snippets to provide
+three primary operations: displacing, hiding, and transforming files.
+
+The I<displace> operation consists of replacing a file on the target
+system.  The original file is renamed out of the way and diverted in the
+dpkg database.  The replacement file is then installed by the package,
+and the config-package-dev maintainer script snippets create a symlink
+from the original name.  A common use of this is to install a wrapper
+script for an executable.
+
+The I<transform> operation is a special case of the displace operation.
+At build time, a "transform script" is applied to the original source,
+and the result is used as the replacement in the displace operation.  A
+common use of this is to change one value in a config file without
+needing to re-type the entire config file (and risk bit-rot).
+
+The I<hide> operation is yet another special case of the displace
+operation, namely that there is no replacement or symlink.  Instead, the
+file is diverted to a unique path on the target system, thus preserving
+its contents.  A common use of this is to suppress a snippet file in a
+configuration directory (e.g. /etc/foo.d), thus disabling a specific
+operation or configuration.
+
+The I<displace extension> is a suffix appended to the diverted versions
+of files, and this suffix plus the string "-orig" is appended to the
+original versions of the files.  The default value is the first word of
+the package name.  For example, the extension for debathena-bin-example
+would be ".debathena".  So if debathena-bin-example displaced /bin/true,
+the original /bin/true would be found at /bin/true.debathena-orig and
+the new version (installed by e.g. dh_install) found at
+/bin/true.debathena.  /bin/true itself would become a symbolic link.
+(For the remainder of this documentation, ".debathena" will be used as
+the displace extension.)
+
+=head1 FILES
+
+=over 4
+
+=item debian/I<package>.displace
+
+List the files to displace, one per line, including the full path and
+displace extension.  For example, to displace /usr/bin/true to
+/usr/bin/true.debathena, you would list "/usr/bin/true.debathena" in
+the file.  (As with other Debhelper commands, you can omit the initial
+leading slash in pathnames in the package, but these examples retain
+it.)
+
+=item debian/I<package>.hide
+
+List the files to hide, one per line, including the full path and
+displace extension.  As noted above, these files won't actually be
+removed, but merely diverted and renamed to a unique path below
+/usr/share/I<package>.
+
+=item debian/I<package>.undisplace
+
+List the files to undisplace, one per line, including the full path and
+displace extension.  B<NOTE:> This is only needed when a new version of
+the package no longer needs to displace a file (for example, if an
+upstream bug was fixed).  Packages automatically undo all operations
+upon removal or deconfiguration.
+
+=item debian/I<package>.unhide
+
+List the files to unhide, one per line, including the full path
+and displace extension.  B<NOTE:> As with undisplace, this is only needed
+when a new version of the package no longer needs to hide a file.
+
+=item debian/I<package>.transform
+
+Each line in the file specifies a transformation.  A transformation
+consists of two space-separated fields: the full path of the
+target file including the displace extension and the transformation
+command itself.  The transformation can either be a single shell
+command, or an executable file in the debian directory.  The
+transformation takes the original source of the file on stdin and prints
+its transformation on stdout.  Transformations are typically performed
+by perl, sed, or awk, but there is no limitation on what can be used as
+a transformation.
+
+For example, to transform /etc/school.conf by replacing all
+occurrences of the word 'Harvard' with the word 'MIT', you might
+specify the following line:
+
+ /etc/school.conf.debathena sed -e 's/Harvard/MIT/g'
+
+Or, storing the command in a separate script:
+
+ /etc/school.conf.debathena debian/transform_school.conf.pl
+
+If the transformation script fails, the package build fails. You can use
+this with e.g. Perl's C<or die> syntax to make sure that the source
+file of the transformation has not changed from what you expected.
+
+I<Transformation sources>: Under normal operation, the source (passed
+on stdin) for the transformation is the name of the diversion without
+the divert extension.  In some cases, you may wish to use a different
+source (e.g. a sample configuration file in /usr/share/doc).  You can
+specify this source as an optional field between the diversion
+filename and the transformation.  This field must begin with a '<'
+immediately followed by the full path to the source.  Taking the
+example above, we might alter it as follows:
+
+ /etc/school.conf.debathena </usr/share/doc/school/conf.example sed -e 's/Harvard/MIT/g'
+
+B<NOTE:> There is no "untransform" operation.  Because a transform
+operation is a special case of a displace operation, the "undisplace"
+operation is the correct way of removing a no-longer-needed
+transformation in future versions of the package.
+
+=item debian/I<package>.displace-extension
+
+This file is used to specify the displace extension for any files
+diverted by this package, if you do not want to accept the default of
+the first word in the package name.  It will not normally be present.
+(See L<"CAVEATS">.)
+
+=back
 
 =head1 OPTIONS
 
 =over 4
 
 =item B<-n>, B<--noscripts>
 
-Do not modify maintainer scripts.
+Do not modify maintainer scripts.  This is a standard debhelper
+option, though you are strongly discouraged from using it except for
+debugging, as these operations rely heavily on the maintainer scripts.
+
+=item B<--displace> I<path>
+
+=item B<--hide> I<path>
+
+=item B<--undisplace> I<path>
+
+=item B<--unhide> I<path>
+
+=item B<--transform> I<transformation>
+
+These options allow for specifying an operation on the command line.
+The argument to the option is the same as a single line of the
+corresponding file, as described above.  You may specify multiple
+occurrences of B<--displace>, or you may invoke B<dh_configpackage>
+repeatedly with different invocations.  The most common use of this
+format is in a rules file when performing conditional operations, in an
+C<override_dh_configpackage> target in the C<rules> file.  See the
+debathena-conffile-example-1.1 package in
+/usr/share/doc/config-package-dev/EXAMPLES for one such use.
 
 =back
 
@@ -279,16 +424,25 @@ foreach my $package (@{$dh{DOPACKAGES}}) {
     }
 }
 
+=head1 CAVEATS
+
+Because the displace extension is automatically generated from the
+package name, renaming the package can have unintended consequences.
+If you must rename a package such that the first component of the name
+changes, specify the old extension using the C<displace-extension> file
+(see above).
+
 =head1 SEE ALSO
 
-L<debhelper(7)>
+L<debhelper(7)>, L<The config-package-dev
+homepage|http://debathena.mit.edu/config-package-dev>
 
 This program is a part of config-package-dev.
 
 =head1 AUTHOR
 
 config-package-dev was written by Anders Kaseorg <andersk@mit.edu> and
 Tim Abbott <tabbott@mit.edu>. The debhelper port is by Geoffrey Thomas
-<geofft@mit.edu>.
+<geofft@mit.edu>.  Documentation by Jonathan Reed <jdreed@mit.edu>.
 
 =cut