X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-export.1.in;h=bd24e36cd1a374447d93e1b249a980ab0d8d5ae4;hp=10e0e152127efe63af9aa32bbe7584159121a8a2;hb=731a41d6d86be9c27e9f1f99bb35ee3772cb0f61;hpb=297e0855665e45708b114048e42befc4654cdbee

diff --git a/doc/imagex-export.1.in b/doc/imagex-export.1.in
index 10e0e152..bd24e36c 100644
--- 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
-\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,
@@ -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
-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
-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
-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
-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
@@ -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
-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
@@ -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 ""
+\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
-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
@@ -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"
-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.
+existed and was already pipable, or was "-" (standard output).
 .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
-pipable.
+pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
 .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
@@ -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
-\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
-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