remove dead variable store

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

diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in
index dbacc36d5dfd2696a7b025aa532ec78ee7a90be3..e97d32d71280c5a22fb27fb68431ef0636e53cd6 100644 (file)
--- a/doc/imagex-capture.1.in
+++ b/doc/imagex-capture.1.in
@@ -1,6 +1,6 @@
-.TH IMAGEX "1" "October 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
 .SH NAME
-imagex capture, append \- Capture a WIM image from a directory tree
+imagex-capture, imagex-append \- Capture a WIM image from a directory tree
 
 .SH SYNOPSIS
 \fBimagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
@@ -56,7 +56,9 @@ information from the directory tree:
 .IP \[bu] 4
 File permissions.  The resulting WIM image will not contain any security
 descriptors because the format of the security descriptors is Windows-specific,
-and they cannot contain UNIX file modes.
+and they cannot contain UNIX file modes.  (Exception: see the \fB--unix-data\fR
+option.)
+
 .IP \[bu]
 No alternate data streams will be captured, since these do not exist on
 POSIX-compliant filesystems.  The resulting WIM image will not contain any
@@ -113,6 +115,18 @@ must be the same as that of the existing WIM.  \fITYPE\fR may be "none",
 You may also specify the actual names of the compression algorithms, "XPRESS"
 and "LZX", instead of "fast" and "maximum", respectively.
 .TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data.  Default: autodetect (number of
+processors).  Note: if creating or appending to an uncompressed WIM, additional
+threads will not be used, regardless of this parameter, since no compression
+needs to be done in this case.
+.TP
+\fB--rebuild\fR
+For \fBimagex append\fR: rebuild the entire WIM rather than appending the new
+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.
+.TP
 \fB--flags\fR=\fIEDITIONID\fR
 Specify a string to use in the <FLAGS> element of the XML data for the new
 image.
@@ -175,6 +189,14 @@ used:
 .RE
 .RE
 
+.TP
+\fB--unix-data\fR
+Store the UNIX owner, group, and mode of regular files, symbolic links, and
+directories.  This is done by adding a special alternate data stream to each
+directory entry that contains this information.  Please note that this flag is
+for convenience only, in case you want to use \fBimagex\fR to archive files on
+UNIX.  Microsoft's software will not understand this special information.
+
 .SH NOTES
 
 \fBimage append\fR does not support appending an image to a split WIM.
@@ -188,6 +210,24 @@ type, and \fBimagex\fR always enforces this.
 stream chunk size of 32768.  The only WIMs I've seen that are different from
 this are some pre-Vista WIMs that had a different version number.
 
+Unless \fB--rebuild\fR is specified, aborting an \fBimagex append\fR command
+mid-way through has a small chance of corrupting the WIM file.  However, a
+precaution is taken against this, so it should be very unlikely.  In the event
+of an aborted \fBimagex append\fR, \fBimagex optimize\fR may be run to remove
+extra data that may have been partially appended to the physical WIM file but
+not yet incorporated into the structure of the WIM.
+
+Capturing or appending an image happens in two main phases: (1) scanning the
+directory or NTFS volume to checksum all the files and determine the streams to
+be written, and (2) writing the new streams to the WIM file.  Streams are not
+stored in memory after (1), since there could easily be gigabytes of data;
+instead, they are read again during step (2); however, duplicate streams in the
+image, and streams already existing in any other image in the WIM, are not read
+again.  In the future, it may be possible to introduce the ability to capture an
+image with reading each file only one time, although this mode would have some
+limitations--- for example, a stream might be compressed only to be thrown away
+as a duplicate once it's been checksummed.
+
 .SH EXAMPLES
 Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and
 including an integrity table:
@@ -199,8 +239,8 @@ imagex capture somedir mywim.wim --compress=maximum --check
 Append an image to the WIM we just captured, but do it from a NTFS volume on the
 partition /dev/sda2, and name the image "Windows 7" and give it a description.
 You do not need to specify the compression type, because the WIM already is
-using LZX compression and this cannot be changed.  You need to specify --check
-if you don't want the integrity table to be discarded.
+using LZX compression and this cannot be changed.  You need to specify
+\fB--check\fR if you don't want the integrity table to be discarded.
 .RS
 .PP
 imagex append /dev/sda2 mywim.wim --check "Windows 7" "Warning: This operating