Update wimlib-imagex documentation

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index e9cb05a66e4d8116ae9503acc91d248dae04f3c5..663cad5fd66c8deb8817be3b5bb723b7567bb7d5 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -382,6 +382,12 @@ certain that the file streams are extracted correctly, even though
 ImageX does.  Note that this is separate from the integrity table of the WIM,
 which provides SHA1 message digests over raw chunks of the entire WIM file and
 is checked separately if the \fB--check\fR option is specified.
+.PP
+wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
+use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
+rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
+Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
+files until they are first decrypted.
 .SH EXAMPLES
 Extract the first image from the Windows PE image on the Windows Vista/7/8
 installation media to the directory "boot":

diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in
index 6a0ed43d2c644e9817a35653822251ba9d52673c..8b70c9ba3e301ea585ff0a2369bf0d56c41ab9d4 100644 (file)
--- a/doc/imagex-capture.1.in
+++ b/doc/imagex-capture.1.in
@@ -189,6 +189,14 @@ request a better compression ratio at the cost of more time spent compressing.
 .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 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.
 .TP
 \fB--compress-slow\fR
 Like \fB--compress\fR=\fImaximum\fR, but spend even more time compressing the
@@ -196,13 +204,31 @@ data to achieve a very slightly better compression ratio.
 .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 are not
-supported by Microsoft's software.  But if you decide to use this option
-regardless, you can choose a chunk size that is any power of 2 greater than or
-equal to 2^15 (32768) up to 2^21 (2097152) for LZX ("maximum") compression or
-2^26 (67108864) for XPRESS ("fast") compression.  Larger chunks mean larger LZ77
-dictionaries and better compression ratios on sufficiently large files, but
-slower random access.
+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).
+.TP
+\fB--pack-streams\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 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.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of

diff --git a/doc/imagex-export.1.in b/doc/imagex-export.1.in
index 31ced855e86b23b2e6cdb105373f730c1f4af62c..ba80bf54d119fa905ef452bbad14cce5a9b45205 100644 (file)
--- a/doc/imagex-export.1.in
+++ b/doc/imagex-export.1.in
@@ -74,6 +74,16 @@ that of the input WIM file.
 .IP ""
 You may also specify the actual names of the compression algorithms, "XPRESS"
 and "LZX", instead of "fast" and "maximum", respectively.
+.IP ""
+\fITYPE\fR may also be "recovery" (or "LZMS"); however, this will result in
+reduced compatibility.  See the documentation for this option to
+\fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
+.TP
+\fB--pack-streams\fR
+Create a "solid" archive that compresses multiple files together.  This can
+result in a higher compression ratio, but has disadvantages such as reduced
+compatibility; see the documentation for this option to
+\fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of

diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in
index c3f01031965fdc1126522599bca204081bcf4a11..0a1fca4d05f88e9a73096d0906a7ad009f562cd0 100644 (file)
--- a/doc/imagex-extract.1.in
+++ b/doc/imagex-extract.1.in
@@ -92,6 +92,13 @@ extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 .PP
 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 support extracting files directly to a NTFS volume using libntfs-3g.
+.PP
+wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
+use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
+rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
+Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
+files until they are first decrypted.  Furthermore, such files are not designed
+for random access, so extracting individual files from them may be slow.
 .SH EXAMPLES
 Extract a file from the first image in "boot.wim" to the current directory:
 .RS

diff --git a/doc/imagex-mount.1.in b/doc/imagex-mount.1.in
index caedd08e190a27f95f872ef4cc4b68a14c4604a7..4875b162367f60c5baf099b8c0ace23aee1f0431 100644 (file)
--- a/doc/imagex-mount.1.in
+++ b/doc/imagex-mount.1.in
@@ -72,6 +72,13 @@ rebuilt to make a small change.  But, if you are making many changes to a
 read-write mounted WIM, especially deleting large files, it is suggested to
 provide the \fB--rebuild\fR option to \fB@IMAGEX_PROGNAME@ unmount\fR to force the WIM to
 be rebuilt, or else run \fB@IMAGEX_PROGNAME@ optimize\fR on the WIM afterwards.
