imagex.1.in: Remove redundant words

[wimlib] / doc / imagex.1.in

diff --git a/doc/imagex.1.in b/doc/imagex.1.in
index d62ec8965aba604bdc1878e8b6f6546bccfe90c3..6838f2a170ced16fbddeea1957a62ceaed4a91e9 100644 (file)
--- a/doc/imagex.1.in
+++ b/doc/imagex.1.in
@@ -1,77 +1,76 @@
-.TH IMAGEX 1 "January 2013" "imagex (wimlib @VERSION@)" "User Commands"
+.TH IMAGEX 1 "March 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"

 .SH NAME
 .SH NAME

-imagex \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive
+@IMAGEX_PROGNAME@ \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive

 .SH SYNOPSIS
 .SH SYNOPSIS

-\fBimagex append\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ append\fR \fIarguments...\fR

 .br
 .br

-\fBimagex apply\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ apply\fR \fIarguments...\fR

 .br
 .br

-\fBimagex capture\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ capture\fR \fIarguments...\fR

 .br
 .br

-\fBimagex delete\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ delete\fR \fIarguments...\fR

 .br
 .br

-\fBimagex dir\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ dir\fR \fIarguments...\fR

 .br
 .br

-\fBimagex export\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ export\fR \fIarguments...\fR

 .br
 .br

-\fBimagex info\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ info\fR \fIarguments...\fR

 .br
 .br

-\fBimagex join\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ join\fR \fIarguments...\fR

 .br
 .br

-\fBimagex mount\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ mount\fR \fIarguments...\fR

 .br
 .br

-\fBimagex mountrw\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ mountrw\fR \fIarguments...\fR

 .br
 .br

-\fBimagex optimize\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ optimize\fR \fIarguments...\fR

 .br
 .br

-\fBimagex split\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ split\fR \fIarguments...\fR

 .br
 .br

-\fBimagex unmount\fR \fIarguments...\fR
+\fB@IMAGEX_PROGNAME@ unmount\fR \fIarguments...\fR

 
 .SH DESCRIPTION
 
 .SH DESCRIPTION

-\fBimagex\fR is able to deal with archives in the Windows Imaging Format (.wim
+\fB@IMAGEX_PROGNAME@\fR is able to deal with archives in the Windows Imaging Format (.wim

 files). Its interface is meant to be similar to Microsoft's imagex.exe program.
 
 files). Its interface is meant to be similar to Microsoft's imagex.exe program.
 

-To do its work, \fBimagex\fR uses \fBwimlib\fR, a library which provides
+To do its work, \fB@IMAGEX_PROGNAME@\fR uses \fBwimlib\fR, a library which provides

 interfaces for manipulating WIM archives.  You could wimlib in your own programs
 if you wanted to.  wimlib's public interface is documented.
 
 interfaces for manipulating WIM archives.  You could wimlib in your own programs
 if you wanted to.  wimlib's public interface is documented.
 

-See \fBWARNING\fR.
-

 .SH COMMANDS
 
 .SH COMMANDS
 

-There is a separate manual page for each \fBimagex\fR command.
+There is a separate manual page for each \fB@IMAGEX_PROGNAME@\fR command.

 
 .SH SUPPORTED FEATURES
 
 
 .SH SUPPORTED FEATURES
 

-The following features are currently supported:
+The following general features are currently supported (note: this is not a
+complete list):

 
 .IP \[bu] 3
 
 .IP \[bu] 3

-Create a stand-alone WIM from a directory or NTFS volume (\fBimagex capture\fR)
+Create a stand-alone WIM from a directory or NTFS volume (\fB@IMAGEX_PROGNAME@ capture\fR)

 .IP \[bu]
 .IP \[bu]

-Append a directory or NTFS volume onto a stand-alone WIM as a new image (\fBimagex
+Append a directory or NTFS volume onto a stand-alone WIM as a new image (\fB@IMAGEX_PROGNAME@

 append\fR)
 .IP \[bu]
 Apply an image from a stand-alone or split WIM to a directory or NTFS volume
 append\fR)
 .IP \[bu]
 Apply an image from a stand-alone or split WIM to a directory or NTFS volume

-(\fBimagex apply\fR)
+(\fB@IMAGEX_PROGNAME@ apply\fR)

 .IP \[bu]
 .IP \[bu]

-Mount an image from a stand-alone or split WIM read-only (\fBimagex mount\fR)
+Mount an image from a stand-alone or split WIM read-only (\fB@IMAGEX_PROGNAME@ mount\fR)

 .IP \[bu]
 .IP \[bu]

-Mount an image from a stand-alone WIM read-write (\fBimagex mountrw\fR)
+Mount an image from a stand-alone WIM read-write (\fB@IMAGEX_PROGNAME@ mountrw\fR)

 .IP \[bu]
 .IP \[bu]

