imagex-extract.1.in: Add example for wildcard path

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

diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in
index 6d995f5b184779a22ac600a3fa6b6e7734faee3f..eecfb987c8d077fd9813fba22981f0bae31b7bfe 100644 (file)
--- a/doc/imagex-capture.1.in
+++ b/doc/imagex-capture.1.in
@@ -65,13 +65,20 @@ FIFOs, cannot be captured and will be excluded by default.
 Extended attributes.  This mainly includes extensions to the traditional UNIX
 security model, such as SELinux security labels, POSIX ACLs, and capabilities
 labels.
+.IP \[bu]
+Linux file attributes, as can be changed using the \fBchattr\fR (1) utility.
+.PP
+Notes: Timestamps are stored with 100 nanosecond granularity and include last
+modification time (mtime) and last access time (atime), but not last status
+change time (ctime).  Hard links and symbolic links are supported by the WIM
+format and \fIare\fR stored.  Symbolic links are turned into "native" Windows
+symbolic links, or "reparse points"; this process is fully reversible, e.g.
+automatically by \fB@IMAGEX_PROGNAME@ apply\fR, unless the symbolic link target
+contains backslash characters.
 .PP
-Notes: hard links and symbolic links are supported by the WIM format and
-\fIare\fR stored.  (Symbolic links are turned into "native" Windows symbolic
-links via reparse points; this process is reversible, e.g. automatically by
-\fB@IMAGEX_PROGNAME@ apply\fR.)  Timestamps are stored with 100 nanosecond
-granularity and include last modification time (mtime) and last access time
-(atime), but not last status change time (ctime).
+Pedantic note: A limitation of the WIM format prevents the unusual case where a
+single symbolic link file itself has multiple names (hard links); in this
+unlikely case, each symbolic link is stored as an independent file.
 .SH NTFS VOLUME CAPTURE (UNIX)
 This section documents how \fB@IMAGEX_PROGNAME@\fR captures files directly from
 an NTFS volume image on UNIX-like systems.
@@ -162,6 +169,14 @@ the above information, at least to the extent supported by the destination
 filesystem.  One exception is that since encrypted files are stored as
 encrypted, their data will not be available if restored on a Windows system
 that does not have the decryption key.
+.PP
+Pedantic note: since Windows is not fully compatible with its own filesystem
+(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
+NTFS filesystem but are inaccessible to the Windows API, for example two files
+with names differing only in case in the same directory, or a file whose name
+contains certain characters considered invalid by Windows.  If you run into
+problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
+(UNIX)\fR mode from Linux.
 .SH OPTIONS
 .TP 6
 \fB--boot\fR
@@ -215,7 +230,7 @@ compression, the maximum allowed chunk size is 2^26 (67108864).
 For XPRESS and LZX compression, Microsoft's implementation (as of Windows 8)
 does not appear to support alternate chunk sizes; although it will still open
 such files, it will crash, extract the data incorrectly, or report that the data
-is invalid.  For LZMS compression, Micrososft's implementation (as of Windows 8)
+is invalid.  For LZMS compression, Microsoft's implementation (as of Windows 8)
 appears to only support chunk sizes that are powers of 2 between 2^15 (32768)
 and 2^20 (1048576) inclusively.  In addition, wimlib versions before 1.6.0 do
 not support alternate chunk sizes.
@@ -233,7 +248,18 @@ Packed resources use a compression type and chunk size that is independent of
 the WIM's "default compression type" and "default chunk size" (which may be
 adjusted by the \fB--compress\fR and \fB--chunk-size\fR options, respectively).
 For compatibility reasons, \fB@IMAGEX_PROGNAME@ capture\fR currently has no
-option to change the compression type or chunk size used in packed resources.
+option to change the compression type used in packed resources; however, the
+\fB--pack-chunk-size\fR option may be used to set the chunk size.
+.TP
+\fB--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in packed resources.  The
+compression format is LZMS, so the chunk size can be any power of 2 between 2^15
+and 2^26, inclusively.  WIMGAPI (Windows 8) appears to be compatible with all
+these sizes, despite not being compatible with sizes greater than 2^20 in
+non-packed resources.  The default is currently 2^25 (33554432).  Note:
+currently, the LZMS compression algorithm uses about 15 times the chunk size in
+memory per thread, which is about 500 MB per thread for the default pack chunk
+size of 2^25 or 1 GB per thread if you change it to 2^26 (67108864).
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of
@@ -538,9 +564,11 @@ created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
 the \fB--pipable\fR flag was specified.
 .IP \[bu]
 WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
-or as solid archives (with the \fB--pack-streams\fR option) have varying levels
-of compatibility with Microsoft's software.  The best compatibility is achieved
-with WIMGAPI itelf (not ImageX or Dism) on Windows 8 or later.
+or as solid archives (with the \fB--pack-streams\fR option) or with LZMS
+compression (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have
+varying levels of compatibility with Microsoft's software.  The best
+compatibility is achieved with WIMGAPI itself (not ImageX or Dism) on Windows 8
+or later.
 .SH EXAMPLES
 First example:  Create a new WIM 'mywim.wim' with "maximum" (LZX) compression
 that will contain a captured image of the directory tree 'somedir'.  Note that
@@ -554,7 +582,7 @@ or, if the \fBwimcapture\fR hard link or batch file has been installed, the
 abbreviated form can be used:
 .RS
 .PP
-wimcapture somedir mywim.wim
+wimcapture somedir mywim.wim --compress=maximum
 .RE
 .PP
 The remaining examples will use the long form, however.  Next, append the image