From: Eric Biggers <ebiggers3@gmail.com>
Date: Sat, 26 Apr 2014 21:34:51 +0000 (-0500)
Subject: WIMBoot: Update docs
X-Git-Tag: v1.7.0~262
X-Git-Url: https://wimlib.net/git/?p=wimlib;a=commitdiff_plain;h=cd433ce49f582175063141cc3673840bf321c453;ds=sidebyside

WIMBoot: Update docs
---

diff --git a/doc/man1/imagex-apply.1.in b/doc/man1/imagex-apply.1.in
index 9df08fd7..571823e1 100644
--- a/doc/man1/imagex-apply.1.in
+++ b/doc/man1/imagex-apply.1.in
@@ -398,20 +398,31 @@ Windows only: Instead of extracting the files themselves, extract "pointer
 files" back to the WIM archive.  This can result in significant space savings.
 However, it comes at several potential costs, such as not being able to delete
 the WIM archive and possibly having slower access to files.  See Microsoft's
-documentation for "WIMBoot" for more information.  Also, this option only works
-when several conditions hold:
-.RS
-.IP \[bu] 4
-The operating system is Windows 8.1 update 1 or later, since that is the first
-version of Windows that contains the Windows Overlay File System Filter Driver
-("WOF") necessary for this feature.
-.IP \[bu]
-The program is run as an Administrator.
-.IP \[bu]
-The WIM archive is not solid (i.e. is not an "ESD file").
-.IP \[bu]
-The target volume is NTFS or another filesystem that supports reparse points.
-.RE
+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 File System 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.
 .SH NOTES
 \fIData integrity\fR:  WIM files include SHA1 message digests for file data.
 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file
diff --git a/include/wimlib.h b/include/wimlib.h
index 7a453373..a8ab4ba8 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -1326,9 +1326,12 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 #define WIMLIB_ADD_FLAG_WINCONFIG		0x00000800
 
 /**
- * Capture image as WIMBoot compatible.  In addition, use the capture
- * configuration file <c>$SOURCE/Windows/System32/WimBootCompress.ini</c> if it
- * exists, where <c>$SOURCE</c> is the directory being captured.
+ * Capture image as WIMBoot compatible.  In addition, if no capture
+ * configuration file is explicitly specified use the capture configuration file
+ * <c>$SOURCE/Windows/System32/WimBootCompress.ini</c> if it exists, where
+ * <c>$SOURCE</c> is the directory being captured; or, if a capture
+ * configuration file is explicitly specified, use it and also place it at
+ * /Windows/System32/WimBootCompress.ini in the WIM image.
  *
  * Note: this will not by itself change the compression type.  Before writing
  * the WIM file, it's recommended to also do:
@@ -1518,7 +1521,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE	0x00200000
 
-/** Windows only: Extract files as "pointers" back to the WIM archive.  */
+/** Windows only: Extract files as "pointers" back to the WIM archive.  See the
+ * documentation for the <b>--wimboot</b> option of <b>wimlib-imagex apply</b>
+ * for more information.  */
 #define WIMLIB_EXTRACT_FLAG_WIMBOOT			0x00400000
 
 /** @} */