Documentation updates, mainly to the man pages
authorEric Biggers <ebiggers3@gmail.com>
Sun, 1 Jan 2017 23:44:18 +0000 (17:44 -0600)
committerEric Biggers <ebiggers3@gmail.com>
Mon, 2 Jan 2017 00:16:22 +0000 (18:16 -0600)
- Use short command names like wimFOO instead of wimlib-imagex FOO
- Lots of other small improvements

36 files changed:
Makefile.am
NEWS
README
doc/man1/mkwinpeimg.1
doc/man1/wimappend.1 [new file with mode: 0644]
doc/man1/wimapply.1 [new file with mode: 0644]
doc/man1/wimcapture.1 [new file with mode: 0644]
doc/man1/wimdelete.1 [new file with mode: 0644]
doc/man1/wimdir.1 [new file with mode: 0644]
doc/man1/wimexport.1 [new file with mode: 0644]
doc/man1/wimextract.1 [moved from doc/man1/wimlib-imagex-extract.1 with 57% similarity]
doc/man1/wiminfo.1 [new file with mode: 0644]
doc/man1/wimjoin.1 [new file with mode: 0644]
doc/man1/wimlib-imagex-append.1 [deleted file]
doc/man1/wimlib-imagex-apply.1 [deleted file]
doc/man1/wimlib-imagex-capture.1 [deleted file]
doc/man1/wimlib-imagex-delete.1 [deleted file]
doc/man1/wimlib-imagex-dir.1 [deleted file]
doc/man1/wimlib-imagex-export.1 [deleted file]
doc/man1/wimlib-imagex-info.1 [deleted file]
doc/man1/wimlib-imagex-join.1 [deleted file]
doc/man1/wimlib-imagex-mountrw.1 [deleted file]
doc/man1/wimlib-imagex-optimize.1 [deleted file]
doc/man1/wimlib-imagex-split.1 [deleted file]
doc/man1/wimlib-imagex-unmount.1 [deleted file]
doc/man1/wimlib-imagex-verify.1 [deleted file]
doc/man1/wimlib-imagex.1
doc/man1/wimmount.1 [moved from doc/man1/wimlib-imagex-mount.1 with 55% similarity]
doc/man1/wimmountrw.1 [new file with mode: 0644]
doc/man1/wimoptimize.1 [new file with mode: 0644]
doc/man1/wimsplit.1 [new file with mode: 0644]
doc/man1/wimunmount.1 [new file with mode: 0644]
doc/man1/wimupdate.1 [moved from doc/man1/wimlib-imagex-update.1 with 65% similarity]
doc/man1/wimverify.1 [new file with mode: 0644]
include/wimlib.h
tools/make-windows-release

index f59f841..66acc43 100644 (file)
@@ -280,7 +280,7 @@ install-exec-hook:
 install-data-hook:
        for cmd in $(wimlib_imagex_cmds); do                            \
                cd $(DESTDIR)$(mandir)/man1 &&                          \
-                       ln -sf wimlib-imagex-$${cmd}.1 wim$${cmd}.1;    \
+                       ln -sf wim$${cmd}.1 wimlib-imagex-$${cmd}.1;    \
        done
 
 uninstall-hook:
@@ -293,24 +293,24 @@ uninstall-hook:
 #                              Documentation                                #
 ##############################################################################
 
-man1_MANS =                                    \
-       doc/man1/wimlib-imagex.1                \
-       doc/man1/wimlib-imagex-append.1         \
-       doc/man1/wimlib-imagex-apply.1          \
-       doc/man1/wimlib-imagex-capture.1        \
-       doc/man1/wimlib-imagex-delete.1         \
-       doc/man1/wimlib-imagex-dir.1            \
-       doc/man1/wimlib-imagex-export.1         \
-       doc/man1/wimlib-imagex-extract.1        \
-       doc/man1/wimlib-imagex-info.1           \
-       doc/man1/wimlib-imagex-join.1           \
-       doc/man1/wimlib-imagex-mount.1          \
-       doc/man1/wimlib-imagex-mountrw.1        \
-       doc/man1/wimlib-imagex-optimize.1       \
-       doc/man1/wimlib-imagex-split.1          \
-       doc/man1/wimlib-imagex-unmount.1        \
-       doc/man1/wimlib-imagex-update.1         \
-       doc/man1/wimlib-imagex-verify.1         \
+man1_MANS =                            \
+       doc/man1/wimlib-imagex.1        \
+       doc/man1/wimappend.1            \
+       doc/man1/wimapply.1             \
+       doc/man1/wimcapture.1           \
+       doc/man1/wimdelete.1            \
+       doc/man1/wimdir.1               \
+       doc/man1/wimexport.1            \
+       doc/man1/wimextract.1           \
+       doc/man1/wiminfo.1              \
+       doc/man1/wimjoin.1              \
+       doc/man1/wimmount.1             \
+       doc/man1/wimmountrw.1           \
+       doc/man1/wimoptimize.1          \
+       doc/man1/wimsplit.1             \
+       doc/man1/wimunmount.1           \
+       doc/man1/wimupdate.1            \
+       doc/man1/wimverify.1            \
        doc/man1/mkwinpeimg.1
 
 EXTRA_DIST += $(man1_MANS)
diff --git a/NEWS b/NEWS
index f6c24ea..0fb7f91 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -26,6 +26,8 @@ Version 1.11.0-BETA4:
        Fixed configuring with --enable-ssse3-sha1 from release tarball
        (the file nasm_lt.sh was missing).
 
+       Made some documentation improvements.
+
 Version 1.10.0:
        The LZX compression ratio has been slightly improved.  The default mode,
        LZX level 50, is now almost as good as the old LZX level 100, while
diff --git a/README b/README
index 8975d72..490fe36 100644 (file)
--- a/README
+++ b/README
@@ -53,17 +53,18 @@ as additional capabilities.  wimlib-imagex works on both UNIX-like systems and
 Windows, although some features differ between the platforms.
 
 Run `wimlib-imagex' with no arguments to see an overview of the available
-commands and their syntax.  For additional documentation:
+commands and their syntax.  Note that the commands have both long and short
+forms, e.g. `wimlib-imagex apply' is equivalent to `wimapply'.  For additional
+documentation:
 
   * If you have installed wimlib-imagex on a UNIX-like system, you will find
     further documentation in the man pages; run `man wimlib-imagex' to get
     started.
 
   * If you have downloaded the Windows binary distribution, you will find the
-    documentation for wimlib-imagex in PDF format in the "doc" directory,
-    ready for viewing with any PDF viewer.  Please note that although the PDF
-    files are converted from UNIX-style "man pages", they do document
-    Windows-specific behavior when appropriate.
+    documentation for wimlib-imagex in PDF format in the "doc" directory.  Note
+    that although the documentation is written in the style of UNIX manual
+    pages, it does document Windows-specific behavior when relevant.
 
                                   COMPRESSION
 
@@ -76,7 +77,7 @@ algorithms used can be found at https://wimlib.net/compression.html.
 
                                   NTFS SUPPORT
 
-WIM images may contain data, such as alternate data streams and
+WIM images may contain data, such as named data streams and
 compression/encryption flags, that are best represented on the NTFS filesystem
 used on Windows.  Also, WIM images may contain security descriptors which are
 specific to Windows and cannot be represented on other operating systems.
@@ -101,28 +102,19 @@ and then re-applied later.
 
                                    WINDOWS PE
 
-A major use for wimlib and wimlib-imagex is to create customized images of
-Windows PE, the Windows Preinstallation Environment, on either UNIX-like systems
-or Windows without having to rely on Microsoft's software and its restrictions
-and limitations.
+wimlib can also be used to create customized images of Windows PE on either
+UNIX-like systems or Windows.  Windows PE (Preinstallation Environment) is a
+lightweight version of Windows that runs entirely from memory and can be used to
+perform maintenance or to install Windows.  It is the operating system that runs
+when you boot from the Windows installation media.
 
-Windows PE is a lightweight version of Windows that can run entirely from memory
-and can be used to install Windows from local media or a network drive or
-perform maintenance.  It is the operating system that runs when you boot from
-the Windows installation media.
+A copy of Windows PE can be found on the installation media for Windows (Vista
+or later) as the file `sources/boot.wim', or in the Windows Automated
+Installation Kit (WAIK), which is free to download from Microsoft.
 
-You can find Windows PE on the installation media for Windows (Vista or later)
-as the file `sources/boot.wim'.  Windows PE can also be found in the Windows
-Automated Installation Kit (WAIK), which is free to download from Microsoft,
-inside the `WinPE.cab' file, which you can extract natively on Windows, or on
-UNIX-like systems if you install either the `cabextract' or `p7zip' programs.
-
-In addition, Windows installations and recovery partitions frequently contain a
-WIM containing an image of the Windows Recovery Environment, which is similar to
-Windows PE.
-
-A shell script `mkwinpeimg' is distributed with wimlib on UNIX-like systems to
-ease the process of creating and customizing a bootable Windows PE image.
+A shell script `mkwinpeimg' is provided with wimlib on UNIX-like systems to
+simplify the process of creating and customizing a bootable Windows PE image,
+sourcing the needed files from the Windows installation media or from the WAIK.
 
                                   DEPENDENCIES
 
@@ -238,12 +230,12 @@ science papers.
 The code in ntfs-3g_apply.c and ntfs-3g_capture.c uses the NTFS-3G library,
 which is a library for reading and writing to NTFS filesystems (the filesystem
 used by recent versions of Windows).  See
-http://www.tuxera.com/community/ntfs-3g-download/ for more information.
+http://www.tuxera.com/community/open-source-ntfs-3g/ for more information.
 
 A limited number of other free programs can handle some parts of the WIM
 file format:
 
