-.TH WIMLIB-IMAGEX "1" "November 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
.IP ""
You may also specify the actual names of the compression algorithms, "XPRESS"
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 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
+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. 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--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
+decreases the performance of random access to the data, as may occur on a WIM
+mounted with \fB@IMAGEX_PROGNAME@ mount\fR. Also, WIMs created using this
+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 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
Specify a string to use in the <FLAGS> element of the XML data for the new
image.
.TP
-\fB--verbose\fR
-Print the names of files and directories as they are captured.
-.TP
\fB--dereference\fR
(UNIX-like systems only) Follow symbolic links and archive the files they point
to, rather than archiving the links themselves.
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