Update wimlib-imagex documentation

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

diff --git a/doc/imagex-mount.1.in b/doc/imagex-mount.1.in
index 33102ff9e21049b2657bccc7819149dc0677ec9c..4875b162367f60c5baf099b8c0ace23aee1f0431 100644 (file)
--- a/doc/imagex-mount.1.in
+++ b/doc/imagex-mount.1.in
@@ -1,4 +1,4 @@
-.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-mount, @IMAGEX_PROGNAME@-mountrw, @IMAGEX_PROGNAME@-unmount \- Mount and unmount an image from a WIM archive
 .SH SYNOPSIS
@@ -25,21 +25,16 @@ The WIM image can be unmounted using the \fB@IMAGEX_PROGNAME@ unmount\fR command
 made to a WIM mounted read-write will be discarded unless the \fB--commit\fR
 flag is provided to \fB@IMAGEX_PROGNAME@ unmount\fR.
 .SH SPLIT WIMS
-You may use \fB@IMAGEX_PROGNAME@ mount\fR to mount an image from a split WIM read-only.
-However, you may not mount an image from a split WIM read-write.
+You may use \fB@IMAGEX_PROGNAME@ mount\fR to mount an image from a split WIM
+read-only.  However, you may not mount an image from a split WIM read-write.
 .PP
-The \fIWIMFILE\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 \fIWIMFILE\fR as
-well).
+The \fIWIMFILE\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
-Here's an example.  The names for the split WIMs usually go something like:
 .RS
-.PP
 .nf
 mywim.swm
 mywim2.swm
@@ -48,7 +43,7 @@ mywim4.swm
 mywim5.swm
 .RE
 .PP
-To mount the first image of this split WIM to the directory "dir", we would do:
+To mount the first image of this split WIM to the directory "dir", run:
 .PP
 .RS
 @IMAGEX_PROGNAME@ mount mywim.swm 1 dir --ref="mywim*.swm"
@@ -58,7 +53,7 @@ To mount the first image of this split WIM to the directory "dir", we would do:
 If wimlib was configured using the \fB--without-fuse\fR flag, then the
 \fB@IMAGEX_PROGNAME@ mount\fR, \fB@IMAGEX_PROGNAME@ mountrw\fR, and
 \fB@IMAGEX_PROGNAME@ unmount\fR commands will not work.  Also, these commands
-are not available in the Windows builds of wimlib.
+are not available in the Windows builds of \fB@IMAGEX_PROGNAME@\fR.
 .PP
 You can mount multiple images from a WIM file read-only at the same time, but
 you can only mount one image at a time from a WIM read-write.
@@ -77,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
@@ -93,7 +95,8 @@ If "xattr" (default), named data streams will be accessible through extended
 file attributes, unless this support was disabled when compiling wimlib.  The
 named data streams may be accessed through extended attributes named "user.*",
 where the * is the name of the named data stream.  See \fBsetfattr\fR (1) and
-\fBgetfattr\fR (1).
+\fBgetfattr\fR (1).  Note that this is not an ideal interface, since named data
+streams may be larger than the maximum allowed extended attribute size.
 .IP ""
 If "windows", the named data streams will be accessible by specifying the
 filename, then a colon, then the name of the named data stream; for example,
@@ -109,9 +112,11 @@ Turn on debugging information printed by the FUSE library, and do not fork into
 the background.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM being
-mounted.  This option is valid for \fB@IMAGEX_PROGNAME@ mount\fR but not \fB@IMAGEX_PROGNAME@
-mountrw\fR.  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--staging-dir\fR=\fIDIR\fR
 Store temporary staging files in a subdirectory of the directory \fIDIR\fR.
@@ -168,9 +173,6 @@ the temporary staging directory is deleted.
 .PP
 \fB@IMAGEX_PROGNAME@ unmount\fR runs in a separate process from the process that previously
 ran \fB@IMAGEX_PROGNAME@ mount\fR, and these two processes communicate using POSIX message
-queues.  See \fIsrc/mount_image.c\fR in the sources for details.  Note: As of
-wimlib v1.2.1, \fB@IMAGEX_PROGNAME@ unmount\fR correctly fails with an error within a
-reasonable amount of time (1 second) if the filesystem daemon is abnormally
-terminated.
+queues.  See \fIsrc/mount_image.c\fR in the sources for details.
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)