-  * 7-zip is able to extract and create WIMs (as well as files in many
+  * 7-Zip is able to extract and create WIMs (as well as files in many
     other archive formats).  However, wimlib is designed specifically to handle
     WIM files and provides features previously only available in Microsoft's
     implementation, such as the ability to mount WIMs read-write as well as
index 2d8dfa6..92535cb 100644 (file)
@@ -37,9 +37,8 @@ as soon as it starts up.  Use the \fB--start-script\fR \fIFILE\fR option to
 specify such a file.  You may also add arbitrary files to \fIboot.wim\fR by
 putting them in a directory, then specifying the \fB--overlay\fR \fIDIR\fR
 option.  However, for more extensive modifications, consider modifying the
-\fIboot.wim\fR file separately using \fBwimlib-imagex mountrw\fR or
-\fBwimlib-imagex update\fR, then providing it to \fBmkwinpeimg\fR using the
-\fB--wim\fR option.
+\fIboot.wim\fR file separately using \fBwimmountrw\fR(1) or \fBwimupdate\fR(1),
+then providing it to \fBmkwinpeimg\fR using the \fB--wim\fR option.
 .PP
 \fBmkwinpeimg\fR can also make only a modified \fIboot.wim\fR, rather than a
 bootable ISO or disk image, if the \fB--only-wim\fR option is given.
diff --git a/doc/man1/wimappend.1 b/doc/man1/wimappend.1
new file mode 100644 (file)
index 0000000..a117055
--- /dev/null
@@ -0,0 +1 @@
+.so man1/wimcapture.1
diff --git a/doc/man1/wimapply.1 b/doc/man1/wimapply.1
new file mode 100644 (file)
index 0000000..5a7c4a8
--- /dev/null
@@ -0,0 +1,415 @@
+.TH WIMAPPLY "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimapply \- Apply a WIM image
+.SH SYNOPSIS
+\fBwimapply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwimapply\fR, or equivalently \fBwimlib-imagex apply\fR, extracts ("applies")
+an image, or all images, from the Windows Imaging (WIM) archive \fIWIMFILE\fR.
+.PP
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to extract.  It may be the
+1-based index of an image, the name of an image, or the keyword "all" to specify
+all images.  It may be omitted if \fIWIMFILE\fR contains only one image.  You
+can use \fBwiminfo\fR(1) to list the images contained in \fIWIMFILE\fR.
+.PP
+\fITARGET\fR specifies where to extract the image(s) to.  If \fITARGET\fR is a
+directory, then the image(s) will be extracted to that directory as per
+\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR.  If
+\fITARGET\fR does not exist, then a directory will be created there first.
+Alternatively, if \fITARGET\fR specifies a UNIX block device, then the image
+will be extracted to it as described in \fBNTFS VOLUME EXTRACTION (UNIX)\fR.
+.PP
+Note that \fBwimapply\fR is designed to extract, or "apply", full WIM images.
+If you instead want to extract only certain files or directories from a WIM
+image, use \fBwimextract\fR(1) instead.
+.PP
+If \fIIMAGE\fR is "all", then all images in \fIWIMFILE\fR will be extracted into
+subdirectories of \fITARGET\fR named after the images, falling back to the image
+index when an image has no name or an unusual name.  This is not yet supported
+in \fBNTFS VOLUME EXTRACTION (UNIX)\fR mode.
+.PP
+If \fIWIMFILE\fR is "-", then the WIM is read from standard input rather than
+from disk.  See \fBPIPABLE WIMS\fR for more information.
+.SH DIRECTORY EXTRACTION (UNIX)
+On UNIX-like systems, a WIM image may be extracted to a directory.  This mode
+has the limitation that NTFS or Windows-specific metadata will not be extracted.
+Although some concepts such as hard links, symbolic links, last access
+timestamps, and last modification timestamps will be translated to their UNIX
+equivalents, other metadata will be lost (with warnings given).  Notably, the
+following types of metadata will \fInot\fR be extracted in this mode:
+.IP \[bu] 4
+Windows file attribute flags
+.IP \[bu]
+Windows security descriptors (e.g. file owners and DACLs)
+.IP \[bu]
+File creation timestamps
+.IP \[bu]
+Reparse points other than symbolic links and junction points
+.IP \[bu]
+Named data streams
+.IP \[bu]
+Short filenames (also known as 8.3 names or DOS names).
+.IP \[bu]
+Object IDs
+.PP
+These same limitations apply to \fBwimextract\fR.  As such, this mode is most
+useful in situations where NTFS or Windows-specific metadata is unimportant,
+e.g. when wanting to extract specific files, or when doing file archiving only
+on UNIX-like systems, possibly in combination with \fB--unix-data\fR.  When
+Windows-specific metadata is important, then either the \fBNTFS VOLUME
+EXTRACTION (UNIX)\fR mode should be used, or the Windows version of wimlib
+should be used (see \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
+.SH NTFS VOLUME EXTRACTION (UNIX)
+On UNIX-like systems, \fITARGET\fR may also be specified as a block device (e.g.
+/dev/sda3) containing an unmounted NTFS volume.  In this mode, \fBwimapply\fR
+uses libntfs-3g to apply the specified WIM image to the root directory of the
+NTFS volume.  The target volume should be empty, e.g. newly created by
+\fBmkntfs\fR(8).  In this mode, NTFS-specific and Windows-specific data and
+metadata will be extracted, including the following:
+.IP \[bu] 4
+All data streams of all files except encrypted files, including the unnamed data
+stream as well as all named data streams.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points.
+.IP \[bu]
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
+.IP \[bu]
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
+.IP \[bu]
+Windows file attribute flags
+.IP \[bu]
+All names of all files, including names in the Win32 namespace, DOS namespace,
+Win32+DOS namespace, and POSIX namespace.  This includes hard links.
+.IP \[bu]
+Object IDs.
+.PP
+However, encrypted files will not be extracted.
+.PP
+Regardless, since almost all information from the WIM image is restored in this
+mode, it is possible (and fully supported) to restore an image of an actual
+Windows installation using \fBwimapply\fR on a UNIX-like system as an
+alternative to using \fBwimapply\fR or DISM on Windows.  In the \fBEXAMPLES\fR
+section below, there is an example of applying an image from an "install.wim"
+file as may be found in the Windows installation media.
+.PP
+Note that to actually boot Windows (Vista or later) from an applied
+"install.wim" image, you also need to mark the partition as "bootable" and set
+up various boot files, such as \\BOOTMGR and \\BOOT\\BCD.  The latter task is
+most easily accomplished by running bcdboot.exe from a live Windows system such
+as Windows PE, but there are other options as well.
+.PP
+Finally, note that this mode uses libntfs-3g directly, without going through the
+\fBntfs-3g\fR(8) driver.  Hence, there is no special support for applying a WIM
+image to a directory on which an NTFS filesystem has been mounted using
+\fBntfs-3g\fR(8); you have to unmount it first.  There is also no support for
+applying a WIM image to some subdirectory of the NTFS volume; you can only apply
+to the root directory.
+.SH DIRECTORY EXTRACTION (WINDOWS)
+On Windows, \fBwimapply\fR (and \fBwimextract\fR) natively support NTFS and
+Windows-specific metadata.  For best results, the target directory should be
+located on an NTFS volume and the program should be run with Administrator
+privileges; however, non-NTFS filesystems and running without Administrator
+privileges are also supported, subject to limitations.
+.PP
+On Windows, \fBwimapply\fR tries to extract as much data and metadata as
+possible, including:
+.IP \[bu] 4
+All data streams of all files.  This includes the default file contents, as well
+as named data streams if supported by the target volume.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points, if supported by the target volume.  Restoring symlinks requires
+Administrator privileges.  Also see \fB--rpfix\fR and \fB--norpfix\fR for
+details on how absolute symbolic links and junctions are extracted.
+.IP \[bu]
+File and directory creation, access, and modification timestamps, to the highest
+resolution supported by the target volume.
+.IP \[bu]
+Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
+specified.  Note that this, in general, requires Administrator privileges, and
+may be only partially successful if the program is run without Administrator
+privileges (see \fB--strict-acls\fR).
+.IP \[bu]
+File attribute flags, including hidden, compressed, encrypted, sparse, etc, when
+supported by the filesystem.
+.IP \[bu]
+Short filenames (also known as 8.3 names or DOS names).
+.IP \[bu]
+Hard links, if supported by the target filesystem.
+.IP \[bu]
+Object IDs, if supported by the target filesystem.
+.PP
+Additional notes about extracting files on Windows:
+.IP \[bu] 4
+\fBwimapply\fR will issue warnings if unable to extract the exact metadata and
+data of the WIM image due to limitations of the target filesystem.
+.IP \[bu]
+Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
+plaintext in the WIM image, \fBwimapply\fR cannot restore encrypted files to
+filesystems not supporting encryption.  Therefore, on such filesystems,
+encrypted files will not be extracted.  Furthermore, even if encrypted files are
+restored to a filesystem that supports encryption, they will only be decryptable
+if the decryption key is available.
+.IP \[bu]
+Files with names that cannot be represented on Windows will not
+be extracted by default; see \fB--include-invalid-names\fR.
+.IP \[bu]
+Files with full paths over 260 characters (the so-called MAX_PATH) will be
+extracted, but beware that such files will be inaccessible to most Windows
+software and may not be able to be deleted easily.
+.IP \[bu]
+On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt
+to restore files' security descriptors exactly as they are provided in the WIM
+image.  Beware that typical Windows installations contain files whose security
+descriptors do not allow the Administrator to delete them.  Therefore, such
+files will not be able to be deleted, or in some cases even read, after
+extracting, unless processed with a specialized program that knows to acquire
+the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding
+access control lists.  This is not a bug in wimlib, which works as designed to
+correctly restore the data that was archived, but rather a problem with the
+access rights Windows uses on certain files.  But if you just want the file data
+and don't care about security descriptors, use \fB--no-acls\fR to skip restoring
+all security descriptors.
+.IP \[bu]
+A similar caveat to the above applies to file attributes such as Readonly,
+Hidden, and System.  By design, on Windows wimlib will restore such file
+attributes; therefore, extracted files may have those attributes.  If this is
+not what you want, use the \fB--no-attributes\fR option.
+.SH SPLIT WIMS
+You may use \fBwimapply\fR to apply images from a split WIM, or \fBwimextract\fR
+to extract files from a split WIM.  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:
+.RS
+.PP
+.nf
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+.fi
+.PP
+To apply the first image of this split WIM to the directory "dir", run:
+.PP
+.RS
+wimapply mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+.SH PIPABLE WIMS
+\fBwimapply\fR also supports applying a WIM from a nonseekable file, such as a
+pipe, provided that the WIM was captured in the wimlib-specific pipable format
+using \fB--pipable\fR (see \fBwimcapture\fR(1)).  To use standard input as the
+WIM, specify "-" as \fIWIMFILE\fR.  A possible use of this feature is to apply a
+WIM image being streamed from the network.  For example, to apply the first
+image from a WIM file available on a HTTP server to an NTFS volume on /dev/sda1,
+run something like:
+.PP
+.RS
+wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
+.RE
+.PP
+Pipable WIMs may also be split into multiple parts, just like normal WIMs.  To
+apply a split pipable WIM from a pipe, the parts must be concatenated and all
+written to the pipe.  The first part must be sent first, but the remaining parts
+may be sent in any order.
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+Before applying the image, verify the integrity of \fIWIMFILE\fR if it has extra
+integrity information.
+.TP
+\fB--ref\fR="\fIGLOB\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 \fBwimapply\fR and
+may need to be quoted to protect against shell expansion.
+.TP
+\fB--rpfix\fR, \fB--norpfix\fR
+Set whether to fix targets of absolute symbolic links (reparse points in Windows
+terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
+links that are marked in the WIM image as being fixed are assumed to have
+absolute targets relative to the image root, and therefore \fBwimapply\fR
+prepends the absolute path to the extraction target directory to their targets.
+The intention is that you can apply an image containing absolute symbolic links
+and still have them be valid after it has been applied to any location.
+.IP ""
+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.
+.IP ""
+Reparse point fixups are never done in the NTFS volume extraction mode on
+UNIX-like systems.
+.TP
+\fB--unix-data\fR
+(UNIX-like systems only)  Restore UNIX-specific metadata and special files that
+were captured by \fBwimcapture\fR with the \fB--unix-data\fR option.  This
+includes: standard UNIX file permissions (owner, group, and mode); device nodes,
+named pipes, and sockets; and extended attributes (Linux-only).
+.TP
+\fB--no-acls\fR
+Do not restore security descriptors on extracted files and directories.
+.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.  If this option is not specified,
+when \fBwimapply\fR on Windows does not have permission to set a security
+descriptor on an extracted file, it falls back to setting it only partially
+(e.g. with SACL omitted), and in the worst case omits it entirely.  However,
+this should only be a problem when running \fBwimapply\fR without Administrator
+rights.  Also, on UNIX-like systems, this flag can also be combined with
+\fB--unix-data\fR to cause \fBwimapply\fR to issue an error if UNIX permissions
+are unable to be applied to an extracted file.
+.TP
+\fB--no-attributes\fR
+Do not restore Windows file attributes such as readonly, hidden, etc.
+.TP
+\fB--include-invalid-names\fR
+Extract files and directories with invalid names by replacing characters and
+appending a suffix rather than ignoring them.  Exactly what is considered an
+"invalid" name is platform-dependent.
+.IP ""
+On POSIX-compliant systems, filenames are case-sensitive and may contain any
+byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
+have an effect in the unlikely case that the WIM image for some reason has a
+filename containing one of these characters.
+.IP ""
+On Windows, filenames are case-insensitive(*), cannot include control
+characters, and cannot include the characters '/', \'\\0', '\\', ':', '*', '?',
+\'"', '<', '>', or '|'.  Ordinarily, files in WIM images should meet these
+conditions as well. However, it is not guaranteed, and in particular a WIM image
+captured with \fBwimcapture\fR on a POSIX-compliant system could contain such
+files.  By default, invalid names will be ignored, and if there are multiple
+names differing only in case, one will be chosen to extract arbitrarily;
+however, with \fB--include-invalid-names\fR, all names will be sanitized and
+extracted in some form.
+.IP ""
+(*) Unless the ObCaseInsensitive setting has been set to 0 in the Windows
+registry, in which case certain software, including the Windows version of
+\fBwimapply\fR, will honor case-sensitive filenames on NTFS and other compatible
+filesystems.
+.TP
+\fB--wimboot\fR
+Windows only: Instead of extracting the files themselves, extract "pointer
+files" back to the WIM archive(s).  This can result in significant space savings.
+However, it comes at several potential costs, such as not being able to delete
+the WIM archive(s) and possibly having slower access to files.  See Microsoft's
+documentation for "WIMBoot" for more information.
+.IP ""
+If it exists, the [PrepopulateList] section of the file
+\\Windows\\System32\\WimBootCompress.ini in the WIM image will be read.  Files
+matching any of these patterns will be extracted normally, not as WIMBoot
+"pointer files".  This is helpful for certain files that Windows needs to read
+early in the boot process.
+.IP ""
+This option only works when the program is run as an Administrator and the
+target volume is NTFS or another filesystem that supports reparse points.
+.IP ""
+In addition, this option works best when running on Windows 8.1 Update 1 or
+later, since that is the first version of Windows that contains the Windows
+Overlay Filesystem filter driver ("WOF").  If the WOF driver is detected, wimlib
+will create the WIMBoot "pointer files" using documented ioctls provided by WOF.
+.IP ""
+Otherwise, if the WOF driver is not detected, wimlib will create the reparse
+points and edit the file "\\System Volume Information\\WimOverlay.dat" on the
+target volume manually.  This is potentially subject to problems, since although
+the code works in certain tested cases, neither of these data formats is
+actually documented by Microsoft.  Before overwriting this file, wimlib will
+save the previous version in "\\System Volume
+Information\\WimOverlay.wimlib_backup", which you potentially could restore if
+you needed to.
+.IP ""
+You actually can still do a \fB--wimboot\fR extraction even if the WIM image is
+not marked as "WIMBoot-compatible".  This option causes the extracted files to
+be set as "externally backed" by the WIM file.  Microsoft's driver which
+implements this "external backing" functionality seemingly does not care whether
+the image(s) in the WIM are really marked as WIMBoot-compatible.  Therefore, the
+"WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to be a marker for
+intent only.  In addition, the Microsoft driver can externally back files from
+WIM files that use XPRESS chunks of size 8192, 16384, and 32768, or LZX chunks
+of size 32768, in addition to the default XPRESS chunks of size 4096 that are
+created when \fBwimcapture\fR is run with the \fB--wimboot\fR option.
+.TP
+\fB--compact\fR=\fIFORMAT\fR
+Windows-only: compress the extracted files using System Compression, when
+possible.  This only works on either Windows 10 or later, or on an older Windows
+to which Microsoft's wofadk.sys driver has been added.  Several different
+compression formats may be used with System Compression, and one must be
+specified as \fIFORMAT\fR.  The choices are: xpress4k, xpress8k, xpress16k, and
+lzx.
+.IP ""
+Exclusions are handled in the same way as with the \fB--wimboot\fR option.
+That is: if it exists, the [PrepopulateList] section of the file
+\\Windows\\System32\\WimBootCompress.ini in the WIM image will be read, and
+files matching any of the patterns in this section will not be compressed.
+In addition, wimlib has a hardcoded list of files for which it knows, for
+compatibility with the Windows bootloader, to override the requested compression
+format.
+.SH NOTES
+\fIData integrity\fR: WIM files include checksums of file data.  To detect
+accidental (non-malicious) data corruption, wimlib calculates the checksum of
+every file it extracts and issues an error if it does not have the expected
+value.  (This default behavior seems equivalent to the \fB/verify\fR option of
+ImageX.)  In addition, a WIM file can include an integrity table (extra
+checksums) over the raw data of the entire WIM file.  For performance reasons
+wimlib does not check the integrity table by default, but the \fB--check\fR
+option can be passed to make it do so.
+.PP
+\fIESD files\fR: wimlib can extract files from solid-compressed WIMs, or "ESD"
+(.esd) files, just like from normal WIM (.wim) files.  However, Microsoft
+sometimes distributes ESD files with encrypted segments; wimlib cannot extract
+such files until they are first decrypted.
+.PP
+\fISecurity\fR: wimlib has been carefully written to validate all input and is
+believed to be secure against some types of attacks which often plague other
+file archiving programs, e.g. directory traversal attacks (which, as it happens,
+Microsoft's WIM software is vulnerable to).  Important parts of wimlib, e.g. the
+decompressors, have also been fuzz tested.  However, wimlib is not currently
+designed to protect against some types of denial-of-service (DOS) attacks, e.g.
+memory exhaustion or "zip bombs".
+.SH EXAMPLES
+Extract the first image from the Windows PE WIM on the Windows installation
+media to the directory "boot":
+.RS
+.PP
+wimapply /mnt/windows/sources/boot.wim 1 boot
+.RE
+.PP
+On Windows, apply an image of an entire volume, for example from "install.wim"
+which can be found on the Windows installation media:
+.RS
+.PP
+wimapply install.wim 1 E:\\
+.RE
+.PP
+Same as above, but running on a UNIX-like system where the corresponding
+partition is /dev/sda2:
+.RS
+.PP
+wimapply install.wim 1 /dev/sda2
+.RE
+.PP
+Note that before running either of the above commands, an NTFS filesystem may
+need to be created on the partition, for example with format.exe on Windows or
+\fBmkntfs\fR(8) on UNIX-like systems.  For example, on UNIX you might run:
+.RS
+.PP
+mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
+.RE
+.PP
+(Of course don't do that if you don't want to destroy all existing data on the
+partition!)
+.PP
+See \fBSPLIT WIMS\fR and \fBPIPABLE WIMS\fR for examples of applying split and
+pipable WIMs, respectively.
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wimcapture (1)
+.BR wimextract (1)
+.BR wiminfo (1)
diff --git a/doc/man1/wimcapture.1 b/doc/man1/wimcapture.1
new file mode 100644 (file)
index 0000000..1615ea7
--- /dev/null
@@ -0,0 +1,664 @@
+.TH WIMCAPTURE "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimcapture, wimappend \- Capture or append a WIM image
+.SH SYNOPSIS
+\fBwimcapture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
+.br
+\fBwimappend\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
+.SH DESCRIPTION
+The \fBwimcapture\fR (equivalently: \fBwimlib-imagex capture\fR) and
+\fBwimappend\fR (equivalently: \fBwimlib-imagex append\fR) commands create
+("capture") a new Windows Imaging (WIM) image.  \fBwimcapture\fR creates a new
+WIM archive \fIWIMFILE\fR to contain the new image, while \fBwimappend\fR adds
+the image to the existing WIM archive \fIWIMFILE\fR.
+.PP
+\fISOURCE\fR specifies the location of the files from which to create the WIM
+image.  If \fISOURCE\fR is a directory or a symbolic link pointing to a
+directory, then the image is captured from that directory as per \fBDIRECTORY
+CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE (WINDOWS)\fR.   Alternatively, if
+\fB--source-list\fR is specified, then \fISOURCE\fR is interpreted as a file
+containing a list of files and directories to include in the image.  Still
+alternatively, if \fISOURCE\fR is a UNIX block device, then an image is captured
+from the NTFS volume on it as per \fBNTFS VOLUME CAPTURE (UNIX)\fR.
+.PP
+\fIIMAGE_NAME\fR and \fIIMAGE_DESC\fR specify the name and description to give
+the new image.  If \fIIMAGE_NAME\fR is unspecified, it defaults to the filename
+component of \fISOURCE\fR, appending a unique suffix if needed.  Otherwise,
+\fIIMAGE_NAME\fR must be either a name not already used by an image in
+\fIWIMFILE\fR, or the empty string to create an unnamed image.  If
+\fIIMAGE_DESC\fR is unspecified then the new image is given no description.
+.PP
+If \fIWIMFILE\fR is specified as "-", then the \fB--pipable\fR option is assumed
+and a pipable WIM is written to standard output (this is a wimlib extension).
+.SH DIRECTORY CAPTURE (UNIX)
+On UNIX-like systems, if \fISOURCE\fR specifies a directory or a symbolic link
+to a directory, then the WIM image will be captured from that directory.  The
+directory can be on any type of filesystem, and mountpoints are followed.  In
+this mode, the following types of information are captured:
+.IP \[bu] 4
+Directories and regular files, and the contents of regular files
+.IP \[bu]
+Hard links
+.IP \[bu]
+Symbolic links (translated losslessly to Windows reparse points)
+.IP \[bu]
+Last modification times (mtime) and last access times (atime) with 100
+nanosecond granularity
+.IP \[bu]
+Files that appear to be sparse will be flagged as such, but their full data will
+still be stored, subject to the usual compression.
+.IP \[bu]
+With \fB--unix-data\fR: standard UNIX file permissions (owner, group, and mode)
+.IP \[bu]
+With \fB--unix-data\fR: device nodes, named pipes, and sockets
+.IP \[bu]
+With \fB--unix-data\fR: extended attributes (Linux only)
+.PP
+There is no support for storing last status change times (ctimes), or hard link
+information for symlinks (each symlink will be stored as a separate file).
+Also, filenames and symlink targets which are not valid UTF-8 with the addition
+of surrogate codepoints are unsupported.  Note that if you have a filesystem
+containing filenames in another multibyte encoding, such as ISO-8859-1, and you
+wish to archive it with wimlib, you may be able to mount it with an option which
+causes its filenames to be presented as UTF-8.
+.SH NTFS VOLUME CAPTURE (UNIX)
+On UNIX-like systems, \fISOURCE\fR may also be specified as a block device (e.g.
+/dev/sda3) containing an unmounted NTFS volume.  In this mode, \fBwimcapture\fR
+uses libntfs-3g to capture a WIM image from root directory of the NTFS volume.
+In this mode, as much data and metadata as possible is captured, including
+NTFS-specific and Windows-specific metadata:
+.IP \[bu] 4
+All data streams of all unencrypted files, including the unnamed data stream as
+well as all named data streams.
+.IP \[bu]
+Reparse points.  See \fBREPARSE POINTS AND SYMLINKS\fR for details.
+.IP \[bu]
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
+.IP \[bu]
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
+.IP \[bu]
+DOS/Windows file attribute flags.
+.IP \[bu]
+All names of all files, including names in the Win32 namespace, DOS namespace,
+Win32+DOS namespace, and POSIX namespace.  This includes hard links.
+.IP \[bu]
+Object IDs.
+.PP
+However, the main limitations of this mode are:
+.IP \[bu] 4
+Encrypted files are excluded.
+.IP \[bu]
+Sparse files will be flagged as such, but their full data will still be stored,
+subject to the usual compression.
+.IP \[bu]
+Some types of reparse points are transparently dereferenced by Windows but not
+by NTFS-3G.  See \fBREPARSE POINTS AND SYMLINKS\fR.
+.PP
+Note that this mode uses libntfs-3g directly, without going through the
+\fBntfs-3g\fR(8) driver.  Hence, there is no special support for capturing a WIM
+image from a directory on which an NTFS filesystem has been mounted using
+\fBntfs-3g\fR(8); you have to unmount it first.  There is also no support for
+capturing a subdirectory of the NTFS volume; you can only capture the full
+volume.
+.SH DIRECTORY CAPTURE (WINDOWS)
+On Windows, \fBwimcapture\fR and \fBwimappend\fR natively support
+Windows-specific and NTFS-specific data.  They therefore act similarly to the
+corresponding commands of Microsoft's ImageX or DISM.  For best results, the
+directory being captured should be on an NTFS volume and the program should be
+run with Administrator privileges; however, non-NTFS filesystems and running
+without Administrator privileges are also supported, subject to limitations.
+.PP
+On Windows, \fBwimcapture\fR and \fBwimappend\fR try to capture as much data and
+metadata as possible, including:
+.IP \[bu] 4
+All data streams of all files.
+.IP \[bu]
+Reparse points, if supported by the source filesystem.  See \fBREPARSE POINTS
+AND SYMLINKS\fR for details.
+.IP \[bu]
+File and directory creation, access, and modification timestamps.  These are
+stored with Windows' native timestamp resolution of 100 nanoseconds.
+.IP \[bu]
+Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
+is not specified.  Note: when not running as an Administrator, security
+descriptors may be only partially captured (see \fB--strict-acls\fR).
+.IP \[bu]
+File attributes, including hidden, sparse, compressed, encrypted, etc.
+Encrypted files will be stored in encrypted form rather than in plain text.
+Transparently compressed files will be read as uncompressed and stored subject
+to the WIM's own compression.  There is no special handling for storing sparse
+files, but they are likely to compress to a small size.
+.IP \[bu]
+DOS names (8.3) names of files; however, the failure to read them is not
+considered an error condition.
+.IP \[bu]
+Hard links, if supported by the source filesystem.
+.IP \[bu]
+Object IDs, if supported by the source filesystem.
+.PP
+There is no support yet for capturing NTFS extended attributes.
+.SH REPARSE POINTS AND SYMLINKS
+A "symbolic link" (or "symlink") is a special file which "points to" some other
+file or directory.  On Windows, a "reparse point" is a generalization of a
+symlink which allows access to a file or directory to be redirected in a more
+complex way.  Windows uses reparse points to implement symlinks and sometimes
+uses them for various other features as well.  Normally, applications can choose
+whether they want to "dereference" reparse points and symlinks or not.
+.PP
+The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
+\fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
+are stored in the archive rather than the files or data they point to.  There is
+a \fB--dereference\fR option, but it is currently only supported by the UNIX
+version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
+Windows filesystems).
+.PP
+Windows also treats certain types of reparse points specially.  For example,
+Windows applications reading from deduplicated, WIM-backed, or system-compressed
+files always see the dereferenced data, even if they ask not to.  Therefore,
+\fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
+points.  But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
+files and will store them as reparse points instead.  This difference can be
+significant in certain situations, e.g. when capturing deduplicated files which,
+to be readable after extraction, require that the chunk store also be present.
+.SH OPTIONS
+.TP 6
+\fB--boot\fR
+Mark the new image as the "bootable" image of the WIM.  The "bootable" image is
+the image which the Windows bootloader will use when loading Windows PE from the
+WIM.
+.TP
+\fB--check\fR
+Include extra integrity information in the resulting WIM.  With \fBwimappend\fR,
+also check the integrity of the WIM before appending to it.
+.TP
+\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+With \fBwimcapture\fR, use the specified compression format in the new WIM file.
+\fITYPE\fR may be "none", "XPRESS" (alias: "fast"), "LZX" (alias: "maximum"), or
+"LZMS" (alias: "recovery").  \fITYPE\fR is matched case-insensitively.  The
+default is "LZX".
+.IP ""
+You can optionally also specify an integer compression \fILEVEL\fR.  The
+compression level specifies how hard the compression algorithm for the specified
+compression \fITYPE\fR will work to compress the data.  The values are scaled so
+that 20 is quick compression, 50 is medium compression, and 100 is high
+compression.  However, you can choose any value and not just these particular
+values.  The default is 50.
+.IP ""
+This option only affects the compression type used in non-solid WIM resources.
+If you are creating a solid WIM (using the \fB--solid\fR option), then you
+probably want \fB--solid-compress\fR instead.
+.IP ""
+Be careful if you choose LZMS compression.  It is not compatible with wimlib
+before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip
+before v15.12.  Also note that choosing LZMS compression does not automatically
+imply solid-mode compression, as it does with DISM.  Use \fB--solid\fR if you
+want to create a solid WIM, or "ESD file".
+.TP
+\fB--chunk-size\fR=\fISIZE\fR
+With \fBwimcapture\fR, use a compression chunk size of \fISIZE\fR bytes.  A
+larger compression chunk size results in a better compression ratio.  wimlib
+supports different chunk sizes depending on the compression type:
+.RS
+.IP \[bu] 2
+XPRESS: 4K, 8K, 16K, 32K, 64K
+.IP \[bu]
+LZX: 32K, 64K, 128K, 256K, 512K, 1M, 2M
+.IP \[bu]
+LZMS: 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
+.RE
+.IP ""
+You can provide the full number (e.g. 32768), or you can use one of the K, M, or
+G suffixes.  KiB, MiB, and GiB are also accepted.
+.IP ""
+This option only affects the chunk size used in non-solid WIM resources.  If you
+are creating a solid WIM (using the \fB--solid\fR option), then you probably
+want \fB--solid-chunk-size\fR instead.
+.IP ""
+Use this option with caution if compatibility with Microsoft's WIM software is
+desired, since their software has limited support for non-default chunk sizes.
+.TP
+\fB--solid\fR
+With \fBwimcapture\fR, create a "solid" WIM file that compresses files together
+rather than independently.  This results in a significantly better compression
+ratio, but it comes at the cost of slow compression with very high memory usage,
+reduced compatibility, and slow random access to the resulting WIM file.
+.IP ""
+By default this enables solid LZMS compression, thereby creating a file
+equivalent to one created with DISM's \fB/compress\fR:\fIrecovery\fR option.
+Such files are also called "ESD files" and were first supported by WIMGAPI in
+Windows 8, by DISM in Windows 8.1, and by 7-Zip 15.12.
+.TP
+\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Like \fB--compress\fR, but set the compression type used in solid resources.
+The default is LZMS compression.  This option only has an effect when
+\fB--solid\fR is also specified.
+.TP
+\fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  The
+default, assuming LZMS compression, is 64MiB (67108864); this requires about
+640MiB of memory per thread.  This option only has an effect when \fB--solid\fR
+is also specified.  Note: Microsoft's WIM software is not compatible with LZMS
+chunk sizes larger than 64MiB.
+.TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data.  Default: autodetect (number of
+available CPUs).
+.TP
+\fB--rebuild\fR
+With \fBwimappend\fR, rebuild the entire WIM rather than appending the new data
+to the end of it.  Rebuilding the WIM is slower, but will save some space that
+would otherwise be left as a hole in the WIM.  Also see \fBwimoptimize\fR(1).
+.TP
+\fB--flags\fR=\fIEDITIONID\fR
+Specify a string to use in the <FLAGS> element of the XML data for the new
+image.
+.TP
+\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
+Assign an arbitrary property to the new image in the XML document of the WIM.
+\fIVALUE\fR is the string to set as the property value.  \fINAME\fR is the name
+of the image property, for example "NAME", "DESCRIPTION", or "TOTALBYTES".  The
+name can contain forward slashes to indicate a nested XML element; for example,
+"WINDOWS/VERSION/BUILD" indicates the BUILD element nested within the VERSION
+element nested within the WINDOWS element.  A bracketed number can be used to
+indicate one of several identically-named elements; for example,
+"WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element nested
+within the "WINDOWS/LANGUAGES" element.  When adding a list of elements in this
+way, they must be specified in sequential order.  Note that element names are
+case-sensitive.  This option may be specified multiple times.
+.TP
+\fB--dereference\fR
+(UNIX-like systems only) Follow symbolic links and archive the files they point
+to, rather than archiving the links themselves.
+.TP
+\fB--config\fR=\fIFILE\fR
+Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
+works) for capturing the new image.  The configuration file specifies files that
+are to be treated specially during the image capture.
+.IP ""
+The format of the configuration file is INI-style; that is, it is arranged in
+bracketed sections.  Currently, the following sections are recognized:
+.RS
+.IP \[bu] 4
+[ExclusionList] ---  contains a list of path globs to exclude from capture.  If
+a directory is matched, both the directory and its contents are excluded.
+.IP \[bu]
+[ExclusionException] --- contains a list of path globs to include in the
+capture, even when the file or directory also matches a glob in [ExclusionList].
+.IP \[bu]
+[PrepopulateList] --- this does not affect capture, but if the image is applied
+later with \fB--wimboot\fR, these are globs of files that shall be extracted
+normally, not as WIMBoot "pointer files".  If a directory is matched, all files
+and subdirectories are also matched recursively.
+.RE
+.IP ""
+Path globs may contain the '*' and '?' meta-characters.  Relative globs (e.g.
+*.mp3) match against a filename in any directory.  Absolute globs (e.g.
+/dir/file), are treated as paths starting at the main directory being captured,
+or the root of the NTFS volume for NTFS volume capture mode.  Do not use drive
+letters in the paths; they will be ignored.  Path separators may be either
+forwards slashes or backwards slashes.
+.IP ""
+Lines beginning with the '#' or ';' characters are treated as comments and
+ignored.  Globs with whitespace in them need not be quoted; however, if they
+are, both double and single quotes are accepted.
+.IP ""
+If this option is not specified the following default configuration file is
+used:
+.IP ""
+.RS
+.RS
+.nf
+[ExclusionList]
+\\$ntfs.log
+\\hiberfil.sys
+\\pagefile.sys
+\\swapfile.sys
+\\System Volume Information
+\\RECYCLER
+\\Windows\\CSC
+.RE
+.RE
+.fi
+.IP ""
+However, special behavior applies if \fB--wimboot\fR is also specified.  By
+default, with \fB--wimboot\fR specified, the file
+Windows/System32/WimBootCompress.ini in the directory being captured will be
+used as the configuration file.  However, this can be overridden using
+\fB--config\fR; and this also causes the specified configuration file to be
+saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
+that may be present on the filesystem.
+.TP
+\fB--unix-data\fR
+(UNIX-like systems only)  Store UNIX-specific metadata and special files.  This
+includes: standard UNIX file permissions (owner, group, and mode); device nodes,
+named pipes, and sockets; and extended attributes (Linux only).  This
+information can later be restored by \fBwimapply\fR with the \fB--unix-data\fR
+option.
+.IP
+UNIX-specific information is ignored by Microsoft's WIM software and by the
+Windows version of wimlib.
+.TP
+\fB--no-acls\fR
+Do not capture files' security descriptors.
+.TP
+\fB--strict-acls\fR
+Fail immediately if the full security descriptor of any file cannot be read.  On
+Windows, the default behavior without this option is to first try omitting the
+SACL from the security descriptor, then to try omitting the security descriptor
+entirely.  The purpose of this is to capture as much data as possible without
+always requiring Administrator privileges.  However, if you desire that all
+security descriptors be captured exactly, you may wish to provide this option,
+although the Administrator should have permission to read everything anyway.
+.TP
+\fB--rpfix\fR, \fB--norpfix\fR
+Set whether to fix targets of absolute symbolic links (reparse points in Windows
+terminology) or not.  When enabled (\fB--rpfix\fR), absolute symbolic links that
+point inside the directory tree being captured will be adjusted to be absolute
+relative to the root of the directory tree being captured.  When disabled
+(\fB--norpfix\fR), absolute symbolic links will be captured exactly as is.
+.IP ""
+The default behavior of \fBwimcapture\fR is equivalent to \fB--rpfix\fR.  The
+default behavior of \fBwimappend\fR is equivalent to \fB--rpfix\fR if reparse
+point fixups have previously been done on \fIWIMFILE\fR, otherwise
+\fB--norpfix\fR.
+.IP ""
+In the case of a multi-source capture, (\fB--source-list\fR specified), passing
+\fB--norpfix\fR is recommended.  Otherwise, reparse point fixups will be
+disabled on all capture sources destined for non-root locations in the WIM
+image, while capture sources destined for the WIM root will get the default
+behavior from the previous paragraph.
+.TP
+\fB--source-list\fR
+\fBwimcapture\fR and \fBwimappend\fR support creating a WIM image from multiple
+separate files or directories.  When \fB--source-list\fR is specified, the
+\fISOURCE\fR argument specifies the name of a text file, each line of which is
+either 1 or 2 whitespace separated file paths.  The first file path, the source,
+specifies the path to a file or directory to capture into the WIM image.  It may
+be either absolute or relative to the current working directory.  The second
+file path, if provided, is the target and specifies the path  in the WIM image
+that this file or directory will be saved as.  Leading and trailing slashes in
+the target are ignored, except if it consists entirely of slashes (e.g. "/"),
+which indicates that the directory is to become the root of the WIM image.  If
+omitted, the target string defaults to the same as the source string.
+.IP ""
+An example source list file is as follows:
+.IP ""
+.RS
+.RS
+.nf
+# Make the WIM image from the 'winpe' directory
+winpe  /
+
+# Send the 'overlay' directory to '/overlay' in the WIM image
+overlay        /overlay
+
+# Overlay a separate directory directly on the root of the WIM image.
+/data/stuff    /
+.RE
+.RE
+.fi
+.IP ""
+Subdirectories in the WIM are created as needed.  Multiple source directories
+may share the same target, which implies an overlay.  In the event that this
+results a nondirectory file being added to the WIM image multiple times, the
+last version (as listed in the source list file) overrides any earlier version.
+.IP ""
+File paths containing whitespace may be quoted with either single quotes or
+double quotes.  Quotes may not be escaped.
+.IP ""
+Lines consisting only of whitespace and lines beginning with '#' preceded by
+optional whitespace are ignored.
+.IP ""
+As a special case, if \fISOURCE\fR is "-", the source list is read from standard
+input rather than an external file.
+.IP ""
+The NTFS volume capture mode on UNIX-like systems cannot be used with
+\fB--source-list\fR, as only capturing a full NTFS volume is supported.
+.TP
+\fB--pipable\fR
+With \fBwimcapture\fR, create a wimlib-specific "pipable" WIM which can be
+captured and applied fully sequentially.  If \fIWIMFILE\fR is specified as "-",
+then the pipable WIM is written directly to standard output; otherwise, it is
+written to disk as usual.  The image in the pipable WIM can be later be applied
+with \fBwimapply\fR, either from disk or from standard input.  A typical use of
+pipable WIMs might involve streaming the WIM image to a remote server when
+capturing it and/or streaming the WIM image from a remote server when applying
+it.
+.IP ""
+Generally, all the \fBwimlib-imagex\fR commands work on both pipable and
+non-pipable WIMs.  \fBwimoptimize\fR and \fBwimexport\fR may also be used to
+convert between pipable WIMs and non-pipable WIMs.  However, there are a few
+limitations of pipable WIMs:
+.RS
+.IP \[bu] 4
+Pipable WIMs are a wimlib extension which are \fInot\fR compatible with
+Microsoft's WIM software or with other programs such as 7-Zip.
+.IP \[bu]
+Using \fBwimappend\fR, multiple images may be added to a pipable WIM.  This is
+supported, though it is less efficient than doing so with non-pipable WIMs
+because a pipable WIM is fully rebuilt each time it is appended to; and when
+piping such a WIM to \fBwimapply\fR to extract an image, some unneeded data will
+be sent over the pipe.
+.IP \[bu]
+Although a pipable WIM image may be updated using \fBwimupdate\fR, it requires a
+full rebuild of the WIM file, making it less efficient than updating a
+non-pipable WIM.
+.IP \[bu]
+Solid pipable WIMs are not yet supported.
+.RE
+.TP
+\fB--not-pipable\fR
+With \fBwimappend\fR, rebuild the WIM file in the non-pipable (regular) format.
+This option is only useful if you happen to be adding an image to a pipable WIM
+(see \fB--pipable\fR) which you want in non-pipable format instead.  Note that
+\fBwimoptimize\fR(1) can also be used to convert between non-pipable and pipable
+WIMs.
+.TP
+\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
+Hint that the image being captured or appended from \fISOURCE\fR is mostly the
+same as the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later
+point in time, possibly with some modifications in the intervening time.  This
+is designed to be used in incremental backups of the same filesystem or
+directory tree.  \fIIMAGE\fR can be a 1-based index or name of an existing image
+in \fIWIMFILE\fR.  It can also be a negative integer to index backwards into the
+images (e.g.  -1 means the last existing image in \fIWIMFILE\fR).
+.IP ""
+When this option is provided, the capture or append of the new image will be
+optimized by not reading files that, based on metadata such as timestamps,
+appear not to have been modified since they were archived in the existing
+\fIIMAGE\fR.  Barring manipulation of timestamps, this option only affects
+performance and does not change the resulting WIM image (but see note below).
+.IP ""
+As shown, the full syntax for the argument to this option is to specify the WIM
+file, a colon, and the image; for example, "--update-of mywim.wim:1".  However,
+the WIM file and colon may be omitted, in which case the WIM file will default
+to the WIM file being appended to for append operations, or the WIM file from
+which a delta is being taken (only if \fB--delta-from\fR is specified exactly
+once) for capture operations.
+.IP ""
+Note: in the Windows version of wimlib, it has been observed that
+\fB--update-of\fR mode is not completely reliable at detecting changes in file
+contents, sometimes causing the old contents of a few files to be archived
+rather than the current contents.  The cause of this problem is that Windows
+does not immediately update a file's last modification timestamp after every
+write to that file.  Unfortunately, there is no known way for applications like
+wimlib to automatically work around this bug.  Manual workarounds are possible;
+theoretically, taking any action that causes the problematic files to be closed,
+such as restarting applications or the computer itself, should cause the files'
+last modification timestamps to be updated.  Also note that wimlib compares file
+sizes as well as timestamps in determining whether a file has changed, which
+helps make the problem less likely to occur; and the problem does not occur on
+other operating systems such as Linux which maintain files' last modification
+timestamps correctly.
+.TP
+\fB--delta-from\fR=\fIWIMFILE\fR
+With \fBwimcapture\fR, capture the new WIM as a "delta" from \fIWIMFILE\fR.  Any
+file data that would ordinarily need to be archived in the new WIM is omitted if
+it is already present in the \fIWIMFILE\fR on which the delta is being based.
+The new WIM will still contain a full copy of the image metadata, but this is
+typically only a small fraction of a WIM's total size.
+.IP ""
+This option can be specified multiple times, in which case the resulting delta
+WIM will only contain file data not present in any of the specified base WIMs.
+.IP ""
+To operate on the resulting delta WIM using other commands such as
+\fBwimapply\fR, you must specify the delta WIM as the WIM file to operate on,
+but also reference the base WIM(s) using the \fB--ref\fR option.  Beware: to
+retain the proper functioning of the delta WIM, you can only add, not delete,
+files and images to the base WIM(s) following the capture of a delta from it.
+.IP ""
+\fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
+speed of capturing a delta WIM.
+.IP ""
+As an example, consider the following backup and restore sequence:
+.IP ""
+.RS
+.nf
+(initial backup)
+
+$ wimcapture /some/directory bkup-base.wim
+
+(some days later, create second backup as delta from first)
+
+$ wimcapture /some/directory bkup-2013-08-20.dwm \\
+       --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
+
+(restoring the second backup)
+
+$ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
+       /some/directory
+.RE
+.fi
+.IP ""
+However, note that as an alternative to the above sequence that used a delta
+WIM, the second backup could have simply been appended to the WIM as new image
+using \fBwimappend\fR.  Delta WIMs should be used only if it's desired to base
+the backups or images on a separate, large file that is rarely modified.
+.IP ""
+Delta WIMs are compatible with Microsoft's WIM software.  For example, you can
+use the /ref option of ImageX to reference the base WIM(s), similar to above.
+.IP ""
+Additional note: wimlib is generalized enough that you can in fact combine
+\fB--pipable\fR and \fB--delta-from\fR to create pipable delta WIMs.  In such
+cases, the base WIM(s) must be captured as pipable as well as the delta WIM, and
+when applying an image, the base WIM(s) must be sent over the pipe after the
+delta WIM.
+.TP
+\fB--wimboot\fR
+Mark the image as WIMBoot-compatible.  See Microsoft's documentation for more
+information about WIMBoot.  With \fBwimcapture\fR this option will set the
+compression type to XPRESS and the chunk size to 4096 bytes; these can, however,
+still be overridden through the \fB--compress\fR and \fB--chunk-size\fR
+parameters, respectively.  In addition, this option will set the configuration
+file to \fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and
+accessible; however, this may still be overridden through the \fB--config\fR
+parameter.
+.TP
+\fB--unsafe-compact\fR
+With \fBwimappend\fR, compact the WIM archive in-place and append any new data,
+eliminating "holes".  This is efficient, but in general this option should
+\fInot\fR be used because a failed or interrupted compaction will corrupt the
+WIM archive.  For more information, see the documentation for this option to
+\fBwimoptimize\fR(1).
+.TP
+\fB--snapshot\fR
+Create a temporary filesystem snapshot of the source directory and capture the
+files from it.  Currently, this option is only supported on Windows, where it
+uses the Volume Shadow Copy Service (VSS).  Using this option, you can create a
+consistent backup of the system volume of a running Windows system without
+running into problems with locked files.  For the VSS snapshot to be
+successfully created, \fBwimlib-imagex\fR must be run as an Administrator, and
+it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then
+\fBwimlib-imagex\fR must be 64-bit as well).
+.SH NOTES
+\fBwimappend\fR does not support appending an image to a split WIM.
+.PP
+Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimappend\fR
+command partway through; however, after doing this, it is recommended to run
+\fBwimoptimize\fR to remove any data that was appended to the physical WIM file
+but not yet incorporated into the structure of the WIM, unless the WIM was being
+fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
+temporary file left over.
+.PP
+\fBwimlib-imagex\fR creates WIMs compatible with Microsoft's software (WIMGAPI,
+ImageX, DISM), with some caveats:
+.IP \[bu] 4
+With \fBwimlib-imagex\fR on UNIX-like systems, it is possible to create a WIM
+image containing files with names differing only in case, or files with names
+containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\', which are
+valid on POSIX-compliant filesystems but not Windows.  Be warned that such files
+will not be extracted by default by the Windows version of \fBwimlib-imagex\fR,
+and (even worse) Microsoft's ImageX can be confused by such names and quit
+extracting the image partway through.
+.IP \[bu]
+Pipable WIMs are incompatible with Microsoft's software.  Pipable WIMs are
+created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
+the \fB--pipable\fR flag was specified.
+.IP \[bu]
+WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
+or as solid archives (with the \fB--solid\fR option) or with LZMS compression
+(with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have varying levels of
+compatibility with Microsoft's software.  Generally, more recent versions of
+Microsoft's software are more compatible.
+.SH EXAMPLES
+First example:  Create a new WIM 'mywim.wim' with LZX ("maximum") compression
+that will contain a captured image of the directory tree 'somedir'.  Note that
+the image name need not be specified and will default to 'somedir':
+.RS
+.PP
+wimcapture somedir mywim.wim
+.RE
+.PP
+Next, append the image of a different directory tree to the WIM created above:
+.RS
+.PP
+wimappend anotherdir mywim.wim
+.RE
+.PP
+Easy enough, and the above examples of imaging directory trees work on both
+UNIX-like systems and Windows.  Next, capture a WIM with several non-default
+options, including XPRESS ("fast") compression, extra integrity information, no
+messing with absolute symbolic links, and an image name and description:
+.RS
+.PP
+wimcapture somedir mywim.wim --compress=fast \\
+.RS
+--check --norpfix "Some Name" "Some Description"
+.RE
+.RE
+.PP
+On a UNIX-like system, capture a full NTFS volume into a new WIM using the
+\fBNTFS VOLUME CAPTURE (UNIX)\fR mode, and name the image "Windows 7":
+.RS
+.PP
+wimcapture /dev/sda2 windows7.wim "Windows 7"
+.RE
+.PP
+or, on Windows, to capture a full NTFS volume you instead need to specify the
+root directory of the mounted volume, for example:
+.RS
+.PP
+wimcapture E:\\ windows7.wim "Windows 7"
+.RE
+.PP
+Same as UNIX example above, but capture the WIM in the wimlib-specific "pipable"
+format that can be piped to \fBwimapply\fR:
+.RS
+.PP
+wimcapture /dev/sda2 windows7.wim "Windows 7" --pipable
+.RE
+.PP
+Same as above, but instead of writing the pipable WIM to the file
+"windows7.wim", write it directly to standard output through a pipe into some
+other program "someprog", which could, for example, be a program or script that
+streams the data to a server:
+.RS
+.PP
+wimcapture /dev/sda2 - "Windows 7" | someprog
+.RE
+.SH SEE ALSO
+.BR wimlib-imagex (1),
+.BR wimapply (1)
+.BR wimoptimize (1)
diff --git a/doc/man1/wimdelete.1 b/doc/man1/wimdelete.1
new file mode 100644 (file)
index 0000000..ca3954e
--- /dev/null
@@ -0,0 +1,55 @@
+.TH WIMDELETE "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimdelete \- Delete an image from a WIM archive
+.SH SYNOPSIS
+\fBwimdelete\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwimdelete\fR, or equivalently \fBwimlib-imagex delete\fR, deletes the
+specified image from the Windows Imaging (WIM) archive \fIWIMFILE\fR.
+.PP
+\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to delete.  It may be the
+1-based index of an image, the name of an image, or the keyword "all" to specify
+all images.  You can use \fBwiminfo\fR(1) to list the images contained in
+\fIWIMFILE\fR.
+.SH NOTES
+By default, \fBwimdelete\fR rebuilds the WIM with all unnecessary file data
+removed.  This is different from Microsoft's ImageX and DISM, which only will
+delete the directory tree metadata and XML data for this operation.  Use
+\fB--soft\fR if you want the other kind of delete.
+.PP
+wimlib allows you to delete all the images from a WIM and have a WIM with 0
+images, although such a file may not be very useful.
+.PP
+\fBwimdelete\fR does not support split WIMs.
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+Before deleting the image, verify the WIM's integrity if extra integrity
+information is present.  In addition, include extra integrity information in the
+modified WIM, even if it was not present before.
+.TP 6
+\fB--soft\fR
+Perform a "soft delete".  Specifying this flag overrides the default behavior of
+rebuilding the entire WIM after deleting an image.  Instead, only minimal
+changes to correctly remove the image from the WIM will be taken.  In
+particular, all file resources will be left alone, even if they are no longer
+referenced.  This may not be what you want, because no space will be saved by
+deleting an image in this way.  However, \fBwimoptimize\fR can later be used to
+rebuild a WIM file that has had images soft-deleted from it.
+.TP
+\fB--unsafe-compact\fR
+Compact the WIM archive in-place, eliminating "holes".  This is efficient, but
+in general this option should \fInot\fR be used because a failed or interrupted
+compaction will corrupt the WIM archive.  For more information, see the
+documentation for this option to \fBwimoptimize\fR(1).
+.SH EXAMPLES
+Delete the first image from 'boot.wim':
+.RS
+.PP
+wimdelete boot.wim 1
+.RE
+.PP
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wiminfo (1)
+.BR wimoptimize (1)
diff --git a/doc/man1/wimdir.1 b/doc/man1/wimdir.1
new file mode 100644 (file)
index 0000000..9fbc671
--- /dev/null
@@ -0,0 +1,46 @@
+.TH WIMDIR "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimdir \- List the files contained in a WIM image
+.SH SYNOPSIS
+\fBwimdir\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIOPTIONS\fR]
+.SH DESCRIPTION
+\fBwimdir\fR, or equivalently \fBwimlib-imagex dir\fR, lists the files and
+directories contained in the specified image of the Windows Imaging (WIM)
+archive \fIWIMFILE\fR.
+.PP
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to list.  It may be the 1-based
+index of an image, the name of an image, or the keyword "all" to specify all
+images.  It may be omitted if \fBWIMFILE\fR contains only one image.  You can
+use \fBwiminfo\fR(1) to list the images contained in \fIWIMFILE\fR.
+.SH OPTIONS
+.TP 6
+\fB--path\fR=\fIPATH\fR
+List the files under \fIPATH\fR instead of under the root directory.
+.TP
+\fB--detailed\fR
+List detailed information about each file.
+.TP
+\fB--one-file-only\fR
+List information about the specified file only.  Intended for use with both
+\fB--path\fR and \fB--detailed\fR.
+.TP
+\fB--ref\fR="\fIGLOB\fR"
+File glob of additional WIMs or split WIM parts to reference resources from.
+This option can be specified multiple times.  This option is only useful when
+\fB--detailed\fR is also specified.
+.SH NOTES
+\fBwimdir\fR supports split WIMs, but it only works on the first part of the
+split WIM.
+.PP
+Detailed metadata such as timestamps and data streams is not shown unless the
+\fB--detailed\fR option is used.
+.SH EXAMPLES
+List all files and directories in the first image of 'boot.wim':
+.RS
+.PP
+wimdir boot.wim 1
+.RE
+.PP
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wiminfo (1)
diff --git a/doc/man1/wimexport.1 b/doc/man1/wimexport.1
new file mode 100644 (file)
index 0000000..cb24ab1
--- /dev/null
@@ -0,0 +1,193 @@
+.TH WIMEXPORT "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimexport \- Export image(s) from a WIM archive
+.SH SYNOPSIS
+\fBwimexport\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR \fIDEST_WIMFILE\fR
+ [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESC\fR]] [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwimexport\fR, or equivalently \fBwimlib-imagex export\fR, exports the
+specified image from \fISRC_WIMFILE\fR into \fIDEST_WIMFILE\fR, optionally
+changing the image's name and/or description.  If \fIDEST_WIMFILE\fR already
+exists, the image will be appended to it; otherwise, a new WIM archive will be
+created to contain the exported image.
+.PP
+\fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be
+the 1-based index of an image, the name of an image, or the keyword "all" to
+specify all images.  You can use \fBwiminfo\fR(1) to list the images contained
+in \fISRC_WIMFILE\fR.
+.PP
+If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being
+exported.  The default is its name in \fISRC_WIMFILE\fR.  If specified,
+\fIDEST_IMAGE_NAME\fR must be either a name not already used in
+\fIDEST_WIMFILE\fR, or the empty string to leave the image unnamed.
+\fIDEST_IMAGE_NAME\fR cannot be specified if "all" images are being exported.
+.PP
+If specified, \fIDEST_IMAGE_DESC\fR is the description to give the image being
+exported.  The default is its description in \fISRC_WIMFILE\fR.
+.PP
+\fBwimexport\fR supports exporting images from stand-alone WIMs as well as from
+split WIMs and delta WIMs.  See \fBSPLIT WIMS\fR.
+.PP
+\fBwimexport\fR also supports exporting images from a non-pipable WIM into a
+pipable WIM or vice versa, or from a non-solid WIM into a solid WIM or vice
+versa.  It can also export a pipable WIM directly to standard output if
+\fIDEST_WIMFILE\fR is specified as "-"; see \fB--pipable\fR.
+.PP
+.SH OPTIONS
+.TP 6
+\fB--boot\fR
+Mark the exported image as the "bootable" image of the WIM; or, if multiple
+images are being exported, make the image that was the bootable image of the
+source WIM also the bootable image of the destination WIM.
+.TP
+\fB--check\fR
+Before exporting the image(s), verify the integrity of the source and
+destination WIMs if extra integrity information is present.  Also include extra
+integrity information in the destination WIM, even if it was not present before.
+.TP
+\fB--nocheck\fR
+Do not include extra integrity information in the destination WIM, even if it
+was present before.
+.TP
+\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Specify the compression type, and optionally the compression level for that
+compression type, for \fIDEST_WIMFILE\fR.  Note that if \fIDEST_WIMFILE\fR
+already exists, then its compression type cannot be changed by this option.  See
+the documentation for this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--chunk-size\fR=\fISIZE\fR
+Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
+this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--recompress\fR
+Force all exported data to be recompressed, even if the destination WIM will use
+the same compression type as the source WIM.
+.TP
+\fB--solid\fR
+Create a "solid" archive that compresses multiple files together.  This usually
+results in a significantly better compression ratio but has disadvantages such
+as reduced compatibility.  See the documentation for this option to
+\fBwimcapture\fR(1) for more details.
+.TP
+\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Like \fB--compress\fR, but set the compression type used in solid resources.
+See the documentation for this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See
+the documentation for this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data.  Default: autodetect (number of
+processors).
+.TP
+\fB--rebuild\fR
+If exporting to an existing WIM, rebuild it rather than appending to it.
+Rebuilding is slower but will save some space that would otherwise be left as a
+hole in the WIM.  Also see \fBwimoptimize\fR(1).
+.TP
+\fB--ref\fR="\fIGLOB\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 \fBwimexport\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" that can be applied fully
+sequentially, including from a pipe.  See \fBwimcapture\fR(1) for more details
+about creating pipable WIMs.  The default without this option is to make
+\fIDEST_WIMFILE\fR pipable only if it was "-" (standard output) or was an
+existing pipable WIM.
+.TP
+\fB--not-pipable\fR
+Rebuild \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This only useful if
+you are exporting image(s) to a pipable WIM but you want it rebuilt as
+non-pipable.
+.TP
+\fB--wimboot\fR
+Mark the destination image as WIMBoot-compatible.  Also, if exporting to a new
+archive, set the compression type to that recommended for WIMBoot (currently,
+XPRESS with 4096 byte chunks).
+.TP
+\fB--unsafe-compact\fR
+Compact the existing destination WIM in-place and append any new data,
+eliminating "holes".  This is efficient, but in general this option should
+\fInot\fR be used because a failed or interrupted compaction will corrupt the
+WIM archive.  For more information, see the documentation for this option to
+\fBwimoptimize\fR(1).
+.SH SPLIT WIMS
+You may use \fBwimexport\fR to export images from (but not to) 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
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+.PP
+To export the first image of this split WIM to a new or existing WIM file
+"other.wim", run:
+.PP
+.RS
+wimexport mywim.swm 1 other.wim --ref="mywim*.swm"
+.RE
+.SH NOTES
+\fIData consistency\fR: Except when using \fB--unsafe-compact\fR, it is safe to
+abort a \fBwimexport\fR command partway through.  However, after doing this, it
+is recommended to run \fBwimoptimize\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 the WIM was being rebuilt (e.g. with
+\fB--rebuild\fR), in which case you should delete the temporary file left over.
+.PP
+\fIData deduplication\fR: The WIM format has built-in deduplication (also called
+"single instancing") of file contents.  Therefore, when an image is exported,
+only the file contents not already present in the destination WIM will be
+physically copied.  However, a new copy of the image's metadata resource, which
+describes the image's directory structure, will always be created.
+.PP
+\fIESD files\fR: \fBwimexport\fR supports solid-compressed WIMs, or "ESD" (.esd)
+files, except for encrypted ESDs, which must be decrypted first.  The source and
+destination files of \fBwimexport\fR can be solid WIMs, non-solid WIMs, or a
+combination thereof.  If the destination file does not exist, then by default it
+will be created as solid if the source was solid, or as non-solid if the source
+was non-solid.  To override this, either specify \fB--solid\fR to create a solid
+WIM (.esd file), or specify \fB--compress\fR=\fILZX\fR to create a standard
+non-solid WIM (.wim file).
+.SH EXAMPLES
+Export the second image of 'boot.wim' to the new WIM file 'new.wim':
+.RS
+.PP
+wimexport 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
+wimexport boot.wim 2 new.wim --compress=LZX
+.RE
+.PP
+Export "ESD to WIM" --- that is, solid WIM to non-solid WIM:
+.RS
+.PP
+wimexport install.esd all install.wim --compress=LZX
+.RE
+.PP
+Export "WIM to ESD" --- that is, non-solid WIM to solid WIM:
+.RS
+.PP
+wimexport install.wim all install.esd --solid
+.RE
+.PP
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wiminfo (1)
+.BR wimoptimize (1)
similarity index 57%
rename from doc/man1/wimlib-imagex-extract.1
rename to doc/man1/wimextract.1
index 6a9f3fc..688d191 100644 (file)
@@ -1,23 +1,21 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.TH WIMEXTRACT "1" "August 2016" "wimlib 1.10.0" "User Commands"
 .SH NAME
-wimlib-imagex-extract \- Extract files or directories from a WIM image
+wimextract \- Extract files from a WIM image
 .SH SYNOPSIS
-\fBwimlib-imagex extract\fR \fIWIMFILE\fR \fIIMAGE\fR [(\fIPATH\fR | @\fILISTFILE\fR)...]  [\fIOPTION\fR...]
+\fBwimextract\fR \fIWIMFILE\fR \fIIMAGE\fR [(\fIPATH\fR | @\fILISTFILE\fR)...]  [\fIOPTION\fR...]
 .SH DESCRIPTION
-\fBwimlib-imagex 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.
+\fBwimextract\fR, or equivalently \fBwimlib-imagex extract\fR, extracts one or
+more files or directory trees from the specified \fIIMAGE\fR contained in the
+Windows Imaging (WIM) archive \fIWIMFILE\fR.
 .PP
-\fBwimlib-imagex 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
-NTFS volume, use \fBwimlib-imagex apply\fR (1) instead.
+\fBwimextract\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 NTFS volume,
+use \fBwimapply\fR(1) instead.
 .PP
-\fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
-directory trees to extract.  It may be a 1-based index of an image in the WIM or
-the name of an image in the WIM.  Use the \fBwimlib-imagex info\fR (1)
-command to show what images a WIM file contains.
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR from which to extract the files
+or directory trees.  It may be the 1-based index of an image or the name of an
+image.  It may be omitted if \fIWIMFILE\fR contains only one image.  You can use
+\fBwiminfo\fR(1) to list the images contained in \fIWIMFILE\fR.
 .PP
 If no additional arguments are given, the entire WIM image is extracted.
 Otherwise, each additional argument is interpreted as a \fIPATH\fR if it does
@@ -38,20 +36,19 @@ directory in such a way that the archive's directory structure is
 preserved.  Use \fB--preserve-dir-structure\fR to always get the latter
 behavior.
 .PP
-\fBwimlib-imagex extract\fR supports extracting files and directory trees
-from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
+\fBwimextract\fR supports extracting files and directory trees from stand-alone
+WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
 .SH PATHS AND LISTFILES
 Each path, including those on the command line and those in listfiles, must be
 specified as an absolute path starting from the root of the WIM image, like
-those output by the \fBwimlib-imagex dir\fR (1) command.  However, path
-separators may be either forward or backward slashes, and the leading slash is
-optional.
+those output by \fBwimdir\fR(1).  However, path separators may be either forward
+or backward slashes, and the leading slash is optional.
 .PP
 On Windows, by default paths are treated case-insensitively, whereas on
 UNIX-like systems, by default paths are treated case-sensitively.  In either
 case, the default behavior may be overridden through the
 \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental variable, as documented in
-\fBwimlib-imagex\fR (1).
+\fBwimlib-imagex\fR(1).
 .PP
 By default, each path may contain the wildcard characters '?' and '*'.  The '?'
 character matches any non-path-separator character, whereas the '*' character
@@ -82,21 +79,20 @@ allowed by default.  The following demonstrates an example listfile:
     \\Windows\\notepad*
 
 .SH SPLIT WIMS
-You may use \fBwimlib-imagex extract\fR to extract files or directory trees
-from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
-way as in other commands such as \fBwimlib-imagex apply\fR.  See
-\fBwimlib-imagex apply\fR (1) for more details.
+You may use \fBwimextract\fR to extract files or directory trees from a split
+WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same way as in other
+commands such as \fBwimapply\fR.  See \fBwimapply\fR(1) for more details.
 .SH OPTIONS
 .TP 6
 \fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
-present.
+Before extracting the files, verify the integrity of \fIWIMFILE\fR if it
+contains extra integrity information.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
 File glob of additional WIMs or split WIM parts to reference resources from.
 See \fBSPLIT_WIMS\fR.  Note: \fIGLOB\fR is listed in quotes because it is
-interpreted by \fBwimlib-imagex\fR and may need to be quoted to protect
-against shell expansion.
+interpreted by \fBwimextract\fR and may need to be quoted to protect against
+shell expansion.
 .TP
 \fB--dest-dir\fR=\fIDIR\fR
 Extract the files and directories to the directory \fIDIR\fR instead of to the
@@ -105,23 +101,23 @@ current working directory.
 \fB--to-stdout\fR
 Extract the files to standard output instead of to the filesystem.  This can
 only be provided if all the specified paths are to regular files (not
-directories or reparse points).  If present, alternate data streams are not
+directories or reparse points).  If present, named data streams are not
 extracted.
 .TP
 \fB--unix-data\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--no-acls\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--strict-acls\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--no-attributes\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--include-invalid-names\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--no-globs\fR
 Do not recognize wildcard characters in paths.  Each path will be searched for
