- * two ways to create such a structure: wimlib_open_wim(), which opens a WIM
- * file and creates a ::WIMStruct representing it, and wimlib_create_new_wim(),
- * which creates a new ::WIMStruct that initially contains no images and does
- * not yet have a backing on-disk file. See @ref G_creating_and_opening_wims
- * for more details.
- *
- * A WIM file, represented by a ::WIMStruct, contains zero or more images.
- * Images can be extracted (or "applied") using wimlib_extract_image(), added
- * (or "captured" or "appended") using wimlib_add_image(), deleted using
- * wimlib_delete_image(), exported using wimlib_export_image(), and updated or
- * modified using wimlib_update_image(). However, changes made to a WIM
- * represented by a ::WIMStruct have no persistent effect until the WIM is
- * actually written to an on-disk file. This can be done using wimlib_write(),
- * but if the WIM was originally opened using wimlib_open_wim(), then
- * wimlib_overwrite() can be used instead. See @ref G_extracting_wims, @ref
- * G_modifying_wims, and @ref G_writing_and_overwriting_wims for more details.
- *
- * Note that with this ::WIMStruct abstraction, performing many tasks on WIM
- * files is a multi-step process. For example, to add, or "append" an image to
- * an existing stand-alone WIM file in a way similar to <b>wimlib-imagex
- * append</b>, you must call the following functions:
+ * two ways to create such a structure:
+ *
+ * 1. wimlib_open_wim() opens an on-disk WIM file and creates a ::WIMStruct for
+ * it.
+ * 2. wimlib_create_new_wim() creates a new ::WIMStruct that initially contains
+ * no images and does not yet have a backing on-disk file.
+ *
+ * A ::WIMStruct contains zero or more independent directory trees called @a
+ * images. Images may be extracted, added, deleted, exported, and updated using
+ * various API functions. (See @ref G_extracting_wims and @ref G_modifying_wims
+ * for more details.)
+ *
+ * Changes made to a WIM represented by a ::WIMStruct have no persistent effect
+ * until the WIM is actually written to an on-disk file. This can be done using
+ * wimlib_write(), but if the WIM was originally opened using wimlib_open_wim(),
+ * then wimlib_overwrite() can be used instead. (See @ref
+ * G_writing_and_overwriting_wims for more details.)
+ *
+ * wimlib's API is designed to let you combine functions to accomplish tasks in
+ * a flexible way. Here are some example sequences of function calls:
+ *
+ * Apply an image from a WIM file, similar to the command-line program
+ * <b>wimapply</b>: