Write multisession/growing/modification info to the Tutorial.

COPYRIGHT

@@ -1,7 +1,7 @@
 Vreixo Formoso <metalpain2002@yahoo.es>,
 Mario Danic <mario.danic@gmail.com>, 
 Thomas Schmitt <scdbackup@gmx.net>
-Copyright (C) 2007 Vreixo Formoso, Mario Danic, Thomas Schmitt
+Copyright (C) 2007-2008 Vreixo Formoso, Mario Danic, Thomas Schmitt
 
 
     This program is free software; you can redistribute it and/or modify

doc/Tutorial

@@ -20,7 +20,10 @@ Contents:
    2.1 Image tree manipulation
    2.2 Set the write options
    2.3 Obtaining a burn_source
-3. Image growing and multisession
+3. Image growing and modification
+   3.1 Growing vs Modification
+   3.2 Image import
+   3.3 Generating a new image
 4. Bootable images
 5. Advanced features
 
@@ -337,3 +340,168 @@ You can get the state of the buffer in any moment, with the function:
 You can also cancel the writer thread at any time, with the cancel() function
 of the burn_source.
 
+
+-------------------------------------------------------------------------------
+3. Image growing and modification
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+3.1 Growing vs Modification
+
+Libisofs is not restricted only to create new images. It can also be used to
+modify existing images. It supports two kind of image modifications, that we
+have called image growing and image modification:
+
+Image modification consists in generating a new image, based on the contents
+of an existing image. In this mode, libisofs takes an image, the users modifies
+its contents (adding new files, removing files, changing their names...), and
+finally libisofs generates a completely new image.
+
+On the other side, image growing is similar, with the difference that the new
+image is dependent on the other, i.e., it refers to files of the other image.
+Thus, it can't be mounted without the old image. The purpose of this kind of
+images is to increment or add files to a multisession disc. The new image only
+contains the new files. Old files are just references to the old image blocks.
+
+The advantage of the growing approach is that the generated image is smaller,
+as only the new files are written. This mode is suitable when you just want to
+add some files to a very big image, or when dealing with write-once media, such
+as CD-R. Both the time and space needed for the modification is much less than
+with normal image modify.
+
+The main problem of growing is that the new image needs to be recorded together 
+with the old image, in order to be mountable. The total size of the image 
+(old + new) is bigger (even much bigger) than a completely new image. So, if 
+you plan to distribute an image on Internet, or burn it to a disc, generate a
+completely new image is usually a better alternative. 
+
+To be able to mount a grown image, the OS needs to now you have appended new 
+data to the original image. In multisession media (such as CD-R), the new data
+is appended as a new session, so the OS can identify this and mount the image
+propertly. However, when dealing with non-multisession media (such as DVD+RW)
+or plain .iso files, the new data is just appended at the end of the old image,
+and the OS has no way to know that the appended data is in fact a "new 
+session". The method introduced by Andy Polyakov in growisofs can be used in
+those cases. It consists in overwrite the volume descriptors of the old image
+with a new ones that refer to the newly appended contents.
+
+-------------------------------------------------------------------------------
+3.2 Image import
+
+The first thing you need to do in order to modify or grow an image is to import
+it, with the function:
+
+	iso_image_import()
+	
+It takes several arguments. 
+
+First, the image context, an IsoImage previously obtained with iso_image_new().
+In most cases you will want to use an empty image. However, if you have already
+added files to the image, they will be removed and replaced with the contents
+of the image being imported.
+
+The second parameter is an IsoDataSource instance. It abstracts the original 
+image, and it is used by libisofs to access its contents. You are free to 
+implement your own data source to access image contents. However, libisofs has
+a simple implementation suitable for reading images on the local filesystem,
+that can be used for import both .iso files and inserted media, via the block
+device and POSIX functions. You can get it with 
+
+	iso_data_source_new_from_file()
+	
+The third parameter of iso_image_import() is a pointer to an IsoReadOpts 
+struct. It holds the options for image reading. You get it with:
+
+	iso_read_opts_new()
+	
+and after calling iso_image_import() you should free it with
+
+	iso_read_opts_free()
+	
+Some options are related to select what extensions to read. Default options
+are suitable for most users.
+
+	iso_read_opts_set_no_rockridge()
+	iso_read_opts_set_no_joliet()
+	iso_read_opts_set_no_iso1999()
+	iso_read_opts_set_preferjoliet()
+	
+If RockRidge extensions are not present, many files attributes can't be 
+obtained. In those cases libisofs uses default values. You have options to
+configure what default values to use.
+
+	iso_read_opts_set_default_uid()
+	iso_read_opts_set_default_gid()
+	iso_read_opts_set_default_permissions()
+	
+If the original image has been created in another system with a different
+charset, you may want to use:
+
+	iso_read_opts_set_input_charset()
+	
+to specify the encoding of the file names on image.
+
+Finally, to import multisession images, you should tell libisofs that it must
+read the last session. For that, you must set the block where the last session
+starts:
+
+	iso_read_opts_set_start_block()
+
+The last parameter for iso_image_import(), optional, is a pointer that will
+be filled with a library-allocated IsoReadImageFeatures, that lets you access
+some information about the image: size, extensions used,...
+
+[TODO: explain that iso_image_import uses dir rec options]
+
+-------------------------------------------------------------------------------
+3.3 Generating a new image
+
+After importing the image, the old image tree gets loaded. You are free to 
+make any changes to it: add new files, remove files, change names or 
+attributes... Refer to "2.1 Image tree manipulation" for details.
+
+When it is ready, you can now create the new image. The process is the same as
+explained in "2.2 Set the write options" and "2.3 Obtaining a burn_source".
+However, there are some write options that should be taken into account.
+
+First of all, you must select whether you want to grow or modify the image 
+(read "3.1 Growing vs Modification" for details). You must call
+
+	iso_write_opts_set_appendable()
+	
+An appendable image leads to image growing, and a non-appendable image leads
+to a completelly new image (modification). An appendable image will be appended
+after the old image (in a new session, for example). Thus, in those cases, the 
+first block of the image is not 0. You should set the correct lba of the first
+block with:
+
+	iso_write_opts_set_ms_block()
+
+That is usually the "Next Writable Address" on a multisession media, and a 
+value slightly greater than the old image size on .iso files or DVD+RW media.
+You can obtain the old image size with the iso_read_image_features_get_size()
+function.
+
+In this last case (i.e., on a non multisession media), you will need to
+overwrite the volume descriptors of the old image with the new ones. To do 
+this you need:
+
+- Allocate a buffer of at least 64 KiBs.
+- Initialize it with the first 64 KiBs of the original image.
+- Pass the buffer to libisofs with the iso_write_opts_set_overwrite_buf()
+  option.
+- After appending the new image, you have to overwrite the first 64 KiBs of 
+  the original image with the new content of the buffer.
+
+
+-------------------------------------------------------------------------------
+4. Bootable images
+-------------------------------------------------------------------------------
+
+
+
+-------------------------------------------------------------------------------
+5. Advanced features
+-------------------------------------------------------------------------------
+
+