@@ -150,53 +146,37 @@ default behavior for paths in listfiles, but not paths directly specified on the
 command line.
 .TP
 \fB--wimboot\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .TP
 \fB--compact\fR=\fIFORMAT\fR
-See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
+See the documentation for this option to \fBwimapply\fR(1).
 .SH NOTES
-See the documentation \fBwimlib-imagex apply\fR (1) for documentation about
-what data and metadata are extracted on UNIX-like systems versus on Windows.
-.PP
-On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
-one can alternatively mount the WIM image with \fBwimlib-imagex mount\fR (1)
-and then extract the desired files or directories using any standard
-command-line or graphical program.
+See \fBwimapply\fR(1) for information about what data and metadata are extracted
+on UNIX-like systems versus on Windows.
 .PP
 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
-point within the extraction location) are never done by \fBwimlib-imagex
-extract\fR.  Use \fBwimlib-imagex apply\fR if you want this behavior.
-.PP
-Unlike \fBwimlib-imagex apply\fR, \fBwimlib-imagex extract\fR does not
-support extracting files directly to an NTFS volume using libntfs-3g.
-.PP
-wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
-contain LZMS-compressed solid resources 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.
+point within the extraction location) are never done by \fBwimextract\fR.
+Use \fBwimapply\fR if you want this behavior.
+.PP
+Unlike \fBwimapply\fR, \fBwimextract\fR does not support extracting files
+directly to an NTFS volume using libntfs-3g.
 .SH EXAMPLES
 Extract a file from the first image in "boot.wim" to the current directory:
 .RS
 .PP
-wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe
+wimextract boot.wim 1 /Windows/System32/notepad.exe
 .RE
 .PP
 Extract a file from the first image in "boot.wim" to standard output:
 .RS
 .PP
-wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe \\
-.br
-.RS
---to-stdout
-.RE
+wimextract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
 .RE
 .PP
 Extract a file from the first image in "boot.wim" to the specified directory:
 .RS
 .PP
-wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe \\
+wimextract boot.wim 1 /Windows/System32/notepad.exe \\
 .br
 .RS
 --dest-dir=somedir
@@ -207,13 +187,13 @@ Extract the "sources" directory from the first image in "boot.wim" to the
 current directory:
 .RS
 .PP
-wimlib-imagex extract boot.wim 1 /sources
+wimextract boot.wim 1 /sources
 .RE
 .PP
 Extract multiple files and directories in one command:
 .RS
 .PP
-wimlib-imagex extract boot.wim 1 /Windows/Fonts \\
+wimextract boot.wim 1 /Windows/Fonts \\
 .br
 .RS
 /sources /Windows/System32/cmd.exe
@@ -223,13 +203,13 @@ wimlib-imagex extract boot.wim 1 /Windows/Fonts \\
 Extract many files to the current directory using a wildcard pattern:
 .RS
 .PP
-wimlib-imagex extract install.wim 1 "/Windows/Fonts/*.ttf"
+wimextract install.wim 1 "/Windows/Fonts/*.ttf"
 .RE
 .PP
 Extract files using a list file:
 .RS
 .PP
-wimlib-imagex extract install.wim 1 @files.txt
+wimextract install.wim 1 @files.txt
 .RE
 .PP
  ...  where files.txt could be something like:
@@ -245,7 +225,6 @@ Windows\\System32\\en-US\\*.*
 .fi
 .SH SEE ALSO
 .BR wimlib-imagex (1)
