Generalized support for referencing resources in external WIMs

[wimlib] / doc / imagex-apply.1.in

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index b7b87a2eca716ea586f0647e1118cdb1d9f9ff3c..0c536df2d51619135926815a126de879cccf5de8 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -74,7 +74,9 @@ Notes: Unsupported data and metadata is simply not extracted, but
 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.
+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.  See \fBDIRECTORY EXTRACTION
@@ -118,11 +120,16 @@ DOS/Windows file attribute flags.
 All names of all files, including names in the Win32 namespace, DOS namespace,
 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
 .PP
-Currently, the only known limitation (in terms of exactly extracting all data
-and metadata) is that the extraction of encrypted files is not expected to work
-properly.
+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
-Since all (or almost all) information from the WIM image is restored in this
+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
@@ -215,10 +222,10 @@ 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.  (The current behavior is to
-just extract the encrypted data anyway.)  Furthermore, even if encrypted files
-are restored to a filesystem that supports encryption, they will only be
-decryptable if the decryption key is available.
+files to filesystems not supporting encryption.  Therefore, such files are not
+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.
@@ -228,16 +235,11 @@ Files with full paths over 260 characters (MAX_PATH) are extracted by using the
 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 is used to specify the first part of the split WIM, and
-the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
-that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
-be a single string on the command line, so \fIGLOB\fR must be quoted so that it
-is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
-the split WIM, except optionally the first part which may either omitted or
-included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
-well).
-.PP
-Here's an example.  The names for the split WIMs usually go something like:
+\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
@@ -287,8 +289,11 @@ When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM being
-applied.  See \fBSPLIT_WIMS\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