Doc updates
authorEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 05:28:15 +0000 (00:28 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 05:28:15 +0000 (00:28 -0500)
Makefile.am
configure.ac
doc/imagex-apply.1.in
doc/imagex-capture.1.in
doc/imagex-extract.1.in
make-windoze-release
programs/imagex.c
src/wimlib.h

index 788a72351066dc2391b92eadc8f3e6a7608e1c3e..d75d065b303c0f09e6d835bd63767235d3b3dee1 100644 (file)
@@ -162,6 +162,7 @@ wimlib_manpages =                           \
        doc/@IMAGEX_PROGNAME@-optimize.1        \
        doc/@IMAGEX_PROGNAME@-split.1           \
        doc/@IMAGEX_PROGNAME@-unmount.1         \
+       doc/@IMAGEX_PROGNAME@-update.1          \
        doc/mkwinpeimg.1
 
 man1_MANS = $(wimlib_manpages)
index 7fca1542e1a072ab7cdd648e32dfcba148bdbf46..ba2baa55ad8c67735013ea4b59efef4f196e9e8e 100644 (file)
@@ -36,6 +36,7 @@ AC_CONFIG_FILES([Makefile]
                [doc/"$IMAGEX_PROGNAME"-optimize.1:doc/imagex-optimize.1.in]
                [doc/"$IMAGEX_PROGNAME"-split.1:doc/imagex-split.1.in]
                [doc/"$IMAGEX_PROGNAME"-unmount.1:doc/imagex-unmount.1.in]
+               [doc/"$IMAGEX_PROGNAME"-update.1:doc/imagex-update.1.in]
                [doc/mkwinpeimg.1])
 
 AC_CONFIG_FILES([programs/mkwinpeimg], [chmod +x programs/mkwinpeimg])
index 76913a32c4e1c61169c65d02b42ffcfe6200cdb5..b078ba0bbaf604f1838e54aae831438ed904cda4 100644 (file)
@@ -253,9 +253,7 @@ the \fB--unix-data\fR flag.  By passing \fB--unix-data\fR to
 restored when available.
 .TP
 \fB--no-acls\fR
-In the NTFS apply mode, do not apply security descriptors.  This flag is also
-available in the native Win32 build of wimlib and may be useful when running
-\fB@IMAGEX_PROGNAME@\fR as a non-administrator.
+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
index a3c0ac653333396f4a921efcfb679eadf6d319c9..6a46eb2c86cb46b47bffe7f5b5f867cff79eacb1 100644 (file)
@@ -237,6 +237,16 @@ information.
 In the NTFS capture mode, do not capture security descriptors.  This flag is
 also available in the native Win32 build of wimlib.
 .TP
+\fB--strict-acls\fR
+In the Win32 native build of wimlib, fail immediately if the full security
+descriptor of any file or directory cannot be read.  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 with 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
@@ -255,16 +265,6 @@ Links are fixed up on a per-source basis in the case of a multi-source capture
 (\fB--source-list\fR specified), so you may wish to set \fB--norpfix\fR in that
 case.
 .TP
-\fB--strict-acls\fR
-In the Win32 native build of wimlib, fail immediately if the full security
-descriptor of any file or directory cannot be read.  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 with to provide this option, although the
-Administrator should have permission to read everything anyway.
-.TP
 \fB--source-list\fR
 \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR, as of wimlib 1.3.0, support a new
 option to create a WIM image from multiple files or directories.  When
@@ -324,11 +324,9 @@ type, and \fB@IMAGEX_PROGNAME@\fR always enforces this.
 stream chunk size of 32768.  The only WIMs I've seen that are different from
 this are some pre-Vista WIMs that had a different version number.
 
-Unless \fB--rebuild\fR is specified, aborting an \fB@IMAGEX_PROGNAME@ append\fR command
-mid-way through has a small chance of corrupting the WIM file.  However, a
-precaution is taken against this, so it should be very unlikely.  In the event
-of an aborted \fB@IMAGEX_PROGNAME@ append\fR, \fB@IMAGEX_PROGNAME@ optimize\fR may be run to remove
-extra data that may have been partially appended to the physical WIM file but
+It is safe to abort an \fB@IMAGEX_PROGNAME@ append\fR command partway through;
+however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
+optimize\fR to remove any data that was appended to the physical WIM file but
 not yet incorporated into the structure of the WIM.
 
 \fISOURCE\fR may be a symbolic link to a directory rather than a directory
index f6bbedada3cf2e694b731d48b280a8dffd952b4d..ce1e8e4fa598d08f937faabb0a1ac6809ff4dfa1 100644 (file)
@@ -56,7 +56,7 @@ present.
 .TP
 \fB--verbose\fR
 Print the path to of each file or directory within the WIM image as it is
-extracted, and some additional informational messages.
+extracted.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
 File glob of additional split WIM parts that are part of the split WIM.  See
@@ -67,15 +67,14 @@ Restore the UNIX-specific data captured using \fB@IMAGEX_PROGNAME@ capture\fR
 with the \fB--unix-data\fR option.  This option is only available on UNIX.
 .TP
 \fB--no-acls\fR
-Do not restore security descriptors on extracted files and directories.  This
-option is only available on Windows.
+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.  The default behavior without this
 option is to fall back to setting a security descriptor with the SACL omitted,
 then only the default inherited security descriptor, if we do not have
-permission to set the desired one.  This option is only available on Windows.
+permission to set the desired one.
 .TP
 \fB--to-stdout\fR
 Extract the files to standard output instead of to the filesystem.  This can
@@ -89,14 +88,14 @@ extracted.
 stream it extracts and verifies that it is the same as the SHA1 message digest
 provided in the WIM file.  Thus, it should provide assurance of data integrity.
 
-Reparse-point fixups (a.k.a. changing absolute symbolic links and junction to
+Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 
 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 support extracting files directly to a NTFS volume using libntfs-3g.
 
-Not all data and metadata containing in each WIM \fIPATH\fR will necessarily be
+Not all data and metadata contained in each WIM \fIPATH\fR will necessarily be
 extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
 platform (UNIX or Windows) and supported features of the filesystem.  The
 documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
index 132937fbbe69e897d0abf8cd6fe4f62f61d95d8a..296948add3a5a066ff100c07c4b2f168f88f8a09 100755 (executable)
@@ -25,10 +25,12 @@ for fil in ./doc/wimlib-imagex-*.1; do
        echo $fil
        base=`basename $fil`
        base=${base%%.1}
-       MANWIDTH=80 man $fil | col -b > $DESTDIR/doc/$base
+       #MANWIDTH=80 man $fil | col -b > $DESTDIR/doc/$base
+       man -t $fil | ps2pdf - $DESTDIR/doc/${base}.pdf
 done
 
-for fil in $DESTDIR/{README*,NEWS} $DESTDIR/doc/*; do
+#for fil in $DESTDIR/{README*,NEWS} $DESTDIR/doc/*; do
+for fil in $DESTDIR/{README*,NEWS}; do
        sed < $fil > ${fil}.txt -e 's/$/\r/g'
        rm $fil
 done
index 407967fa784d6363907793f7e3eb5cc05e788303..42ba17fa8a7856cda80576464d094d7abbdbf9f5 100644 (file)
@@ -180,6 +180,20 @@ IMAGEX_PROGNAME" update WIMFILE IMAGE [--check] [--rebuild]\n"
 ),
 };
 
+
+static void
+recommend_man_page(const tchar *cmd_name)
+{
+#ifdef __WIN32__
+       tprintf(T("\nSee "IMAGEX_PROGNAME"-%"TS".pdf in the "
+                 "doc directory for more details.\n"),
+               cmd_name);
+#else
+       tprintf(T("\nTry `man "IMAGEX_PROGNAME"-%"TS"' "
+                 "for more details.\n"), cmd_name);
+#endif
+}
+
 enum {
        IMAGEX_ALLOW_OTHER_OPTION,
        IMAGEX_BOOT_OPTION,
@@ -2989,8 +3003,9 @@ imagex_update(int argc, tchar **argv)
        }
 
        /* Read update commands from standard input */
-       if (isatty(STDIN_FILENO))
+       if (isatty(STDIN_FILENO)) {
                tputs(T("Reading update commands from standard input..."));
+       }
        cmd_file_contents = stdin_get_text_contents(&cmd_file_nchars);
        if (!cmd_file_contents) {
                ret = -1;
@@ -3134,8 +3149,7 @@ usage(int cmd_type)
        tprintf(T("Usage:\n%"TS), usage_strings[cmd_type]);
        for_imagex_command(cmd) {
                if (cmd->cmd == cmd_type) {
-                       tprintf(T("\nTry `man "IMAGEX_PROGNAME"-%"TS"' "
-                                 "for more details.\n"), cmd->name);
+                       recommend_man_page(cmd->name);
                }
        }
 }
index dd20f0854bcee30999a9ee7106ec6886667b74f8..9ffcc6ca33033e9b62dd83a6ffed52f33b7468cb 100644 (file)
@@ -743,7 +743,7 @@ struct wimlib_capture_config {
 /** Do not issue an error if the path to delete does not exist. */
 #define WIMLIB_DELETE_FLAG_FORCE                       0x00000001
 
-/** Delete a file or directory tree recursively; if not specified, an error is
+/** Delete the file or directory tree recursively; if not specified, an error is
  * issued if the path to delete is a directory. */
 #define WIMLIB_DELETE_FLAG_RECURSIVE                   0x00000002
 
@@ -2571,8 +2571,14 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  *     Attempted to perform an add command that conflicted with previously
  *     existing files in the WIM when an overlay was attempted.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- *     Attempted to perform an add command with ::WIMLIB_ADD_FLAG_NTFS set, but
- *     the same image had previously already been added from a NTFS volume.
+ *     An unknown operation type was specified in the update commands; or,
+ *     attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set
+ *     in the @a add_flags, but the same image had previously already been
+ *     added from a NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
+ *     ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @a add_flags for one add
+ *     command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were
+ *     specified in the @a add_flags for an add command in which @a
+ *     wim_target_path was not the root directory of the WIM image.
  * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA
  *     (Windows only):  While executing an add command, tried to capture a
  *     reparse point with invalid data.
@@ -2626,7 +2632,10 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  *     directory.
  * @retval ::WIMLIB_ERR_UNSUPPORTED
  *     ::WIMLIB_ADD_FLAG_NTFS was specified in the @a add_flags for an update
- *     command, but wimlib was configured with the @c --without-ntfs-3g flag.
+ *     command, but wimlib was configured with the @c --without-ntfs-3g flag;
+ *     or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA
+ *     or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @a
+ *     add_flags for an update command.
  */
 extern int
 wimlib_update_image(WIMStruct *wim,