Added compilation check macros as proposed by Thomas.

libisofs/libisofs.h

@@ -8,6 +8,55 @@
 #ifndef LIBISO_LIBISOFS_H_
 #define LIBISO_LIBISOFS_H_
 
+/** 
+ * These three release version numbers tell the revision of this header file
+ * and of the API it describes. They are memorized by applications at compile 
+ * time.
+ * 
+ * Before usage on your code, please read the usage discussion below.
+ */
+#define libisofs_header_version_major  0
+#define libisofs_header_version_minor  6
+#define libisofs_header_version_micro  1
+
+/** 
+ * Usage discussion:
+ * 
+ * Some developers of the libburnia project have differing opinions how to 
+ * ensure the compatibility of libaries and applications.
+ * 
+ * It is about whether to use at compile time and at runtime the version 
+ * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso 
+ * advises to use other means.
+ * 
+ * At compile time:
+ * 
+ * Vreixo Formoso advises to leave proper version matching to properly 
+ * programmed checks in the the application's build system, which will 
+ * eventually refuse compilation.
+ * 
+ * Thomas Schmitt advises to use the macros defined here for comparison with 
+ * the application's requirements of library revisions and to eventually 
+ * break compilation.
+ * 
+ * Both advises are combinable. I.e. be master of your build system and have 
+ * #if checks in the source code of your application, nevertheless.
+ * 
+ * At runtime (via iso_lib_is_compatible()):
+ * 
+ * Vreixo Formoso advises to compare the application's requirements of 
+ * library revisions with the runtime library. This is to allow runtime 
+ * libraries which are young enough for the application but too old for
+ * the lib*.h files seen at compile time.
+ * 
+ * Thomas Schmitt advises to compare the header revisions defined here with 
+ * the runtime library. This is to enforce a strictly monotonous chain of 
+ * revisions from app to header to library, at the cost of excluding some older
+ * libraries.
+ * 
+ * These two advises are mutually exclusive.
+ */
+
 #include <sys/stat.h>
 #include <stdint.h>
 
@@ -141,7 +190,8 @@ typedef struct iso_data_source IsoDataSource;
  * it with regular .iso images, and also with block devices that represent a 
  * drive.
  */
-struct iso_data_source {
+struct iso_data_source
+{
 
     /* reserved for future usage, set to 0 */
     int version;
@@ -1016,8 +1066,7 @@ int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset);
  * @return
  *     1 on success, < 0 on error
  */
-int iso_image_import(IsoImage *image, IsoDataSource *src,
-                     IsoReadOpts *opts, 
+int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts,
                      struct iso_read_image_features **features);
 
 /**
@@ -1211,7 +1260,8 @@ const char *iso_image_get_biblio_file_id(const IsoImage *image);
  * @return 
  *      1 on success, < 0 on error
  */
-int iso_image_set_boot_image(IsoImage *image, const char *image_path,
+int
+        iso_image_set_boot_image(IsoImage *image, const char *image_path,
                                  enum eltorito_boot_media_type type,
                                  const char *catalog_path,
                                  ElToritoBootImage **boot);
@@ -1447,7 +1497,8 @@ void iso_node_set_hidden(IsoNode *node, int hide_attrs);
  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
  *         ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1)
  */
-int iso_dir_add_node(IsoDir *dir, IsoNode *child, 
+int
+        iso_dir_add_node(IsoDir *dir, IsoNode *child,
                          enum iso_replace_mode replace);
 
 /**
@@ -1886,8 +1937,7 @@ int iso_tree_remove_exclude(IsoImage *image, const char *path);
  *      continue, < 0 to abort the process
  *      NULL is allowed if you don't want any callback.
  */
-void iso_tree_set_report_callback(IsoImage *image, 
-                                  int (*report)(IsoImage*, IsoFileSource*));
+void iso_tree_set_report_callback(IsoImage *image, int (*report)(IsoImage*, IsoFileSource*));
 
 /**
  * Add a new node to the image tree, from an existing file. 
@@ -2297,8 +2347,8 @@ void iso_filesystem_unref(IsoFilesystem *fs);
  * @param
  *      1 on success, < 0 on error
  */
-int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts,
-                             int msgid, IsoImageFilesystem **fs);
+int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid,
+                             IsoImageFilesystem **fs);
 
 /**
  * Get the volset identifier for an existent image. The returned string belong