-.BR wimlib-imagex-apply (1)
-.BR wimlib-imagex-dir (1)
-.BR wimlib-imagex-info (1)
-.BR wimlib-imagex-mount (1)
+.BR wimapply (1)
+.BR wimdir (1)
+.BR wiminfo (1)
diff --git a/doc/man1/wiminfo.1 b/doc/man1/wiminfo.1
new file mode 100644 (file)
index 0000000..7c44b47
--- /dev/null
@@ -0,0 +1,61 @@
+.TH WIMINFO "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wiminfo \- Display or change information about a WIM file or image
+.SH SYNOPSIS
+\fBwiminfo\fR \fIWIMFILE\fR [\fIIMAGE\fR [\fINEW_NAME\fR [\fINEW_DESC\fR]]] [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwiminfo\fR, or equivalently \fBwimlib-imagex info\fR, displays information
+about \fIWIMFILE\fR or the specified \fIIMAGE\fR in it, and optionally changes
+properties of \fIIMAGE\fR such as its name and description, or changes the
+bootable image of the WIM.
+.PP
+If neither an image nor any flags other than \fB--check\fR are specified, then
+basic information about the WIM and the images contained in it is shown.  If an
+image is specified by \fIIMAGE\fR (as a 1-based image index or an image name),
+then the information is restricted to that concerning the specified image.
+.PP
+Changes to the WIM are made if \fINEW_NAME\fR and/or \fB--boot\fR and/or
+\fB--image-property\fR are specified.  \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, then the image's
+description is not changed.
+.PP
+\fBwiminfo\fR does not support modifying a split WIM, although you may display
+information about one, including any of its parts.
+.SH OPTIONS
+.TP 6
+\fB--boot\fR
+Mark the specified \fIIMAGE\fR as the "bootable" image of the WIM.  The
+"bootable" image is the image which the Windows bootloader will use when loading
+Windows PE from the WIM.
+.TP
+\fB--check\fR
+Verify the integrity of WIM if it contains extra integrity information.  In
+addition, if modifying the WIM, include extra integrity information in the
+modified WIM, even if it was not present before.
+.TP
+\fB--nocheck\fR
+If modifying the WIM, remove its extra integrity information, if it had any.
+.TP
+\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
+Assign an arbitrary property to the specified \fIIMAGE\fR in the XML document of
+the WIM.  \fINAME\fR is an element path such as "WINDOWS/VERSION/MAJOR", and
+\fIVALUE\fR is the string to place in the element, such as "10".  See the
+documentation for this option to \fBwimcapture\fR(1) for more details.  This
+option may be specified multiple times.
+.TP
+\fB--header\fR
+Show detailed information from the WIM header.
+.TP
+\fB--blobs\fR
+List all the "blobs" (unique file data) in the WIM.
+.TP
+\fB--extract-xml\fR=\fIFILE\fR
+Extract the WIM's raw XML document to \fIFILE\fR.
+.TP
+\fB--xml\fR
+.br
+Extract the WIM's raw XML document to standard output.
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wimdir (1)
diff --git a/doc/man1/wimjoin.1 b/doc/man1/wimjoin.1
new file mode 100644 (file)
index 0000000..bdfde02
--- /dev/null
@@ -0,0 +1,37 @@
+.TH WIMJOIN "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimjoin\- Join a split WIM into a standalone WIM
+.SH SYNOPSIS
+\fBwimjoin\fR [\fIOPTION\fR...] \fIOUT_WIMFILE\fR \fISPLIT_WIM_PART\fR...
+.SH DESCRIPTION
+\fBwimjoin\fR, or equivalently \fBwimlib-imagex join\fR, joins the
+\fISPLIT_WIM_PARTs\fR into a standalone (one-part) WIM \fIOUT_WIMFILE\fR.  All
+parts of the split WIM must be specified; you probably want to do so using a
+shell wildcard.
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+When reading each \fISPLIT_WIM_PART\fR, verify its integrity if it contains
+extra integrity information.  In addition, include extra integrity information
+in \fIOUT_WIMFILE\fR, even if the split WIM parts did not contain this
+information.
+.SH EXAMPLES
+Join a split WIM, with the parts named `windows*.swm' where the * is anything
+(usually the number of the part, except for the first part which may have no
+number), and write the joined WIM to the file `windows.wim'.
+.RS
+.PP
+wimjoin windows.wim windows*.swm
+.RE
+.SH NOTES
+Both non-pipable and pipable split WIMs may be joined.
+.PP
+\fBwimjoin\fR is roughly equivalent to:
+.RS
+.PP
+\fBwimexport\fR \fISWM_PART_1\fR --ref="\fISWM_GLOB\fR" all \fIOUT_WIMFILE\fR
+.RE
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wimexport (1)
+.BR wimsplit (1)
diff --git a/doc/man1/wimlib-imagex-append.1 b/doc/man1/wimlib-imagex-append.1
deleted file mode 100644 (file)
index b5121a0..0000000
+++ /dev/null
@@ -1 +0,0 @@
-.so man1/wimlib-imagex-capture.1
diff --git a/doc/man1/wimlib-imagex-apply.1 b/doc/man1/wimlib-imagex-apply.1
deleted file mode 100644 (file)
index 9009680..0000000
+++ /dev/null
@@ -1,473 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-apply \- Extract one image, or all images, from a WIM archive
-.SH SYNOPSIS
-\fBwimlib-imagex apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
-.SH DESCRIPTION
-\fBwimlib-imagex apply\fR extracts an image, or all images, from the Windows
-Imaging (WIM) file \fIWIMFILE\fR.  This command is also available as simply
-\fBwimapply\fR if the appropriate hard link or batch file has been installed.
-.PP
-This command is designed to extract, or "apply", one or more full WIM images.
-If you instead want to extract only certain files or directories contained in a
-WIM image, consider using \fBwimlib-imagex extract\fR or
-\fBwimlib-imagex mount\fR instead.  (\fBwimlib-imagex mount\fR is not
-supported on Windows.)
-.PP
-\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract.  It may be a
-1-based index of an image in \fIWIMFILE\fR, the name of an image in
-\fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR
-are to be extracted.  Use the \fBwimlib-imagex info\fR (1) command to show
-what images a WIM file contains.  \fIIMAGE\fR may be omitted if \fIWIMFILE\fR
-contains only one image.
-.PP
-\fITARGET\fR specifies where to extract the WIM image to.  If \fITARGET\fR
-specifies a directory, the WIM image is extracted to that directory (see
-\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
-Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created
-in that location and the WIM image is extracted to that directory.
-.PP
-If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are
-actually extracted into subdirectories of \fITARGET\fR, each of which is given
-the name of the corresponding image, falling back to the image index in the case
-of an image with no name or a name not valid as a filename.
-.PP
-Alternatively, on UNIX-like systems only, if \fITARGET\fR specifies a regular
-file or block device, it is interpreted as an NTFS volume to which the WIM image
-is to be extracted (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR).  Only a single
-image can be extracted in this mode, and only extracting to the root of the NTFS
-volume (not a subdirectory thereof) is supported.
-.PP
-\fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a
-file, but see \fBPIPABLE WIMS\fR for more information.
-.PP
-\fBwimlib-imagex apply\fR supports applying images from stand-alone WIMs as
-well as split WIMs.  See \fBSPLIT WIMS\fR.
-.SH DIRECTORY EXTRACTION (UNIX)
-This section documents how \fBwimlib-imagex apply\fR (and also
-\fBwimlib-imagex extract\fR) extract a WIM image (or a possibly a subset
-thereof, in the case of \fBwimlib-imagex extract\fR) to a directory on
-UNIX-like systems.  See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
-corresponding documentation for Windows.
-.PP
-As mentioned, a WIM image can be applied to a directory on a UNIX-like system by
-providing a \fITARGET\fR directory.  However, it is important to keep in mind
-that the WIM format was designed for Windows, and as a result WIM files can
-contain data or metadata that cannot be represented on UNIX-like systems.  The
-main information that \fBwimlib-imagex\fR will \fInot\fR be able to extract
-on UNIX-like systems is the following:
-.IP \[bu] 4
-Windows security descriptors (which include the file owner, group, and ACLs).
-.IP \[bu]
-Named data streams.
-.IP \[bu]
-Reparse points other than symbolic links and junction points.
-.IP \[bu]
-Certain file attributes such as compression and encryption.
-.IP \[bu]
-Short (DOS) names for files.
-.IP \[bu]
-File creation timestamps.
-.PP
-Notes: Unsupported data and metadata is simply not extracted, but
-\fBwimlib-imagex\fR will attempt to warn you when the contents of the WIM
-image can't be exactly represented when extracted.  Last access and last
-modification timestamps are specified to 100 nanosecond granularity in the WIM
-file, but will only be extracted to the highest precision supported by the
-underlying operating system, C library, and filesystem.  Compressed files will
-be extracted as uncompressed, while encrypted files will not be extracted at
-all.
-.SH NTFS VOLUME EXTRACTION (UNIX)
-This section documents how \fBwimlib-imagex apply\fR extracts a WIM image
-directly to an NTFS volume image on UNIX-like systems.
-.PP
-As mentioned, \fBwimlib-imagex\fR running on a UNIX-like system can apply a
-WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
-or block device containing an NTFS filesystem.  The NTFS filesystem need not be
-empty, although it's expected that it be empty for the intended use cases.  A
-new NTFS filesystem can be created using the \fBmkntfs\fR(8) command provided
-with \fBntfs-3g\fR.
-.PP
-In this NTFS volume extraction mode, the WIM image is extracted to the root of
-the NTFS volume in a way preserves almost all information contained in the WIM
-image.  It therefore does not suffer from the limitations described in
-\fBDIRECTORY EXTRACTION (UNIX)\fR.  This support relies on libntfs-3g to write
-to the NTFS volume and handle NTFS-specific and Windows-specific data.
-.PP
-Please note that this NTFS volume extraction mode is \fInot\fR entered if
-\fITARGET\fR is a directory, even if an NTFS filesystem is mounted on
-\fITARGET\fR.  You must specify the NTFS volume itself (and it must be
-unmounted, and you must have permission to write to it).
-.PP
-This NTFS volume extraction mode attempts to extract as much information as
-possible, including:
-.IP \[bu] 4
-All data streams of all files except encrypted files, including the unnamed data
-stream as well as all named data streams.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points.
-.IP \[bu]
-File and directory creation, access, and modification timestamps, using the
-native NTFS resolution of 100 nanoseconds.
-.IP \[bu]
-Windows security descriptors, including all components (owner, group, DACL, and
-SACL).
-.IP \[bu]
-DOS/Windows file attribute flags.
-.IP \[bu]
-All names of all files, including names in the Win32 namespace, DOS namespace,
-Win32+DOS namespace, and POSIX namespace.  This includes hard links.
-.IP \[bu]
-Object IDs.
-.PP
-However, a limitation of the NTFS volume extraction mode is that encrypted files
-will not be extracted.
-.PP
-Regardless, since almost all information from the WIM image is restored in this
-mode, it is possible (and fully supported) to restore an image of an actual
-Windows installation using \fBwimlib-imagex\fR on UNIX-like systems as an
-alternative to using \fBwimlib-imagex\fR on Windows.  In the examples at the end
-of this manual page, there is an example of applying an image from the
-"install.wim" file contained in the installation media for Windows (Vista or
-later) in the "sources" directory.
-.PP
-Note that to actually boot Windows (Vista or later) from an applied
-"install.wim" image, you also need to mark the partition as "bootable" and set
-up various boot files, such as \\BOOTMGR and \\BOOT\\BCD.  The latter task is
-most easily accomplished by running the "bcdboot.exe" program from a live
-Windows system (such as Windows PE), but there are other options as well.
-.SH DIRECTORY EXTRACTION (WINDOWS)
-On Windows, \fBwimlib-imagex apply\fR and \fBwimlib-imagex extract\fR
-natively support Windows-specific and NTFS-specific data.  For best results, the
-target directory should be located on an NTFS volume and \fBwimlib-imagex\fR
-should be run with Administrator privileges; however, non-NTFS filesystems and
-running without Administrator privileges are also supported.
-.PP
-On Windows, \fBwimlib-imagex apply\fR and \fBwimlib-imagex extract\fR
-try to extract as much data and metadata as possible, including:
-.IP \[bu] 4
-All data streams of all files.  This includes the default file contents, as well
-as named data streams if supported by the target volume.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the target volume.  (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are extracted.)  However, as per the default security settings of
-Windows, it is impossible to create a symbolic link or junction point without
-Administrator privileges; therefore, you must run \fBwimlib-imagex\fR as the
-Administrator if you wish to fully restore an image containing symbolic links
-and/or junction points.  (Otherwise, merely a warning will be issued when a
-symbolic link or junction point cannot be extracted due to insufficient
-privileges.)
-.IP \[bu]
-File and directory creation, access, and modification timestamps, to the highest
-resolution supported by the target volume.
-.IP \[bu]
-Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
-specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
-descriptors for individual files or directories may be omitted or only partially
-set if the user does not have permission to set them, which can be a problem if
-\fBwimlib-imagex\fR is run as a non-Administrator.
-.IP \[bu]
-File attributes, including hidden, compressed, encrypted, etc, when supported by
-the filesystem.
-.IP \[bu]
-DOS names (8.3) names of files; however, the failure to set them is not
-considered an error condition.
-.IP \[bu]
-Hard links, if supported by the target filesystem.
-.IP \[bu]
-Object IDs, if supported by the target filesystem.
-.PP
-Additional notes about extracting files on Windows:
-.IP \[bu] 4
-\fBwimlib-imagex\fR will issue a warning when it is unable to extract the
-exact metadata and data of the WIM image, for example due to features mentioned
-above not being supported by the target filesystem.
-.IP \[bu]
-Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
-plaintext in the WIM image, \fBwimlib-imagex\fR cannot restore encrypted
-files to filesystems not supporting encryption.  Therefore, on such filesystems,
-encrypted files will not be extracted.  Furthermore, even if encrypted
-files are restored to a filesystem that supports encryption, they will only be
-decryptable if the decryption key is available.
-.IP \[bu]
-Files with names that cannot be represented on Windows will not
-be extracted by default; see \fB--include-invalid-names\fR.
-.IP \[bu]
-Files with full paths over 260 characters (the so-called MAX_PATH) will be
-extracted, but beware that such files will be inaccessible to most Windows
-software and may not be able to be deleted easily.
-.IP \[bu]
-On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt
-to restore files' security descriptors exactly as they are provided in the WIM
-image.  Beware that typical Windows installations contain files whose security
-descriptors do not allow the Administrator to delete them.  Therefore, such
-files will not be able to be deleted, or in some cases even read, after
-extracting, unless processed with a specialized program that knows to acquire
-the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding
-access control lists.  This is not a bug in wimlib, which works as designed to
-correctly restore the data that was archived, but rather a problem with the
-access rights Windows uses on certain files.  But if you just want the file data
-and don't care about security descriptors, use \fB--no-acls\fR to skip restoring
-all security descriptors.
-.IP \[bu]
-A similar caveat to the above applies to file attributes such as Readonly,
-Hidden, and System.  By design, on Windows wimlib will restore such file
-attributes; therefore, extracted files may have those attributes.  If this is
-not what you want, use the \fB--no-attributes\fR option.
-.SH SPLIT WIMS
-You may use \fBwimlib-imagex apply\fR to apply images from a split WIM.  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:
-.RS
-.PP
-.nf
-mywim.swm
-mywim2.swm
-mywim3.swm
-mywim4.swm
-mywim5.swm
-.RE
-.fi
-.PP
-To apply the first image of this split WIM to the directory "dir", run:
-.PP
-.RS
-wimlib-imagex apply mywim.swm 1 dir --ref="mywim*.swm"
-.RE
-.PP
-As a special case, if you are applying an image from standard input from a split
-WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
-option is unneeded; instead you must ensure that all the split WIM parts are
-concatenated together on standard input.  They can be provided in any order,
-with the exception of the first part, which must be first.
-.SH PIPABLE WIMS
-Since wimlib v1.5.0, \fBwimlib-imagex apply\fR supports applying a WIM from a
-nonseekable file, such as a pipe, provided that the WIM was captured with
-\fB--pipable\fR (see \fBwimlib-imagex capture\fR(1)).  To use standard input as
-the WIM, specify "-" as \fIWIMFILE\fR.  A useful use of this ability is to apply
-an image from a WIM while streaming it from a server.  For example, to apply the
-first image from a WIM file available on a HTTP server to an NTFS volume on
-/dev/sda1, run something like:
-.PP
-.RS
-wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
-.RE
-.PP
-(The above also used the \fBwimapply\fR abbreviation for \fBwimlib-imagex
-apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
-explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
-with Microsoft's software.  See \fBwimlib-imagex capture\fR(1) for more
-information.
-.PP
-It is possible to apply an image from a pipable WIM split into multiple parts;
-see \fBSPLIT WIMS\fR.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present.
-.TP
-\fB--ref\fR="\fIGLOB\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
-\fBwimlib-imagex\fR and may need to be quoted to protect against shell
-expansion.
-.TP
-\fB--rpfix\fR, \fB--norpfix\fR
-Set whether to fix targets of absolute symbolic links (reparse points in Windows
-terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
-links that are marked in the WIM image as being fixed are assumed to have
-absolute targets relative to the image root, and therefore \fBwimlib-imagex
-apply\fR prepends the absolute path to the extraction target directory to their
-targets.  The intention is that you can apply an image containing absolute
-symbolic links and still have them be valid after it has been applied to any
-location.
-.IP ""
-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.
-.IP ""
-Reparse point fixups are never done in the NTFS volume extraction mode on
-UNIX-like systems.
-.TP
-\fB--unix-data\fR
-(UNIX-like systems only)  Restore UNIX-specific metadata and special files that
-were captured by \fBwimlib-imagex capture\fR with the \fB--unix-data\fR option.
-This includes: standard UNIX file permissions (owner, group, and mode); device
-nodes, named pipes, and sockets; and extended attributes (Linux-only).
-.TP
-\fB--no-acls\fR
-Do not restore security descriptors on extracted files and directories.
-.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.  If this option is not specified,
-when \fBwimlib-imagex\fR on Windows does not have permission to set a
-security descriptor on an extracted file, it falls back to setting it only
-partially (e.g. with SACL omitted), and in the worst case omits it entirely.
-However, this should only be a problem when running \fBwimlib-imagex\fR
-without Administrator rights.  Also, on UNIX-like systems, this flag can also be
-combined with \fB--unix-data\fR to cause \fBwimlib-imagex\fR to fail
-immediately if the UNIX owner, group, or mode on an extracted file cannot be set
-for any reason.
-.TP
-\fB--no-attributes\fR
-Do not restore Windows file attributes such as readonly, hidden, etc.
-.TP
-\fB--include-invalid-names\fR
-Extract files and directories with invalid names by replacing characters and
-appending a suffix rather than ignoring them.  Exactly what is considered an
-"invalid" name is platform-dependent.
-.IP ""
-On POSIX-compliant systems, filenames are case-sensitive and may contain any
-byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
-have an effect in the unlikely case that the WIM image for some reason has a
-filename containing one of these characters.
-.IP ""
-On Windows, filenames are case-insensitive(*), cannot include control
-characters, and cannot include the characters '/', \'\\0', '\\', ':', '*', '?',
-\'"', '<', '>', or '|'.  Ordinarily, files in WIM images should meet these
-conditions as well. However, it is not guaranteed, and in particular a WIM image
-captured with \fBwimlib-imagex\fR on a POSIX-compliant system could contain such
-files.  By default, invalid names will be ignored, and if there are multiple
-names differing only in case, one will be chosen to extract arbitrarily;
-however, with \fB--include-invalid-names\fR, all names will be sanitized and
-extracted in some form.
-.IP ""
-(*) Unless the ObCaseInsensitive setting has been set to 0 in the Windows
-registry, in which case certain software, including the Windows version of
-\fBwimlib-imagex\fR, will honor case-sensitive filenames on NTFS and other
-compatible filesystems.
-.TP
-\fB--wimboot\fR
-Windows only: Instead of extracting the files themselves, extract "pointer
-files" back to the WIM archive(s).  This can result in significant space savings.
-However, it comes at several potential costs, such as not being able to delete
-the WIM archive(s) and possibly having slower access to files.  See Microsoft's
-documentation for "WIMBoot" for more information.
-.IP ""
-If it exists, the [PrepopulateList] section of the file
-\\Windows\\System32\\WimBootCompress.ini in the WIM image will be read.  Files
-matching any of these patterns will be extracted normally, not as WIMBoot
-"pointer files".  This is helpful for certain files that Windows needs to read
-early in the boot process.
-.IP ""
-This option only works when the program is run as an Administrator and the
-target volume is NTFS or another filesystem that supports reparse points.
-.IP ""
-In addition, this option works best when running on Windows 8.1 Update 1 or
-later, since that is the first version of Windows that contains the Windows
-Overlay Filesystem filter driver ("WOF").  If the WOF driver is detected, wimlib
-will create the WIMBoot "pointer files" using documented ioctls provided by WOF.
-.IP ""
-Otherwise, if the WOF driver is not detected, wimlib will create the reparse
-points and edit the file "\\System Volume Information\\WimOverlay.dat" on the
-target volume manually.  This is potentially subject to problems, since although
-the code works in certain tested cases, neither of these data formats is
-actually documented by Microsoft.  Before overwriting this file, wimlib will
-save the previous version in "\\System Volume
-Information\\WimOverlay.wimlib_backup", which you potentially could restore if
-you needed to.
-.IP ""
-You actually can still do a \fB--wimboot\fR extraction even if the WIM image is
-not marked as "WIMBoot-compatible".  This option causes the extracted files to
-be set as "externally backed" by the WIM file.  Microsoft's driver which
-implements this "external backing" functionality seemingly does not care whether
-the image(s) in the WIM are really marked as WIMBoot-compatible.  Therefore, the
-"WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to be a marker for
-intent only.  In addition, the Microsoft driver can externally back files from
-WIM files that use XPRESS chunks of size 8192, 16384, and 32768, or LZX chunks
-of size 32768, in addition to the default XPRESS chunks of size 4096 that are
-created when \fBwimlib-imagex capture\fR is run with the \fB--wimboot\fR
-option.
-.TP
-\fB--compact\fR=\fIFORMAT\fR
-Windows-only: compress the extracted files using System Compression, when
-possible.  This only works on either Windows 10 or later, or on an older Windows
-to which Microsoft's wofadk.sys driver has been added.  Several different
-compression formats may be used with System Compression, and one must be
-specified as \fIFORMAT\fR.  The choices are: xpress4k, xpress8k, xpress16k, and
-lzx.
-.IP ""
-Exclusions are handled in the same way as with the \fB--wimboot\fR option.
-That is: if it exists, the [PrepopulateList] section of the file
-\\Windows\\System32\\WimBootCompress.ini in the WIM image will be read, and
-files matching any of the patterns in this section will not be compressed.
-In addition, wimlib has a hardcoded list of files for which it knows, for
-compatibility with the Windows bootloader, to override the requested compression
-format.
-.SH NOTES
-\fIData integrity\fR:  WIM files include SHA1 message digests for file data.
-\fBwimlib-imagex apply\fR calculates the SHA1 message digest of every file
-it extracts and issues an error if it is not equal to the SHA1 message digest
-provided in the WIM.  (This default behavior seems equivalent to the
-\fB/verify\fR option of ImageX.)  Note that this is separate from the integrity
-table of the WIM, which provides SHA1 message digests over raw chunks of the
-entire WIM file and is checked separately if the \fB--check\fR option is
-specified.
-.PP
-\fIESD files\fR: wimlib v1.6.0 and later can extract files from version 3584
-WIMs, which usually contain LZMS-compressed solid resources 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.
-.PP
-\fIDirectory traversal attacks\fR:  wimlib validates filenames before extracting
-them and is not vulnerable to directory traversal attacks.  This is in contrast
-to Microsoft WIMGAPI/ImageX/DISM which can overwrite arbitrary files on the
-target drive when extracting a malicious WIM file containing files named
-\fI..\fR or containing path separators.
-.SH EXAMPLES
-Extract the first image from the Windows PE image on the Windows (Vista or
-later) installation media to the directory "boot":
-.RS
-.PP
-wimlib-imagex apply /mnt/windows/sources/boot.wim 1 boot
-.RE
-.PP
-Same as above, but using the \fBwimapply\fR abbreviation:
-.RS
-.PP
-wimapply /media/windows/sources/boot.wim 1 boot
-.RE
-.PP
-On Windows, apply an image of an entire volume, for example from "install.wim"
-which can be found on the Windows (Vista or later) installation media:
-.RS
-.PP
-wimlib-imagex apply install.wim 1 E:\\
-.RE
-.PP
-Same as above, but running on a UNIX-like system where the corresponding
-partition is /dev/sda2:
-.RS
-.PP
-wimlib-imagex apply install.wim 1 /dev/sda2
-.RE
-.PP
-Note that before running either of the above commands, an NTFS filesystem may
-need to be created on the partition, for example with format.exe on Windows or
-\fBmkntfs\fR(8) (part of NTFS-3G) on UNIX-like systems.  For example, you might
-run:
-.RS
-.PP
-mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
-.RE
-.PP
-(Of course don't do that if you don't want to destroy all existing data on the
-partition!)
-.PP
-An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
-WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
-WIMS\fR.
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-capture (1)
-.BR wimlib-imagex-extract (1)
-.BR wimlib-imagex-info (1)
diff --git a/doc/man1/wimlib-imagex-capture.1 b/doc/man1/wimlib-imagex-capture.1
deleted file mode 100644 (file)
index 72608dc..0000000
+++ /dev/null
@@ -1,741 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-capture, wimlib-imagex-append \- Create or append a WIM image
-.SH SYNOPSIS
-\fBwimlib-imagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.br
-\fBwimlib-imagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.SH DESCRIPTION
-The \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR commands
-create a Windows Imaging (WIM) image from a directory tree.  The
-\fBwimlib-imagex capture\fR command creates a new WIM file containing the
-captured image, while the \fBwimlib-imagex append\fR command appends the
-captured image to an existing WIM file.
-These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR
-if the appropriate hard links or batch files are installed.
-.PP
-Background information: A WIM image is an independent directory tree in a WIM
-file.  A WIM file may contain any number of separate images.  WIM files are
-single-instancing with regards to file data, so a file is stored only one time
-in the entire WIM, regardless of how many images the file appears in.
-.PP
-\fISOURCE\fR specifies the location of the files to create the new WIM image
-from.  If \fISOURCE\fR is a directory, the WIM image is captured from that
-directory (see \fBDIRECTORY CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE
-(WINDOWS)\fR).   Alternatively, if the \fB--source-list\fR option is specified,
-\fISOURCE\fR is interpreted as a file that itself provides a list of
-files and directories to include in the new WIM image.  Still
-alternatively, only on UNIX-like systems, if \fISOURCE\fR is a
-regular file or block device, it is interpreted as an NTFS volume from
-which a WIM image is to be captured using libntfs-3g (see \fBNTFS VOLUME CAPTURE
-(UNIX)\fR).
-.PP
-\fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description to
-give the new WIM image.  If \fIIMAGE_NAME\fR is not specified, it defaults to
-the base name (excluding path to parent directory) of \fISOURCE\fR, but if this
-name already exists in \fIWIMFILE\fR, a unique suffix is added.  Otherwise,
-\fIIMAGE_NAME\fR must be either a name that does not already exist as an image in
-\fIWIMFILE\fR, or the empty string to create an image with no name.  If
-\fIIMAGE_DESCRIPTION\fR is not specified, no description is given to the new
-image.
-.PP
-As a special case, if \fIWIMFILE\fR is "-", the \fB--pipable\fR option is
-assumed and the WIM file is written to standard output in a special pipable
-format.   See the documentation for \fB--pipable\fR for more details.
-.SH DIRECTORY CAPTURE (UNIX)
-This section documents how \fBwimlib-imagex\fR captures files from a
-directory tree on UNIX-like systems.  See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
-.PP
-On UNIX-like systems, when \fISOURCE\fR specifies a directory or a symbolic link
-to a directory, the WIM image will be captured from the directory tree rooted at
-this directory.  This directory can be on any type of filesystem, and
-mountpoints are followed recursively.  In this mode, wimlib will store the
-following types of information:
-.IP \[bu] 4
-Directories and regular files, and the contents of regular files
-.IP \[bu]
-Hard links
-.IP \[bu]
-Symbolic links (translated losslessly to Windows reparse points)
-.IP \[bu]
-Last modification times (mtime) and last access times (atime) with 100
-nanosecond granularity
-.IP \[bu]
-With \fB--unix-data\fR: standard UNIX file permissions (owner, group, and mode)
-.IP \[bu]
-With \fB--unix-data\fR: device nodes, named pipes, and sockets
-.IP \[bu]
-With \fB--unix-data\fR: extended attributes (Linux only)
-.PP
-There is no support for storing last status change times (ctimes), or hard link
-information for symbolic link files (each symbolic link will be stored as an
-independent file).  In addition, filenames and symbolic link targets on UNIX
-filesystems which are not valid UTF-8 with the addition of surrogate codepoints
-are unsupported.  Note: if you have a filesystem containing filenames in another
-multibyte encoding, such as ISO-8859-1, and you wish to archive it with wimlib,
-you may be able to mount it with an option which causes its filenames to be
-presented as UTF-8.
-.SH NTFS VOLUME CAPTURE (UNIX)
-This section documents how \fBwimlib-imagex\fR captures files directly from
-an NTFS volume image on UNIX-like systems.
-.PP
-On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
-is a regular file or block device.  In this mode, \fISOURCE\fR is assumed to be
-an NTFS volume or volume image, and \fBwimlib-imagex\fR will capture a WIM
-image containing the full contents of the NTFS volume, including NTFS-specific
-data.  This is done using libntfs-3g.
-.PP
-Note that the NTFS volume capture mode is \fInot\fR entered if \fISOURCE\fR is a
-directory, even if an NTFS filesystem is mounted on \fISOURCE\fR using ntfs-3g.
-You must specify the NTFS volume itself (and it must be unmounted, and you must
-have permission to read from it).
-.PP
-The NTFS volume capture mode attempts to capture as much data and metadata as
-possible, including:
-.IP \[bu] 4
-All data streams of all unencrypted files, including the unnamed data stream as
-well as all named data streams.
-.IP \[bu]
-Reparse points.  See \fBREPARSE POINTS AND SYMLINKS\fR for details.
-.IP \[bu]
-File and directory creation, access, and modification timestamps, using the
-native NTFS resolution of 100 nanoseconds.
-.IP \[bu]
-Windows security descriptors, including all components (owner, group, DACL, and
-SACL).
-.IP \[bu]
-DOS/Windows file attribute flags.
-.IP \[bu]
-All names of all files, including names in the Win32 namespace, DOS namespace,
-Win32+DOS namespace, and POSIX namespace.  This includes hard links.
-.IP \[bu]
-Object IDs.
-.PP
-However, the main limitations of this NTFS volume capture mode are:
-.IP \[bu] 4
-Encrypted files are excluded by default.  Although libntfs-3g can read their
-data, they need to be stored in the WIM file in a special format that wimlib
-does not yet support (except on Windows, where wimlib can treat the data as
-opaque and hand it off to the appropriate API function).
-.IP \[bu]
-The sparse attribute on sparse files will be saved, but the data stored will be
-the full data of the file rather than the "sparse" data.  (The data is, however,
-subject to the WIM format's compression.)
-.IP \[bu]
-Some types of reparse points are transparently dereferenced by Windows but not
-by NTFS-3G.  See \fBREPARSE POINTS AND SYMLINKS\fR.
-.SH DIRECTORY CAPTURE (WINDOWS)
-On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
-natively support Windows-specific and NTFS-specific data.  They therefore act
-similarly to the corresponding commands of Microsoft's ImageX or DISM.  For best
-results, the directory being captured should be on an NTFS volume and
-\fBwimlib-imagex\fR should be run with Administrator privileges; however,
-non-NTFS filesystems and running without Administrator privileges are also
-supported.
-.PP
-On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
-try to archive as much data and metadata as possible, including:
-.IP \[bu] 4
-All data streams of all files.
-.IP \[bu]
-Reparse points, if supported by the source filesystem.  See \fBREPARSE POINTS
-AND SYMLINKS\fR for details.
-.IP \[bu]
-File and directory creation, access, and modification timestamps.  These are
-stored with Windows NT's native timestamp resolution of 100 nanoseconds.
-.IP \[bu]
-Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
-is not specified.  However, beware that unless \fB--strict-acls\fR is specified,
-the security descriptors for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read them, which
-can be a problem if \fBwimlib-imagex\fR is run as a non-Administrator.
-.IP \[bu]
-File attributes, including hidden, sparse, compressed, encrypted, etc.
-Encrypted files will be stored in encrypted form rather than in plain text.
-Transparently compressed files will be read as uncompressed and stored subject
-to the WIM's own compression.  There is no special handling for storing sparse
-files, but they are likely to compress to a small size.
-.IP \[bu]
-DOS names (8.3) names of files; however, the failure to read them is not
-considered an error condition.
-.IP \[bu]
-Hard links, if supported by the source filesystem.
-.IP \[bu]
-Object IDs, if supported by the source filesystem.
-.PP
-There is no support for storing NTFS extended attributes.
-.PP
-The capture process is reversible, since when \fBwimlib-imagex apply\fR (on
-Windows) extracts the captured WIM image, it will extract all of the above
-information, at least to the extent supported by the destination filesystem.
-.PP
-Pedantic note: since Windows is not fully compatible with its own filesystem
-(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
-NTFS filesystem but are inaccessible to the Windows API, for example two files
-with names differing only in case in the same directory (unless
-ObCaseInsensitive has been set to 0 in the Windows registry), or a file whose
-name contains certain characters considered invalid by Windows.  If you run into
-problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
-(UNIX)\fR mode from Linux.
-.SH REPARSE POINTS AND SYMLINKS
-A "symbolic link" (or "symlink") is a special file which "points to" some other
-file or directory.  On Windows, a "reparse point" is a generalization of a
-symlink which allows access to a file or directory to be redirected in a more
-complex way.  Windows uses reparse points to support symlinks, and sometimes
-uses them for various other features as well.  Normally, applications can choose
-whether they want to "dereference" reparse points and symlinks or not.
-.PP
-The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
-\fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
-are stored in the archive rather than the files or data they point to.  There is
-a \fB--dereference\fR option, but it is currently only supported by the UNIX
-version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
-Windows filesystems).
-.PP
-Windows also treats certain types of reparse points specially.  For example,
-Windows applications reading from deduplicated, WIM-backed, or system-compressed
-files always see the dereferenced data, even if they ask not to.  Therefore,
-\fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
-points.  But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
-files and will store them as reparse points instead.  This difference can be
-significant in certain situations, e.g. when capturing deduplicated files which,
-to be readable after extraction, require that the chunk store also be present.
-.SH OPTIONS
-.TP 6
-\fB--boot\fR
-Specifies that the new image is to be made the bootable image of the WIM archive.
-.TP
-\fB--check\fR
-For \fBwimlib-imagex append\fR, before performing the append operation,
-check the integrity of \fIWIMFILE\fR if an integrity table is present.
-Furthermore, include an integrity table in the new WIM file
-(\fBwimlib-imagex capture\fR) or the modified WIM file (\fBwimlib-imagex
-append\fR).  If this option is not specified, no integrity table is included in
-a WIM file created with \fBwimlib-imagex capture\fR, while a WIM file
-updated with \fBwimlib-imagex append\fR will be written with an integrity
-table if and only if one was present before.
-.TP
-\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Specifies the compression format for the new WIM file.  \fITYPE\fR may be
-"none", "XPRESS" (alias: "fast"), "LZX" (alias: "maximum"), or "LZMS" (alias:
-"recovery").  \fITYPE\fR is matched case-insensitively.  The default is "LZX".
-.IP ""
-You can optionally also specify an integer compression \fILEVEL\fR.  The
-compression level specifies how hard the compression algorithm for the specified
-compression \fITYPE\fR will work to compress the data.  The values are scaled so
-that 20 is quick compression, 50 is medium compression, and 100 is high
-compression.  However, you can choose any value, and not just these particular
-values.  The default is 50.
-.IP ""
-This option only affects the compression type used in non-solid WIM resources.
-If you are creating a solid WIM (using the \fB--solid\fR option), then you
-probably want \fB--solid-compress\fR instead.
-.IP ""
-Be careful if you choose LZMS compression.  It is not compatible with wimlib
-before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip
-before v15.12.
-.IP ""
-Also note that choosing LZMS compression does not automatically imply solid-mode
-compression, as it does with DISM.  Use \fB--solid\fR if you want to create a
-solid WIM, or "ESD file".
-.TP
-\fB--chunk-size\fR=\fISIZE\fR
-Set the compression chunk size to \fISIZE\fR bytes.  A larger compression chunk
-size results in a better compression ratio.  wimlib supports different chunk
-sizes depending on the compression type:
-.RS
-.IP \[bu] 2
-XPRESS: 4K, 8K, 16K, 32K, 64K
-.IP \[bu]
-LZX: 32K, 64K, 128K, 256K, 512K, 1M, 2M
-.IP \[bu]
-LZMS: 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
-.RE
-.IP ""
-You can provide the full number (e.g. 32768), or you can use one of the K, M, or
-G suffixes.  KiB, MiB, and GiB are also accepted.
-.IP ""
-This option only affects the chunk size used in non-solid WIM resources.  If you
-are creating a solid WIM (using the \fB--solid\fR option), then you probably
-want \fB--solid-chunk-size\fR instead.
-.IP ""
-Use this option with caution if compatibility with Microsoft's implementation is
-desired, since their implementation has limited support for non-default chunk
-sizes.
-.TP
-\fB--solid\fR
-Create a "solid" WIM file that compresses files together rather than
-independently.  This results in a significantly better compression ratio, but it
-comes at the cost of various tradeoffs, including: slow compression with very
-high memory usage; slow random access to the resulting WIM file; and reduced
-compatibility.
-.IP ""
-Compatibility-wise, the first version of Microsoft's WIMGAPI to support solid
-WIM files was released with Windows 8, and the first version of DISM to do so
-was released with Windows 8.1.
-.IP ""
-If you want to create an "ESD file", then use this option.  An (unencrypted)
-"ESD file" is a solid WIM file.
-.IP ""
-By default, this option has an effect equivalent to DISM's option
-\fB/compress:recovery\fR.  The options for wimlib-imagex are different because
-they try not to conflate the compression type (e.g. LZX or LZMS) with solid-mode
-compression, as these are two different things.
-.TP
-\fB--solid-chunk-size\fR=\fISIZE\fR
-Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  The
-default, assuming LZMS compression, is 64MiB (67108864); this requires about
-640MiB of memory per thread.  This option only has an effect when \fB--solid\fR
-is also specified.  Note: Microsoft's implementation is not compatible with LZMS
-chunk sizes larger than 64MiB.
-.TP
-\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Like \fB--compress\fR, but set the compression type used in solid resources.
-The default is LZMS compression.  This option only has an effect when
-\fB--solid\fR is also specified.
-.TP
-\fB--threads\fR=\fINUM_THREADS\fR
-Number of threads to use for compressing data.  Default: autodetect (number of
-available CPUs).
-.TP
-\fB--rebuild\fR
-For \fBwimlib-imagex 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 \fBwimlib-imagex
-optimize\fR(1).
-.TP
-\fB--flags\fR=\fIEDITIONID\fR
-Specify a string to use in the <FLAGS> element of the XML data for the new
-image.
-.TP
-\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
-Specify an arbitrary per-image property to set in the XML document of the WIM
-file.  \fIVALUE\fR is the string to set as the property value.  \fINAME\fR is
-the name of the image property, for example "NAME", "DESCRIPTION", or
-"TOTALBYTES".  The name can contain forward slashes to indicate a nested XML
-element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD element nested
-within the VERSION element nested within the WINDOWS element.  A bracketed
-number can be used to indicate one of several identically-named elements; for
-example, "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
-nested within the "WINDOWS/LANGUAGES" element.  When adding a list of elements
-in this way, they must be specified in sequential order.  Note that element
-names are case-sensitive.  This option may be specified multiple times.
-.TP
-\fB--dereference\fR
-(UNIX-like systems only) Follow symbolic links and archive the files they point
-to, rather than archiving the links themselves.
-.TP
-\fB--config\fR=\fIFILE\fR
-Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
-works) for capturing the new image.  The configuration file specifies files that
-are to be treated specially during the image capture.
-.IP ""
-The format of the configuration file is INI-style; that is, it is arranged in
-bracketed sections.  Currently, the following sections are recognized:
-.RS
-.IP \[bu] 4
-[ExclusionList] ---  contains a list of path globs to exclude from capture.  If
-a directory is matched, both the directory and its contents are excluded.
-.IP \[bu]
-[ExclusionException] --- contains a list of path globs to include in the
-capture, even when the file or directory also matches a glob in [ExclusionList].
-.IP \[bu]
-[PrepopulateList] --- this does not affect capture, but if the image is applied
-later with \fB--wimboot\fR, these are globs of files that shall be extracted
-normally, not as WIMBoot "pointer files".  If a directory is matched, all files
-and subdirectories are also matched recursively.
-.RE
-.IP ""
-Path globs may contain the '*' and '?' meta-characters.  Relative globs (e.g.
-*.mp3) match against a filename in any directory.  Absolute globs (e.g.
-/dir/file), are treated as paths starting at the main directory being captured,
-or the root of the NTFS volume for NTFS volume capture mode.  Do not use drive
-letters in the paths; they will be ignored.  Path separators may be either
-forwards slashes or backwards slashes.
-.IP ""
-Lines beginning with the '#' or ';' characters are treated as comments and
-ignored.  Globs with whitespace in them need not be quoted; however, if they
-are, both double and single quotes are accepted.
-.IP ""
-If this option is not specified the following default configuration file is
-used:
-.IP ""
-.RS
-.RS
-.nf
-[ExclusionList]
-\\$ntfs.log
-\\hiberfil.sys
-\\pagefile.sys
-\\swapfile.sys
-\\System Volume Information
-\\RECYCLER
-\\Windows\\CSC
-.RE
-.RE
-.fi
-.IP ""
-However, special behavior applies if \fB--wimboot\fR is also specified.  By
-default, with \fB--wimboot\fR specified, the file
-Windows/System32/WimBootCompress.ini in the directory being captured will be
-used as the configuration file.  However, this can be overridden using
-\fB--config\fR; and this also causes the specified configuration file to be
-saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
-that may be present on the filesystem.
-.TP
-\fB--unix-data\fR
-(UNIX-like systems only)  Store UNIX-specific metadata and special files.  This
-includes: standard UNIX file permissions (owner, group, and mode); device nodes,
-named pipes, and sockets; and extended attributes (Linux only).  This
-information can later be restored by \fBwimlib-imagex apply\fR with the
-\fB--unix-data\fR option.
-.IP
-UNIX-specific information is ignored by Microsoft's WIM software and by the
-Windows version of wimlib.
-.TP
-\fB--no-acls\fR
-Do not capture files' security descriptors.
-.TP
-\fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file cannot be read.  On
-Windows, the default behavior without this option is to first try omitting the
-SACL from the security descriptor, then to try omitting the security descriptor
-entirely.  The purpose of this is to capture as much data as possible without
-always requiring Administrator privileges.  However, if you desire that all
-security descriptors be captured exactly, you may wish to provide this option,
-although the Administrator should have permission to read everything anyway.
-.TP
-\fB--rpfix\fR, \fB--norpfix\fR
-Set whether to fix targets of absolute symbolic links (reparse points in Windows
-terminology) or not.  When enabled (\fB--rpfix\fR), absolute symbolic links that
-point inside the directory tree being captured will be adjusted to be absolute
-relative to the root of the directory tree being captured.  When disabled
-(\fB--norpfix\fR), absolute symbolic links will be captured exactly as is.
-.IP ""
-The default behavior for \fBwimlib-imagex capture\fR is equivalent to
-\fB--rpfix\fR.  The default behavior for \fBwimlib-imagex append\fR will be
-\fB--rpfix\fR if reparse point fixups have previously been done on
-\fIWIMFILE\fR, otherwise \fB--norpfix\fR.
-.IP ""
-In the case of a multi-source capture, (\fB--source-list\fR specified), passing
-\fB--norpfix\fR is recommended.  Otherwise, reparse point fixups will be
-disabled on all capture sources destined for non-root locations in the WIM
-image, while capture sources destined for the WIM root will get the default
-behavior from the previous paragraph.
-.TP
-\fB--source-list\fR
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR support
-creating a WIM image from multiple separate files or directories.  When
-\fB--source-list\fR is specified, the \fISOURCE\fR argument specifies the name
-of a text file, each line of which is either 1 or 2 whitespace separated file
-paths.  The first file path, the source, specifies the path to a file or
-directory to capture into the WIM image.  It may be either absolute or relative
-to the current working directory.  The second file path, if provided, is the
-target and specifies the path  in the WIM image that this file or directory will
-be saved as.  Leading and trailing slashes in the target are ignored, except if
-it consists entirely of slashes (e.g. "/"), which indicates that the directory
-is to become the root of the WIM image.  If omitted, the target string defaults
-to the same as the source string.
-.IP ""
-An example source list file is as follows:
-.IP ""
-.RS
-.RS
-.nf
-# Make the WIM image from the 'winpe' directory
-winpe  /
-
-# Send the 'overlay' directory to '/overlay' in the WIM image
-overlay        /overlay
-
-# Overlay a separate directory directly on the root of the WIM image.
-/data/stuff    /
-.RE
-.RE
-.fi
-.IP ""
-Subdirectories in the WIM are created as needed.  Multiple source directories
-may share the same target, which implies an overlay.  In the event that this
-results a nondirectory file being added to the WIM image multiple times, the
-last version (as listed in the source list file) overrides any earlier version.
-.IP ""
-File paths containing whitespace may be quoted with either single quotes or
-double quotes.  Quotes may not be escaped.
-.IP ""
-Lines consisting only of whitespace and lines beginning with '#' preceded by
-optional whitespace are ignored.
-.IP ""
-As a special case, if \fISOURCE\fR is "-", the source list is read from standard
-input rather than an external file.
-.IP ""
-The NTFS volume capture mode on UNIX-like systems cannot be used with
-\fB--source-list\fR, as only capturing a full NTFS volume is supported.
-.TP
-\fB--pipable\fR
-Create a "pipable" WIM, which can be applied fully sequentially, including from
-a pipe.  An image in the resulting WIM can be applied with \fBwimlib-imagex
-apply\fR, either normally by specifying the WIM file name, or with
-\fBwimlib-imagex apply -\fR to read the WIM from standard input.  See
-\fBwimlib-imagex apply\fR(1) for more details.
-.IP ""
-For append operations, this option will result in a full rebuild of the WIM to
-make it pipable.  For capture operations, the captured WIM is simply created as
-pipable.  Beware that the more images you add to a pipable WIM, the less
-efficient piping it will be, since more unneeded data will be sent through the
-pipe.
-.IP ""
-When wimlib creates a pipable WIM, it carefully re-arranges the components of
-the WIM so that they can be read sequentially and also makes several other
-modifications.  As a result, these "pipable" WIMs are \fInot compatible with
-Microsoft's software\fR, so keep this in mind if you're going to use them.  If
-desired, you can use \fBwimlib-imagex optimize --not-pipable\fR to re-write
-a pipable WIM as a regular WIM.  (\fBwimlib-imagex export\fR also provides
-the capability to export images from a pipable WIM into a non-pipable WIM, or
-vice versa.)
-.IP ""
-For the most part, wimlib operates on pipable WIMs transparently.  You can
-modify them, add or delete images, export images, and even create split pipable
-WIMs.  The main disadvantages are that appending is (currently) less efficient
-(\fB--rebuild\fR is always implied), and also they aren't compatible with
-Microsoft's software.
-.IP ""
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR can both
-write a pipable WIM directly to standard output; this is done automatically if
-\fIWIMFILE\fR is specified as "-".  (In that case, \fB--pipable\fR is assumed.)
-.TP
-\fB--not-pipable\fR
-Ensure the resulting WIM is in the normal, non-pipable WIM format.  This is the
-default for \fBwimlib-imagex capture\fR, except when writing to standard
-output (\fIWIMFILE\fR specified as "-"), and also for \fBwimlib-imagex
-append\fR, except when appending to a WIM that is already pipable.
-.TP
-\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
-Declares that the image being captured or appended from \fISOURCE\fR is mostly the same as
-the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later point
-in time, possibly with some modifications in the intervening time.  This is
-designed to be used in incremental backups of the same filesystem or directory
-tree.  \fIIMAGE\fR can be a 1-based index or name of an existing image in
-\fIWIMFILE\fR.  It can also be a negative integer to index backwards into the
-images (e.g.  -1 means the last existing image in \fIWIMFILE\fR).
-.IP ""
-When this option is provided, the capture or append of the new image will be
-optimized by not reading files that, based on metadata such as timestamps,
-appear not to have been modified since they were archived in the existing
-\fIIMAGE\fR.  Barring manipulation of timestamps, this option only affects
-performance and does not change the resulting WIM image (but see note below).
-.IP ""
-As shown, the full syntax for the argument to this option is to specify the WIM
-file, a colon, and the image; for example, "--update-of mywim.wim:1".  However,
-the WIM file and colon may be omitted, in which case the WIM file will default
-to the WIM file being appended to for append operations, or the WIM file from
-which a delta is being taken (only if \fB--delta-from\fR is specified exactly
-once) for capture operations.
-.IP ""
-Note: in the Windows version of wimlib, it has been observed that
-\fB--update-of\fR mode is not completely reliable at detecting changes in file
-contents, sometimes causing the old contents of a few files to be archived
-rather than the current contents.  The cause of this problem is that Windows
-does not immediately update a file's last modification timestamp after every
-write to that file.  Unfortunately, there is no known way for applications like
-wimlib to automatically work around this bug.  Manual workarounds are possible;
-theoretically, taking any action that causes the problematic files to be closed,
-such as restarting applications or the computer itself, should cause the files'
-last modification timestamps to be updated.  Also note that wimlib compares file
-sizes as well as timestamps in determining whether a file has changed, which
-helps make the problem less likely to occur; and the problem does not occur on
-other operating systems such as Linux which maintain files' last modification
-timestamps correctly.
-.TP
-\fB--delta-from\fR=\fIWIMFILE\fR
-For \fBwimlib-imagex capture\fR only: capture the new WIM as a "delta" from
-\fIWIMFILE\fR.  Any streams that would ordinarily need to be archived in the new
-WIM are omitted if they are already present in the \fIWIMFILE\fR on which the
-delta is being based.  The new WIM will still contain a full copy of the image
-metadata, but this is typically only a small fraction of a WIM's total size.
-.IP ""
-This option can be specified multiple times, in which case the resulting delta
-WIM will only contain streams not present in any of the specified base WIMs.
-.IP ""
-To operate on the resulting delta WIM using other commands such as
-\fBwimlib-imagex apply\fR, you must specify the delta WIM as the WIM file to
-operate on, but also reference the base WIM(s) using the \fB--ref\fR option.
-Beware: to retain the proper functioning of the delta WIM, you can only add, not
-delete, files and images to the base WIM(s) following the capture of a delta
-from it.
-.IP ""
-\fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
-speed of capturing a delta WIM.
-.IP ""
-As an example, consider the following backup and restore sequence:
-.IP ""
-.RS
-.nf
-(initial backup)
-
-$ wimcapture /some/directory bkup-base.wim
-
-(some days later, create second backup as delta from first)
-
-$ wimcapture /some/directory bkup-2013-08-20.dwm \\
-       --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
-
-(restoring the second backup)
-
-$ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
-       /some/directory
-.RE
-.fi
-.IP ""
-However, note that as an alternative to the above sequence that used a delta
-WIM, the second backup could have simply been appended to the WIM as new image
-using \fBwimlib-imagex append\fR.  Delta WIMs should be used only if it's
-desired to base the backups or images on a separate, large file that is rarely
-modified.
-.IP ""
-Note: unlike "pipable" WIMs (created with the \fB--pipable\fR option), "delta"
-WIMs (created with the \fB--delta-from\fR option) are compatible with
-Microsoft's software.  For example, you can use the /ref option of ImageX to
-reference the base WIM(s), similar to above.
-.IP ""
-Additional note:  \fBwimlib-imagex\fR is generalized enough that you can in
-fact combine \fB--pipable\fR and \fB--delta-from\fR to create pipable delta
-WIMs.  In such cases, the base WIM(s) must be captured as pipable as well as the
-delta WIM, and when applying an image, the base WIM(s) must be sent over the
-pipe after the delta WIM.
-.TP
-\fB--wimboot\fR
-Mark the image as WIMBoot-compatible.  See Microsoft's
-documentation for more information about WIMBoot.  This option will, by default,
-set the compression type to XPRESS and the chunk size to 4096 bytes; these
-can, however, still be overridden through the \fB--compress\fR and
-\fB--chunk-size\fR parameters, respectively.  In addition, this option will, by
-default, set the configuration file to
-\fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and accessible;
-however, this may still be overridden through the \fB--config\fR parameter.
-.TP
-\fB--unsafe-compact\fR
-For \fBwimlib-imagex append\fR: compact the WIM archive in-place and append any
-new data, eliminating "holes".  In general, this option should \fInot\fR be used
-because a failed or interrupted compaction will corrupt the WIM archive.  For
-more information, see the documentation for this option in
-\fBwimlib-imagex-optimize\fR (1).
-.TP
-\fB--snapshot\fR
-Create a temporary filesystem snapshot of the source directory and capture the
-files from it.  Currently, this option is only supported on Windows, where it
-uses the Volume Shadow Copy Service (VSS).  Using this option, you can create a
-consistent backup of the system volume of a running Windows system without
-running into problems with locked files.  For the VSS snapshot to be
-successfully created, \fBwimlib-imagex\fR must be run as an Administrator, and
-it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then
-\fBwimlib-imagex\fR must be 64-bit as well).
-.SH NOTES
-\fBwimlib-imagex append\fR does not support appending an image to a split WIM.
-.PP
-Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimlib-imagex
-append\fR command partway through; however, after doing this, it is recommended
-to run \fBwimlib-imagex 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
-the WIM was being fully rebuilt (e.g. with \fB--rebuild\fR), in which case you
-should delete the temporary file left over.
-.PP
-\fBwimlib-imagex\fR creates WIMs compatible with Microsoft's software
-(WIMGAPI, ImageX, DISM), with some caveats:
-.IP \[bu] 4
-With \fBwimlib-imagex\fR on UNIX-like systems, it is possible to create a
-WIM image containing files with names differing only in case, or files with
-names containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\',
-which are valid on POSIX-compliant filesystems but not Windows.  Be warned that
-such files will not be extracted by default by the Windows version of
-\fBwimlib-imagex\fR, and (even worse) Microsoft's ImageX can be confused by
-such names and quit extracting the image partway through.  (It perhaps is worth
-pointing out that Windows' own default filesystem, NTFS, supports these
-characters, although Windows does not!)
-.IP \[bu]
-Pipable WIMs are incompatible with Microsoft's software.  Pipable WIMs are
-created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
-the \fB--pipable\fR flag was specified.
-.IP \[bu]
-WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
-or as solid archives (with the \fB--solid\fR option) or with LZMS
-compression (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have
-varying levels of compatibility with Microsoft's software.  Generally, more
-recent versions of Microsoft's software are more compatible.
-.SH EXAMPLES
-First example:  Create a new WIM 'mywim.wim' with LZX ("maximum") compression
-that will contain a captured image of the directory tree 'somedir'.  Note that
-the image name need not be specified and will default to 'somedir':
-.RS
-.PP
-wimlib-imagex capture somedir mywim.wim
-.RE
-.PP
-or, if the \fBwimcapture\fR hard link or batch file has been installed, the
-abbreviated form can be used:
-.RS
-.PP
-wimcapture somedir mywim.wim
-.RE
-.PP
-The remaining examples will use the long form, however.  Next, append the image
-of a different directory tree to the WIM created above:
-.RS
-.PP
-wimlib-imagex append anotherdir mywim.wim
-.RE
-.PP
-Easy enough, and the above examples of imaging directory trees work on both
-UNIX-like systems and Windows.  Next, capture a WIM with several non-default
-options, including XPRESS ("fast") compression, an integrity table, no messing
-with absolute symbolic links, and an image name and description:
-.RS
-.PP
-wimlib-imagex capture somedir mywim.wim --compress=fast \\
-.RS
---check --norpfix "Some Name" "Some Description"
-.RE
-.RE
-.PP
-Capture an entire NTFS volume into a new WIM file and name the image "Windows
-7".  On UNIX-like systems, this requires using the special mode described in
-\fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
-containing an NTFS filesystem:
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 windows7.wim "Windows 7"
-.RE
-.PP
-or, on Windows, to capture a full NTFS volume you instead need to specify the
-root directory of the mounted volume, for example:
-.RS
-.PP
-wimlib-imagex capture E:\\ windows7.wim "Windows 7"
-.RE
-.PP
-Same as above example with capturing an NTFS volume from \fBwimlib-imagex\fR
-running on a UNIX-like system, but capture the WIM in the wimlib-specific
-"pipable" format that can be piped to \fBwimlib-imagex apply\fR:
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 windows7.wim "Windows 7" \\
-.br
-.RS
---pipable
-.RE
-.RE
-.PP
-Same as above, but instead of writing the pipable WIM to the file
-"windows7.wim", write it directly to standard output through a pipe into some
-other program "someprog", which could, for example, be a program or script that
-streams the data to a server.  Note that \fB--pipable\fR need not be explicitly
-specified when using standard output as the WIM "file":
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 - "Windows 7" | someprog
-.RE
-.SH SEE ALSO
-.BR wimlib-imagex (1),
-.BR wimlib-imagex-apply (1)
diff --git a/doc/man1/wimlib-imagex-delete.1 b/doc/man1/wimlib-imagex-delete.1
deleted file mode 100644 (file)
index 729b28c..0000000
+++ /dev/null
@@ -1,63 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-delete \- Delete an image from a WIM archive
-.SH SYNOPSIS
-\fBwimlib-imagex delete\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIOPTION\fR...]
-.SH DESCRIPTION
-\fBwimlib-imagex delete\fR deletes the specified image from the Windows Imaging (WIM)
-file \fIWIMFILE\fR.
-This command is also available as simply \fBwimdelete\fR if the appropriate hard
-link or batch file has been installed.
-.PP
-\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to delete.  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 deleted.  Use the
-\fBwimlib-imagex info\fR (1) command to show what images a WIM file
-contains.
-.SH NOTES
-By default, the WIM file is rebuilt with all unnecessary file data removed.
-This is different from Microsoft's ImageX and DISM, which only will delete the
-directory tree metadata and XML data for this operation.  (See the \fB--soft\fR
-option for the other kind of delete).
-.PP
-Also wimlib allows you to delete all the images from a WIM and have a WIM with 0
-images, although such a file wouldn't be very useful.
-.PP
-\fBwimlib-imagex delete\fR does not support split WIMs.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present; additionally, when rewriting \fIWIMFILE\fR after the specified image
-was deleted, always write an integrity table.  If this option is not specified,
-the integrity of \fIWIMFILE\fR will not be checked when it's opened, but an
-integrity table will be written in the updated WIM if and only if one was
-present before.
-.TP 6
-\fB--soft\fR
-Perform a "soft delete".  Specifying this flag overrides the default behavior of
-rebuilding the entire WIM after deleting an image.  Instead, only minimal
-changes to correctly remove the image from the WIM will be taken.  In
-particular, all streams will be left alone, even if they are no longer
-referenced.  This is probably not what you want, because no space will be
-saved by deleting an image in this way.
-.IP ""
-You may use \fBwimlib-imagex optimize\fR to delete unreferenced streams from a WIM that
-has had images soft-deleted from it.
-.TP
-\fB--unsafe-compact\fR
-Compact the WIM archive in-place, eliminating "holes".  In general, this option
-should \fInot\fR be used because a failed or interrupted compaction will corrupt
-the WIM archive.  For more information, see the documentation for this option in
-\fBwimlib-imagex-optimize\fR (1).
-.SH EXAMPLES
-Delete the first image from 'boot.wim':
-.RS
-.PP
-wimlib-imagex delete boot.wim 1
-.RE
-.PP
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-info (1)
-.BR wimlib-imagex-optimize (1)
diff --git a/doc/man1/wimlib-imagex-dir.1 b/doc/man1/wimlib-imagex-dir.1
deleted file mode 100644 (file)
index 0036e6e..0000000
+++ /dev/null
@@ -1,49 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-dir \- Show the files contained in a WIM archive
-.SH SYNOPSIS
-\fBwimlib-imagex dir\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIOPTIONS\fR]
-.SH DESCRIPTION
-Lists the files and directories contained in the specified image of the Windows
-Imaging (WIM) file \fIWIMFILE\fR.
-This command is also available as simply \fBwimdir\fR if the appropriate hard
-link or batch file has been installed.
-.PP
-\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to show the files of.  It may
-be a 1-based index of an image in \fIWIMFILE\fR, the name of an image in
-\fIWIMFILE\fR, or the keyword "all" to indicate that files from all images in
-\fIWIMFILE\fR are to be shown.  Use the \fBwimlib-imagex info\fR (1) command
-to show what images a WIM file contains.
-.SH OPTIONS
-.TP 6
-\fB--path\fR=\fIPATH\fR
-List the files recursively from the \fIPATH\fR directory instead of from the
-root directory.
-.TP
-\fB--detailed\fR
-List detailed information about each file.
-.TP
-\fB--one-file-only\fR
-Show information about one file only.  Intended for use with both \fB--path\fR
-and \fB--detailed\fR.
-.TP
-\fB--ref\fR="\fIGLOB\fR"
-File glob of additional WIMs or split WIM parts to reference resources from.
-This option can be specified multiple times.  This option is only useful when
-\fB--detailed\fR is also specified.
-.SH NOTES
-\fBwimlib-imagex dir\fR supports split WIMs, but it will only work on the
-first part of the split WIM.
-.PP
-DOS names and alternate (named) data streams are not listed unless the
-\fB--detailed\fR mode is used.
-.SH EXAMPLES
-List all files in the first image of 'boot.wim':
-.RS
-.PP
-wimlib-imagex dir boot.wim 1
-.RE
-.PP
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-info (1)
diff --git a/doc/man1/wimlib-imagex-export.1 b/doc/man1/wimlib-imagex-export.1
deleted file mode 100644 (file)
index 9eaf5be..0000000
+++ /dev/null
@@ -1,217 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-export \- Exports an image from a WIM archive to an existing or new WIM archive
-.SH SYNOPSIS
-\fBwimlib-imagex export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\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,
-optionally changing its name and/or description and/or compression type.
-If \fIDEST_WIMFILE\fR exists, it is taken 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 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 \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 \fBwimlib-imagex info\fR (1)
-command to list the images a WIM file contains.
-.PP
-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 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
-\fBwimlib-imagex export\fR supports exporting images from stand-alone WIMs as well as
-from split WIMs.  However, you cannot export an image to a split WIM.  See
-\fBSPLIT WIMS\fR.
-.PP
-\fBwimlib-imagex export\fR also supports exporting images from a non-pipable
-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
-.TP 6
-\fB--boot\fR
-Specifies that the exported image is to be the bootable image of the destination
-WIM archive.
-.IP ""
-If multiple images are being exported, this flag indicates that the image in the
-\fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
-\fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
-error.
-.TP
-\fB--check\fR
-When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
-file's integrity if the integrity table is present; additionally, when writing
-\fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
-If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
-table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
-already existed and it had an integrity table before.
-.TP
-\fB--nocheck\fR
-When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
-integrity table.
-If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
-table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
-already existed and it had an integrity table before.
-.TP
-\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Specifies the compression type, and optionally the compression level for that
-compression type, for \fIDEST_WIMFILE\fR.  Setting the compression type only has
-an effect if \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR
-exists, the compression type must be the same as that of \fIDEST_WIMFILE\fR.
-.IP ""
-See the documentation for this option to \fBwimlib-imagex capture\fR (1) for
-more details.
-.TP
-\fB--recompress\fR
-Force all exported data to be recompressed, even if the destination WIM will use
-the same compression type as the source WIM.
-.TP
-\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
-this option to \fBwimlib-imagex capture\fR (1) for more details.
-.TP
-\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 \fBwimlib-imagex
-capture\fR (1) for more details.
-.TP
-\fB--solid-chunk-size\fR=\fISIZE\fR
-Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See the
-documentation for this option to \fBwimlib-imagex capture\fR (1) for more
-details.
-.TP
-\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Like \fB--compress\fR, but set the compression type used in solid resources.  See
-the documentation for this option to \fBwimlib-imagex capture\fR (1) for
-more details.
-.TP
-\fB--threads\fR=\fINUM_THREADS\fR
-Number of threads to use for compressing data.  Default: autodetect (number of
-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
-appending 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
-\fBwimlib-imagex optimize\fR.
-.TP
-\fB--ref\fR="\fIGLOB\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
-\fBwimlib-imagex\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 \fBwimlib-imagex
-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, or was "-" (standard output).
-.TP
-\fB--not-pipable\fR
-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, or if \fIDEST_WIMFILE\fR was "-" (standard output).
-.TP
-\fB--wimboot\fR
-Mark the destination image as WIMBoot-compatible.  Also, if exporting to a new
-archive, set the compression type to that recommended for WIMBoot (currently,
-XPRESS with 4096 byte chunks).
-.TP
-\fB--unsafe-compact\fR
-Compact the WIM archive in-place and append any new data, eliminating "holes".
-In general, this option should \fInot\fR be used because a failed or interrupted
-compaction will corrupt the WIM archive.  For more information, see the
-documentation for this option in \fBwimlib-imagex-optimize\fR (1).
-.SH SPLIT WIMS
-You may use \fBwimlib-imagex 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
-mywim.swm
-mywim2.swm
-mywim3.swm
-mywim4.swm
-mywim5.swm
-.RE
-.PP
-To export the first image of this split WIM to a new or existing WIM file
-"other.wim", run:
-.PP
-.RS
-wimlib-imagex export mywim.swm 1 other.wim --ref="mywim*.swm"
-.RE
-.SH NOTES
-\fIData integrity\fR: Except when using \fB--unsafe-compact\fR, it is safe to
-abort a \fBwimlib-imagex export\fR command partway through.  However, after
-doing this, it is recommended to run \fBwimlib-imagex 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 the WIM was being
-rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
-temporary file left over.
-.PP
-\fISingle instancing\fR: The WIM format uses single-instance streams (roughly,
-"files").  When an image is exported, only the streams ("files") not already
-present in the destination WIM will be copied.  However, a new copy of the
-image's metadata resource, which describes the full directory structure, will
-always be created.
-.PP
-\fIESD files\fR: wimlib v1.6.0 and later can export images from version 3584
-WIMs, which usually contain LZMS-compressed solid resources 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 export images from such files until they are first decrypted.  In
-addition, to ensure the destination archive is created in the original WIM
-format rather than in the newer format, specify \fB--compress\fR=\fILZX\fR (or
-\fB--compress\fR=\fImaximum\fR).
-.SH EXAMPLES
-Export the second image of 'boot.wim' to the new WIM file 'new.wim':
-.RS
-.PP
-wimlib-imagex 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
-wimlib-imagex export boot.wim 2 new.wim --compress=LZX
-.RE
-.PP
-Export "ESD to WIM" --- that is, solid WIM to non-solid WIM:
-.RS
-.PP
-wimlib-imagex export install.esd all install.wim --compress=LZX
-.RE
-.PP
-Export "WIM to ESD" --- that is, non-solid WIM to solid WIM:
-.RS
-.PP
-wimlib-imagex export install.wim all install.esd --solid
-.RE
-.PP
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-info (1)
-.BR wimlib-imagex-optimize (1)
diff --git a/doc/man1/wimlib-imagex-info.1 b/doc/man1/wimlib-imagex-info.1
deleted file mode 100644 (file)
index 17cc6f3..0000000
+++ /dev/null
@@ -1,72 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-info \- Display information about a WIM file, or change information about
-an image
-.SH SYNOPSIS
-\fBwimlib-imagex info\fR \fIWIMFILE\fR [\fIIMAGE\fR [\fINEW_NAME\fR
-[\fINEW_DESC\fR]]] [\fIOPTION\fR...]
-.SH DESCRIPTION
-\fBwimlib-imagex info\fR displays information about \fIWIMFILE\fR, and optionally
-changes which image is bootable, or what the name and description of an image
-are.
-This command is also available as simply \fBwiminfo\fR if the appropriate hard
-link or batch file has been installed.
-.PP
-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 by \fIIMAGE\fR (as a
-1-based image index or an image name), the printed information is restricted to
-that concerning the specified image.
-.PP
-Changes to the WIM are made if \fINEW_NAME\fR and/or \fB--boot\fR and/or
-\fB--image-property\fR are specified.  \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.
-.PP
-\fBwimlib-imagex info\fR does not support modifying a split WIM, although you may
-display information about one.
-.SH OPTIONS
-.TP 6
-\fB--boot\fR
-Indicates that the specified image is to be made the bootable image of the WIM
-archive.
-.TP
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present; additionally if an action that requires modifying the WIM archive is
-specified, include an integrity table in the modified WIM.  If this option is
-not specified and \fIWIMFILE\fR is modified, an integrity table will be included
-in the modified WIM if and only if there was one before.
-.TP
-\fB--nocheck\fR
-If an action that requires modifying the WIM archive is specified, do not
-include an integrity table in the modified WIM.  If this option is not specified
-and \fIWIMFILE\fR is modified, an integrity table will be included in the
-modified WIM if and only if there was one before.
-.TP
-\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.
-.TP
-\fB--header\fR
-Shows detailed information from the WIM header.
-.TP
-\fB--blobs\fR
-Prints information about all the blobs ("file data") in the WIM.  A WIM file
-stores only one copy of each unique blob.
-.TP
-\fB--xml\fR
-Prints the raw XML data from the WIM.  Note: the XML data will be encoded using
-UTF-16LE, and it will begin with a byte-order mark.
-.TP
-\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
-Set an arbitrary per-image property in the XML document of the WIM file.
-\fINAME\fR is an element path such as "WINDOWS/VERSION/MAJOR", and \fIVALUE\fR
-is the string to place in the element, such as "10".  See the documentation for
-this option to \fBwimlib-imagex capture\fR (1) for more details.  This option
-may be specified multiple times.
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-dir (1)
diff --git a/doc/man1/wimlib-imagex-join.1 b/doc/man1/wimlib-imagex-join.1
deleted file mode 100644 (file)
index 9b683ef..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-join \- Join split WIMs into a standalone one-part WIM
-.SH SYNOPSIS
-\fBwimlib-imagex join\fR [\fIOPTION\fR...] \fIOUT_WIMFILE\fR
-\fISPLIT_WIM_PART\fR...
-.SH DESCRIPTION
-Joins the \fISPLIT_WIM_PARTs\fR into a standalone one-part WIM \fIOUT_WIMFILE\fR.
-This command is also available as simply \fBwimjoin\fR if the appropriate hard
-link or batch file has been installed.
-.PP
-All parts of the split WIM  must be specified.  You probably want to do so using
-a shell wildcard.
-.PP
-\fBwimlib-imagex join\fR can join both non-pipable and pipable split WIMs.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading each \fISPLIT_WIM_PART\fR, verify its integrity if the integrity table
-is present; additionally, when writing \fIOUT_WIMFILE\fR, write an integrity
-table.  If this option is not specified, an integrity table will be included in
-\fIOUT_WIMFILE\fR if and only if one was present in the first part of the split
-WIM.
-.SH EXAMPLES
-Join a split WIM, with the parts named `windows*.swm' where the * is anything
-(usually the number of the part, except for the first part which may have no
-number), and write the joined WIM to the file `windows.wim'.
-.RS
-.PP
-wimlib-imagex join windows.wim windows*.swm
-.RE
-.SH NOTES
-\fBwimlib-imagex join\fR is roughly equivalent to:
-.RS
-.PP
-\fBwimlib-imagex export\fR \fISWM_PART_1\fR --ref="\fISWM_GLOB\fR" all \fIOUT_WIMFILE\fR
-.RE
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-export (1)
diff --git a/doc/man1/wimlib-imagex-mountrw.1 b/doc/man1/wimlib-imagex-mountrw.1
deleted file mode 100644 (file)
index f8db8d8..0000000
+++ /dev/null
@@ -1 +0,0 @@
-.so man1/wimlib-imagex-mount.1
diff --git a/doc/man1/wimlib-imagex-optimize.1 b/doc/man1/wimlib-imagex-optimize.1
deleted file mode 100644 (file)
index 1f74553..0000000
+++ /dev/null
@@ -1,125 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-optimize \- Optimize a WIM archive
-.SH SYNOPSIS
-\fBwimlib-imagex optimize\fR \fIWIMFILE\fR [\fIOPTION\fR...]
-.SH DESCRIPTION
-\fBwimlib-imagex optimize\fR will rebuild the stand-alone WIM \fIWIMFILE\fR.  The new
-WIM is written to a temporary file, and it is renamed to the original file when
-it's ready.  This action will remove any holes that have been left as a result
-of appending images, so the new WIM may be slightly smaller than the old WIM.
-.PP
-By default, compressed data will be re-used, and not recompressed.  Use the
-\fB--recompress\fR or \fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR] option to
-request recompression.
-.PP
-This command is also available as simply \fBwimoptimize\fR if the appropriate
-hard link or batch file has been installed.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
-present.  In addition, include an integrity table in the optimized WIM.  If this
-option is not specified, by default the integrity table (if present) is not
-checked, and an integrity table is included in the rebuilt WIM if and only if
-one was present in the original WIM.
-.TP
-\fB--nocheck\fR
-Neither verify the integrity of \fIWIMFILE\fR using the integrity table, nor
-include an integrity table in the rebuilt WIM file.
-.TP
-\fB--recompress\fR
-Recompress all compressed streams in \fIWIMFILE\fR when rebuilding it.  This
-will greatly increase the time needed to rebuild the WIM file, but it may result
-in a better compression ratio if wimlib can do a better job than the program
-that wrote the original file.
-.TP
-\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Recompress the WIM file using the specified compression type, and optionally the
-specified compression level for that compression type.  This implies
-\fB--recompress\fR.
-.IP ""
-See the documentation for this option to \fBwimlib-imagex capture\fR (1) for
-more details.
-.TP
-\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
-this option to \fBwimlib-imagex capture\fR (1) for more details.
-.TP
-\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 \fBwimlib-imagex
-capture\fR (1) for more details.
-.TP
-\fB--solid-chunk-size\fR=\fISIZE\fR
-Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See the
-documentation for this option to \fBwimlib-imagex capture\fR (1) for more
-details.
-.TP
-\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Like \fB--compress\fR, but set the compression type used in solid resources.  See
-the documentation for this option to \fBwimlib-imagex capture\fR (1) for
-more details.
-.TP
-\fB--threads\fR=\fINUM_THREADS\fR
-Number of threads to use for compressing data.  Default: autodetect (number of
-processors).  This parameter only has an effect when data recompression is
-requested.
-.TP
-\fB--pipable\fR
-Rebuild the WIM so that it can be applied fully sequentially, including from a
-pipe.  See \fBwimlib-imagex capture\fR(1) for more details about creating
-pipable WIMs.  By default, when neither \fB--pipable\fR or \fB--not-pipable\fR
-is specified, the rebuilt WIM will be pipable if and only if it was already
-pipable.
-.TP
-\fB--not-pipable\fR
-Rebuild the WIM in the non-pipable format.  (This is the default if
-\fIWIMFILE\fR is not pipable.)
-.TP
-\fB--unsafe-compact\fR
-Compact the WIM file in-place, without using a temporary file.  Existing
-resources are shifted down to fill holes and new resources are appended as
-needed.  The WIM file is truncated to its final size, which may shrink the
-on-disk file.  THIS OPERATION CANNOT BE SAFELY INTERRUPTED!  If the operation is
-interrupted, then the WIM file will be corrupted, and it may be impossible (or
-at least very difficult) to recover any data from it.  Users of this option are
-expected to know what they are doing and assume responsibility for any data
-corruption that may result.
-.SH NOTES
-\fBwimlib-imagex optimize\fR does not support split WIMs.
-.PP
-\fBwimlib-imagex optimize\fR is roughly equivalent to:
-.RS
-.PP
-\fBwimlib-imagex export\fR \fIWIMFILE\fR all tmp.wim && mv tmp.wim \fIWIMFILE\fR
-.RE
-.PP
-.SH EXAMPLES
-Rebuild the WIM file 'install.wim':
-.RS
-.PP
-wimoptimize install.wim
-.RE
-.PP
-Rebuild and recompress the WIM file 'install.wim':
-.RS
-.PP
-wimoptimize install.wim --recompress
-.RE
-.PP
-Rebuild and recompress the WIM file 'install.wim', using LZX ("maximum")
-compression at a higher-than-default compression level.  The compression chunk
-size remains unchanged.  This command will be slow, but it might be useful for
-optimizing files for distribution.  See
-\fIhttps://wimlib.net/compression.html\fR for some benchmark results.
-.RS
-.PP
-wimoptimize install.wim --compress=LZX:100
-.RE
-.PP
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-export (1)
-.BR wimlib-imagex-verify (1)
diff --git a/doc/man1/wimlib-imagex-split.1 b/doc/man1/wimlib-imagex-split.1
deleted file mode 100644 (file)
index aacf7b3..0000000
+++ /dev/null
@@ -1,37 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-split \- Split a WIM into multiple parts
-.SH SYNOPSIS
-\fBwimlib-imagex split\fR \fIWIMFILE\fR \fISPLIT_WIM_PART_1\fR \fIPART_SIZE\fR [\fIOPTION...\fR]
-.SH DESCRIPTION
-Splits \fIWIMFILE\fR into parts with size at most \fIPART_SIZE\fR mebibytes,
-with the first part having the name \fISPLIT_WIM_PART_1\fR and the other parts
-having names numbered in order of the parts.
-This command is also available as simply \fBwimsplit\fR if the appropriate
-hard link or batch file has been installed.
-.PP
-\fBwimlib-imagex split\fR can split both non-pipable and pipable WIMs.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present; additionally, when writing each split WIM part, write an integrity
-table.  If this option is not specified, integrity tables will be included in
-the split WIMs if and only if one was present in \fIWIMFILE\fR.
-.SH EXAMPLES
-Splits the WIM 'windows.wim' into 'windows.swm', 'windows2.swm', 'windows3.swm',
-etc. where each part is at most 100 MiB:
-.RS
-.PP
-wimlib-imagex split windows.wim windows.swm 100
-.RE
-.SH LIMITATIONS
-It is possible for the size of the parts to exceed the \fIPART_SIZE\fR given.
-This is impossible to avoid
-because the WIM file format provides no way to divide a single file resource in
-the WIM among multiple split WIM parts.  So if you, for example, have a file
-inside the WIM that is 100 MiB, then an uncompressed split WIM will have at
-least one part that is 100 MiB in size to contain that file.  However, if the
-WIM resources are compressed then less space would be needed.
-.SH SEE ALSO
-.BR wimlib-imagex (1)
diff --git a/doc/man1/wimlib-imagex-unmount.1 b/doc/man1/wimlib-imagex-unmount.1
deleted file mode 100644 (file)
index f8db8d8..0000000
+++ /dev/null
@@ -1 +0,0 @@
-.so man1/wimlib-imagex-mount.1
diff --git a/doc/man1/wimlib-imagex-verify.1 b/doc/man1/wimlib-imagex-verify.1
deleted file mode 100644 (file)
index 6290a5e..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
-.SH NAME
-wimlib-imagex-verify \- Verify a WIM file
-.SH SYNOPSIS
-\fBwimlib-imagex verify\fR \fIWIMFILE\fR [\fIOPTION\fR...]
-.SH DESCRIPTION
-\fBwimlib-imagex verify\fR checks the validity of the specified WIM archive.
-This command is also available as simply \fBwimverify\fR if the appropriate hard
-link or batch file has been installed.
-.PP
-Specifically, this command performs the following verifications on the WIM
-archive:
-.IP \[bu] 4
-Verify that the WIM file can be successfully opened, which involves parsing the
-header, blob table, and XML data.
-.IP \[bu]
-If the WIM archive contains an integrity table, verify the integrity of the
-entire WIM archive.  Otherwise, print a warning.
-.IP \[bu]
-Verify that the metadata for each image in the WIM archive can be successfully
-parsed.
-.IP \[bu]
-Verify that all files needed by each image are actually contained in the WIM
-archive or in one of the WIM archives referenced by the \fB--ref\fR option.
-.IP \[bu]
-Verify that all files contained in the WIM archive can be successfully
-decompressed, with matching cryptographic checksums.
-.SH OPTIONS
-.TP 6
-\fB--ref\fR="\fIGLOB\fR"
-File glob of additional WIMs or split WIM parts to reference resources from.
-This option can be specified multiple times.  Note: \fIGLOB\fR is listed in
-quotes because it is interpreted by \fBwimlib-imagex\fR and may need to be
-quoted to protect against shell expansion.
-.TP
-\fB--nocheck\fR
-Do not check the WIM file's contents against its integrity table (if it has one).
-.SH NOTES
-This is a read-only command.  It will never modify the WIM file.
-.PP
-In the future, this command might do more thorough verifications than it does
-now.
-.SH EXAMPLES
-Verify the WIM file 'boot.wim':
-.RS
-.PP
-wimverify boot.wim
-.RE
-.PP
-Verify the split WIM file consisting of 'boot.swm', 'boot2.swm', 'boot3.swm', ...:
-.RS
-.PP
-wimverify boot.swm --ref="boot*.swm"
-.RE
-.PP
-.SH SEE ALSO
-.BR wimlib-imagex (1)
-.BR wimlib-imagex-optimize (1)
index 9508da2..b16c364 100644 (file)
@@ -1,42 +1,42 @@
 .TH WIMLIB-IMAGEX 1 "August 2016" "wimlib 1.10.0" "User Commands"
 .SH NAME
-wimlib-imagex \- Extract, create, modify, or mount a WIM (Windows Imaging Format) archive
+wimlib-imagex \- Extract, create, modify, or mount a WIM archive
 .SH SYNOPSIS
-\fBwimlib-imagex append\fR \fIarguments...\fR
+\fBwimlib-imagex append\fR \fIarguments...\fR (or \fBwimappend\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex apply\fR \fIarguments...\fR
+\fBwimlib-imagex apply\fR \fIarguments...\fR (or \fBwimapply\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex capture\fR \fIarguments...\fR
+\fBwimlib-imagex capture\fR \fIarguments...\fR (or \fBwimcapture\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex delete\fR \fIarguments...\fR
+\fBwimlib-imagex delete\fR \fIarguments...\fR (or \fBwimdelete\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex dir\fR \fIarguments...\fR
+\fBwimlib-imagex dir\fR \fIarguments...\fR (or \fBwimdir\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex export\fR \fIarguments...\fR
+\fBwimlib-imagex export\fR \fIarguments...\fR (or \fBwimexport\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex extract\fR \fIarguments...\fR
+\fBwimlib-imagex extract\fR \fIarguments...\fR (or \fBwimextract\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex info\fR \fIarguments...\fR
+\fBwimlib-imagex info\fR \fIarguments...\fR (or \fBwiminfo\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex join\fR \fIarguments...\fR
+\fBwimlib-imagex join\fR \fIarguments...\fR (or \fBwimjoin\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex mount\fR \fIarguments...\fR
+\fBwimlib-imagex mount\fR \fIarguments...\fR (or \fBwimmount\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex mountrw\fR \fIarguments...\fR
+\fBwimlib-imagex mountrw\fR \fIarguments...\fR (or \fBwimmountrw\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex optimize\fR \fIarguments...\fR
+\fBwimlib-imagex optimize\fR \fIarguments...\fR (or \fBwimoptimize\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex split\fR \fIarguments...\fR
+\fBwimlib-imagex split\fR \fIarguments...\fR (or \fBwimsplit\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex unmount\fR \fIarguments...\fR
+\fBwimlib-imagex unmount\fR \fIarguments...\fR (or \fBwimunmount\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex update\fR \fIarguments...\fR
+\fBwimlib-imagex update\fR \fIarguments...\fR (or \fBwimupdate\fR \fIarguments...\fR)
 .br
-\fBwimlib-imagex verify\fR \fIarguments...\fR
+\fBwimlib-imagex verify\fR \fIarguments...\fR (or \fBwimverify\fR \fIarguments...\fR)
 .SH DESCRIPTION
-\fBwimlib-imagex\fR deals with archives in the Windows Imaging Format (WIM).
-Its interface is similar to Microsoft's ImageX, but \fBwimlib-imagex\fR is
-cross-platform and has useful improvements and extensions.
+\fBwimlib-imagex\fR deals with archive files in the Windows Imaging (WIM)
+format.  Its interface is similar to Microsoft's ImageX, but \fBwimlib-imagex\fR
+is cross-platform and has useful improvements and extensions.
 .PP
 To do its work, \fBwimlib-imagex\fR uses \fBwimlib\fR, an open source C
 library that provides interfaces for manipulating WIM archives.  wimlib is
@@ -45,7 +45,7 @@ wimgapi.dll).  You can use wimlib in your own programs, although for
 command-line use \fBwimlib-imagex\fR already provides access to most of
 wimlib's functionality.
 .SH BACKGROUND INFORMATION
-The Windows Imaging Format (WIM) was designed by Microsoft primarily for
+The Windows Imaging (WIM) format was designed by Microsoft primarily for
 archiving Windows filesystems, such as NTFS.  However, it can be used on other
 platforms as well, with some limitations.  A WIM archive contains one or more
 images, each of which is a logically independent directory tree.  Images are
@@ -53,10 +53,10 @@ indexed starting from 1, and each may also have a name.  File data is stored as
 content-addressable "blobs" that are deduplicated across the entire archive.
 Data may be compressed using one of several compression algorithms.
 .PP
-An update of the WIM format released with Windows 8 features solid compression
-using the LZMS compression algorithm.  Such files are also called "ESD files"
-and may carry the extension \.esd instead of .wim.  \fBwimlib-imagex\fR
-v1.6.0 and later supports these new files, unless they are encrypted.
+An update of the WIM format which Microsoft released with Windows 8 uses
+solid-mode LZMS compression to achieve a better compression ratio.  Such files
+are also called "ESD files" and may have the \.esd extension instead of .wim.
+wimlib fully supports these files except when they are encrypted.
 .SH COMMANDS
 \fBwimlib-imagex\fR accepts one of a number of commands (listed above in
 \fBSYNOPSYS\fR), and additional arguments depending on the specific command.
@@ -64,114 +64,80 @@ Although \fBwimlib-imagex\fR will print usage information with \fB--help\fR
 or if you invoke it incorrectly, the full documentation for each
 \fBwimlib-imagex\fR command can be found in the appropriate manual page.
 .PP
-Note: to save typing, if appropriate hard links or batch files have been
-installed, a command \fBwimlib-imagex \fICOMMAND\fR can also be accessed as
-simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fBwimlib-imagex
-apply\fR.
+Note: if appropriate hard links or batch files have been installed, a command
+\fBwimlib-imagex \fICOMMAND\fR can also be accessed as simply
+\fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fBwimlib-imagex apply\fR.
+For brevity the documentation uses the shorter names.
 .SH GENERAL FEATURES
 The following are some of the general features, or use cases, currently
 supported by \fBwimlib-imagex\fR, and pointers to the relevant commands:
 .IP \[bu] 4
-Display information about a WIM file
- (\fBwimlib-imagex info\fR)
+Display information about a WIM file (\fBwiminfo\fR)
 .IP \[bu]
-List the files in a WIM image
- (\fBwimlib-imagex dir\fR)
+List the files in a WIM image (\fBwimdir\fR)
 .IP \[bu]
-Extract, or "apply", a full WIM image
- (\fBwimlib-imagex apply\fR)
+Extract, or "apply", a full WIM image (\fBwimapply\fR)
 .IP \[bu]
-Extract files or directories from a WIM image
- (\fBwimlib-imagex extract\fR)
+Extract files or directories from a WIM image (\fBwimextract\fR)
 .IP \[bu] 4
-Capture a WIM image and save it to a new WIM file
- (\fBwimlib-imagex capture\fR)
+Capture a WIM image and save it to a new WIM file (\fBwimcapture\fR)
 .IP \[bu]
-Capture a WIM image and append it to an existing WIM file
- (\fBwimlib-imagex append\fR)
+Capture a WIM image and append it to an existing WIM file (\fBwimappend\fR)
 .IP \[bu]
-Modify a WIM image by adding, deleting, or renaming files
- (\fBwimlib-imagex update\fR)
+Modify a WIM image by adding, deleting, or renaming files (\fBwimupdate\fR)
 .IP \[bu]
-(Linux only) Mount a WIM image read-only
- (\fBwimlib-imagex mount\fR)
+(Linux only) Mount a WIM image read-only (\fBwimmount\fR)
 .IP \[bu]
-(Linux only) Mount a WIM image read-write
- (\fBwimlib-imagex mountrw\fR)
+(Linux only) Mount a WIM image read-write (\fBwimmountrw\fR)
 .IP \[bu]
-Delete an image from a WIM file
- (\fBwimlib-imagex delete\fR)
+Delete an image from a WIM file (\fBwimdelete\fR)
 .IP \[bu]
-Export image(s) from a WIM file
- (\fBwimlib-imagex export\fR)
+Export image(s) from a WIM file (\fBwimexport\fR)
 .IP \[bu]
-Change the name or description of a WIM image
- (\fBwimlib-imagex info\fR)
+Change the name or description of a WIM image (\fBwiminfo\fR)
 .IP \[bu]
-Change the bootable image index of a WIM file
- (\fBwimlib-imagex info\fR)
+Change the bootable image index of a WIM file (\fBwiminfo\fR)
 .IP \[bu]
-Rebuild, and optionally recompress, a WIM file
- (\fBwimlib-imagex optimize\fR)
+Rebuild, and optionally recompress, a WIM file (\fBwimoptimize\fR)
 .IP \[bu]
-Split a WIM file into multiple parts
- (\fBwimlib-imagex split\fR)
+Split a WIM file into multiple parts (\fBwimsplit\fR)
 .IP \[bu]
-Join a split WIM
- (\fBwimlib-imagex join\fR)
+Join a split WIM (\fBwimjoin\fR)
 .IP \[bu]
-Verify a WIM file
- (\fBwimlib-imagex verify\fR)
+Verify the validity and integrity of a WIM file (\fBwimverify\fR)
 .SH DETAILED FEATURES
 This section presents some of the interesting features of
 \fBwimlib-imagex\fR in more detail.
 .IP \[bu] 4
 Multi-platform support.  \fBwimlib-imagex\fR is supported on both UNIX-like
-systems (mainly Linux, but also FreeBSD, Mac OS X, etc.) and Windows, and most
-code is shared among all platforms.  However, platform-specific features are
+systems (mainly Linux, but also FreeBSD, Mac OS X, etc.) and Windows.  Most code
+is shared among all platforms, but platform-specific features are still
 supported when possible.
 .IP \[bu]
-On UNIX-like systems, integration with libntfs-3g allows capturing a WIM image
-directly from a block device containing an NTFS volume, or applying a WIM image
-directly to a block device containing an NTFS volume.  This allows saving and
-restoring NTFS-specific data, such as security descriptors and named data
-streams, which would otherwise only be supported on Windows.
-.IP \[bu]
-Long path support on Windows.  \fBwimlib-imagex\fR can capture and apply files
-with paths exceeding the MAX_PATH (260 character) limitation of the Win32
-subsystem.
-.IP \[bu]
-Non-Administrator support on Windows.  You can run \fBwimlib-imagex\fR without
-Administrator rights, subject to some limitations.
-.IP \[bu]
-Support for WIM integrity tables.  An integrity table is a list of SHA-1 message
-digests appended to the end of a WIM file which gives checksums over the WIM
-file itself.  The \fB--check\fR option to several \fBwimlib-imagex\fR commands
-can be used to verify or add integrity tables.
+XPRESS, LZX, and LZMS compression and decompression.  wimlib contains advanced
+implementations of all these compression algorithms.  These have been improved
+over time and now usually outperform and outcompress their Microsoft
+equivalents, while remaining fully compatible.
 .IP \[bu]
-On UNIX-like systems, support for saving and restoring UNIX uids (user IDs),
-gids (group IDs), and modes to/from WIM images.  This is a wimlib extension, but
-the Microsoft implementation ignores this extra metadata.
+Solid-mode compression, or "ESD file", support. "ESD files" are an updated WIM
+format that uses solid LZMS compression to achieve a better compression ratio.
 .IP \[bu]
-Multithreaded compression.  By default, data compression is multithreaded and
-will use all available processors.
+Multithreaded compression.  By default, wimlib's data compression is
+multithreaded and will use all available processors.
 .IP \[bu]
-XPRESS, LZX, and LZMS decompression and compression.  wimlib contains
-independent implementations of all these compression algorithms.  Sometimes they
-can do better than the equivalent Microsoft implementations.
-.IP \[bu]
-"ESD file" support.  As mentioned in \fBBACKGROUND INFORMATION\fR, "ESD files"
-use a new WIM format that features solid resources and LZMS compression.  This
-support was first present in wimlib v1.6.0, but v1.7.0 and later have improved
-compatibility.
+On UNIX-like systems, integration with libntfs-3g allows capturing a WIM image
+directly from an NTFS volume, or applying a WIM image directly to an NTFS
+volume.  This allows saving and restoring NTFS-specific data and metadata, such
+as security descriptors and named data streams, which would otherwise only be
+supported on Windows.
 .IP \[bu]
-On Linux, support for mounting WIM images with FUSE (Filesystem in UserSpacE).
+On UNIX-like systems, optional support for saving and restoring standard UNIX
+file permissions (owner/group/mode), UNIX special files, and extended
+attributes.  (This is a wimlib extension; Microsoft's WIM software ignores this
+extra information.)
 .IP \[bu]
-"Pipable" WIMs.  This is a wimlib extension and is not compatible with the
-Microsoft implementation.  A pipable WIM, created with \fBwimcapture\fR with the
-\fB--pipable\fR option, can be written to standard output or read from standard
-input.  This can be used to pipe images to or from a server over the network to
-implement fast filesystem imaging and restore.
+On Linux, support for mounting WIM images with FUSE (Filesystem in UserSpacE),
+both readonly and read-write.
 .IP \[bu]
 Split WIMs.  A split WIM is a WIM archive split into multiple parts.
 \fBwimsplit\fR can create a split WIM from a standalone WIM, and \fBwimjoin\fR
@@ -181,35 +147,53 @@ Delta WIMs.  A delta WIM contains image metadata but excludes file data already
 present in another WIM file.  A delta WIM can be created using \fBwimcapture\fR
 with the \fB--delta-from\fR option.
 .IP \[bu]
-Fast incremental backups.  Using the \fB--update-of\fR option of
-\fBwimcapture\fR or \fBwimappend\fR, you can optimize an image capture so that
-files that are unmodified based on timestamps are not be read from disk.  But
-even without this option, since the WIM format features single-instance files, a
-file identical to any already present in the WIM archive (in any image) will not
-be written, but rather a reference to the stored file will be used.
+"Pipable" WIMs.  As a wimlib extension (not compatible with the Microsoft
+implementation), \fBwimcapture\fR supports capturing a WIM file to standard
+output in a special "pipable" format which can later be applied by sending it to
+\fBwimapply\fR on standard input.  Among other things, this can be used to pipe
+images to or from a server over the network to implement fast filesystem imaging
+and restore.
+.IP \[bu]
+Support for WIM integrity tables.  Although file data in WIM archives is always
+checksummed, there can also be an extra set of checksums (an "integrity table")
+associated with the WIM file itself to provide extra integrity assurance.  The
+\fB--check\fR option to several \fBwimlib-imagex\fR commands can be used to
+verify or add these extra checksums.
+.IP \[bu]
+Fast incremental backups.  Because WIM archives use content-addressible file
+data, the contents of files are automatically deduplicated.  In addition, using
+the \fB--update-of\fR option of \fBwimcapture\fR or \fBwimappend\fR, you can
+optimize an image capture so that files that are unmodified based on timestamps
+are not even read from disk.
 .IP \[bu]
 Windows-specific image metadata support.  When capturing an image of a Windows
 operating system, wimlib will automatically populate XML metadata fields such as
 the Windows OS version details by scanning well-known system files.
 .IP \[bu]
 WIMBoot support.  On Windows 8.1 and later, files can be "externally backed" by
-a WIM archive with the help of Microsoft's Windows Overlay Filesystem filter
-driver (WOF).  With the \fB--wimboot\fR option, \fBwimapply\fR will extract
+a WIM archive with the help of Microsoft's Windows Overlay Filesystem (WOF)
+filter driver.  With the \fB--wimboot\fR option, \fBwimapply\fR will extract
 "pointer files" to the WIM archive rather than the files themselves.
 .IP \[bu]
 VSS snapshot support.  On Windows, \fBwimcapture\fR or \fBwimappend\fR with the
 \fB--snapshot\fR option will automatically create a temporary VSS snapshot and
 capture the image from it.  This can be used to image a "live" Windows system.
+.IP \[bu]
+Long path support on Windows.  \fBwimlib-imagex\fR can capture and apply files
+with paths exceeding the MAX_PATH (260 character) limitation of the Win32
+subsystem.
+.IP \[bu]
+Non-Administrator support on Windows.  You can run \fBwimlib-imagex\fR without
+Administrator rights, subject to some limitations.
 .SH CASE SENSITIVITY
-By default, the case sensitivity of \fBwimlib-imagex\fR differs somewhat
-between UNIX-like systems and Windows.  WIM images may (but usually do not) have
-multiple files with the same case-insensitive name.  Internally, wimlib
-stores filenames as case-sensitive, but on Windows paths
-actually provided by the user for use in a WIM image (e.g. for extracting,
-adding, renaming, or deleting files) will by default be treated as
-case-insensitive in order to get the "expected" behavior. This differs from the
-default behavior on UNIX-like systems, where such paths will be treated as
-case-sensitive.
+By default, the case sensitivity of \fBwimlib-imagex\fR differs somewhat between
+UNIX-like systems and Windows.  WIM images may (but usually do not) have
+multiple files with the same case-insensitive name.  Internally, wimlib stores
+filenames as case-sensitive, but on Windows paths actually provided by the user
+for use in a WIM image (e.g. for extracting, adding, renaming, or deleting
+files) will by default be treated as case-insensitive in order to get the
+"expected" behavior. This differs from the default behavior on UNIX-like
+systems, where such paths will be treated as case-sensitive.
 .PP
 Note that with case insensitivity, a path component may in general be ambiguous
 due to multiple files or directories having the same case-insensitive name.  In
@@ -229,21 +213,22 @@ wimlib-imagex may be redistributed and/or modified under the terms of the GNU
 General Public License; either version 3 of the License, or (at your option) any
 later version.  There is NO WARRANTY, to the extent permitted by law.
 .SH REPORTING BUGS
-Report bugs to ebiggers3@gmail.com.  Feedback and suggestions are also welcome.
+Report bugs to ebiggers3@gmail.com or to \fIhttps://wimlib.net/forums/\fR.
+Feedback and suggestions are also welcome.
 .SH SEE ALSO
-.BR wimlib-imagex-append (1),
-.BR wimlib-imagex-apply (1),
-.BR wimlib-imagex-capture (1),
-.BR wimlib-imagex-delete (1),
-.BR wimlib-imagex-dir (1),
-.BR wimlib-imagex-export (1),
-.BR wimlib-imagex-extract (1),
-.BR wimlib-imagex-info (1),
-.BR wimlib-imagex-join (1),
-.BR wimlib-imagex-mount (1),
-.BR wimlib-imagex-mountrw (1),
-.BR wimlib-imagex-optimize (1),
-.BR wimlib-imagex-split (1),
-.BR wimlib-imagex-unmount (1),
-.BR wimlib-imagex-update (1),
-.BR wimlib-imagex-verify (1),
+.BR wimappend (1),
+.BR wimapply (1),
+.BR wimcapture (1),
+.BR wimdelete (1),
+.BR wimdir (1),
+.BR wimexport (1),
+.BR wimextract (1),
+.BR wiminfo (1),
+.BR wimjoin (1),
+.BR wimmount (1),
+.BR wimmountrw (1),
+.BR wimoptimize (1),
+.BR wimsplit (1),
+.BR wimunmount (1),
+.BR wimupdate (1),
+.BR wimverify (1),
similarity index 55%
rename from doc/man1/wimlib-imagex-mount.1
rename to doc/man1/wimmount.1
index aa01ecc..b13d4c4 100644 (file)
@@ -1,29 +1,27 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.TH WIMMOUNT "1" "August 2016" "wimlib 1.10.0" "User Commands"
 .SH NAME
-wimlib-imagex-mount, wimlib-imagex-mountrw, wimlib-imagex-unmount \- Mount and unmount an image from a WIM archive
+wimmount, wimmountrw, wimunmount \- Mount or unmount a WIM image
 .SH SYNOPSIS
-\fBwimlib-imagex mount\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
+\fBwimmount\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
 .br
-\fBwimlib-imagex mountrw\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
+\fBwimmountrw\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
 .br
-\fBwimlib-imagex unmount\fR \fIDIRECTORY\fR [\fIOPTION\fR...]
+\fBwimunmount\fR \fIDIRECTORY\fR [\fIOPTION\fR...]
 .SH DESCRIPTION
-On Linux-based systems, the \fBwimlib-imagex mount\fR and \fBwimlib-imagex
-mountrw\fR commands will mount the image in the Windows Imaging (WIM) file
-\fIWIMFILE\fR specified by \fIIMAGE\fR on the directory \fIDIRECTORY\fR using
-FUSE (Filesystem in Userspace).  \fBwimlib-imagex mount\fR will mount the image
-read-only, while \fBwimlib-imagex mountrw\fR will mount the image read-write.
-These commands are also available as simply \fBwimmount\fR, \fBwimmountrw\fR,
-and \fBwimunmount\fR if the appropriate hard links are installed.
+On Linux-based systems, the \fBwimmount\fR and \fBwimmountrw\fR commands will
+mount the specified \fIIMAGE\fR in the Windows Imaging (WIM) archive
+\fIWIMFILE\fR on the directory \fIDIRECTORY\fR using FUSE (Filesystem in
+Userspace).  \fBwimmount\fR will mount the image read-only, while
+\fBwimmountrw\fR will mount the image read-write.
 .PP
-\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 \fBwimlib-imagex info\fR (1)
-command to see the available images in the WIM.  \fIIMAGE\fR may be omitted if
-\fIWIMFILE\fR contains only one image.
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to mount.  It may be the
+1-based index of an image or the name of an image.  It may be omitted if
+\fIWIMFILE\fR contains only one image.  You can use \fBwiminfo\fR(1) to list the
+images contained in \fIWIMFILE\fR.
 .PP
-The WIM image can be unmounted using the \fBwimlib-imagex unmount\fR
-command.  Changes made to a WIM mounted read-write will be discarded unless the
-\fB--commit\fR flag is provided to \fBwimlib-imagex unmount\fR.
+The WIM image can be unmounted using the \fBwimunmount\fR command.  Changes made
+to an image mounted read-write will be discarded unless the \fB--commit\fR flag
+is provided to \fBwimunmount\fR.
 .SH DATA AND METADATA SUPPORT
 WIM images can contain a variety of types of files and file metadata, some of
 which is Windows-specific.  Currently, the mount feature can translate some, but
@@ -64,8 +62,8 @@ WIM images.  (This may be implemented in the future, though it would conflict
 with the use of extended attributes to expose Windows concepts like named data
 streams.)
 .SH SPLIT WIMS
-You may use \fBwimlib-imagex 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 \fBwimmount\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 must specify the first part of the split WIM, while
 the additional parts of the split WIM must be specified in one or more
@@ -85,11 +83,11 @@ mywim5.swm
 To mount the first image of this split WIM to the directory "dir", run:
 .PP
 .RS
-wimlib-imagex mount mywim.swm 1 dir --ref="mywim*.swm"
+wimmount mywim.swm 1 dir --ref="mywim*.swm"
 .RE
 .PP
 .SH NOTES
-\fIAvailablity\fR: Mounting WIM images is only supported on Linux-based systems.
+\fIAvailability\fR: Mounting WIM images is only supported on Linux-based systems.
 These commands will not work on other platforms.  Furthermore, the library
 cannot have been configured \fB--without-fuse\fR.
 .PP
@@ -101,9 +99,8 @@ the same time.
 in-place by appending to the WIM.  This is nice for big WIM files, since the
 entire file doesn't have to be 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 \fBwimlib-imagex
-unmount\fR to force the WIM to be rebuilt, or else run \fBwimlib-imagex
-optimize\fR on the WIM afterwards.
+files, it is suggested to provide the \fB--rebuild\fR option to \fBwimunmount\fR
+to force the WIM to be rebuilt, or else run \fBwimoptimize\fR afterwards.
 .PP
 \fIESD files (solid WIMs)\fR: You can mount version 3584 WIMs, which usually
 contain LZMS-compressed solid resources and may carry the \fI.esd\fR file
@@ -115,30 +112,26 @@ decrypted.
 .SH MOUNT OPTIONS
 .TP 6
 \fB--check\fR
-When reading the WIM, verify its integrity if it contains an integrity table.
+Before mounting the WIM image, verify the integrity of the WIM if it contains
+extra integrity information.
 .TP
 \fB--streams-interface\fR=\fIINTERFACE\fR
-This option is inspired by the ntfs-3g filesystem driver (see \fBntfs-3g\fR
-(8)).  It controls how alternate data streams, or named data streams, in WIM
-files are made available.
+This option is inspired by the \fBntfs-3g\fR(8) filesystem driver.  It controls
+how named data streams (also called "alternate data streams") in WIM files are
+made available.
 .IP ""
 If "none", it will be impossible to read or write the named data streams.
 .IP ""
 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).  Note that this is not an ideal interface, since named data
+where the * is the name of the named data stream.  See \fBsetfattr\fR(1) and
+\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,
 "myfile:mystream".
-.IP ""
-Please note that named data streams are a somewhat obscure NTFS feature that
-aren't actually used much, even though they complicate the WIM file format
-considerably.  Normally, all you care about is the default or "unnamed" data
-stream.
 .TP
 \fB--debug\fR
 Turn on debugging information printed by the FUSE library, and do not fork into
@@ -147,34 +140,31 @@ the background.
 \fB--ref\fR="\fIGLOB\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
-\fBwimlib-imagex\fR and may need to be quoted to protect against shell
-expansion.
+\fIGLOB\fR is listed in quotes because it is interpreted by \fBwimlib-imagex\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.
-Only valid for \fBwimlib-imagex mountrw\fR.
+Only valid for \fBwimmountrw\fR.
 .TP
 \fB--unix-data\fR
-Honor UNIX-specific metadata that was captured by \fBwimlib-imagex
-capture\fR with the \fB--unix-data option\fR.  By default, \fBwimlib-imagex
-mount\fR and \fBwimlib-imagex mountrw\fR will ignore both Windows-style
-security descriptors (which may have been set either from Windows or by
-\fBwimlib-imagex capture\fR from an NTFS-volume) and UNIX-specific metadata.
+Honor UNIX-specific metadata that was captured by \fBwimcapture\fR with the
+\fB--unix-data option\fR.  By default, \fBwimmount\fR (and \fBwimmountrw\fR)
+will ignore both Windows-style security descriptors and UNIX-specific metadata.
 In this default mode, all files will simply be owned by the user running
-\fBwimlib-imagex\fR and will have mode 0777.  (Note: they will still not be
-accessible to other users unless you also specify \fB--allow-other\fR.)  If you
-instead provide the \fB--unix-data\fR option, these default permissions will be
-overridden on a per-file basis with the UNIX-specific data when available, and
-in the case of \fBwimlib-imagex mountrw\fR it will be possible to change the
-UNIX permissions using the standard UNIX tools and functions.  In addition, with
-wimlib v1.7.0 and later, you can create device nodes, named pipes, and sockets
-on the mounted filesystem and have them stored in the WIM image.
+\fBwimmount\fR and will have mode 0777.  (They will still not be accessible to
+other users unless you also specify \fB--allow-other\fR.)  If you instead
+provide the \fB--unix-data\fR option, these default permissions will be
+overridden on a per-file basis with the UNIX-specific metadata from the WIM
+image when available, and in the case of \fBwimmountrw\fR it will also be
+possible to change the UNIX permissions on files in the mounted image using the
+standard UNIX tools and functions, and (if appropriately privileged) create UNIX
+special files such as device nodes.
 .TP
 \fB--allow-other\fR
 Pass the \fBallow_other\fR option to the FUSE mount.  See \fBmount.fuse\fR (8).
-Note: to do this is a non-root user, \fBuser_allow_other\fR needs to be
-specified in /etc/fuse.conf (with the FUSE implementation on Linux, at least).
+Note: to do this as a non-root user, \fBuser_allow_other\fR needs to be
+specified in /etc/fuse.conf.
 .SH UNMOUNT OPTIONS
 .TP
 \fB--commit\fR
@@ -187,9 +177,8 @@ there are open file descriptors to the WIM image.  Any such file descriptors
 will be immediately closed, and the WIM image will be committed and unmounted.
 .TP
 \fB--check\fR
-When writing \fIWIMFILE\fR, include an integrity table.  Has no effect if the
-mount is read-only or if \fB--commit\fR was not specified.  The default behavior
-is to include an integrity table if and only if there was one present before.
+If committing changes to the WIM, include extra integrity information, even if
+it was not present before.
 .TP
 \fB--rebuild\fR
 Rebuild the entire WIM rather than appending any new data to the end of it.
@@ -202,18 +191,18 @@ In combination with \fB--commit\fR for a read-write mounted image, causes the
 modified image to be committed as a new, unnamed image appended to the WIM
 archive.  The original image will be unmodified.
 .SH IMPLEMENTATION DETAILS
-Since a WIM is an archive and not a filesystem, \fBwimlib-imagex mountrw\fR
-creates a temporary staging directory to contain files that are created or
-modified.  This directory is located in the same directory as \fIWIMFILE\fR by
-default, but the location can be set using the \fB--staging-dir\fR option.  When
-the filesystem is unmounted with \fB--commit\fR, the WIM is modified in-place
-(or rebuilt completely with \fB--rebuild\fR), merging in the staging files as
+Since a WIM is an archive and not a filesystem per se, \fBwimmountrw\fR creates
+a temporary staging directory to contain files that are created or modified.
+This directory is located in the same directory as \fIWIMFILE\fR by default, but
+the location can be set using the \fB--staging-dir\fR option.  When the
+filesystem is unmounted with \fB--commit\fR, the WIM is modified in-place (or
+rebuilt completely with \fB--rebuild\fR), merging in the staging files as
 needed.  Then, the temporary staging directory is deleted.
 .PP
-\fBwimlib-imagex unmount\fR runs in a separate process from the process that
-previously ran \fBwimlib-imagex mount\fR.  When unmounting a read-write
-mounted WIM image with \fB--commit\fR, these two processes communicate using a
-POSIX message queue so that the unmount process can track the progress of the
-mount process.  See \fIsrc/mount_image.c\fR in the sources for details.
+\fBwimunmount\fR runs in a separate process from the process that previously ran
+\fBwimmount\fR.  When unmounting a read-write mounted WIM image with
+\fB--commit\fR, these two processes communicate using a POSIX message queue so
+that the unmount process can track the progress of the mount process.  See
+\fIsrc/mount_image.c\fR in the source code for details.
 .SH SEE ALSO
 .BR wimlib-imagex (1)
diff --git a/doc/man1/wimmountrw.1 b/doc/man1/wimmountrw.1
new file mode 100644 (file)
index 0000000..6b3f711
--- /dev/null
@@ -0,0 +1 @@
+.so man1/wimmount.1
diff --git a/doc/man1/wimoptimize.1 b/doc/man1/wimoptimize.1
new file mode 100644 (file)
index 0000000..13444ca
--- /dev/null
@@ -0,0 +1,126 @@
+.TH WIMOPTIMIZE "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimoptimize \- Optimize a WIM archive
+.SH SYNOPSIS
+\fBwimoptimize\fR \fIWIMFILE\fR [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwimoptimize\fR, or equivalently \fBwimlib-imagex optimize\fR, rebuilds the
+standalone WIM archive \fIWIMFILE\fR.  The new WIM is written to a temporary
+file, and it is renamed to the original file when it's ready.  This will remove
+any holes that have been left in the WIM as a result of appending or deleting
+files or images, so the new WIM may be smaller than the old WIM.
+.PP
+By default, \fBwimoptimize\fR will reuse (not recompress) compressed data and
+will not change the solid or pipable status of the WIM.  However, it can also
+perform recompression and/or convert between solid, non-solid, pipable, and
+non-pipable WIMs; see the options and examples below.
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+Before optimizing the WIM, verify its integrity if it contains extra integrity
+information.  Also include extra integrity information in the optimized WIM,
+even if it was not present before.
+.TP
+\fB--nocheck\fR
+Do not include extra integrity information in the optimized WIM, even if it was
+present before.
+.TP
+\fB--recompress\fR
+Recompress all data in the WIM while optimizing it.  This will significantly
+increase the time needed to optimize the WIM, but it may result in a better
+compression ratio if wimlib can do a better job than the program that created
+the WIM --- which is likely the case if the WIM was Microsoft-created, as
+wimlib's compressors are slightly stronger.
+.TP
+\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Recompress the WIM using the specified compression type, and optionally the
+specified compression level for that compression type.  This implies
+\fB--recompress\fR.  See the documentation for this option to
+\fBwimcapture\fR(1) for more details.
+.TP
+\fB--chunk-size\fR=\fISIZE\fR
+Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
+this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--solid\fR
+Create a "solid" archive that compresses multiple files together.  This usually
+results in a significantly better compression ratio but has disadvantages such
+as reduced compatibility.  See the documentation for this option to
+\fBwimcapture\fR(1) for more details.
+.TP
+\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Like \fB--compress\fR, but set the compression type used in solid resources.
+See the documentation for this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See
+the documentation for this option to \fBwimcapture\fR(1) for more details.
+.TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data.  Default: autodetect (number of
+processors).
+.TP
+\fB--pipable\fR
+Rebuild the WIM so that it can be applied fully sequentially, including from a
+pipe.  See \fBwimcapture\fR(1) for more details about creating pipable WIMs.  By
+default, when neither \fB--pipable\fR or \fB--not-pipable\fR is specified, the
+optimized WIM will be pipable if and only if it was pipable before.
+.TP
+\fB--not-pipable\fR
+Rebuild the WIM in the non-pipable format.
+.TP
+\fB--unsafe-compact\fR
+Compact the WIM in-place, without using a temporary file.  Existing resources
+are shifted down to fill holes and new resources are appended as needed.  The
+WIM is truncated to its final size, which may shrink the on-disk file.  This is
+more efficient than a full rebuild, but it is only supported when no
+recompression is being done.  More importantly, AN UNSAFE COMPACTION OPERATION
+CANNOT BE SAFELY INTERRUPTED!  If the operation is interrupted, then the WIM
+will be corrupted, and it may be impossible (or at least very difficult) to
+recover any data from it.  Users of this option are expected to know what they
+are doing and assume responsibility for any data corruption that may result.
+.SH NOTES
+\fBwimoptimize\fR does not support split WIMs or delta WIMs.  For such files,
+consider using \fBwimexport\fR(1) instead.  Note that \fBwimoptimize\fR is
+roughly equivalent to:
+.RS
+.PP
+\fBwimexport\fR \fIWIMFILE\fR all tmp.wim && mv tmp.wim \fIWIMFILE\fR
+.RE
+.PP
+.SH EXAMPLES
+Rebuild 'install.wim':
+.RS
+.PP
+wimoptimize install.wim
+.RE
+.PP
+Rebuild and recompress 'install.wim':
+.RS
+.PP
+wimoptimize install.wim --recompress
+.RE
+.PP
+Rebuild and recompress 'install.wim' using LZX ("maximum") compression at a
+higher-than-default compression level.  The compression chunk size remains
+unchanged.  This command will be slow, but it might be useful for optimizing
+files for distribution.  See \fIhttps://wimlib.net/compression.html\fR for some
+benchmark results.
+.RS
+.PP
+wimoptimize install.wim --compress=LZX:100
+.RE
+.PP
+Recompress 'install.wim' using solid-mode compression, then rename it to
+\'install.esd\'.  This will decrease the archive size significantly.  (Also
+consider using 'wimexport install.wim all install.esd --solid'.):
+.RS
+.PP
+wimoptimize install.wim --solid
+.br
+mv install.wim install.esd
+.RE
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wimexport (1)
+.BR wimverify (1)
diff --git a/doc/man1/wimsplit.1 b/doc/man1/wimsplit.1
new file mode 100644 (file)
index 0000000..b9e738c
--- /dev/null
@@ -0,0 +1,34 @@
+.TH WIMSPLIT "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimsplit \- Split a WIM archive into multiple parts
+.SH SYNOPSIS
+\fBwimsplit\fR \fIWIMFILE\fR \fISPLIT_WIM_PART_1\fR \fIPART_SIZE\fR [\fIOPTION...\fR]
+.SH DESCRIPTION
+\fBwimsplit\fR, or equivalently \fBwimlib-imagex split\fR, splits \fIWIMFILE\fR
+into parts with size at most \fIPART_SIZE\fR mebibytes (power-of-2 megabytes),
+with the first part having the name \fISPLIT_WIM_PART_1\fR and the other parts
+having names numbered in order of the parts.
+.PP
+\fBwimsplit\fR can split both non-pipable and pipable WIMs.
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+Before splitting the WIM, verify its integrity if it contains extra integrity
+information.  Also include extra integrity information in each split WIM part,
+even if \fIWIMFILE\fR did not contain it.
+.SH EXAMPLES
+Splits the WIM 'windows.wim' into 'windows.swm', 'windows2.swm', 'windows3.swm',
+etc. where each part is at most 100 MiB:
+.RS
+.PP
+wimsplit windows.wim windows.swm 100
+.RE
+.SH LIMITATIONS
+It is possible for the size of the parts to exceed the \fIPART_SIZE\fR given.
+This is impossible to avoid because the WIM file format provides no way to
+divide a single file resource among multiple split WIM parts.  So if you, for
+example, have a file inside the WIM that is 100 MiB compressed, then the split
+WIM will have at least one part that is 100 MiB in size to contain that file.
+.SH SEE ALSO
+.BR wimlib-imagex (1)
+.BR wimjoin (1)
diff --git a/doc/man1/wimunmount.1 b/doc/man1/wimunmount.1
new file mode 100644 (file)
index 0000000..6b3f711
--- /dev/null
@@ -0,0 +1 @@
+.so man1/wimmount.1
similarity index 65%
rename from doc/man1/wimlib-imagex-update.1
rename to doc/man1/wimupdate.1
index 107da36..9e6b577 100644 (file)
@@ -1,19 +1,17 @@
-.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.TH WIMUPDATE "1" "August 2016" "wimlib 1.10.0" "User Commands"
 .SH NAME
-wimlib-imagex-update \- Update a WIM image
+wimupdate \- Update a WIM image
 .SH SYNOPSIS
-\fBwimlib-imagex update\fR \fIWIMFILE\fR [\fIIMAGE\fR] [\fIOPTION\fR...] [< \fICMDFILE\fR]
+\fBwimupdate\fR \fIWIMFILE\fR [\fIIMAGE\fR] [\fIOPTION\fR...] [< \fICMDFILE\fR]
 .SH DESCRIPTION
-\fBwimlib-imagex update\fR modifies the specified \fIIMAGE\fR in the Windows
-Imaging (WIM) file \fIWIMFILE\fR by adding, deleting, or renaming files or
-directories in it.
-This command is also available as simply \fBwimupdate\fR if the appropriate
-hard link or batch file has been installed.
+\fBwimupdate\fR, or equivalently \fBwimlib-imagex update\fR, modifies the
+specified \fIIMAGE\fR in the Windows Imaging (WIM) archive \fIWIMFILE\fR by
+adding, deleting, or renaming files or directories in it.
 .PP
-\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to update.  It may be a 1-based
-index of an image in the WIM or the name of an image in the WIM.  Use the
-\fBwimlib-imagex info\fR (1) command to list the images a WIM file contains.
-\fIIMAGE\fR may be omitted if \fIWIMFILE\fR contains only one image.
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to update.  It may be the 1-based
+index of an image or the name of an image.  It may be omitted if \fIWIMFILE\fR
+contains only one image.  You can use \fBwiminfo\fR(1) to list the images
+contained in \fIWIMFILE\fR.
 .PP
 The modifications to perform on the WIM image are specified as a sequence of
 commands, one per line, read in a text file from standard input.  It is
@@ -41,9 +39,9 @@ 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.
 .PP
 The \fBadd\fR command supports a subset of the options accepted by
-\fBwimlib-imagex capture\fR; namely, \fB--dereference\fR,
-\fB--unix-data\fR, \fB--no-acls\fR, and \fB--strict-acls\fR.  See
-\fBwimlib-imagex-capture\fR (1) for explanations of these options.
+\fBwimcapture\fR; namely, \fB--dereference\fR, \fB--unix-data\fR,
+\fB--no-acls\fR, and \fB--strict-acls\fR.  See \fBwimcapture\fR(1) for
+explanations of these options.
 .PP
 In addition, the \fBadd\fR command supports the \fB--no-replace\fR option, which
 causes the \fBadd\fR command to refuse to overwrite existing nondirectory files
@@ -71,8 +69,8 @@ non-directory, which is not allowed.
 .PP
 There are no options available for the \fBrename\fR command.
 .SH OPTIONS
-The following options are accepted on the command line by \fBwimlib-imagex
-update\fR itself:
+The following options are accepted on the command line by \fBwimupdate\fR
+itself:
 .TP 6
 \fB--dereference\fR
 Use \fB--dereference\fR for all \fBadd\fR commands.
@@ -91,7 +89,7 @@ Use \fB--no-replace\fR for all \fBadd\fR commands.
 .TP
 \fB--config\fR=\fIFILE\fR
 Set the capture configuration file for all \fBadd\fR commands.  See the
-description of this option in \fBwimlib-imagex-capture\fR (1).
+description of this option to \fBwimcapture\fR(1).
 .TP
 \fB--force\fR
 Use \fB--force\fR for all \fBdelete\fR commands.
@@ -100,10 +98,9 @@ Use \fB--force\fR for all \fBdelete\fR commands.
 Use \fB--recursive\fR for all \fBdelete\fR commands.
 .TP
 \fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present; in addition, include an integrity table in the updated WIM.  If this
-option is not specified, an integrity table will be included in the updated WIM
-if and only if one was present before.
+Before updating the WIM, verify its integrity if it contains extra integrity
+information.  Also include extra integrity information in the updated WIM even
+if it was not present before.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing newly added files.  Default: autodetect
@@ -114,10 +111,9 @@ Rebuild the entire WIM rather than appending the updated 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 file.
 .IP
-See \fBwimlib-imagex-optimize\fR (1) for a more customizable way of
-rebuilding (and optionally recompressing) a WIM file.  If running
-\fBwimlib-imagex optimize\fR after \fBwimlib-imagex update\fR, there is
-no need to specify \fB--rebuild\fR to \fBwimlib-imagex update\fR.
+See \fBwimoptimize\fR(1) for a more customizable way of rebuilding (and
+optionally recompressing) a WIM file.  If running \fBwimoptimize\fR after
+\fBwimupdate\fR, there is no need to specify \fB--rebuild\fR to \fBwimupdate\fR.
 .TP
 \fB--command\fR=\fISTRING\fR
 Instead of reading update commands from standard input, read a single update
@@ -127,24 +123,18 @@ more than one update command.  Note that the \fISTRING\fR, as well as any
 paths containing spaces within the \fISTRING\fR must be appropriately quoted.
 If running from cmd.exe on Windows, you should use double quotes for the outer
 quotes and single quotes for the inner quotes.  Example:
+.IP
 .RS
 .RS
-.PP
-.nf
-wimlib-imagex update boot.wim 1 \\
-.br
-.RS
---command="add 'C:\\My Dir' '\\My Dir'"
-.RE
+wimupdate boot.wim 1 --command="add 'C:\\My Dir' '\\My Dir'"
 .RE
 .RE
-.fi
 .IP
-This option is provided for convenience only.  Do not execute
-\fBwimlib-imagex update\fR multiple consecutive times, each time passing the
-\fB--command\fR option!  This is inefficient.  Instead, generate an update
-command file and provide it (on standard input) to a single invocation of
-\fBwimlib-imagex update\fR, as explained in this document.
+This option is provided for convenience only.  Do not execute \fBwimupdate\fR
+multiple consecutive times, each time passing the \fB--command\fR option!  This
+is inefficient.  Instead, generate an update command file and provide it (on
+standard input) to a single invocation of \fBwimupdate\fR, as explained in this
+document.
 .TP
 \fB--wimboot-config\fR=\fIFILE\fR
 If this option is specified, no commands shall be read from standard input, and
@@ -162,21 +152,18 @@ This sets \fIFILE\fR as the WIMBoot configuration file for the image.  The
 [PrepopulateList] section of this file specifies path globs that shall not be
 extracted as WIMBoot pointer files (perhaps due to being needed early in the
 boot process).  See the documentation for the \fB--wimboot\fR option of
-\fBwimlib-imagex apply\fR (1) for more information.
+\fBwimapply\fR(1) for more information.
 .TP
 \fB--unsafe-compact\fR
 Compact the WIM archive in-place and append any new data, eliminating "holes".
-In general, this option should \fInot\fR be used because a failed or interrupted
-compaction will corrupt the WIM archive.  For more information, see the
-documentation for this option in \fBwimlib-imagex-optimize\fR (1).
+This is efficient, but in general this option should \fInot\fR be used because a
+failed or interrupted compaction will corrupt the WIM archive.  For more
+information, see the documentation for this option in \fBwimoptimize\fR(1).
 .SH NOTES
-\fBwimlib-imagex update\fR is partly redundant with \fBwimlib-imagex
-mountrw\fR, since if a WIM image can be mounted read-write, then there
-theoretically is no need for \fBwimlib-imagex update\fR.  The main advantage
-of \fBwimlib-imagex update\fR is that it works on both UNIX-like systems and
-Windows, whereas \fBwimlib-imagex mountrw\fR is only available on UNIX-like
-systems, and even then it only works on those with a compatible FUSE
-implementation.
+\fBwimupdate\fR can be viewed as redundant with \fBwimmountrw\fR, since a WIM
+image can also be updated by mounting it read-write.  However, \fBwimupdate\fR
+works on all platforms including Windows, whereas \fBwimmountrw\fR only works on
+Linux.
 .PP
 Symbolic links inside a WIM image are not dereferenced when being interpreted.
 So, for example, if you have a WIM image that contains a symbolic link
@@ -192,24 +179,23 @@ paths are by default treated case-sensitively.  The default case sensitivity may
 be changed by setting the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental
 variable to 0 or 1.
 .PP
-The command file (\fICMDFILE\fR) is parsed by \fBwimlib-imagex update\fR
-itself and not by the system shell.  Therefore, its syntax is limited.  However,
-comment lines beginning with '#' are allowed, and it is also possible to quote
-arguments with whitespace inside them.
+The command file (\fICMDFILE\fR) is parsed by \fBwimupdate\fR itself and not by
+the system shell.  Therefore, its syntax is limited.  However, comment lines
+beginning with '#' are allowed, and it is also possible to quote arguments with
+whitespace inside them.
 .PP
-On UNIX-like systems, you cannot use \fBwimlib-imagex update\fR to add files
-to an image directly from an NTFS volume using libntfs-3g, even though
-\fBwimlib-imagex capture\fR supports capturing a full image this way.
+On UNIX-like systems, you cannot use \fBwimupdate\fR to add files to an image
+directly from an NTFS volume using libntfs-3g, even though \fBwimcapture\fR
+supports capturing a full image this way.
 .PP
-Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimlib-imagex
-update\fR command partway through; however, after doing this, it is recommended
-to run \fBwimlib-imagex 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.
+Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimupdate\fR
+command partway through; however, after doing this, it is recommended to run
+\fBwimoptimize\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
 All the examples below show the update command file to be created as well as the
-\fBwimlib-imagex update\fR command to run to perform the updates.
+\fBwimupdate\fR command to run to perform the updates.
 .PP
 Delete two files from a WIM image:
 .PP
@@ -225,7 +211,7 @@ delete /sources/setup.exe
 .RE
 .PP
 .RS
-$ wimlib-imagex update boot.wim 2 < update_commands.txt
+$ wimupdate boot.wim 2 < update_commands.txt
 .RE
 .PP
 Add some files and directories to a WIM image.  Note that the first path of each
@@ -245,7 +231,7 @@ add somefile    /dir/file
 .RE
 .PP
 .RS
-$ wimlib-imagex update boot.wim 2 < update_commands.txt
+$ wimupdate boot.wim 2 < update_commands.txt
 .RE
 .PP
 Rename a file inside a WIM image.
@@ -261,11 +247,11 @@ rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt
 .RE
 .PP
 .RS
-$ wimlib-imagex update boot.wim 2 < update_commands.txt
+$ wimupdate boot.wim 2 < update_commands.txt
 .RE
 .PP
 Using additional features, such as comments, options, and overlays, and
-including an integrity table in the updated WIM:
+including extra integrity information in the updated WIM:
 .PP
 .RS
 \fIupdate_commands.txt\fR:
@@ -297,12 +283,12 @@ delete --recursive /Users/Me/Documents/Junk
 .RE
 .PP
 .RS
-$ wimlib-imagex update boot.wim 2 --check < update_commands.txt
+$ wimupdate boot.wim 2 --check < update_commands.txt
 .RE
 .PP
 .SH SEE ALSO
 .BR wimlib-imagex (1)
-.BR wimlib-imagex-capture (1)
-.BR wimlib-imagex-info (1)
-.BR wimlib-imagex-mountrw (1)
-.BR wimlib-imagex-optimize (1)
+.BR wimcapture (1)
+.BR wiminfo (1)
+.BR wimmountrw (1)
+.BR wimoptimize (1)
diff --git a/doc/man1/wimverify.1 b/doc/man1/wimverify.1
new file mode 100644 (file)
index 0000000..4d51118
--- /dev/null
@@ -0,0 +1,59 @@
+.TH WIMVERIFY "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimverify \- Verify a WIM archive
+.SH SYNOPSIS
+\fBwimverify\fR \fIWIMFILE\fR [\fIOPTION\fR...]
+.SH DESCRIPTION
+\fBwimverify\fR (or equivalently \fBwimlib-imagex verify\fR) checks the validity
+and integrity of the specified WIM archive.
+.PP
+Specifically, this command performs the following verifications on the WIM:
+.IP \[bu] 4
+Verify that the WIM can be successfully opened, which involves parsing the
+header, blob table, and XML data.
+.IP \[bu]
+If the WIM contains extra integrity information, verify the integrity of the
+entire WIM.
+.IP \[bu]
+Verify that the metadata for each image in the WIM can be successfully parsed.
+.IP \[bu]
+Verify that all files needed by each image are actually contained in the WIM or
+in one of the WIMs referenced by the \fB--ref\fR option.
+.IP \[bu]
+Verify that all files contained in the WIM can be successfully decompressed,
+with matching checksums.
+.SH OPTIONS
+.TP 6
+\fB--ref\fR="\fIGLOB\fR"
+File glob of additional WIMs or split WIM parts to reference resources from.
+This option can be specified multiple times.  Note: \fIGLOB\fR is listed in
+quotes because it is interpreted by \fBwimverify\fR and may need to be quoted to
+protect against shell expansion.
+.TP
+\fB--nocheck\fR
+Do not verify the WIM's integrity using the extra integrity information (the
+integrity table).
+.SH NOTES
+\fBwimverify\fR is a read-only operation; it does not modify the WIM file.
+.PP
+Even if the WIM does not contain extra integrity information (e.g. generated
+with the \fB--check\fR option to \fBwimcapture\fR), \fBwimverify\fR may still be
+quite useful because all file data is still checksummed.
+.PP
+In the future, \fBwimverify\fR might do more thorough verifications than it does
+now.
+.SH EXAMPLES
+Verify the WIM file 'boot.wim':
+.RS
+.PP
+wimverify boot.wim
+.RE
+.PP
+Verify the split WIM file consisting of 'boot.swm', 'boot2.swm', 'boot3.swm', ...:
+.RS
+.PP
+wimverify boot.swm --ref="boot*.swm"
+.RE
+.PP
+.SH SEE ALSO
+.BR wimlib-imagex (1)
index c7ad3e0..2a957a7 100644 (file)
@@ -13,9 +13,9 @@
  *
  * This is the documentation for the library interface of wimlib 1.10.0, a C
  * library for creating, modifying, extracting, and mounting files in the
- * Windows Imaging Format.  This documentation is intended for developers only.
- * If you have installed wimlib and want to know how to use the @b wimlib-imagex
- * program, please see the manual pages and also the <a
+ * Windows Imaging (WIM) format.  This documentation is intended for developers
+ * only.  If you have installed wimlib and want to know how to use the @b
+ * wimlib-imagex program, please see the manual pages and also the <a
  * href="https://wimlib.net/git/?p=wimlib;a=blob;f=README">README file</a>.
  *
  * @section sec_installing Installing
index 70cb5f6..b215511 100755 (executable)
@@ -107,21 +107,22 @@ function gen_pdf_from_man_page() {
        MANPATH="./doc" man -t $manbase | ps2pdf - $pdf
 }
 
-for fil in ./doc/man1/wimlib-imagex-*.1; do
+for fil in ./doc/man1/wim*.1; do
        manbase=`basename $fil`
-       manbase=${manbase%%.1}
-       cmd=$(echo $manbase | sed s/wimlib-imagex-//)
-       if [ $cmd == mount -o $cmd == mountrw -o $cmd == unmount ]; then
+       cmd=${manbase%.1}
+       case $cmd in
+       wimlib-imagex|wimmount|wimmountrw|wimunmount)
                continue
-       fi
+               ;;
+       esac
 
-       gen_pdf_from_man_page $manbase
+       gen_pdf_from_man_page $cmd
 
-       sed 's/$/\r/g' > ${DESTDIR}/wim${cmd}.cmd <<- EOF
+       sed 's/$/\r/g' > ${DESTDIR}/${cmd}.cmd <<- EOF
                @echo off
-               "%~dp0\\wimlib-imagex" $cmd %*
+               "%~dp0\\wimlib-imagex" ${cmd#wim} %*
        EOF
-       chmod +x ${DESTDIR}/wim${cmd}.cmd
+       chmod +x ${DESTDIR}/${cmd}.cmd
 done
 
 gen_pdf_from_man_page wimlib-imagex