-Delete image(s) from a stand-alone WIM (\fBimagex delete\fR)
+Delete image(s) from a stand-alone WIM (\fB@IMAGEX_PROGNAME@ delete\fR)

 .IP \[bu]
 .IP \[bu]

-Export image(s) from a stand-alone or split WIM (\fBimagex export\fR)
+Export image(s) from a stand-alone or split WIM (\fB@IMAGEX_PROGNAME@ export\fR)

 .IP \[bu]
 .IP \[bu]

-Display information about a WIM file (\fBimagex info\fR, \fBimagex dir\fR)
+Display information about a WIM file (\fB@IMAGEX_PROGNAME@ info\fR, \fB@IMAGEX_PROGNAME@ dir\fR)

 .IP \[bu]
 .IP \[bu]

-Change the name or description of an image in the WIM (\fBimagex info\fR)
+Change the name or description of an image in the WIM (\fB@IMAGEX_PROGNAME@ info\fR)

 .IP \[bu]
 .IP \[bu]

-Change which image in a WIM is bootable (\fBimagex info\fR)
+Change which image in a WIM is bootable (\fB@IMAGEX_PROGNAME@ info\fR)

 .IP \[bu]
 .IP \[bu]

-Combine split WIMs into one stand-alone WIM (\fBimage join\fR)
+Combine split WIMs into one stand-alone WIM (\fB@IMAGEX_PROGNAME@ join\fR)

 .IP \[bu]
 .IP \[bu]

-Split a stand-alone WIM into multiple parts (\fBimage split\fR)
+Split a stand-alone WIM into multiple parts (\fB@IMAGEX_PROGNAME@ split\fR)

 .IP \[bu]
 Support for all WIM compression types, both compression and decompression (LZX,
 XPRESS, and none)
 .IP \[bu]
 Support for all WIM compression types, both compression and decompression (LZX,
 XPRESS, and none)


@@ -80,53 +79,96 @@ WIM integrity table is supported (\fB--check\fR option to many commands)
 .IP \[bu]
 WIM XML data (parsed and written using \fBlibxml\fR(3))
 
 .IP \[bu]
 WIM XML data (parsed and written using \fBlibxml\fR(3))
 

-.SH UNSUPPORTED FEATURES
-
-As of version 1.0.0, wimlib supports capturing and applying WIMs directly from
-NTFS and has much improved support for hard links and symbolic links.  In
-addition, you may now apply split WIMs and mount them read-only.  I don't think
-there are many other features that would be worth it to implement.  Besides
-porting the library to Windows (which I'm not really interested in), the main
-thing that could use improvement (in my opinion) is that the LZX compression
-ratio still isn't quite as good as Microsoft's version.  Furthermore, if
-Microsoft updates the WIM format, I'd need to support it, but it looks like the
-format for Windows 8 is the same as that of Windows 7.
-

 .SH DIFFERENCES FROM MICROSOFT IMAGEX
 
 While similar to Microsoft's "imagex.exe" program, this program is designed for
 UNIX-based systems and by the nature of the platform cannot be exactly the same
 .SH DIFFERENCES FROM MICROSOFT IMAGEX
 
 While similar to Microsoft's "imagex.exe" program, this program is designed for
 UNIX-based systems and by the nature of the platform cannot be exactly the same

-as Microsoft's version.
+as Microsoft's version.  In addition, I have added additional useful features
+when appropriate.

 
 

-In particular, because Microsoft designed the WIM file format to accomodate
-Windows-specific and NTFS-specific features, we must have two separate image
-capture and application modes (although the \fBimagex\fR subcommands for the
-modes are the same): one for general image capture and application, and one for
-the capture or application of an image specifically from/to an NTFS volume.
+.IP \[bu] 4
+Because Microsoft designed the WIM file format to accomodate Windows-specific
+and NTFS-specific features, wimlib must have two separate image capture and
+application modes (although the \fB@IMAGEX_PROGNAME@\fR subcommands for the modes are the
+same): one for general image capture and application, and one for the capture or
+application of an image specifically from/to an NTFS volume.

 
 

-Some features, such as the ability to keep files hard-linked across WIM images
-when they are extracted from a WIM, are not available in Microsoft's version of
-imagex.  Also, this version of \fBimagex\fR lets you mount an image from a split
-WIM read-only, while Microsoft's version does not.
+Note: the above applies to UNIX builds.  On the Windows builds of wimlib, there
+is only one image capture and application mode, similar to Microsoft's ImageX.

 
 

+.IP \[bu]

 Microsoft's version has some weird limitations, like it won't let you extract a
 WIM on a shared folder, and it requires some commands to be run only from
 Windows PE and not from regular Windows.  This version does not have these
 Microsoft's version has some weird limitations, like it won't let you extract a
 WIM on a shared folder, and it requires some commands to be run only from
 Windows PE and not from regular Windows.  This version does not have these

-unusual limitations, although it won't actually run on Windows anyway.
+unusual limitations.
+
+.IP \[bu]
+There are bugs in Microsoft's WIM library and I obviously have not included the
+same bugs in wimlib, although in some cases I have had to work around bugs for
+compatibility purposes.
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@ optimize\fR,
+which lets you easily remove wasted space in a WIM (which can arise after
+a WIM image is appended or mounted read-write).
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR, which lets you
+easily join the parts of a split WIM.
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@ apply\fR supports keeping files hard-linked or symlinked
+across WIM images when extracted from a WIM.  So you can, for example, extract
+different versions of Windows from an install.wim without using much extra
+space.  (Note: this functionality is only available in UNIX builds of wimlib.)
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@ capture\fR supports combining multiple separate directories
+and files together in a configurable way to create a WIM image.
+
+.IP \[bu]
+wimlib's XPRESS compressor is better than Microsoft's.

 
 

-There are bugs in Microsoft's WIM library and I obviously have not included
-these bugs in my version; however it's to be expected that despite that fact, my
-version has more bugs because it's been less widely tested and used.
+.IP \[bu]
+wimlib supports multithreaded compression, which can make it much faster to
+create compressed WIM files.

 
 

-Obviously, this version of imagex is free software but Microsoft's version is
-not.
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes,
+owners, and groups are stored.  (Note: this functionality is only available on
+UNIX builds.)
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@ mount\fR and \fB@IMAGEX_PROGNAME@ mountrw\fR are much faster than
+Microsoft's versions for some reason.  I don't know what they have their program
+do that takes so long to simply set up a mountpoint.  (Note: this functionality
+is only available on UNIX builds.)
+
+.IP \[bu]
+\fB@IMAGEX_PROGNAME@ mount\fR supports mounting an image from a split WIM, but
+Microsoft's software does not.  (Note: this functionality is only available on
+UNIX builds.)
+
+.SH LOCALES AND CHARACTER ENCODINGS
+
+wimlib 1.3.0 has improved support for alternate character encodings.
+However, not everything has been well tested, and on UNIX you are strongly
+encouraged to use a UTF-8 locale so that you do not run into any problems.
+In particular, if your locale uses a character encoding that is
+not UTF-8, then you will not be able to open or capture WIM files containing
+files with paths not representable in the current locale's character encoding.
+
+Similar restrictions apply to the Windows-native build of wimlib, but
+unfortunately Windows does not support UTF-8 locales.  So you will not be able
+to apply a WIM image containing files with names not representable in the
+current Windows code page, nor will you be able to capture a directory tree
+containing files with names not representable in the current Windows code page.

 
 .SH WARNING
 
 
 .SH WARNING
 

