From a0ab870124b71d950072609cf97c3c0ef5eb4655 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 12 May 2013 00:28:15 -0500 Subject: [PATCH 1/1] Doc updates --- Makefile.am | 1 + configure.ac | 1 + doc/imagex-apply.1.in | 4 +--- doc/imagex-capture.1.in | 28 +++++++++++++--------------- doc/imagex-extract.1.in | 11 +++++------ make-windoze-release | 6 ++++-- programs/imagex.c | 20 +++++++++++++++++--- src/wimlib.h | 17 +++++++++++++---- 8 files changed, 55 insertions(+), 33 deletions(-) diff --git a/Makefile.am b/Makefile.am index 788a7235..d75d065b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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) diff --git a/configure.ac b/configure.ac index 7fca1542..ba2baa55 100644 --- a/configure.ac +++ b/configure.ac @@ -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]) diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 76913a32..b078ba0b 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -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 diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index a3c0ac65..6a46eb2c 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -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 diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in index f6bbedad..ce1e8e4f 100644 --- a/doc/imagex-extract.1.in +++ b/doc/imagex-extract.1.in @@ -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 diff --git a/make-windoze-release b/make-windoze-release index 132937fb..296948ad 100755 --- a/make-windoze-release +++ b/make-windoze-release @@ -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 diff --git a/programs/imagex.c b/programs/imagex.c index 407967fa..42ba17fa 100644 --- a/programs/imagex.c +++ b/programs/imagex.c @@ -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); } } } diff --git a/src/wimlib.h b/src/wimlib.h index dd20f085..9ffcc6ca 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -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, -- 2.43.0