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 e0ad169aef3712b7f5a6bd77b934c73e6f076ca7..bd24e36cd1a374447d93e1b249a980ab0d8d5ae4 100644 (file)
--- a/doc/imagex-export.1.in
+++ b/doc/imagex-export.1.in
@@ -1,44 +1,49 @@
-.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"

 .SH NAME
 .SH NAME

-imagex-export \- Exports an image from a WIM archive to an existing or new WIM archive
-
+@IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive

 .SH SYNOPSIS
 .SH SYNOPSIS

-\fBimagex export\fR \fISRC_WIMFILE\fR (\fISRC_IMAGE_NUM\fR | \
-\fISRC_IMAGE_NAME\fR | all ) \fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR\] \
-[\fIDEST_IMAGE_DESCRIPTION\fR] [\fIOPTION\fR]...
-
+\fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
+\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESCRIPTION\fR]]
+[\fIOPTION\fR...]

 .SH DESCRIPTION
 .SH DESCRIPTION

-.PP
-

 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
 optionally changing its name and/or description and/or compression type.
 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.
 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
 optionally changing its name and/or description and/or compression type.
 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.

-
-The source image may be specified by \fISRC_IMAGE_NUM\fR, which must be an integer that is
-an index of an image in \fISRC_WIMFILE\fR, starting at 1.  Alternatively, it may be
-the name of an image in \fISRC_WIMFILE\fR, or it may be the keyword "all" to
-specify that all images are to be exported.
-
-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.
+This command is also available as simply \fBwimexport\fR if the appropriate hard
+link or batch file has been installed.
+.PP
+\fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a
+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
+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.
 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.

-
-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
+.PP
+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.
 \fISRC_WIMFILE\fR.

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

 from split WIMs.  However, you cannot export an image to a split WIM.  See
 \fBSPLIT WIMS\fR.
 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
+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
 .TP 6
 \fB--boot\fR
 Specifies that the exported image is to be the bootable image of the destination
 WIM archive.
 .SH OPTIONS
 .TP 6
 \fB--boot\fR
 Specifies that the exported image is to be the bootable image of the destination
 WIM archive.

-
+.IP ""

 If multiple images are being exported, this flag indicates that the image in the
 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
 If multiple images are being exported, this flag indicates that the image in the
 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an


@@ -47,54 +52,87 @@ error.
 \fB--check\fR
 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
 file's integrity if the integrity table is present; additionally, when writing
 \fB--check\fR
 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
 file's integrity if the integrity table is present; additionally, when writing

-\fIDEST_WIMFILE\fR with the new image added, write an integrity table.  If this
-option is not specified, no integrity table is included in \fIDEST_WIMFILE\fR,
-even if there was one before.
+\fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
+If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
+table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
+already existed and it had an integrity table before.
+.TP
+\fB--nocheck\fR
+When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
+integrity table.
+If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
+table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
+already existed and it had an integrity table before.

 .TP
 \fB--compress\fR=\fITYPE\fR
 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
 compression type must be the same as that of \fIDEST_WIMFILE\fR.
 .TP
 \fB--compress\fR=\fITYPE\fR
 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
 compression type must be the same as that of \fIDEST_WIMFILE\fR.

-
+.IP ""

 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
 that of the input WIM file.
 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
 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.
 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
 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
 little bit of space that would otherwise be left as a hole in the WIM.  Also see
 .TP
 \fB--rebuild\fR
 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
 little bit of space that would otherwise be left as a hole in the WIM.  Also see

-\fBimagex optimize\fR.
+\fB@IMAGEX_PROGNAME@ optimize\fR.

 .TP
 \fB--ref\fR="\fIGLOB\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
+existed and was already pipable, or was "-" (standard output).
+.TP
+\fB--not-pipable\fR
+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
+pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).

 .SH SPLIT WIMS
 .SH SPLIT WIMS

-
-You may use \fBimagex 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).
-
-Here's an example.  The names for the split WIMs usually go something like:
-
-.RS
+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
 .PP

+.RS

 .nf
 mywim.swm
 mywim2.swm
 .nf
 mywim.swm
 mywim2.swm


@@ -102,33 +140,42 @@ mywim3.swm
 mywim4.swm
 mywim5.swm
 .RE
 mywim4.swm
 mywim5.swm
 .RE

-
+.PP

 To export the first image of this split WIM to a new or existing WIM file
 "other.wim", run:
 .PP
 .RS
 To export the first image of this split WIM to a new or existing WIM file
 "other.wim", run:
 .PP
 .RS

-imagex export mywim.swm 1 other.wim --ref="mywim*.swm"
+@IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"

 .RE
 .RE

-.PP
-

 .SH NOTES
 .SH NOTES

-
-Unless \fB--rebuild\fR is specified, aborting an \fBimagex export\fR command
-mid-way through has a small chance of corrupting the destination WIM file.
-However, a precaution is taken against this, so it should be very unlikely.  In
-the event of an aborted \fBimagex export\fR, \fBimagex optimize\fR can be run to
-remove extra data that may have been partially appended to the physical
-destination WIM file but not yet incorporated into the structure of the WIM.
-
+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
+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
 .RS
 .PP

-image export boot.wim 2 new.wim --compress=maximum
+@IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum

 .RE
 .PP
 .RE
 .PP

-

 .SH SEE ALSO
 .SH SEE ALSO

-.BR imagex (1)
-
+.BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-optimize (1)