-.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
and "LZX", instead of "fast" and "maximum", respectively.
.IP ""
As of wimlib v1.6.0, a third compression type, "recovery" or "LZMS", is also
-available. Its use is not recommended because other than wimlib itself, as of
-Windows 8 it is only compatible with WIMGAPI and Windows Setup (not even ImageX
-or Dism). Furthermore, wimlib's LZMS compressor is currently less well
-optimized than its LZX compressor. However, LZMS is the compression algorithm
-used in packed resources created if the \fB--pack-streams\fR option is
-specified.
+available. Its use is generally not recommended because other than wimlib
+itself, as of Windows 8 it is only compatible with WIMGAPI and Windows Setup
+(not even ImageX or Dism). However, LZMS is the compression algorithm used in
+packed resources created if the \fB--pack-streams\fR option is specified.
.TP
\fB--compress-slow\fR
-Like \fB--compress\fR=\fImaximum\fR, but spend even more time compressing the
-data to achieve a very slightly better compression ratio.
+Spend even more time compressing the data to achieve a very slightly better
+compression ratio. This currently only has an effect for LZX ("maximum", the
+default) and LZMS ("recovery") compression.
.TP
\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR. Using this option is not
-recommended because WIM chunk sizes other than the default of 32768 have varying
-levels of compatibility with Microsoft's software (depending on the compression
-type, chunk size, and software version). In addition, wimlib versions before
-1.6.0 do not support alternate chunk sizes. But if you decide to use this
-option regardless, you can choose a chunk size that is a power of 2 greater than
-or equal to 2^15 (32768) up to a maximum determined by the compression format.
-Larger chunks mean larger LZ77 dictionaries and better compression ratios on
-sufficiently large files, but slower random access. For LZX ("maximum")
-compression, the maximum allowed chunk size is 2^21 (2097152), and for XPRESS
-("fast") and LZMS ("recovery") compression, the maximum allowed chunk size is
-2^26 (67108644).
+Set the WIM compression chunk size to \fISIZE\fR. Larger chunks mean larger
+LZ77 dictionaries and better compression ratios on sufficiently large files, but
+slower random access. \fBUsing this option is generally not recommended because
+of the compatibility limitations detailed in the next paragraph.\fR But if you
+decide to use this option regardless, you may choose a chunk size that is a
+power of 2 greater than or equal to 2^15 (32768) up to a maximum determined by
+the compression format. For LZX ("maximum") compression, the maximum allowed
+chunk size is 2^21 (2097152), and for XPRESS ("fast") and LZMS ("recovery")
+compression, the maximum allowed chunk size is 2^26 (67108864).
+.IP ""
+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)
+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.
.TP
-\fB--pack-streams\fR
+\fB--pack-streams\fR, \fB--solid\fR
Create a "solid" archive that compresses multiple unique streams ("files")
together, rather than each unique stream ("file") independently. This can
result in a significantly better compression ratio, but this format greatly
option use a different version number in their header and as of Windows 8 are
only compatible with Windows Setup and WIMGAPI, not even ImageX and Dism.
.IP ""
-Packed resources use a chunk size that is independent of the WIM's "default
-chunk size", the latter of which may be adjusted by the \fB--chunk-size\fR
-option. For compatibility reasons, there is currently no option to change the
-compression algorithm or chunk size used in packed resources.
+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.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
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.
.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
git://wimlib.net / wimlib / blobdiff