wimexport: Add --compress-slow option

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

diff --git a/doc/imagex-export.1.in b/doc/imagex-export.1.in
index 10e0e152127efe63af9aa32bbe7584159121a8a2..bd24e36cd1a374447d93e1b249a980ab0d8d5ae4 100644 (file)
--- a/doc/imagex-export.1.in
+++ b/doc/imagex-export.1.in
@@ -1,9 +1,9 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"

 .SH NAME
 @IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
 .SH NAME
 @IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR

-\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR\] [\fIDEST_IMAGE_DESCRIPTION\fR]
+\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESCRIPTION\fR]]

 [\fIOPTION\fR...]
 .SH DESCRIPTION
 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
 [\fIOPTION\fR...]
 .SH DESCRIPTION
 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,


@@ -12,19 +12,20 @@ If \fIDEST_WIMFILE\fR exists, it is taken be be a WIM archive to which the image
 will be appended.  Otherwise, it is created as a new WIM archive containing only
 the exported image.
 This command is also available as simply \fBwimexport\fR if the appropriate hard
 will be appended.  Otherwise, it is created as a new WIM archive containing only
 the exported image.
 This command is also available as simply \fBwimexport\fR if the appropriate hard

-link is installed.
+link or batch file has been installed.

 .PP
 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a
 .PP
 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a

-1-based index of an image in the WIM, the name of an image in the WIM, or the
-keyword "all" to indicate that all images are to be exported.  Use the
-\fB@IMAGEX_PROGNAME@ info\fR (1) command to list the images a WIM file contains.
+1-based index of an image in \fISRC_WIMFILE\fR, the name of an image in
+\fISRC_WIMFILE\fR, or the keyword "all" to indicate that all images in
+\fISRC_WIMFILE\fR are to be exported.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
+command to list the images a WIM file contains.

 .PP
 .PP

-If given, \fIDEST_IMAGE_NAME\fR specifies the name to give the image being
-exported to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
+If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being exported
+to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.

 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
 .PP
 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
 .PP

-If given, \fIDEST_IMAGE_DESCRIPTION\fR specifies the description to give the
-image being exported to \fIDEST_WIMFILE\fR.  The default is its description in
+If specified, \fIDEST_IMAGE_DESCRIPTION\fR is the description to give the image
+being exported to \fIDEST_WIMFILE\fR.  The default is its description in

 \fISRC_WIMFILE\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
 \fISRC_WIMFILE\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as


@@ -32,7 +33,9 @@ from split WIMs.  However, you cannot export an image to a split WIM.  See
 \fBSPLIT WIMS\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable
 \fBSPLIT WIMS\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable

-WIM into a (possibly new) pipable WIM, and vice versa.  See \fB--pipable\fR and
+WIM into a (possibly new) pipable WIM, and vice versa.  Furthermore, it will
+export a pipable WIM directly to standard output if "-" is specified as
+\fIDEST_WIMFILE\fR (this implies \fB--pipable\fR).  See \fB--pipable\fR and

 \fB--not-pipable\fR.
 .PP
 .SH OPTIONS
 \fB--not-pipable\fR.
 .PP
 .SH OPTIONS


@@ -71,13 +74,31 @@ 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 ""
 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--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") and
+LZMS ("recovery") compression.  This option does not itself set the compression
+format.
+.TP
+\fB--pack-streams\fR, \fB--solid\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--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.

 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of

-processors).  Note: if exporting to an uncompressed WIM, or exporting to a WIM
-with the same compression type as the source WIM, additional threads will not
-be used, regardless of this parameter, since no data compression needs to be
-done in these cases.
+processors).  Note: multiple compressor threads are not very useful when
+exporting to a WIM with the same compression type as the source WIM, since
+wimlib optimizes this case by re-using the raw compressed data.

 .TP
 \fB--rebuild\fR
 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
 .TP
 \fB--rebuild\fR
 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than


@@ -86,32 +107,30 @@ little bit of space that would otherwise be left as a hole in the WIM.  Also see
 \fB@IMAGEX_PROGNAME@ optimize\fR.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
 \fB@IMAGEX_PROGNAME@ optimize\fR.
 .TP
 \fB--ref\fR="\fIGLOB\fR"

-File glob of additional split WIM parts that are part of the split WIM being
-exported.  See \fBSPLIT_WIMS\fR.
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
+\fIGLOB\fR is listed in quotes because it is interpreted by
+\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
+expansion.

 .TP
 \fB--pipable\fR
 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
 capture\fR(1) for more details about creating pipable WIMs.  The default without
 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
 .TP
 \fB--pipable\fR
 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
 capture\fR(1) for more details about creating pipable WIMs.  The default without
 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already

-existed and was already pipable.
+existed and was already pipable, or was "-" (standard output).

 .TP
 \fB--not-pipable\fR
 .TP
 \fB--not-pipable\fR

-Build, or rebuld, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
+Build, or rebuild, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the

 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already

-pipable.
+pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).

 .SH SPLIT WIMS
 .SH SPLIT WIMS

-You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.  The
-\fISRC_WIMFILE\fR argument is used to specify the first part of the split WIM, and
-the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
-that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
-be a single string on the command line, so \fIGLOB\fR must be quoted so that it
-is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
-the split WIM, except optionally the first part which may either omitted or
-included in the glob (but the first part MUST be specified as \fISRC_WIMFILE\fR as
-well).
-.PP
-Here's an example.  The names for the split WIMs usually go something like:
+You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.
+The \fISRC_WIMFILE\fR argument must specify the first part of the split WIM,
+while the additional parts of the split WIM must be specified in one or more
+\fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
+option, typically only one \fB--ref\fR option is necessary.  For example, the
+names for the split WIM parts usually go something like:

 .PP
 .RS
 .nf
 .PP
 .RS
 .nf


@@ -133,11 +152,24 @@ It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 optimize\fR on the destination WIM to remove any data that was appended to the
 physical WIM file but not yet incorporated into the structure of the WIM, unless
 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 optimize\fR on the destination WIM to remove any data that was appended to the
 physical WIM file but not yet incorporated into the structure of the WIM, unless

-\fB--rebuild\fR was specified, in which case you should delete the temporary
-file left over.
+the WIM was being rebuild (e.g. with \fB--rebuild\fR), in which case you should
+delete the temporary file left over.
+.PP
+Since the WIM format uses single-instancing (streams are content-addressed by
+SHA1 message digests), when an image is exported, only the streams not already
+present in the destination WIM need to be copied.  However, a new copy of the
+image's metadata resource always needs to be created.
+.PP

 .SH EXAMPLES
 .SH EXAMPLES

-Export the second image of 'boot.wim' to the new WIM file 'new.wim', and
-change the compression type to maximum, if it wasn't maximum already:
+Export the second image of 'boot.wim' to the new WIM file 'new.wim':
+.RS
+.PP
+@IMAGEX_PROGNAME@ export boot.wim 2 new.wim
+.RE
+.PP
+The above example creates "new.wim" with the same compression type as
+"boot.wim".  If you wish to change the compression type, specify
+\fB--compress\fR=\fITYPE\fR; for example:

 .RS
 .PP
 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
 .RS
 .PP
 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum