X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=759bbd86e3b0cd02ed4df137f1c5f50ba3232569;hp=7e09a9497d6e41188388a69c9dc1c55a02d9a446;hb=ba0559b8de169592133bc940b6e986e202f4ec9d;hpb=bec7f491bd14b1da3aae7054edd72575dcf77a4f

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 7e09a949..759bbd86 100644
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -1,55 +1,448 @@
-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
-imagex apply \- Extract one image, or all images, from a WIM archive
-
+@IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
 .SH SYNOPSIS
-\fBimagex apply\fR \fIWIMFILE\fR [\fIIMAGE_NUM\fR | \fIIMAGE_NAME\fR | all] \
-\fIDIRECTORY\fR [\fIOPTION\fR]...
-
+\fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
 .SH DESCRIPTION
+\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows
+Imaging (WIM) file \fIWIMFILE\fR.  This command is also available as simply
+\fBwimapply\fR if the appropriate hard link or batch file has been installed.
 .PP
+This command is designed to extract, or "apply", one or more full WIM images.
+If you instead want to extract only certain files or directories contained in a
+WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or
+\fB@IMAGEX_PROGNAME@ mount\fR instead.  (\fB@IMAGEX_PROGNAME@ mount\fR is not
+supported on Windows.)
+.PP
+\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract.  It may be a
+1-based index of an image in \fIWIMFILE\fR, the name of an image in
+\fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR
+are to be extracted.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command to show
+what images a WIM file contains.  \fIIMAGE\fR may be omitted if \fIWIMFILE\fR
+contains only one image.
+.PP
+\fITARGET\fR specifies where to extract the WIM image to.  If \fITARGET\fR
+specifies a directory, the WIM image is extracted to that directory (see
+\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
+Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created
+in that location and the WIM image is extracted to that directory.
+.PP
+If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are
+actually extracted into subdirectories of \fITARGET\fR, each of which is given
+the name of the corresponding image, falling back to the image index in the case
+of an image with no name or a name not valid as a filename.
+.PP
+Alternatively, on UNIX-like systems only, if \fITARGET\fR specifies a regular
+file or block device, it is interpreted as an NTFS volume to which the WIM image
+is to be extracted (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR).  Only a single
+image can be extracted in this mode, and only extracting to the root of the NTFS
+volume (not a subdirectory thereof) is supported.
+.PP
+\fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a
+file, but see \fBPIPABLE WIMS\fR for more information.
+.PP
+\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
+well as split WIMs.  See \fBSPLIT WIMS\fR.
+.SH DIRECTORY EXTRACTION (UNIX)
+This section documents how \fB@IMAGEX_PROGNAME@ apply\fR (and also
+\fB@IMAGEX_PROGNAME@ extract\fR) extract a WIM image (or a possibly a subset
+thereof, in the case of \fB@IMAGEX_PROGNAME@ extract\fR) to a directory on
+UNIX-like systems.  See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
+corresponding documentation for Windows.
 
-\fBimagex apply\fR extracts the specified image from \fIWIMFILE\fR to
-\fIDIRECTORY\fR.
-
-The image to extract may be specified by \fIIMAGE_NUM\fR, which must be an
-integer that is an index of an image in the WIM file, starting at 1.
-Alternatively, it may be the name of an image in the WIM file.  It also may be
-the keyword \fBall\fR, which indicates that all images in the WIM are to be
-extracted. If the keyword \fBall\fR is given, the images are extracted into
-subdirectories of \fIDIRECTORY\fR that will be named after the image names.
-
+As mentioned, a WIM image can be applied to a directory on a UNIX-like system by
+providing a \fITARGET\fR directory.  However, it is important to keep in mind
+that the WIM format was designed for Windows, and as a result WIM files can
+contain data or metadata that cannot be represented on UNIX-like systems.  The
+main information that \fB@IMAGEX_PROGNAME@\fR will \fInot\fR be able to extract
+on UNIX-like systems is the following:
+.IP \[bu] 4
+Windows security descriptors (which include the file owner, group, and ACLs).
+.IP \[bu]
+Named data streams.
+.IP \[bu]
+Reparse points other than symbolic links and junction points.
+.IP \[bu]
+Certain file attributes such as compression, encryption, and sparseness.
+.IP \[bu]
+Short (DOS) names for files.
+.IP \[bu]
+File creation timestamps.
+.PP
+Notes: Unsupported data and metadata is simply not extracted, but
+\fB@IMAGEX_PROGNAME@\fR will attempt to warn you when the contents of the WIM
+image can't be exactly represented when extracted.  Last access and last
+modification timestamps are specified to 100 nanosecond granularity in the WIM
+file, but will only be extracted to the highest precision supported by the
+underlying operating system, C library, and filesystem.  Compressed files will
+be extracted as uncompressed, while encrypted files will not be extracted at
+all.
+.SH NTFS VOLUME EXTRACTION (UNIX)
+This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
+directly to an NTFS volume image on UNIX-like systems.
+.PP
+As mentioned, \fB@IMAGEX_PROGNAME@\fR running on a UNIX-like system can apply a
+WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
+or block device containing an NTFS filesystem.  The NTFS filesystem need not be
+empty, although it's expected that it be empty for the intended use cases.  A
+new NTFS filesystem can be created using the \fBmkntfs\fR(8) command provided
+with \fBntfs-3g\fR.
+.PP
+In this NTFS volume extraction mode, the WIM image is extracted to the root of
+the NTFS volume in a way preserves almost all information contained in the WIM
+image.  It therefore does not suffer from the limitations described in
+\fBDIRECTORY EXTRACTION (UNIX)\fR.  This support relies on libntfs-3g to write
+to the NTFS volume and handle NTFS-specific and Windows-specific data.
+.PP
+Please note that this NTFS volume extraction mode is \fInot\fR entered if
+\fITARGET\fR is a directory, even if an NTFS filesystem is mounted on
+\fITARGET\fR.  You must specify the NTFS volume itself (and it must be
+unmounted, and you must have permission to write to it).
+.PP
+This NTFS volume extraction mode attempts to extract as much information as
+possible, including:
+.IP \[bu] 4
+All data streams of all files except encrypted files, including the unnamed data
+stream as well as all named data streams.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points.
+.IP \[bu]
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
+.IP \[bu]
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
+.IP \[bu]
+DOS/Windows file attribute flags.
+.IP \[bu]
+All names of all files, including names in the Win32 namespace, DOS namespace,
+Win32+DOS namespace, and POSIX namespace.  This includes hard links.
+.PP
+However, there are also several known limitations of the NTFS volume extraction
+mode:
+.IP \[bu] 4
+Encrypted files will not be extracted.
+.IP \[bu]
+Although sparse file attributes will be applied, the full data will be extracted
+to each sparse file, so extracted "sparse" files may not actually contain any
+sparse regions.
+.PP
+Regardless, since almost all information from the WIM image is restored in this
+mode, it is possible to restore an image of an actual Windows installation using
+\fB@IMAGEX_PROGNAME@\fR on UNIX-like systems in addition to with
+\fB@IMAGEX_PROGNAME@\fR on Windows.  In the examples at the end of this manual
+page, there is an example of applying an image from the "install.wim" file
+contained in the installation media for Windows Vista, Windows 7, and Windows 8
+in the "sources" directory.
+.PP
+But in order to actually boot Windows from an applied image, you must understand
+the boot process of Windows versions Vista and later.  Basically, it is the
+following:
+.nr step 1 1
+.IP \n[step]. 3
+The Master Boot Record loads the Volume Boot Record (also called the Boot
+Sector) of the active partition, which is on an NTFS filesystem.  This partition
+is called the "system partition".
+.IP \n+[step].
+The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR).
+.IP \n+[step].
+bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system
+partition".
+.IP \n+[step].
+Based on the information contained in the Boot Configuration Data, a loader for
+the Windows kernel is executed from the "Boot" partition, which is where Windows
+is installed.
+.PP
+So let's say you applied an image from an existing "install.wim" as in the
+example, or you've applied a custom Windows image that you've created using the
+\fB@IMAGEX_PROGNAME@ capture\fR (1) command.  You've just applied the "Boot" partition, or
+the main Windows partition, but there is no "System" partition yet (i.e.  no
+\\BOOTMGR and no \\Boot\\BCD).
+.PP
+A "System" partition can be created created by running the "bcdboot.exe" program
+from within Windows or Windows PE.  Alternatively, you can capture a separate
+WIM image containing the "System" partition.  Or, the "System" partition may the
+same as the "Boot" partition, so the two "partitions" may be combined in one WIM
+image.  However, as the \\Boot\\BCD file contains the Windows bootloader
+configuration, a WIM containing it can only be used on systems where you are
+setting up the same bootloader configuration, including the same partition
+layout.
+.PP
+Besides setting up the files on the "System" partition, don't forget to set the
+bootable flag on it, and have a master boot record that loads the bootable
+partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
+.SH DIRECTORY EXTRACTION (WINDOWS)
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
+natively support Windows-specific and NTFS-specific data.  For best results, the
+target directory should be located on an NTFS volume and \fB@IMAGEX_PROGNAME@\fR
+should be run with Administrator privileges; however, non-NTFS filesystems and
+running without Administrator privileges are also supported.
+.PP
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
+try to extract as much data and metadata as possible, including:
+.IP \[bu] 4
+All data streams of all files.  This includes the default file contents, as well
+as named data streams if supported by the target volume.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points, if supported by the target volume.  (Note: see \fB--rpfix\fR and
+\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
+junctions are extracted.)  However, as per the default security settings of
+Windows, it is impossible to create a symbolic link or junction point without
+Administrator privileges; therefore, you must run \fB@IMAGEX_PROGNAME@\fR as the
+Administrator if you wish to fully restore an image containing symbolic links
+and/or junction points.  (Otherwise, merely a warning will be issued when a
+symbolic link or junction point cannot be extracted due to insufficient
+privileges.)
+.IP \[bu]
+File and directory creation, access, and modification timestamps, to the highest
+resolution supported by the target volume.
+.IP \[bu]
+Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
+specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
+descriptors for individual files or directories may be omitted or only partially
+set if the user does not have permission to set them, which can be a problem if
+\fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
+.IP \[bu]
+File attributes, including hidden, sparse, compressed, encrypted, etc, when
+supported by the filesystem.
+.IP \[bu]
+DOS names (8.3) names of files; however, the failure to set them is not
+considered an error condition.
+.IP \[bu]
+Hard links, if supported by the filesystem.
+.PP
+Additional notes about extracting files on Windows:
+.IP \[bu] 4
+\fB@IMAGEX_PROGNAME@\fR will issue a warning when it is unable to extract the
+exact metadata and data of the WIM image, for example due to features mentioned
+above not being supported by the target filesystem.
+.IP \[bu]
+Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
+plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
+files to filesystems not supporting encryption.  Therefore, on such filesystems,
+encrypted files will not be extracted.  Furthermore, even if encrypted
+files are restored to a filesystem that supports encryption, they will only be
+decryptable if the decryption key is available.
+.IP \[bu]
+Files with names that cannot be represented on Windows will not
+be extracted by default; see \fB--include-invalid-names\fR.
+.IP \[bu]
+Files with full paths over 260 characters (the so-called MAX_PATH) will be
+extracted, but beware that such files will be inaccessible to most Windows
+software and may not be able to be deleted easily.
+.SH SPLIT WIMS
+You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
+\fIWIMFILE\fR argument must specify the first part of the split WIM, while the
+additional parts of the split WIM must be specified in one or more
+\fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
+option, typically only one \fB--ref\fR option is necessary.  For example, the
+names for the split WIM parts usually go something like:
+.RS
+.PP
+.nf
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+.fi
+.PP
+To apply the first image of this split WIM to the directory "dir", run:
+.PP
+.RS
+@IMAGEX_PROGNAME@ apply mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+As a special case, if you are applying an image from standard input from a split
+WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
+option is unneeded; instead you must ensure that all the split WIM parts are
+concatenated together on standard input.  They can be provided in any order,
+with the exception of the first part, which must be first.
+.SH PIPABLE WIMS
+As of wimlib 1.5.0, \fB@IMAGEX_PROGNAME@ apply\fR supports applying a WIM from a
+nonseekable file, such as a pipe, provided that the WIM was captured with
+\fB--pipable\fR (see \fB@IMAGEX_PROGNAME@ capture\fR(1)).  To use standard input
+as the WIM, specify "-" as \fIWIMFILE\fR.  A useful use of this ability is to
+apply an image from a WIM while streaming it from a server.  For example, to
+apply the first image from a WIM file available on a HTTP server to an NTFS
+volume on /dev/sda1, run something like:
+.PP
+.RS
+wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
+.RE
+.PP
+(The above also used the \fBwimapply\fR abbreviation for \fB@IMAGEX_PROGNAME@
+apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
+explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
+with Microsoft's software.  See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more
+information.
+.PP
+It is possible to apply an image from a pipable WIM split into multiple parts;
+see \fBSPLIT WIMS\fR.
 .SH OPTIONS
 .TP 6
 \fB--check\fR
 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present.
 .TP
+\fB--ref\fR="\fIGLOB\fR"
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
+\fIGLOB\fR is listed in quotes because it is interpreted by
+\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
+expansion.
+.TP
+\fB--rpfix\fR, \fB--norpfix\fR
+Set whether to fix targets of absolute symbolic links (reparse points in Windows
+terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
+links that are marked in the WIM image as being fixed are assumed to have
+absolute targets relative to the image root, and therefore \fB@IMAGEX_PROGNAME@
+apply\fR prepends the absolute path to the extraction target directory to their
+targets.  The intention is that you can apply an image containing absolute
+symbolic links and still have them be valid after it has been applied to any
+location.
+.IP ""
+The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
+captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
+.IP ""
+Reparse point fixups are never done in the NTFS volume extraction mode on
+UNIX-like systems.
+.TP
 \fB--hardlink\fR
-When extracting a file from the WIM that is identical to a file that is already
-extracted, create a hard link using \fBlink\fR (3) rather than creating a
-separate file.  Files of this type are already hard linked together inside the
-WIM to save space.
+When extracting a file from the WIM that is identical to a file that has already
+extracted, create a hard link rather than creating a separate file.  This option
+causes all identical files to be hard-linked, overriding the hard link groups
+that are specified in the WIM image(s).  In the case of extracting all images
+from the WIM, files may be hard-linked even if they are in different WIM images.
+.IP ""
+However, hard-linked extraction mode does have some additional quirks.  Named
+data streams will not be extracted, and files can be hard linked even if their
+metadata is not fully consistent.
 .TP
 \fB--symlink\fR
-When extracting a file from the WIM that is identical to a file that is already
-extracted, create a symbolic link using \fBsymlink\fR (3) rather than creating a
-separate file.  Files of this type are already hard linked together inside the
-WIM to save space.
+This option is similar to \fB--hardlink\fR, except symbolic links are created
+instead.
 .TP
-\fB--verbose\fR
-Print the path to of each file or directory within the WIM image as it is extracted.
+\fB--unix-data\fR
+(UNIX-like systems only)  By default, in the directory extraction mode on UNIX,
+\fB@IMAGEX_PROGNAME@ apply\fR will ignore both Windows-style security
+descriptors and UNIX-specific file owners, groups, and modes set when using
+\fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag.  By passing
+\fB--unix-data\fR to \fB@IMAGEX_PROGNAME@ apply\fR instead, this causes this
+UNIX-specific data to be restored when available.  However, by default, if
+\fB@IMAGEX_PROGNAME@\fR does not have permission to set the UNIX owner, group or
+file mode on an extracted file, a warning will be printed and it will not be
+considered an error condition; use \fB--strict-acls\fR to get stricter behavior.
 .TP
-\fB--verify\fR
-This option is currently unsupported.
-
+\fB--no-acls\fR
+Do not restore security descriptors on extracted files and directories.
+.TP
+\fB--strict-acls\fR
+Fail immediately if the full security descriptor of any file or directory cannot
+be set exactly as specified in the WIM file.  If this option is not specified,
+when \fB@IMAGEX_PROGNAME@\fR on Windows does not have permission to set a
+security descriptor on an extracted file, it falls back to setting it only
+partially (e.g. with SACL omitted), and in the worst case omits it entirely.
+However, this should only be a problem when running \fB@IMAGEX_PROGNAME@\fR
+without Administrator rights.  Also, on UNIX-like systems, this flag can also be
+combined with \fB--unix-data\fR to cause \fB@IMAGEX_PROGNAME@\fR to fail
+immediately if the UNIX owner, group, or mode on an extracted file cannot be set
+for any reason.
+.TP
+\fB--include-invalid-names\fR
+Extract files and directories with invalid names by replacing characters and
+appending a suffix rather than ignoring them.  Exactly what is considered an
+"invalid" name is platform-dependent.
+.IP ""
+On POSIX-compliant systems, filenames are case-sensitive and may contain any
+byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
+have an effect in the unlikely case that the WIM image for some reason has a
+filename containing one of these characters.
+.IP ""
+On Windows, filenames are case-insensitive, cannot include the characters '/',
+\'\\0', '\\', ':', '*', '?', '"', '<', '>', or '|', and cannot end with a space
+or period.  Ordinarily, files in WIM images should meet these conditions as
+well. However, it is not guaranteed, and in particular a WIM image captured with
+\fB@IMAGEX_PROGNAME@\fR on a POSIX-compliant system could contain such files.  By
+default, invalid names will be ignored, and if there are multiple names
+differing only in case, one will be chosen to extract arbitrarily; however, with
+\fB--include-invalid-names\fR, all names will be sanitized and extracted in some
+form.
+.SH NOTES
+\fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file
+stream it extracts and verifies that it is the same as the SHA1 message digest
+provided in the WIM file.  It is an error if the message digests don't match.
+It's also considered to be an error if any WIM resources that need to be
+extracted cannot be found in the stream lookup table.  So you can be fairly
+certain that the file streams are extracted correctly, even though
+\fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like Microsoft's
+ImageX does.  Note that this is separate from the integrity table of the WIM,
+which provides SHA1 message digests over raw chunks of the entire WIM file and
+is checked separately if the \fB--check\fR option is specified.
+.PP
+wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
+use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
+rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
+Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
+files until they are first decrypted.
 .SH EXAMPLES
-.IP 
-image apply boot.wim all boot --hardlink
-.LP 
-Extract all images in the WIM 'boot.wim' to the directory 'boot', and hard link
-all identical files.
-
+Extract the first image from the Windows PE image on the Windows Vista/7/8
+installation media to the directory "boot":
+.RS
+.PP
+@IMAGEX_PROGNAME@ apply /mnt/windows/sources/boot.wim 1 boot
+.RE
+.PP
+Same as above, but using the \fBwimapply\fR abbreviation:
+.RS
+.PP
+wimapply /media/windows/sources/boot.wim 1 boot
+.RE
+.PP
+On Windows, apply an image of an entire volume, for example from "install.wim"
+which can be found on the Windows Vista/7/8 installation media:
+.RS
+.PP
+@IMAGEX_PROGNAME@ apply install.wim 1 E:\\
+.RE
+.PP
+Same as above, but running on a UNIX-like system where the corresponding
+partition is /dev/sda2:
+.RS
+.PP
+@IMAGEX_PROGNAME@ apply install.wim 1 /dev/sda2
+.RE
+.PP
+Note that before running either of the above commands, an NTFS filesystem may
+need to be created on the partition, for example with format.exe on Windows or
+\fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems.  For example, you might
+run:
+.RS
+.PP
+mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
+.RE
+.PP
+(Of course don't do that if you don't want to destroy all existing data on the
+partition!)
+.PP
+An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
+WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
+WIMS\fR.
+.PP
+And finally, just for fun, a silly way to recursively copy a directory tree
+\fIsrc\fR to \fIdst\fR (but subject to the documented limitations, e.g.
+platform and filesystem-dependent, of the capture and apply functionality of
+\fB@IMAGEX_PROGNAME@\fR):
+.RS
+.PP
+@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - dst
+.RE
+.PP
 .SH SEE ALSO
-.BR imagex (1)
-
+.BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-capture (1)
+.BR @IMAGEX_PROGNAME@-extract (1)
+.BR @IMAGEX_PROGNAME@-info (1)