-Note: \fBwimlib\fR and \fBimagex\fR are experimental.  Use Microsoft's
-imagex.exe if you have to make sure your WIM files are made "correctly".  Not
-all features listed under \fBSUPPORTED FEATURES\fR have been thoroughly tested.
-Feel free to submit a bug report if you find a bug.
+Note: \fBwimlib\fR and \fB@IMAGEX_PROGNAME@\fR are experimental.  Use Microsoft's
+imagex.exe if you have to make sure your WIM files are made "correctly".  Feel
+free to submit a bug report if you find a bug.

 
 Some parts of the WIM file format are poorly documented or even completely
 undocumented, so I've just had to do the best I can to read and write WIMs in a
 
 Some parts of the WIM file format are poorly documented or even completely
 undocumented, so I've just had to do the best I can to read and write WIMs in a


@@ -137,17 +179,16 @@ way that appears to be compatible with Microsoft's software.
 Report bugs to ebiggers3@gmail.com.
 
 .SH SEE ALSO
 Report bugs to ebiggers3@gmail.com.
 
 .SH SEE ALSO

-.BR imagex-append (1),
-.BR imagex-apply (1),
-.BR imagex-capture (1),
-.BR imagex-delete (1),
-.BR imagex-dir (1),
-.BR imagex-export (1),
-.BR imagex-info (1),
-.BR imagex-join (1),
-.BR imagex-mount (1),
-.BR imagex-mountrw (1),
-.BR imagex-optimize (1),
-.BR imagex-split (1),
-.BR imagex-unmount (1),
-
+.BR @IMAGEX_PROGNAME@-append (1),
+.BR @IMAGEX_PROGNAME@-apply (1),
+.BR @IMAGEX_PROGNAME@-capture (1),
+.BR @IMAGEX_PROGNAME@-delete (1),
+.BR @IMAGEX_PROGNAME@-dir (1),
+.BR @IMAGEX_PROGNAME@-export (1),
+.BR @IMAGEX_PROGNAME@-info (1),
+.BR @IMAGEX_PROGNAME@-join (1),
+.BR @IMAGEX_PROGNAME@-mount (1),
+.BR @IMAGEX_PROGNAME@-mountrw (1),
+.BR @IMAGEX_PROGNAME@-optimize (1),
+.BR @IMAGEX_PROGNAME@-split (1),
+.BR @IMAGEX_PROGNAME@-unmount (1),