imagex-update.1.in: Explain --command quoting

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

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 94ca6f5d76d326897633234f83a432bb596cc277..b7a1936df829fbd23caa0583f0e75ac16f5ab789 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -193,10 +193,21 @@ considered an error condition.
 .IP \[bu]
 Hard links, if supported by the filesystem.
 .PP
-Note: encrypted files will be extracted as raw encrypted data if the filesystem
-does not support encryption.  Compressed files and directories (with the
-compression attribute set) will be extracted as uncompressed if the filesystem
-does not support transparent compression.
+Additional notes about extracting files on Windows:
+.IP \[bu] 4
+Encrypted files will be extracted as raw encrypted data if the filesystem
+does not support encryption.
+.IP \[bu]
+Compressed files and directories (with the compression attribute set) will be
+extracted as uncompressed if the filesystem does not support transparent
+compression.
+.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 (MAX_PATH) are extracted by using the
+\\\\?\\-prefixed path hack.  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 is used to specify the first part of the split WIM, and
@@ -218,7 +229,7 @@ mywim3.swm
 mywim4.swm
 mywim5.swm
 .RE
-.nf
+.fi
 .PP
 To apply the first image of this split WIM to the directory "dir", run:
 .PP
@@ -289,6 +300,25 @@ with the SACL omitted, then only the default inherited security descriptor, if
 we do not have permission to set the desired one.  On UNIX: with
 \fB--unix-data\fR, fail immediately if the UNIX owner, group, or file 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.  The meaning of this is
+platform-dependent.
+.IP "" 6
+On UNIX, filenames are case-sensitive and may contain any byte except '\\0' and
+\'/', so on UNIX 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 "" 6
+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 UNIX 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