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

README.libcdio: revise for FreeBSD and other BSDs.

README.libcdio

@@ -2,7 +2,7 @@ See README.develop if you plan use the git or development version.
 
 0. To compile the source, you'll need a POSIX shell and utilities (sh,
 sed, grep, cat), an ANSI C compiler like gcc, and a POSIX "make"
-program like GNU make. You may also want to have "libtool" installed
+program like GNU make or remake. You may also want to have "libtool" installed
 for building portable shared libraries.
 
 1. Uncompress and unpack the source code using for example "tar". Recent
@@ -12,7 +12,7 @@ versions of GNU tar can do this in one step like this:
 2. Go into the directory, run "configure" followed by "make":
 
   cd libcdio-*
-  sh ./configure MAKE=make  # or gmake or remake
+  sh ./configure MAKE=make  # or remake or gmake
 
 3. If step 2 works, compile everything:
 
@@ -79,11 +79,12 @@ XBOX
 Consult the xboxmediacenter team (www.xboxmediacenter.de)
 
 
-BSD
+BSD, FreeBSD, NetBSD
 ---
 
 Unless you use --without-versioned-libs (not recommended), you need to
-use GNU make which usually can be found under the name "gmake".
+use GNU make or remake (http://bashdb.sf.net/remake). GNU make can be
+found under the name "gmake".
 
 If you use another make you are likely to get problems linking libcdio
 and libiso9660.

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
+The same program as @code{isolist.c} written in C++.
-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++.
 
 @item @code{isofuzzy.c}
 

example/isofile.c

@@ -1,6 +1,4 @@
 /*
-  $Id: isofile.c,v 1.2 2008/03/24 15:30:55 karl Exp $
-
   Copyright (C) 2004, 2005, 2006, 2008, 2009 Rocky Bernstein <rocky@gnu.org>
   
   This program is free software: you can redistribute it and/or modify