More wimlib-imagex man pages updates
authorEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 20:13:53 +0000 (15:13 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 20:13:53 +0000 (15:13 -0500)
12 files changed:
doc/imagex-apply.1.in
doc/imagex-capture.1.in
doc/imagex-delete.1.in
doc/imagex-dir.1.in
doc/imagex-export.1.in
doc/imagex-extract.1.in
doc/imagex-info.1.in
doc/imagex-join.1.in
doc/imagex-mount.1.in
doc/imagex-optimize.1.in
doc/imagex-split.1.in
doc/imagex-update.1.in

index c8a96a0..5b91707 100644 (file)
@@ -3,7 +3,7 @@
 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
 
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
 
 .SH DESCRIPTION
 .PP
 Imaging (WIM) file \fIWIMFILE\fR.
 
 This command is designed to extract, or "apply", one or more full WIM images.
-If you want to extract only certain files or directories contained in a WIM
-image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or \fB@IMAGEX_PROGNAME@
-mount\fR instead.
+If you instead want to extract only certain files or directories contained in a
+WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or
+\fB@IMAGEX_PROGNAME@ mount\fR instead.
 
 \fIIMAGE\fR specifies the WIM image to extract.  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 extracted.  Use the \fB@IMAGEX_PROGNAME@
-info\fR (1) command to show what images a WIM file contains.
+info\fR (1) command to show what images a WIM file contains.  \fIIMAGE\fR may be
+omitted if \fIWIMFILE\fR contains only one image.
 
 \fITARGET\fR specifies where to extract the WIM image(s) to.  If \fITARGET\fR
 specifies a directory, the WIM image(s) are extracted to that directory.  If
@@ -57,9 +58,9 @@ File and directory creation, access, and modification timestamps to the nearest
 100 nanoseconds, if supported by the underlying filesystem, operating system,
 and C library
 .IP \[bu]
-Symbolic links and junction points, although they will not necessarily point to
-the desired location (for example, the target of the link may contain a Windows
-drive letter).
+Symbolic links and junction points.  Drive letters will be stripped.
+(Note: see \fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute
+symbolic links and junctions are applied.)
 
 .PP
 However, in the "normal" mode of extraction on UNIX, the following information
@@ -266,10 +267,12 @@ links that are marked in the WIM image as being fixed are assumed to have
 absolute targets relative to the image root, and therefore have the actual root
 of extraction prepended to their targets.  The intention is that you can apply
 an image containing absolute symbolic links and still have them be valid after
-it's been applied to any location.
+it has been applied to any location.
 
 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
+
+Reparse point fixups are never done in the NTFS extraction mode on UNIX.
 .TP
 \fB--verbose\fR
 Print the path to of each file or directory within the WIM image as it is
index 4b17e42..8623181 100644 (file)
@@ -4,10 +4,10 @@
 
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIIMAGE_DESCRIPTION\fR] [\fIOPTION\fR]...
+[\fIIMAGE_DESCRIPTION\fR] [\fIOPTION\fR...]
 .br