+.PP
+wimlib v1.6.0 and later can mount version 3584 WIMs, which usually use packed,
+LZMS-compressed streams and may carry the \fI.esd\fR file extension rather than
+\fI.wim\fR.  However, such files are not designed for random access, so reading
+data from them when mounted may be very slow.  In addition, \fI.esd\fR files
+downloaded directly by the Windows 8 web downloader have encrypted segments, and
+wimlib cannot mount such files until they are first decrypted.
 .SH MOUNT OPTIONS
 .TP 6
 \fB--check\fR

diff --git a/doc/imagex-optimize.1.in b/doc/imagex-optimize.1.in
index c1cf5cb1290a0ea004e526f6340b6558fd09a9b4..c14456fff087e564f8fed048b4b55f2c1c652f74 100644 (file)
--- a/doc/imagex-optimize.1.in
+++ b/doc/imagex-optimize.1.in
@@ -46,16 +46,20 @@ compression about twice as slow and will increase the compression ratio by maybe
 \fB--compress\fR=\fITYPE\fR
 Recompress the WIM file using the specified compression type.  \fITYPE\fR may be
 "none", "fast", or "maximum".  This implies \fB--recompress\fR.
+.IP ""
+\fITYPE\fR may also be "recovery" (or "LZMS"); however, this will result in
+reduced compatibility.  See the documentation for this option to
+\fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
 .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 are not
-supported by Microsoft's software.  But if you decide to use this option
-regardless, you can choose a chunk size that is any power of 2 greater than or
-equal to 2^15 (32768) up to 2^21 (2097152) for LZX ("maximum") compression or
-2^26 (67108864) for XPRESS ("fast") compression.  Larger chunks mean larger LZ77
-dictionaries and better compression ratios on sufficiently large files, but
-slower random access.
+Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
+this option to \fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
+.TP
+\fB--pack-streams\fR
+Create a "solid" archive that compresses multiple files together.  This can
+result in a higher compression ratio, but has disadvantages such as reduced
+compatibility; see the documentation for this option to
+\fB@IMAGEX_PROGNAME@-capture\fR (1) for more details.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of

diff --git a/programs/imagex.c b/programs/imagex.c
index 347564c55a8c3e4787205dc618f033f93212eee1..4800633e07a80254e8fd1ab34532664269e6646e 100644 (file)
--- a/programs/imagex.c
+++ b/programs/imagex.c
@@ -3821,9 +3821,9 @@ T(
 [CMD_APPLY] =
 T(
 "    %"TS" WIMFILE [(IMAGE_NUM | IMAGE_NAME | all)]\n"
-"                    (DIRECTORY | NTFS_VOLUME) [--check] [--hardlink]\n"
-"                    [--symlink] [--ref=\"GLOB\"] [--no-acls] [--strict-acls]\n"
-"                    [--rpfix] [--norpfix] [--include-invalid-names]\n"
+"                    (DIRECTORY | NTFS_VOLUME) [--check] [--ref=\"GLOB\"]\n"
+"                    [--no-acls] [--strict-acls] [--rpfix] [--norpfix]\n"
+"                    [--hardlink] [--symlink] [--include-invalid-names]\n"
 ),
 [CMD_CAPTURE] =
 T(
@@ -3980,9 +3980,11 @@ recommend_man_page(int cmd, FILE *fp)
 {
        const tchar *format_str;
 #ifdef __WIN32__
-       format_str = T("See %"TS".pdf in the doc directory for more details.\n");
+       format_str = T("Uncommon options are not listed;\n"
+                      "See %"TS".pdf in the doc directory for more details.\n");
 #else
-       format_str = T("Try `man %"TS"' for more details.\n");
+       format_str = T("Uncommon options are not listed;\n"
+                      "Try `man %"TS"' for more details.\n");
 #endif
        tfprintf(fp, format_str, get_cmd_string(cmd, true));
 }
@@ -4010,7 +4012,6 @@ usage_all(FILE *fp)
 "    %"TS" --version\n"
 "\n"
 "    The compression TYPE may be \"maximum\", \"fast\", or \"none\".\n"
-"    Uncommon options are not listed; see the documentation for full details.\n"
 "\n"
        );
        tfprintf(fp, extra, invocation_name, invocation_name);