Documentation fixes/additions
authorEric Biggers <ebiggers3@gmail.com>
Sat, 19 May 2012 18:30:58 +0000 (13:30 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Sat, 19 May 2012 18:30:58 +0000 (13:30 -0500)
doc/imagex-append.1.in
doc/imagex-apply.1.in
doc/imagex-capture.1.in
doc/imagex-delete.1.in
doc/imagex-dir.1.in
doc/imagex-export.1.in
doc/imagex-join.1.in
doc/imagex.1.in
programs/imagex.c
src/wimlib.h

index 2a7b2abed6482d2453c23435dbf456c454d6c32c..d5fa11ece97ec301b470337498a2fa69393bb353 100644 (file)
@@ -36,6 +36,15 @@ Specify a string to use in the <FLAGS> element of the XML data for the image.
 .TP
 \fB--verify\fR
 This option is currently unsupported.
+
+.SH EXAMPLES
+.IP 
+image append boot.wim winpe/ "Microsoft Windows PE"
+.LP 
+Add a new image to the existing WIM file boot.wim.  The files in the directory 'winpe' 
+are added recursively to the image.  The image is given the name "Microsoft
+Windows PE" and no description.
+
 .SH SEE ALSO
 .BR imagex (1)
 
index d66034ef7278aae28741dc525ba549d8b7b1ad84..7e09a9497d6e41188388a69c9dc1c55a02d9a446 100644 (file)
@@ -42,6 +42,14 @@ Print the path to of each file or directory within the WIM image as it is extrac
 .TP
 \fB--verify\fR
 This option is currently unsupported.
+
+.SH EXAMPLES
+.IP 
+image apply boot.wim all boot --hardlink
+.LP 
+Extract all images in the WIM 'boot.wim' to the directory 'boot', and hard link
+all identical files.
+
 .SH SEE ALSO
 .BR imagex (1)
 
index 02d47650b0393faebb0fe6f3946f4b3eb91c6278..3c51ab779a8a3616353bd5fa41530ff2772cecbb 100644 (file)
@@ -46,6 +46,14 @@ This option is currently unsupported.
 .TP
 \fB--verbose\fR
 Print the names of files and directories as they are captured.
+
+.SH EXAMPLES
+.IP 
+image capture boot boot.wim --compress=maximum --check
+.LP 
+Create a new WIM 'boot.wim' from the directory 'boot', using LZX compression and
+including an integrity table.
+
 .SH SEE ALSO
 .BR imagex (1)
 
index a2bea2329ded4b574686851973f94e8564acaa39..ef8b3f61e8a16cc139418ec202ec6db35f833dff 100644 (file)
@@ -29,6 +29,13 @@ When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present; additionally, when rewriting \fIWIMFILE\fR after the specified image was
 deleted, write an integrity table.  If this option is not specified, no integrity
 table is included in the new WIM file, even if there was one before.
+
+.SH EXAMPLES
+.IP 
+image delete boot.wim 1
+.LP 
+Delete the first image from 'boot.wim'.
+
 .SH SEE ALSO
 .BR imagex (1)
 
index fd2646751f0a3e6a0128e1d5ba2c8f009c327a30..34dbe54057007c2cda728833114e6df7d771f784 100644 (file)
@@ -15,6 +15,12 @@ an index of an image in the WIM file, starting at 1.  Alternatively, it may be
 the name of an image in the WIM file.  It also may be the keyword "all", which
 specifies all images.
 
+.SH EXAMPLES
+.IP 
+image dir boot.wim 1
+.LP 
+Show all files in the first image of 'boot.wim'
+
 .SH SEE ALSO
 .BR imagex (1)
 
index aa8030eb38071291849fbb4b540ff492c6659887..6ec57160f6c715e7d7fb17ce99912bde71c2096b 100644 (file)
@@ -54,6 +54,13 @@ Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
 is specified but \fITYPE\fR is not, the compression type is taken to be
 "maximum", which is LZX compression.  "fast" compression is XPRESS compression.
 
+.SH EXAMPLES
+.IP 
+image export boot.wim 2 image2.wim --compress=maximum
+.LP 
+Export the second image of 'boot.wim' to the new WIM file 'image2.wim', and
+change the compression type to maximum, if it wasn't maximum already.
+
 .SH SEE ALSO
 .BR imagex (1)
 
index db149fa57d1a2dc91cac9c5f8c4cc53c9029df22..5b65238c9ee69cb0e9b05247f5af827ce590353b 100644 (file)
@@ -12,14 +12,6 @@ Joins the \fISPLIT_WIMs\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 EXAMPLES
-
-.IP 
-imagex join windows.wim windows*.swm
-.LP
-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 with to the file `windows.wim'.
 
 .SH OPTIONS
 .TP 6
@@ -28,6 +20,14 @@ When reading each \fISPLIT_WIM\fR, verify its integrity if the integrity table i
 present; additionally, when writing \fIOUT_WIMFILE\fR,
 write an integrity table.  If this option is not specified, no integrity table
 is included in the new WIM file, even if there was one before.
-.TP
+
+.SH EXAMPLES
+.IP 
+imagex join windows.wim windows*.swm
+.LP
+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 with to the file `windows.wim'.
+
 .SH SEE ALSO
 .BR imagex (1)
index 0a24ca4d9f4b048797d0bb4a00747b89058953e8..c65cd2d870deffbcf71a9ca3f39e8863f55928f5 100644 (file)
@@ -69,7 +69,7 @@ Change the name or description of an image in the WIM (\fBimagex info\fR)
 .IP \[bu] 2
 Change which image in a WIM is bootable (\fBimagex info\fR)
 .IP \[bu] 2
-Combining split WIMs into one WIM (\fB image join\fR)
+Combining split WIMs into one WIM (\fBimage join\fR)
 
 .SH UNSUPPORTED FEATURES
 The following features are currently unsupported:
@@ -82,7 +82,8 @@ be applied with the correct file permissions.
 .IP \[bu] 2
 Split WIMs are not fully supported.  These can be used to split up a WIM to fit
 on multiple CDs, if you can't use a DVD for some reason.  You can use
-\fBimagex join\fR to combine split WIMs, but you cannot yet create split WIMs.
+\fBimagex join\fR to combine split WIMs, but you cannot yet create split WIMs or
+mount them directly.
 .IP \[bu] 2
 The \fB--verify\fR option, for all commands that use it.  Without this option,
 there theoretically could be a SHA1 hash collision between two files, although
index 6dcc62d3b63dbcb29704a95e443294a046bb760c..66772ae48c2f0fe5e0fe9b0a759a986128d432c7 100644 (file)
@@ -93,7 +93,7 @@ static const char *usage_strings[] = {
 "        [NEW_DESC] [--boot] [--check] [--header] [--lookup-table]\n"
 "        [--xml] [--extract-xml FILE] [--metadata]\n",
 [JOIN] = 
-"    imagex join [--check] --output WIMFILE SPLIT_WIM...\n",
+"    imagex join [--check] WIMFILE SPLIT_WIM...\n",
 [MOUNT] = 
 "    imagex mount WIMFILE (IMAGE_NUM | IMAGE_NAME) DIRECTORY\n"
 "        [--check] [--debug]\n",
@@ -1004,16 +1004,13 @@ static int imagex_join(int argc, const char **argv)
        int flags = WIMLIB_OPEN_FLAG_SPLIT_OK | WIMLIB_OPEN_FLAG_SHOW_PROGRESS;
        int image;
        int ret;
-       const char *output_path = NULL;
+       const char *output_path;
 
        for_opt(c, join_options) {
                switch (c) {
                case 'c':
                        flags |= WIMLIB_OPEN_FLAG_CHECK_INTEGRITY;
                        break;
-               case 'o':
-                       output_path = optarg;
-                       break;
                default:
                        goto err;
                }
@@ -1021,16 +1018,13 @@ static int imagex_join(int argc, const char **argv)
        argc -= optind;
        argv += optind;
 
-       if (argc < 2) {
+       if (argc < 3) {
                imagex_error("Must specify at least two split WIM "
                                "(.swm) parts to join!\n");
                goto err;
        }
-       if (!output_path) {
-               imagex_error("Must specify output_path!\n");
-               goto err;
-       }
-       return wimlib_join(argv, argc, output_path, flags);
+       output_path = argv[0];
+       return wimlib_join(++argv, --argc, output_path, flags);
 err:
        usage(JOIN);
        return -1;
index c284dbc34802a8d33f0007074247b3329cf936cf..1bc239702f4b251675043352e0c35eebab4edc9c 100644 (file)
  *   WIM without security data, including a boot.wim for Windows PE, but <b>do
  *   not expect to be able to use wimlib to image a Windows installation and
  *   preserve file attributes</b>.
- * - There is no support for split WIMs, which have an image divided up between
- *   multiple WIM files.
+ * - There is no way to create split WIMs.
  * - There is not yet any code to verify that there are no collisions between
  *   different files that happen to have the same SHA1 message digest.
  *   This is extremely unlikely, but could result in something bad such as a
@@ -265,9 +264,7 @@ enum wim_compression_type {
 #define WIMLIB_OPEN_FLAG_SHOW_PROGRESS         0x2
 
 /** If this flag is not given, an error is issued if the WIM is part of a split
- * WIM.  Giving this flag makes the function allows split WIMS to be opened, but
- * beware: wimlib has little support for split WIMs and only certain functions
- * will work on them. */
+ * WIM.  */
 #define WIMLIB_OPEN_FLAG_SPLIT_OK              0x4
 
 /**
@@ -699,7 +696,20 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name);
  *     ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY to check the split WIMs' integrity
  *     tables (if present) when opening them, and include an integrity table in
  *     the output WIM.
- * @return 0 on success; nonzero on error.
+ *
+ * @return 0 on success; nonzero on error.  This function may return any value
+ * returned by wimlib_open_wim() except ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well
+ * as the following error codes:
+ *
+ * @retval ::WIMLIB_ERR_SPLIT_INVALID
+ *     The split WIMs do not form a valid WIM because they do not include all
+ *     the parts of the original WIM, there are duplicate parts, or not all the
+ *     parts have the same GUID and compression type.
+ * @retval ::WIMLIB_ERR_WRITE
+ *     An error occurred when trying to write data to to the new WIM at @a output_path.
+ *
+ * Note that this function merely copies the resources, so it will not check to
+ * see if the resources, including the metadata resource, are valid or not.
  */
 extern int wimlib_join(const char **swms, int num_swms,
                       const char *output_path, int flags);
@@ -771,7 +781,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  *     If ::WIMLIB_OPEN_FLAG_SHOW_PROGRESS is given, progress information will
  *     be shown if the integrity of the WIM is checked.
  *     If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the
- *     WIM is part of a split WIM.
+ *     WIM is part of a split WIM.  However, wimlib does not fully support
+ *     split WIMs, so not all functions will work correctly after opening a
+ *     split WIM.  For example, you cannot use wimlib_mount() or
+ *     wimlib_extract_image() on a split WIM.
  *
  * @param wim_ret
  *     On success, a pointer to an opaque ::WIMStruct for the opened WIM file
@@ -785,10 +798,10 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  *     added to wimlib if needed, but it appears to be the case that the lookup
  *     table is never compressed.
  * @retval ::WIMLIB_ERR_IMAGE_COUNT
- *     The number of metadata resources found in the WIM did not match the
- *     image count given in the WIM header, or the number of &lt;IMAGE&gt;
- *     elements in the XML data for the WIM did not match the image count given
- *     in the WIM header.
+ *     The WIM is not the non-first part of a split WIM, and the number of
+ *     metadata resources found in the WIM did not match the image count given
+ *     in the WIM header, or the number of &lt;IMAGE&gt; elements in the XML
+ *     data for the WIM did not match the image count given in the WIM header.
  * @retval ::WIMLIB_ERR_INTEGRITY
  *     ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a flags and @a
  *     wim_file contains an integrity table, but the SHA1 message digest for a
@@ -814,7 +827,7 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags);
  * @retval ::WIMLIB_ERR_READ
  *     An unexpected end-of-file or read error occurred when trying to read
  *     data from @a wim_file.
- * @retval ::WIMLIB_ERR_SPLIT
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  *     @a wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not
  *     givin in @a flags.
  * @retval ::WIMLIB_ERR_UNKNOWN_VERSION
@@ -1292,6 +1305,9 @@ extern int wimlib_unmount(const char *dir, int flags);
  *     with @a wim, or some file resources in @a wim refer to files in the
  *     outside filesystem, and a read error occurred when reading one of these
  *     files.
+ * @retval ::WIMLIB_ERR_WRITE
+ *     An error occurred when trying to write data to the new WIM file at @a
+ *     path.
  */
 extern int wimlib_write(WIMStruct *wim, const char *path, int image, int flags);