-\fB@IMAGEX_PROGNAME@ append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIIMAGE_DESCRIPTION\fR] [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
+[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
 
 .SH DESCRIPTION
 .PP
@@ -336,7 +336,8 @@ this are some pre-Vista WIMs that had a different version number.
 It is safe to abort an \fB@IMAGEX_PROGNAME@ append\fR command partway through;
 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 optimize\fR to remove any data that was appended to the physical WIM file but
-not yet incorporated into the structure of the WIM.
+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.
 
 \fISOURCE\fR may be a symbolic link to a directory rather than a directory
 itself.  However, additional symbolic links in subdirectories, or in additional
index 2272f03..b930f5c 100644 (file)
@@ -51,10 +51,12 @@ has had images soft-deleted from it.
 Delete the first image from 'boot.wim':
 .RS
 .PP
-image delete boot.wim 1
+@IMAGEX_PROGNAME@ delete boot.wim 1
 .RE
 .PP
 
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-optimize (1)
 
index 25875ab..2372cdd 100644 (file)
@@ -12,24 +12,27 @@ Windows Imaging (WIM) file \fIWIMFILE\fR.
 
 \fIIMAGE\fR specifies the WIM image to show the files of.  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 files from all images are to be shown.  Use the \fB@IMAGEX_PROGNAME@
-info\fR (1) command to show what images a WIM file contains.
+"all" to indicate that files from all images are to be shown.  Use the
+\fB@IMAGEX_PROGNAME@ info\fR (1) command to show what images a WIM file
+contains.
 
 .SH NOTES
 
-\fB@IMAGEX_PROGNAME@ dir\fR supports split WIMs, but it will only work on the first part of
-the split WIM.
+\fB@IMAGEX_PROGNAME@ dir\fR supports split WIMs, but it will only work on the
+first part of the split WIM.
 
 The DOS names of files are not displayed.
 
+Alternate data streams are not displayed.
+
 .SH EXAMPLES
-Show all files in the first image of 'boot.wim':
+List all files in the first image of 'boot.wim':
 .RS
 .PP
-image dir boot.wim 1
+@IMAGEX_PROGNAME@ dir boot.wim 1
 .RE
 .PP
 
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
-
+.BR @IMAGEX_PROGNAME@-info (1)
index e0991fc..25996eb 100644 (file)
@@ -3,9 +3,9 @@
 @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_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
 .PP
@@ -16,10 +16,10 @@ 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.
+\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.
 
 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.
@@ -113,22 +113,22 @@ To export the first image of this split WIM to a new or existing WIM file
 
 .SH NOTES
 
-Unless \fB--rebuild\fR is specified, aborting an \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ export\fR, \fB@IMAGEX_PROGNAME@ 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 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.
 
 .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:
 .RS
 .PP
-image export boot.wim 2 new.wim --compress=maximum
+@IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
 .RE
 .PP
 
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
-
+.BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-optimize (1)
index ce1e8e4..3fde788 100644 (file)
@@ -3,7 +3,7 @@
 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
 
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR \fI[PATH\fR]... [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIPATH\fR...]  [\fIOPTION\fR...]
 
 .SH DESCRIPTION
 .PP
@@ -25,7 +25,9 @@ Each \fIPATH\fR specifies a file or directory tree within the WIM image to
 extract.  See \fBPATH_SPECIFICATIONS\fR.
 
 By default, files and directories are extracted to the current directory.  Use
-\fB--dest-dir\fR to choose an alternate target directory.
+\fB--dest-dir\fR to choose an alternate target directory.  Alternatively, use
+\fB--to-stdout\fR to extract a file to standard output to pipe into another
+program.
 
 \fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
@@ -54,27 +56,22 @@ way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present.
 .TP
-\fB--verbose\fR
-Print the path to of each file or directory within the WIM image as it is
-extracted.
-.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 to of each file or directory within the WIM image as it is
+extracted.
+.TP
 \fB--unix-data\fR
-Restore the UNIX-specific data captured using \fB@IMAGEX_PROGNAME@ capture\fR
-with the \fB--unix-data\fR option.  This option is only available on UNIX.
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 \fB--no-acls\fR
-Do not restore security descriptors on extracted files and directories.
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 \fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file or directory cannot
-be set exactly as specified in the WIM file.  The default behavior without this
-option is to fall back to setting a security descriptor with the SACL omitted,
-then only the default inherited security descriptor, if we do not have
-permission to set the desired one.
+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
@@ -84,9 +81,12 @@ extracted.
 
 .SH NOTES
 
-\fB@IMAGEX_PROGNAME@ extract\fR calculates the SHA1 message digest of every file
-stream it extracts and verifies that it is the same as the SHA1 message digest
-provided in the WIM file.  Thus, it should provide assurance of data integrity.
+See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
+what data and metadata are extracted on UNIX versus on Windows.
+
+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
+command-line or graphical program.
 
 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
@@ -95,12 +95,6 @@ extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 support extracting files directly to a NTFS volume using libntfs-3g.
 
-Not all data and metadata contained in each WIM \fIPATH\fR will necessarily be
-extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
-platform (UNIX or Windows) and supported features of the filesystem.  The
-documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
-what data and metadata is extracted and what is not.
-
 .SH EXAMPLES
 Extract a file from the first image in "boot.wim" to the current directory:
 .RS
@@ -139,3 +133,4 @@ Extract multiple files and directories in one command:
 .BR @IMAGEX_PROGNAME@-apply (1)
 .BR @IMAGEX_PROGNAME@-dir (1)
 .BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-mount (1)
index b492e07..bdd2041 100644 (file)
@@ -4,8 +4,8 @@
 an image
 
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ info\fR \fIWIMFILE\fR [\fIIMAGE_NUM\fR | \fIIMAGE_NAME\fR]  \
-[\fINEW_NAME\fR] [\fINEW_DESC\fR] [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ info\fR \fIWIMFILE\fR [\fIIMAGE\fR [\fINEW_NAME\fR
+[\fINEW_DESC\fR]]] [\fIOPTION\fR...]
 
 
 .SH DESCRIPTION
@@ -17,32 +17,18 @@ are.
 
 If neither an image nor any flags other than \fB--check\fR are specified, some
 basic information about the WIM archive as well as information about the images
-contained in it will be printed.  If an image is specified (as a 1-based image
-index or an image name), the printed information is restricted to that
-concerning the specified image.
+contained in it will be printed.  If an image is specified by \fIIMAGE\fR (as a
+1-based image index or an image name), the printed information is restricted to
+that concerning the specified image.
 
 Changes to the WIM are made if \fINEW_NAME\fR and/or \fB--boot\fR are specified.
-\fINEW_NAME\fR is taken to be the new name of the image specified by
-\fIIMAGE_NUM\fR or \fIIMAGE_NAME\fR, while \fINEW_DESC\fR is taken to be its new
-description.  If \fINEW_DESC\fR is not specified, the image's description is
-unchanged.
+\fINEW_NAME\fR is taken to be the new name of the image specified by \fIIMAGE\fR
+while \fINEW_DESC\fR is taken to be its new description.  If \fINEW_DESC\fR is
+not specified, the image's description is unchanged.
 
 \fB@IMAGEX_PROGNAME@ info\fR does not support modifying a split WIM, although you may
 display information about one.
 
-.SH NOTES
-
-The possible modifications to \fIWIMFILE\fR by \fB@IMAGEX_PROGNAME@ info\fR are made
-quickly without re-building the entire WIM.  \fB@IMAGEX_PROGNAME@ info\fR will only take a
-significant amount of time to complete if \fB--check\fR is specified when the
-WIM previously had no integrity table.
-
-Aborting an \fB@IMAGEX_PROGNAME@ info\fR command that modifies \fIWIMFILE\fR is unlikely to
-result in corruption of \fIWIMFILE\fR.  Even if \fB@IMAGEX_PROGNAME@ info\fR is aborted
-while the integrity table is being calculated (with \fB--check\fR), the WIM
-should be in a consistent state with any changes to the bootable index,
-name, or description of the specified image committed.
-
 .SH OPTIONS
 .TP 6
 \fB--boot\fR
@@ -56,7 +42,7 @@ specified, include an integrity table in the modified WIM.  If this option is
 not specified and \fIWIMFILE\fR is modified, no integrity table is included in
 the modified WIM, even if there was one before.
 .TP
-\fB--extract-xml\fR \fIFILE\fR
+\fB--extract-xml\fR=\fIFILE\fR
 Extracts the raw data from the XML resource in the WIM file to \fIFILE\fR.
 Note: the XML data will be encoded using UTF-16LE, and it will begin with a
 byte-order mark.
index 9f7f998..f3cdc59 100644 (file)
@@ -3,7 +3,7 @@
 @IMAGEX_PROGNAME@-join \- Join split WIMs into a standalone one-part WIM
 
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ join\fR [\fIOPTION...] \fIOUT_WIMFILE\fR \fISPLIT_WIM...\fR
+\fB@IMAGEX_PROGNAME@ join\fR [\fIOPTION\fR...] \fIOUT_WIMFILE\fR \fISPLIT_WIM\fR...
 
 .SH DESCRIPTION
 .PP
index f4c0673..9256fc7 100644 (file)
@@ -3,9 +3,9 @@
 @IMAGEX_PROGNAME@-mount, @IMAGEX_PROGNAME@-mountrw, @IMAGEX_PROGNAME@-unmount \- Mount and unmount an image from a WIM archive
 
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ mount\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ mount\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
 .br
-\fB@IMAGEX_PROGNAME@ mountrw\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ mountrw\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
 .br
 \fB@IMAGEX_PROGNAME@ unmount\fR \fIDIRECTORY\fR [--commit] [--check] [--rebuild]
 
@@ -18,9 +18,10 @@ mount\fR will mount the image read-only, while \fB@IMAGEX_PROGNAME@ mountrw\fR w
 the image read-write.
 
 \fIIMAGE\fR may be a 1-based index of the image in the WIM to mount, or it may
-be the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command to
-see the available images in the WIM.  It is possible to omit \fIIMAGE\fR, but
-only if the WIM contains only one image.
+be the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
+command to see the available images in the WIM.  \fIIMAGE\fR may be omitted if
+\fIWIMFILE\fR contains only one image.
+
 
 The WIM image can be unmounted using the \fB@IMAGEX_PROGNAME@ unmount\fR command.  Changes
 made to a WIM mounted read-write will be discarded unless the \fB--commit\fR
index 5baaa71..9c783c2 100644 (file)
@@ -34,7 +34,7 @@ Note: as mentioned in the README, wimlib generally provides a slightly better
 XPRESS compression ratio than Microsoft's software, while it generally provides
 a slightly worse LZX compression ratio than Microsoft's software.  So, you may
 not want to specify \fB--recompress\fR when optimizing a LZX-compressed WIM
-created on Windows.
+created on Windows with Microsoft's ImageX.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of
index 77057e6..f02ce9d 100644 (file)
@@ -28,7 +28,7 @@ etc. where each part is at most 100 MiB:
 @IMAGEX_PROGNAME@ split windows.wim windows.swm 100
 .RE
 
-.SH NOTE
+.SH LIMITATIONS
 
 It it possible for the size of the parts to exceed the \fIPART_SIZE\fR given.
 This is impossible to avoid and Microsoft's program has this problem as well
index 691d02c..4c52ea0 100644 (file)
@@ -28,13 +28,14 @@ This section documents the commands that may appear in the \fICMDFILE\fR
 described above.
 
 .SS \fBadd\fR [\fIOPTION\fR...] \fISOURCE\fR \fIDESTINATION\fR
-Adds a file or directory tree to the WIM image.  \fISOURCE\fR must specify the
+Add a file or directory tree to the WIM image.  \fISOURCE\fR must specify the
 path to a file or directory on your filesystem.  \fIDESTINATION\fR must specify
 the path inside the WIM image at which to add the file or directory tree.  If
-\fIDESTINATION\fR already exists in the WIM image, then an overlay is attempted;
-this can be used to add multiple files to an existing directory in the WIM image
-in one command.  If \fIDESTINATION\fR does not exist, then any prerequisite
-directories are created as needed to add the \fISOURCE\fR at that location.
+\fIDESTINATION\fR already exists in the WIM image, then an overlay is attempted
+if it is a directory; this feature can be used to add multiple files to an
+existing directory in the WIM image in one command.  If \fIDESTINATION\fR does
+not exist in the WIM image, then any prerequisite directories are created as
+needed to add the \fISOURCE\fR at that location.
 
 The available options for the \fBadd\fR command are:
 
@@ -173,6 +174,9 @@ specified, in which case you should delete the temporary file left over.
 
 .SH EXAMPLES
 
+All the examples below show the update command file to be created as well as the
+\fB@IMAGEX_PROGNAME@ update\fR command to run to perform the updates.
+
 Delete two files from a WIM image:
 
 .RS
@@ -192,8 +196,8 @@ $ @IMAGEX_PROGNAME@ update boot.wim 2 < update_commands.txt
 
 Add some files and directories to a WIM image.  Note that the first path of each
 \fBadd\fR command specifies the files to add, while the second path of each
-\fBadd\fR command specify the locations at which to to add them \fIinside the
-WIM image\fR:
+\fBadd\fR command specify the locations at which to to add them inside the WIM
+image:
 
 .RS
 \fIupdate_commands.txt\fR: