From fcaa0f32bc29135d8f5a8986a61dd5d1ea50545b Mon Sep 17 00:00:00 2001
From: Vreixo Formoso <metalpain2002@yahoo.es>
Date: Sun, 27 Jan 2008 23:50:44 +0100
Subject: [PATCH] Little documentation improves.

---
 doc/Tutorial        | 71 ++++++++++++++++++++++++++++++++++++++++++---
 libisofs/libisofs.h | 13 +++++++--
 2 files changed, 78 insertions(+), 6 deletions(-)

diff --git a/doc/Tutorial b/doc/Tutorial
index b54d168..ba74df2 100644
--- a/doc/Tutorial
+++ b/doc/Tutorial
@@ -14,7 +14,8 @@ Contents:
 
 1. Introduction
    1.1 Library initialization
-   1.2 Error reporting
+   1.2 Image context
+   1.3 Error reporting
 2. Creating an image
    2.1 Image context
    2.2 Image tree manipulation
@@ -26,10 +27,72 @@ Contents:
 
 -------------------------------------------------------------------------------
 1. Introduction
+-------------------------------------------------------------------------------
 
 
-1.1. Library initialization  --------------------------------------------------
-
-
+-------------------------------------------------------------------------------
+1.1. Library initialization
+
+Before any usage of the library, you have to call
+
+	iso_init()
+
+in the same way, when you have finished using the library, you should call
+
+	iso_finish()
+
+to free all resources reserved by the library.
+
+-------------------------------------------------------------------------------
+1.2. Image context
+
+Libisofs is image-oriented, the core of libisofs usage is the IsoImage object.
+Thus, the first you need to do is to get your own IsoImage object:
+
+	IsoImage *my_image;
+	iso_image_new("NEW DISC", &my_image);
+
+An IsoImage is a context for image creation. It holds the files than will be 
+added to image, other related information and several options to customize
+the behavior of libisofs when working with such Image. i.e., an IsoImage is
+a context for libisofs operations. As such, you can work with several image
+contexts at a time. 
+
+-------------------------------------------------------------------------------
+1.3. Error reporting
+
+In libisofs error reporting is done in two ways: with the return value of
+the functions and with the message queue. 
+
+Error codes are negative numbers, defined in private header "error.h". An
+error code is associated with a given severity, either "DEBUG", "UPDATE",
+"NOTE", "HINT", "WARNING", "SORRY", "FAILURE" and "FATAL". For the meaning
+of each severity take a look at private header "libiso_msgs.h". Errors 
+reported by function return value are always "FAILURE" or "FATAL". Other kind
+of errors are only reported with the message queue.
+
+First of all, most libisofs functions return an integer. If such integer is 
+a negative number, it means the function has returned an error. The error code
+and its severity is encoded in the return value (take a look at error.h private
+header).
+
+Additionally, libisofs reports most of its errors in a message queue. Error
+messages on that queue can be printed directly to stderr or programmatically
+retrieved. First of all, you should set the severity threshold over which an
+error is printed or enqueued, with function:
+
+	iso_set_msgs_severities()
+
+Errors enqueued can be retrieved with function:
+
+	iso_obtain_msgs()
+	
+Together with the code error, a text message and its severity, this function
+also returns the image id. This is an identifier that uniquely identifies a
+given image context. You can get the identifier of each IsoImage with the
+
+	iso_image_get_msg_id()
+
+and that way distinguish what image has issued the message.
 
 
diff --git a/libisofs/libisofs.h b/libisofs/libisofs.h
index 30e8939..868f7c8 100644
--- a/libisofs/libisofs.h
+++ b/libisofs/libisofs.h
@@ -13,6 +13,10 @@
 
 struct burn_source;
 
+/**
+ * Context for image creation. It holds the files that will be added to image,
+ * and several options to control libisofs behavior.
+ */
 typedef struct Iso_Image IsoImage;
 
 typedef struct Iso_Node IsoNode;
@@ -74,7 +78,8 @@ enum eltorito_boot_media_type {
 
 /**
  * Replace mode used when addding a node to a file.
- * TODO comment
+ * This controls how libisofs will act when you tried to add to a dir a file
+ * with the same name that an existing file.
  */
 enum iso_replace_mode {
     /**
@@ -1797,10 +1802,14 @@ int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path,
 /**
  * Add the contents of a dir to a given directory of the iso tree.
  * 
+ * There are several options to control what files are added or how they are
+ * managed. Take a look at iso_tree_set_* functions to see diferent options
+ * for recursive directory addition.
+ * 
  * TODO comment Builder and Filesystem related issues when exposing both
  * 
  * @param image
- *      TODO expose dir rec options and explain that here
+ *      The image to which the directory belong.
  * @param parent
  *      Directory on the image tree where to add the contents of the dir
  * @param dir