Update wimlib-imagex documentation

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

diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in
index 98e609c69b2b4a83e355a2fd742a1a3734a520bd..0a1fca4d05f88e9a73096d0906a7ad009f562cd0 100644 (file)
--- a/doc/imagex-extract.1.in
+++ b/doc/imagex-extract.1.in
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
 .SH SYNOPSIS
@@ -7,6 +7,8 @@
 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
 \fIWIMFILE\fR.
+This command is also available as simply \fBwimextract\fR if the appropriate hard
+link or batch file has been installed.
 .PP
 \fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
@@ -31,8 +33,9 @@ from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
 extract.  Each path must be specified as an absolute path starting from the root
 of the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1)
-command.  Path separators may be forward slashes on UNIX, or either forward
-slashes or backward slashes on Windows.  The leading slash is optional.
+command.  However, path separators may be either forward or backward slashes,
+and the leading slash is optional; also, on Windows, the paths are treated
+case-insensitively, while on UNIX, paths are treated case-sensitively.
 .PP
 If no \fIPATH\fRs are provided, the default behavior is to extract the full
 image, as if the path "/" had been provided.
@@ -48,12 +51,10 @@ When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
 present.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM.  See
-\fBSPLIT_WIMS\fR.
-.TP
-\fB--verbose\fR
-Print the path of each file or directory within the WIM image as it is
-extracted.
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR.  Note: since \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--unix-data\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
@@ -64,6 +65,9 @@ See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 \fB--strict-acls\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
+\fB--include-invalid-names\fR
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
+.TP
 \fB--to-stdout\fR
 Extract the files to standard output instead of to the filesystem.  This can
 only be provided if all the specified \fIPATH\fRs are to regular files (not
@@ -75,10 +79,11 @@ Extract the files and directories to the directory \fIDIR\fR instead of to the
 current working directory.
 .SH NOTES
 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
-what data and metadata are extracted on UNIX versus on Windows.
+what data and metadata are extracted on UNIX-like systems versus on Windows.
 .PP
-On UNIX, one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@
-mount\fR and then extract the desired files or directories using any standard
+On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
+one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
+and then extract the desired files or directories using any standard
 command-line or graphical program.
 .PP
 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
@@ -87,6 +92,13 @@ extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 .PP
 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 support extracting files directly to a NTFS volume using libntfs-3g.
+.PP
+wimlib v1.6.0 and later can extract files from 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, \fI.esd\fR files downloaded directly by the
+Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
+files until they are first decrypted.  Furthermore, such files are not designed
+for random access, so extracting individual files from them may be slow.
 .SH EXAMPLES
 Extract a file from the first image in "boot.wim" to the current directory:
 .RS
@@ -97,13 +109,21 @@ Extract a file from the first image in "boot.wim" to the current directory:
 Extract a file from the first image in "boot.wim" to standard output:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--to-stdout
+.RE
 .RE
 .PP
 Extract a file from the first image in "boot.wim" to the specified directory:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --dest-dir=somedir
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--dest-dir=somedir
+.RE
 .RE
 .PP
 Extract the "sources" directory from the first image in "boot.wim" to the
@@ -116,7 +136,11 @@ current directory:
 Extract multiple files and directories in one command:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
+.br
+.RS
+/sources /Windows/System32/cmd.exe
+.RE
 .RE
 .PP
 .SH SEE ALSO