libcdio.texi: add information about the cdio/cdio_config.h and cdio_unconfig.hs header mess.

README.libcdio: revise for FreeBSD and other BSDs.

doc/libcdio.texi

@@ -1116,6 +1116,7 @@ Other sources for examples would be the larger utility programs
 @xref{Utility Programs}.
 
 @menu
+* Include problem::  A note about including <cdio/cdio.h>
 * Example 1::        list out tracks and LSNs
 * Example 2::        list drivers available and default CD device 
 * Example 3::        figure out what kind of CD (image) we've got
@@ -1126,6 +1127,77 @@ Other sources for examples would be the larger utility programs
 * All sample programs:: list of all programs in the example directory
 @end menu
 
+@node Include problem
+@section A note about including @code{<cdio/cdio.h>}
+
+libcdio installs @code{<cdio/cdio_config.h>}. This file contains all of
+the C Preprocessor values from @code{config.h} (created by configure).
+
+This header can be used to consult exactly how libcdio was built. Initially
+I had selected ``interesting'' values, but this became too hard to maintain.
+
+One set of values that libdio needs internally is the whether the CPU
+that was used to compile libcdio is BigEndian or not; it can get this
+from libcdio's @code{config.h} which is not installed and preferred or
+@code{cdio/cdio_config.h}.
+
+Some of the libcdio programs like the demo programs include
+@code{config.h} for the generic reasons that the configuration-created
+@code{config.h} file is used: to figure out what headers are available.
+For example, do we have @code{<unistd.h>}?
+
+The file @code{config.h} is generated by an autotools-generated
+@code{configure} script. It doesn't check to see if it has been included
+previously.
+
+Later, the demo programs include @code{<cdio.h>} to get libcdio headers.
+But because libcdio needs some of the same information like the BigEndian
+value, this creates a duplicate include.
+
+The way I get around this in the demo programs is by defining @code{__CDIO_CONFIG_H__} after
+including @code{config.h} as follows:
+
+@smallexample
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+# define __CDIO_CONFIG_H__ 1
+#endif
+@end smallexample
+
+Applications using libcdio may find it handy to do something like this as well.
+
+Defining @code{__CDIO_CONFIG_H__} will make sure @code{config_cdio.h}
+which is internally used,  doesn't try to redefine preprocessor symbols.
+
+Ok. But now what about the problem that there are common preprocessor
+symbols in @code{config_cdio.h} that an application may want to define in a
+different manner, like @code{PACKAGE_NAME}?
+
+For this, there is yet another header, @code{<cdio/cdio_unconfig.h>}.
+This file undefines any symbol that @code{config.h} defines. And now we
+bounce to the problem that there may be symbols that are normally
+defined (@code{HAVE_UNISTD_H}) and you want to keep that way, but others that
+you don't.  So here is what I suggest:
+
+@smallexample
+  // for cdio:
+  #include <cdio.h>
+  #include <cdio_unconfig.h> # remove *all* symbols libcdio defines
+
+  // Add back in the ones you want your program
+  #include <config.h>
+@end smallexample
+
+The solution isn't the most simple or natural, but programming sometimes can
+be difficult. If someone has a better solution, let me know.
+
+Between header files @code{cdio_config.h} and @code{cdio_unconfig.h} and
+all the fact that almost all headers@footnote{@code{<cdio_unconfig.h>} is
+one of the few headers that doesn't set a preprocessor symbol: it does
+its thing every time it is @code{#included}} define a symbol to indicate they
+have been included, I think there is enough mechanism to cover most
+situations that may arise.
+
 @node Example 1
 @section Example 1: list out tracks and LSNs
 Here we will give an annotated example which can be found in the
@@ -1445,7 +1517,7 @@ main(int argc, const char *argv[])
 
 Next a program to show using @command{libiso9660} to extract a file
 from an ISO-9660 image.  This can be found in the distribution as
-@file{example/iso3.c}. A more complete and expanded version of this
+@file{example/isofile.c}. A more complete and expanded version of this
 is @command{iso-read}, part of this distribution.
 
 @smallexample
@@ -1641,6 +1713,7 @@ This can be found in the distribution as @file{example/mmc1.c}.
 @smallexample
 #ifdef HAVE_CONFIG_H
 # include "config.h"
+# define __CDIO_CONFIG_H__ 1 /* assumes config.h is libcdio's config.h /
 #endif
 #include <stdio.h>
 #include <sys/types.h>
@@ -1701,6 +1774,13 @@ main(int argc, const char *argv[])
 @}
 @end smallexample 
 
+Note the include of @code{#define} of @code{__CDIO_CONFIG_H__} towards
+the beginning.  This is useful if the prior @code{#include} of
+@code{config.h} refers to libcdio's configuration header. It indicates
+that libcdio's configuration settings have been used. Without it, you
+may get messages about C Preprocessor symbols getting redefined in the
+@code{#include} of @code{<cdio.cdio.h>}.
+
 @node Example 7
 @section Example 7: Using the CD Paranoia library for CD-DA reading
 
@@ -1708,9 +1788,12 @@ The below program reads CD-DA data. For a more complete program to add
 a WAV header so that the CD can be played from a copy on a hard disk,
 see the corresponding distribution program.
 
+This can be found in the distribution as @file{example/paranoia.c}.
+
 @smallexample
 #ifdef HAVE_CONFIG_H
 # include "config.h"
+# define __CDIO_CONFIG_H__ 1 /* assumes config.h is libcdio's config.h /
 #endif
 
 #include <cdio/cdda.h>
@@ -1841,10 +1924,18 @@ Descriptions of the sample are as follows...
 
 @table @code 
 
+@item @code{audio.c}
+
+A program to show audio controls.
+
 @item @code{cdchange.c}
 
 A program to test if a CD has been changed since the last change test.
 
+@item @code{cd-eject.c}
+
+A a stripped-down "eject" command to open or close a CD-ROM tray.
+
 @item @code{cdtext.c}
 
 A program to show CD-Text and CD disc mode info.
@@ -1858,6 +1949,22 @@ is and what CD drives are available.
 
 A program eject a CD from a CD-ROM drive and then close the door again.
 
+@item @code{isofile.c}
+
+A program to show using libiso9660 to extract a file from an ISO-9660 image.
+
+@item @code{isofile2.c}
+
+A program to show using libiso9660 to extract a file from a CDRWIN cue/bin CD image.
+
+@item @code{C++/isofile2.cpp}
+
+The same program as @code{isofile2.c} written in C++.
+
+@item @code{isofuzzy.c}
+
+A program showing fuzzy ISO-9660 detection/reading.
+
 @item @code{isolist.c}
 
 A program to show using @code{libiso9660} to list files in a
@@ -1867,23 +1974,9 @@ A program to show using @code{libiso9660} to list files in a
 
 The same program as @code{isolist.c} written in C++.
 
-@item @code{iso2.c}
+@item @code{C++/isolist.cpp}
 
-A program to show using @code{libiso9660} to extract a file from a
-CDRWIN cue/bin CD image.
-
-@item @code{C++/iso2.cpp}
-
-The same program as @code{iso2.c} written in C++.
-
-@item @code{iso3.c}
-
-A program to show using libiso9660 to extract a file from an ISO-9660
-image.
-
-@item @code{C++/iso3.cpp}
-
-The same program as @code{iso3.c} written in C++.
+The same program as @code{isolist.c} written in C++.
 
 @item @code{isofuzzy.c}