First commit after CVS conversion. Should be just administrative changes.

8 files changed, 4695 insertions, 0 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..a07183bf
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,7 @@
+/Makefile
+/Makefile.in
+/libcdio.info
+/mdate-sh
+/stamp-vti
+/texinfo.tex
+/version.texi
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 00000000..f8e72e86
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,46 @@
+#   $Id: Makefile.am,v 1.9 2008/04/17 17:39:47 karl Exp $
+#
+#   Copyright (C) 2003, 2004, 2008 Rocky Bernstein <rocky@gnu.org>
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+EXTRA_DIST = doxygen/Doxyfile.in doxygen/run_doxygen
+info_TEXINFOS = libcdio.texi 
+libcdio_TEXINFOS = fdl.texi glossary.texi
+
+reference:
+	-( cd ${top_srcdir} && $(MAKE) doxygen )
+
+pdf: libcdio.pdf 
+
+txt: libcdio.txt
+
+ps: libcdio.ps
+
+html: libcdio.html
+
+%.ps.gz: %.ps
+	gzip -9c $< > $@
+
+.texi.pdf:
+	texi2pdf $<
+
+.texi.html:
+	texi2html $<
+
+.texi.txt:
+	makeinfo --no-headers $< > $@
+
+all-formats: pdf dvi txt ps html
+
+MOSTLYCLEANFILES = libcdio.html libcdio.pdf libcdio.ps.gz
diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore
new file mode 100644
index 00000000..eeb3b95d
--- /dev/null
+++ b/doc/doxygen/.gitignore
@@ -0,0 +1 @@
+/Doxyfile
diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
new file mode 100644
index 00000000..868137ee
--- /dev/null
+++ b/doc/doxygen/Doxyfile.in
@@ -0,0 +1,1302 @@
+# Doxyfile 1.5.3
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+#       TAG = value [value, ...]
+# For lists items can also be appended using:
+#       TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the config file that 
+# follow. The default is UTF-8 which is also the encoding used for all text before 
+# the first occurrence of this tag. Doxygen uses libiconv (or the iconv built into 
+# libc) for the transcoding. See http://www.gnu.org/software/libiconv for the list of 
+# possible encodings.
+
+DOXYFILE_ENCODING      = UTF-8
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
+# by quotes) that should identify the project.
+
+PROJECT_NAME           = @PACKAGE@
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number. 
+# This could be handy for archiving the generated documentation or 
+# if some version control system is used.
+
+PROJECT_NUMBER         = @VERSION@
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
+# base path where the generated documentation will be put. 
+# If a relative path is entered, it will be relative to the location 
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY       = 
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
+# 4096 sub-directories (in 2 levels) under the output directory of each output 
+# format and will distribute the generated files over these directories. 
+# Enabling this option can be useful when feeding doxygen a huge amount of 
+# source files, where putting all generated files in the same directory would 
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS         = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all 
+# documentation generated by doxygen is written. Doxygen will use this 
+# information to generate all constant output in the proper language. 
+# The default language is English, other supported languages are: 
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, 
+# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, 
+# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, 
+# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, 
+# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
+
+OUTPUT_LANGUAGE        = English
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will 
+# include brief member descriptions after the members that are listed in 
+# the file and class documentation (similar to JavaDoc). 
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC      = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend 
+# the brief description of a member or function before the detailed description. 
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the 
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF           = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator 
+# that is used to form the text in various listings. Each string 
+# in this list, if found as the leading text of the brief description, will be 
+# stripped from the text and the result after processing the whole list, is 
+# used as the annotated text. Otherwise, the brief description is used as-is. 
+# If left blank, the following values are used ("$name" is automatically 
+# replaced with the name of the entity): "The $name class" "The $name widget" 
+# "The $name file" "is" "provides" "specifies" "contains" 
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF       = "The $name class " \
+                         "The $name widget " \
+                         "The $name file " \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then 
+# Doxygen will generate a detailed section even if there is only a brief 
+# description.
+
+ALWAYS_DETAILED_SEC    = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all 
+# inherited members of a class in the documentation of that class as if those 
+# members were ordinary class members. Constructors, destructors and assignment 
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB  = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full 
+# path before files name in the file list and in the header files. If set 
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES        = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag 
+# can be used to strip a user-defined part of the path. Stripping is 
+# only done if one of the specified strings matches the left-hand part of 
+# the path. The tag can be used to show relative paths in the file list. 
+# If left blank the directory from which doxygen is run is used as the 
+# path to strip.
+
+STRIP_FROM_PATH        = @LIBCDIO_SOURCE_PATH@
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
+# the path mentioned in the documentation of a class, which tells 
+# the reader which header file to include in order to use a class. 
+# If left blank only the name of the header file containing the class 
+# definition is used. Otherwise one should specify the include paths that 
+# are normally passed to the compiler using the -I flag.
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
+# (but less readable) file names. This can be useful is your file systems 
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES            = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen 
+# will interpret the first line (until the first dot) of a JavaDoc-style 
+# comment as the brief description. If set to NO, the JavaDoc 
+# comments will behave just like regular Qt-style comments 
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF      = NO
+
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will 
+# interpret the first line (until the first dot) of a Qt-style 
+# comment as the brief description. If set to NO, the comments 
+# will behave just like regular Qt-style comments (thus requiring 
+# an explicit \brief command for a brief description.)
+
+QT_AUTOBRIEF           = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen 
+# treat a multi-line C++ special comment block (i.e. a block of //! or /// 
+# comments) as a brief description. This used to be the default behaviour. 
+# The new default is to treat a multi-line C++ comment block as a detailed 
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen 
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member 
+# documentation.
+
+DETAILS_AT_TOP         = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented 
+# member inherits the documentation from any documented member that it 
+# re-implements.
+
+INHERIT_DOCS           = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce 
+# a new page for each member. If set to NO, the documentation of a member will 
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES  = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab. 
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE               = 8
+
+# This tag can be used to specify a number of aliases that acts 
+# as commands in the documentation. An alias has the form "name=value". 
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to 
+# put the command \sideeffect (or @sideeffect) in the documentation, which 
+# will result in a user-defined paragraph with heading "Side Effects:". 
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES                = 
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C 
+# sources only. Doxygen will then generate output that is more tailored for C. 
+# For instance, some of the names that are used will be different. The list 
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java 
+# sources only. Doxygen will then generate output that is more tailored for Java. 
+# For instance, namespaces will be presented as packages, qualified scopes 
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA   = NO
+
+# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to 
+# include (a tag file for) the STL sources as input, then you should 
+# set this tag to YES in order to let doxygen match functions declarations and 
+# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. 
+# func(std::string) {}). This also make the inheritance and collaboration 
+# diagrams that involve STL classes more complete and accurate.
+
+BUILTIN_STL_SUPPORT    = NO
+
+# If you use Microsoft's C++/CLI language, you should set this option to YES to
+# enable parsing support.
+
+CPP_CLI_SUPPORT        = NO
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC 
+# tag is set to YES, then doxygen will reuse the documentation of the first 
+# member in the group (if any) for the other members of the group. By default 
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC   = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of 
+# the same type (for instance a group of public functions) to be put as a 
+# subgroup of that type (e.g. under the Public Functions section). Set it to 
+# NO to prevent subgrouping. Alternatively, this can be done per class using 
+# the \nosubgrouping command.
+
+SUBGROUPING            = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in 
+# documentation are documented, even if no documentation was available. 
+# Private class members and static file members will be hidden unless 
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL            = YES
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
+# will be included in the documentation.
+
+EXTRACT_PRIVATE        = YES
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file 
+# will be included in the documentation.
+
+EXTRACT_STATIC         = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) 
+# defined locally in source files will be included in the documentation. 
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES  = YES
+
+# This flag is only useful for Objective-C code. When set to YES local 
+# methods, which are defined in the implementation section but not in 
+# the interface are included in the documentation. 
+# If set to NO (the default) only methods in the interface are included.
+
+EXTRACT_LOCAL_METHODS  = NO
+
+# If this flag is set to YES, the members of anonymous namespaces will be extracted 
+# and appear in the documentation as a namespace called 'anonymous_namespace{file}', 
+# where file will be replaced with the base name of the file that contains the anonymous 
+# namespace. By default anonymous namespace are hidden.
+
+EXTRACT_ANON_NSPACES   = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all 
+# undocumented members of documented classes, files or namespaces. 
+# If set to NO (the default) these members will be included in the 
+# various overviews, but no documentation section is generated. 
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS     = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all 
+# undocumented classes that are normally visible in the class hierarchy. 
+# If set to NO (the default) these classes will be included in the various 
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES     = NO
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all 
+# friend (class|struct|union) declarations. 
+# If set to NO (the default) these declarations will be included in the 
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS  = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any 
+# documentation blocks found inside the body of a function. 
+# If set to NO (the default) these blocks will be appended to the 
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS      = NO
+
+# The INTERNAL_DOCS tag determines if documentation 
+# that is typed after a \internal command is included. If the tag is set 
+# to NO (the default) then the documentation will be excluded. 
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS          = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate 
+# file names in lower-case letters. If set to YES upper-case letters are also 
+# allowed. This is useful if you have classes or files whose names only differ 
+# in case and if your file system supports case sensitive file names. Windows 
+# and Mac users are advised to set this option to NO.
+
+CASE_SENSE_NAMES       = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen 
+# will show members with their full class and namespace scopes in the 
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES       = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen 
+# will put a list of the files that are included by a file in the documentation 
+# of that file.
+
+SHOW_INCLUDE_FILES     = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] 
+# is inserted in the documentation for inline members.
+
+INLINE_INFO            = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen 
+# will sort the (detailed) documentation of file and class members 
+# alphabetically by member name. If set to NO the members will appear in 
+# declaration order.
+
+SORT_MEMBER_DOCS       = YES
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the 
+# brief documentation of file, namespace and class members alphabetically 
+# by member name. If set to NO (the default) the members will appear in 
+# declaration order.
+
+SORT_BRIEF_DOCS        = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be 
+# sorted by fully-qualified names, including namespaces. If set to 
+# NO (the default), the class list will be sorted only by class name, 
+# not including the namespace part. 
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the 
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME     = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or 
+# disable (NO) the todo list. This list is created by putting \todo 
+# commands in the documentation.
+
+GENERATE_TODOLIST      = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or 
+# disable (NO) the test list. This list is created by putting \test 
+# commands in the documentation.
+
+GENERATE_TESTLIST      = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or 
+# disable (NO) the bug list. This list is created by putting \bug 
+# commands in the documentation.
+
+GENERATE_BUGLIST       = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or 
+# disable (NO) the deprecated list. This list is created by putting 
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional 
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS       = 
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines 
+# the initial value of a variable or define consists of for it to appear in 
+# the documentation. If the initializer consists of more lines than specified 
+# here it will be hidden. Use a value of 0 to hide initializers completely. 
+# The appearance of the initializer of individual variables and defines in the 
+# documentation can be controlled using \showinitializer or \hideinitializer 
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES  = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated 
+# at the bottom of the documentation of classes and structs. If set to YES the 
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES        = YES
+
+# If the sources in your project are distributed over multiple directories 
+# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy 
+# in the documentation. The default is NO.
+
+SHOW_DIRECTORIES       = NO
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that 
+# doxygen should invoke to get the current version for each file (typically from the 
+# version control system). Doxygen will invoke the program by executing (via 
+# popen()) the command <command> <input-file>, where <command> is the value of 
+# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file 
+# provided by doxygen. Whatever the program writes to standard output 
+# is used as the file version. See the manual for examples.
+
+FILE_VERSION_FILTER    = 
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated 
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET                  = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are 
+# generated by doxygen. Possible values are YES and NO. If left blank 
+# NO is used.
+
+WARNINGS               = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings 
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will 
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED   = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for 
+# potential errors in the documentation, such as not documenting some 
+# parameters in a documented function, or documenting parameters that 
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR      = YES
+
+# This WARN_NO_PARAMDOC option can be abled to get warnings for 
+# functions that are documented, but have no documentation for their parameters 
+# or return value. If set to NO (the default) doxygen will only warn about 
+# wrong or incomplete parameter documentation, but not about the absence of 
+# documentation.
+
+WARN_NO_PARAMDOC       = NO
+
+# The WARN_FORMAT tag determines the format of the warning messages that 
+# doxygen can produce. The string should contain the $file, $line, and $text 
+# tags, which will be replaced by the file and line number from which the 
+# warning originated and the warning text. Optionally the format may contain 
+# $version, which will be replaced by the version of the file (if it could 
+# be obtained via FILE_VERSION_FILTER)
+
+WARN_FORMAT            = "$file:$line: $text "
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning 
+# and error messages should be written. If left blank the output is written 
+# to stderr.
+
+WARN_LOGFILE           = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain 
+# documented source files. You may enter file names like "myfile.cpp" or 
+# directories like "/usr/src/myproject". Separate the files or directories 
+# with spaces.
+
+INPUT                  = ../../include/cdio/
+
+# This tag can be used to specify the character encoding of the source files that 
+# doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
+# input encoding. Doxygen uses libiconv (or the iconv built into libc) for the transcoding. 
+# See http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+INPUT_ENCODING         = UTF-8
+
+# If the value of the INPUT tag contains directories, you can use the 
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
+# and *.h) to filter out the source-files in the directories. If left 
+# blank the following patterns are tested: 
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx 
+# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
+
+FILE_PATTERNS          = *.h
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories 
+# should be searched for input files as well. Possible values are YES and NO. 
+# If left blank NO is used.
+
+RECURSIVE              = NO
+
+# The EXCLUDE tag can be used to specify files and/or directories that should 
+# excluded from the INPUT source files. This way you can easily exclude a 
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE                = 
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
+# directories that are symbolic links (a Unix filesystem feature) are excluded 
+# from the input.
+
+EXCLUDE_SYMLINKS       = NO
+
+# If the value of the INPUT tag contains directories, you can use the 
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude 
+# certain files from those directories. Note that the wildcards are matched 
+# against the file with absolute path, so to exclude all test directories 
+# for example use the pattern */test/*
+
+EXCLUDE_PATTERNS       = 
+
+# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names 
+# (namespaces, classes, functions, etc.) that should be excluded from the output. 
+# The symbol name can be a fully qualified name, a word, or if the wildcard * is used, 
+# a substring. Examples: ANamespace, AClass, AClass::ANamespace, ANamespace::*Test
+
+EXCLUDE_SYMBOLS        = 
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or 
+# directories that contain example code fragments that are included (see 
+# the \include command).
+
+EXAMPLE_PATH           = ../../example
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the 
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
+# and *.h) to filter out the source-files in the directories. If left 
+# blank all files are included.
+
+EXAMPLE_PATTERNS       = 
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be 
+# searched for input files to be used with the \include or \dontinclude 
+# commands irrespective of the value of the RECURSIVE tag. 
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE      = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or 
+# directories that contain image that are included in the documentation (see 
+# the \image command).
+
+IMAGE_PATH             = 
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should 
+# invoke to filter for each input file. Doxygen will invoke the filter program 
+# by executing (via popen()) the command <filter> <input-file>, where <filter> 
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an 
+# input file. Doxygen will then use the output that the filter program writes 
+# to standard output.  If FILTER_PATTERNS is specified, this tag will be 
+# ignored.
+
+INPUT_FILTER           = 
+
+# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern 
+# basis.  Doxygen will compare the file name with each pattern and apply the 
+# filter if there is a match.  The filters are a list of the form: 
+# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further 
+# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER 
+# is applied to all files.
+
+FILTER_PATTERNS        = 
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using 
+# INPUT_FILTER) will be used to filter the input files when producing source 
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES    = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will 
+# be generated. Documented entities will be cross-referenced with these sources. 
+# Note: To get rid of all source code in the generated output, make sure also 
+# VERBATIM_HEADERS is set to NO. If you have enabled CALL_GRAPH or CALLER_GRAPH 
+# then you must also enable this option. If you don't then doxygen will produce 
+# a warning and turn it on anyway
+
+SOURCE_BROWSER         = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body 
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES         = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct 
+# doxygen to hide any special comment blocks from generated source code 
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS    = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default) 
+# then for each documented function all documented 
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default) 
+# then for each documented function all documented entities 
+# called/used by that function will be listed.
+
+REFERENCES_RELATION    = YES
+
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code.  Otherwise they will link to the documentstion.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code 
+# will point to the HTML generated by the htags(1) tool instead of doxygen 
+# built-in source browser. The htags tool is part of GNU's global source 
+# tagging system (see http://www.gnu.org/software/global/global.html). You 
+# will need version 4.8.6 or higher.
+
+USE_HTAGS              = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen 
+# will generate a verbatim copy of the header file for each class for 
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS       = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index 
+# of all compounds will be generated. Enable this if the project 
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX     = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then 
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns 
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX    = 5
+
+# In case all classes in a project start with a common prefix, all 
+# classes will be put under the same header in the alphabetical index. 
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that 
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX          = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will 
+# generate HTML output.
+
+GENERATE_HTML          = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. 
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT            = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for 
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank 
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION    = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for 
+# each generated HTML page. If it is left blank doxygen will generate a 
+# standard header.
+
+HTML_HEADER            = 
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for 
+# each generated HTML page. If it is left blank doxygen will generate a 
+# standard footer.
+
+HTML_FOOTER            = 
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading 
+# style sheet that is used by each HTML page. It can be used to 
+# fine-tune the look of the HTML output. If the tag is left blank doxygen 
+# will generate a default style sheet. Note that doxygen will try to copy 
+# the style sheet file to the HTML output directory, so don't put your own 
+# stylesheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET        = 
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, 
+# files or namespaces will be aligned in HTML using tables. If set to 
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS     = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files 
+# will be generated that can be used as input for tools like the 
+# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) 
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP      = NO
+
+# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML 
+# documentation will contain sections that can be hidden and shown after the 
+# page has loaded. For this to work a browser that supports 
+# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox 
+# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+
+HTML_DYNAMIC_SECTIONS  = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can 
+# be used to specify the file name of the resulting .chm file. You 
+# can add a path in front of the file if the result should not be 
+# written to the html output directory.
+
+CHM_FILE               = 
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can 
+# be used to specify the location (absolute path including file name) of 
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run 
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION           = 
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag 
+# controls if a separate .chi index file is generated (YES) or that 
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI           = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag 
+# controls whether a binary table of contents is generated (YES) or a 
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC             = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members 
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND             = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at 
+# top of each HTML page. The value NO (the default) enables the index and 
+# the value YES disables it.
+
+DISABLE_INDEX          = NO
+
+# This tag can be used to set the number of enum values (range [1..20]) 
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE   = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that 
+# is generated for HTML Help). For this to work a browser that supports 
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, 
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are 
+# probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW      = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 
+# used to set the initial width (in pixels) of the frame in which the tree 
+# is shown.
+
+TREEVIEW_WIDTH         = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will 
+# generate Latex output.
+
+GENERATE_LATEX         = YES
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. 
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT           = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be 
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME         = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to 
+# generate index for LaTeX. If left blank `makeindex' will be used as the 
+# default command name.
+
+MAKEINDEX_CMD_NAME     = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact 
+# LaTeX documents. This may be useful for small projects and may help to 
+# save some trees in general.
+
+COMPACT_LATEX          = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used 
+# by the printer. Possible values are: a4, a4wide, letter, legal and 
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE             = letter
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX 
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES         = 
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for 
+# the generated latex document. The header should contain everything until 
+# the first chapter. If it is left blank doxygen will generate a 
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER           = 
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated 
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will 
+# contain links (just like the HTML output) instead of page references 
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS         = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of 
+# plain latex in the generated Makefile. Set this option to YES to get a 
+# higher quality PDF documentation.
+
+USE_PDFLATEX           = NO
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. 
+# command to the generated LaTeX files. This will instruct LaTeX to keep 
+# running if errors occur, instead of asking the user for help. 
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE        = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not 
+# include the index chapters (such as File Index, Compound Index, etc.) 
+# in the output.
+
+LATEX_HIDE_INDICES     = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output 
+# The RTF output is optimized for Word 97 and may not look very pretty with 
+# other RTF readers or editors.
+
+GENERATE_RTF           = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. 
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT             = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact 
+# RTF documents. This may be useful for small projects and may help to 
+# save some trees in general.
+
+COMPACT_RTF            = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated 
+# will contain hyperlink fields. The RTF file will 
+# contain links (just like the HTML output) instead of page references. 
+# This makes the output suitable for online browsing using WORD or other 
+# programs which support those fields. 
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS         = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's 
+# config file, i.e. a series of assignments. You only have to provide 
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE    = 
+
+# Set optional variables used in the generation of an rtf document. 
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE    = 
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will 
+# generate man pages
+
+GENERATE_MAN           = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put. 
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT             = man
+
+# The MAN_EXTENSION tag determines the extension that is added to 
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION          = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output, 
+# then it will generate one additional man file for each entity 
+# documented in the real man page(s). These additional files 
+# only source the real man page, but without them the man command 
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS              = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will 
+# generate an XML file that captures the structure of 
+# the code including all documentation.
+
+GENERATE_XML           = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put. 
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT             = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema, 
+# which can be used by a validating XML parser to check the 
+# syntax of the XML files.
+
+XML_SCHEMA             = 
+
+# The XML_DTD tag can be used to specify an XML DTD, 
+# which can be used by a validating XML parser to check the 
+# syntax of the XML files.
+
+XML_DTD                = 
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will 
+# dump the program listings (including syntax highlighting 
+# and cross-referencing information) to the XML output. Note that 
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will 
+# generate an AutoGen Definitions (see autogen.sf.net) file 
+# that captures the structure of the code including all 
+# documentation. Note that this feature is still experimental 
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF   = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will 
+# generate a Perl module file that captures the structure of 
+# the code including all documentation. Note that this 
+# feature is still experimental and incomplete at the 
+# moment.
+
+GENERATE_PERLMOD       = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate 
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able 
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX          = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be 
+# nicely formatted so it can be parsed by a human reader.  This is useful 
+# if you want to understand what is going on.  On the other hand, if this 
+# tag is set to NO the size of the Perl module output will be much smaller 
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY         = YES
+
+# The names of the make variables in the generated doxyrules.make file 
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. 
+# This is useful so different doxyrules.make files included by the same 
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will 
+# evaluate all C-preprocessor directives found in the sources and include 
+# files.
+
+ENABLE_PREPROCESSING   = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro 
+# names in the source code. If set to NO (the default) only conditional 
+# compilation will be performed. Macro expansion can be done in a controlled 
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION        = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
+# then the macro expansion is limited to the macros specified with the 
+# PREDEFINED and EXPAND_AS_DEFINED tags.
+
+EXPAND_ONLY_PREDEF     = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that 
+# contain include files that are not input files but should be processed by 
+# the preprocessor.
+
+INCLUDE_PATH           = 
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard 
+# patterns (like *.h and *.hpp) to filter out the header-files in the 
+# directories. If left blank, the patterns specified with FILE_PATTERNS will 
+# be used.
+
+INCLUDE_FILE_PATTERNS  = 
+
+# The PREDEFINED tag can be used to specify one or more macro names that 
+# are defined before the preprocessor is started (similar to the -D option of 
+# gcc). The argument of the tag is a list of macros of the form: name 
+# or name=definition (no spaces). If the definition and the = are 
+# omitted =1 is assumed. To prevent a macro definition from being 
+# undefined via #undef or recursively expanded use the := operator 
+# instead of the = operator.
+
+PREDEFINED             = 
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
+# this tag can be used to specify a list of macro names that should be expanded. 
+# The macro definition that is found in the sources will be used. 
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED      = 
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then 
+# doxygen's preprocessor will remove all function-like macros that are alone 
+# on a line, have an all uppercase name, and do not end with a semicolon. Such 
+# function macros are typically used for boiler-plate code, and will confuse 
+# the parser if not removed.
+
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles. 
+# Optionally an initial location of the external documentation 
+# can be added for each tagfile. The format of a tag file without 
+# this location is as follows: 
+#   TAGFILES = file1 file2 ... 
+# Adding location for the tag files is done as follows: 
+#   TAGFILES = file1=loc1 "file2 = loc2" ... 
+# where "loc1" and "loc2" can be relative or absolute paths or 
+# URLs. If a location is present for each tag, the installdox tool 
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen 
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES               = 
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create 
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE       = libcdio.xml
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed 
+# in the class index. If set to NO only the inherited external classes 
+# will be listed.
+
+ALLEXTERNALS           = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed 
+# in the modules index. If set to NO, only the current project's groups will 
+# be listed.
+
+EXTERNAL_GROUPS        = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script 
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will 
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base 
+# or super classes. Setting the tag to NO turns the diagrams off. Note that 
+# this option is superseded by the HAVE_DOT option below. This is only a 
+# fallback. It is recommended to install and use dot, since it yields more 
+# powerful graphs.
+
+CLASS_DIAGRAMS         = YES
+
+# You can define message sequence charts within doxygen comments using the \msc 
+# command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to 
+# produce the chart and insert it in the documentation. The MSCGEN_PATH tag allows you to 
+# specify the directory where the mscgen tool resides. If left empty the tool is assumed to 
+# be found in the default search path.
+
+MSCGEN_PATH            = 
+
+# If set to YES, the inheritance and collaboration graphs will hide 
+# inheritance and usage relations if the target is undocumented 
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS   = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is 
+# available from the path. This tool is part of Graphviz, a graph visualization 
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section 
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT               = NO
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen 
+# will generate a graph for each documented class showing the direct and 
+# indirect inheritance relations. Setting this tag to YES will force the 
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH            = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen 
+# will generate a graph for each documented class showing the direct and 
+# indirect implementation dependencies (inheritance, containment, and 
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH    = YES
+
+# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen 
+# will generate a graph for groups, showing the direct groups dependencies
+
+GROUP_GRAPHS           = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and 
+# collaboration diagrams in a style similar to the OMG's Unified Modeling 
+# Language.
+
+UML_LOOK               = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the 
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS     = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT 
+# tags are set to YES then doxygen will generate a graph for each documented 
+# file showing the direct and indirect include dependencies of the file with 
+# other documented files.
+
+INCLUDE_GRAPH          = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and 
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each 
+# documented header file showing the documented files that directly or 
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH      = YES
+
+# If the CALL_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will 
+# generate a call dependency graph for every global function or class method. 
+# Note that enabling this option will significantly increase the time of a run. 
+# So in most cases it will be better to enable call graphs for selected 
+# functions only using the \callgraph command.
+
+CALL_GRAPH             = NO
+
+# If the CALLER_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will 
+# generate a caller dependency graph for every global function or class method. 
+# Note that enabling this option will significantly increase the time of a run. 
+# So in most cases it will be better to enable caller graphs for selected 
+# functions only using the \callergraph command.
+
+CALLER_GRAPH           = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY    = YES
+
+# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES 
+# then doxygen will show the dependencies a directory has on other directories 
+# in a graphical way. The dependency relations are determined by the #include
+# relations between the files in the directories.
+
+DIRECTORY_GRAPH        = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images 
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT       = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be 
+# found. If left blank, it is assumed the dot tool can be found in the path.
+
+DOT_PATH               = 
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that 
+# contain dot files that are included in the documentation (see the 
+# \dotfile command).
+
+DOTFILE_DIRS           = 
+
+# The MAX_DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of 
+# nodes that will be shown in the graph. If the number of nodes in a graph 
+# becomes larger than this value, doxygen will truncate the graph, which is 
+# visualized by representing a node as a red box. Note that doxygen if the number 
+# of direct children of the root node in a graph is already larger than 
+# MAX_DOT_GRAPH_NOTES then the graph will not be shown at all. Also note 
+# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+
+DOT_GRAPH_MAX_NODES    = 50
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the 
+# graphs generated by dot. A depth value of 3 means that only nodes reachable 
+# from the root by following a path via at most 3 edges will be shown. Nodes 
+# that lay further from the root node will be omitted. Note that setting this 
+# option to 1 or 2 may greatly reduce the computation time needed for large 
+# code bases. Also note that the size of a graph can be further restricted by 
+# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
+
+MAX_DOT_GRAPH_DEPTH    = 0
+
+# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent 
+# background. This is disabled by default, which results in a white background. 
+# Warning: Depending on the platform used, enabling this option may lead to 
+# badly anti-aliased labels on the edges of a graph (i.e. they become hard to 
+# read).
+
+DOT_TRANSPARENT        = NO
+
+# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output 
+# files in one run (i.e. multiple -o and -T options on the command line). This 
+# makes dot run faster, but since only newer versions of dot (>1.8.10) 
+# support this, this feature is disabled by default.
+
+DOT_MULTI_TARGETS      = NO
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will 
+# generate a legend page explaining the meaning of the various boxes and 
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND        = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will 
+# remove the intermediate dot files that are used to generate 
+# the various graphs.
+
+DOT_CLEANUP            = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be 
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE           = NO
diff --git a/doc/doxygen/run_doxygen b/doc/doxygen/run_doxygen
new file mode 100755
index 00000000..1765ed59
--- /dev/null
+++ b/doc/doxygen/run_doxygen
@@ -0,0 +1,107 @@
+#!/bin/sh
+# $Id: run_doxygen,v 1.1 2003/11/09 14:11:02 rocky Exp $
+
+# Runs doxygen and massages the output files.
+# Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
+#
+# Synopsis:  run_doxygen --mode=[user|maint|man]  v3srcdir  v3builddir
+#
+# Originally hacked together by Phil Edwards <pme@gcc.gnu.org>
+
+
+# We can check now that the version of doxygen is >= this variable.
+DOXYVER=1.2.15
+doxygen=
+
+find_doxygen() {
+    v_required=`echo $DOXYVER |  \
+                awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
+    testing_version=
+    # thank you goat book
+    set `IFS=:; X="$PATH:/usr/local/bin:/bin:/usr/bin"; echo $X`
+    for dir
+    do
+      # AC_EXEEXT could come in useful here
+      maybedoxy="$dir/doxygen"
+      test -f "$maybedoxy" && testing_version=`$maybedoxy --version`
+      if test -n "$testing_version"; then
+       v_found=`echo $testing_version |  \
+                awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
+       if test $v_found -ge $v_required; then
+         doxygen="$maybedoxy"
+         break
+       fi
+      fi
+    done
+    if test -z "$doxygen"; then
+        echo run_doxygen error:  Could not find Doxygen $DOXYVER in path. 1>&2
+        print_usage
+    fi
+}
+
+print_usage() {
+    cat 1>&2 <<EOF
+Usage:  run_doxygen --mode=MODE [<options>] <v3-src-dir> <v3-build-dir>
+      MODE is one of:
+          user           Generate user-level HTML library documentation.
+          maint          Generate maintainers' HTML documentation (lots more;
+                             exposes non-public members, etc).
+          man            Generate user-level man pages.
+
+      more options when i think of them
+
+Note:  Requires Doxygen ${DOXYVER} or later; get it at
+       ftp://ftp.stack.nl/pub/users/dimitri/doxygen-${DOXYVER}.src.tar.gz
+
+EOF
+    exit 1
+}
+
+parse_options() {
+  for o
+  do
+    # Blatantly ripped from autoconf, er, I mean, "gratefully standing
+    # on the shoulders of those giants who have gone before us."
+    case "$o" in
+      -*=*) arg=`echo "$o" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+      *) arg= ;;
+    esac
+
+    case "$o" in
+      --mode=*)
+        mode=$arg ;;
+      --mode | --help | -h)
+        print_usage ;;
+      *)
+        # this turned out to be a mess, maybe change to --srcdir=, etc
+        if test $srcdir = unset; then
+          srcdir=$o
+        elif test $outdir = unset; then
+          builddir=${o}
+          outdir=${o}/doc/doxygen
+        else
+          echo run_doxygen error:  Too many arguments 1>&2
+          exit 1
+        fi
+        ;;
+      esac
+  done
+}
+
+
+# script begins here
+mode=unset
+srcdir=unset
+outdir=unset
+do_html=no
+do_man=no
+enabled_sections=
+DATEtext=`date '+%Y-%m-%d'`
+
+parse_options $*
+find_doxygen
+$doxygen ./Doxyfile
+
+exit 0
+
+# vim:ts=4:et:
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 00000000..96ce74ea
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,451 @@
+@c The GNU Free Documentation License.
+@center Version 1.2, November 2002
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification.  Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+@acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License.  Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.2
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.'' line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/glossary.texi b/doc/glossary.texi
new file mode 100644
index 00000000..c7d2c2f5
--- /dev/null
+++ b/doc/glossary.texi
@@ -0,0 +1,360 @@
+See also @uref{http://www.dvdrhelp.com/glossary}.
+
+@table @dfn
+
+@item ASPI
+@cindex ASPI
+See @acronym{Win32 ASPI}
+
+@item ATA
+
+Advanced Technology Attachment (ATA). The same things as IDE.
+
+@item ATAPI
+
+Advanced Technology Attachment (ATA) Packet Interface. The interface
+provides a mechanism for transferring and executing SCSI CDBs on IDE
+CD Drives and DVD Drives.
+
+IDE (also called ATA) was originally designed for hard drives only,
+but with help of ATAPI it is possible to connect other devices, in
+particular CD-ROMS to the IDE/EIDE connections.
+
+The ATAPI CD-ROM drives understand a subset of MMC commands. In
+particular multi-initiator commands are neither needed nor deviced for
+ATAPI devices.
+
+@item BIN/CUE
+
+A CD-image format developed by Jeff Arnold for CDRWIN software on
+Microsoft Windows. Many other programs subsequently support using this
+format. The @code{.CUE} file is a text file which contains CD format
+and track layout information, while the @code{.BIN} file holds the
+actual data of each track.
+
+@item CD
+Compact Disc
+
+@item CD-DA
+@cindex CD-DA
+Compact Disc Digital Audio, described in the ``Red Book'' or IEC 60908
+(formerly IEC 908). This commonly referred to as an audio @acronym{CD}
+and what most people think of when you play a @acronym{CD} as it was
+the first to use the @acronym{CD} medium.
+
+See @url{http://en.wikipedia.org/wiki/Red_Book_(audio_CD_standard)}
+
+@item CD+G
+@cindex CD+G
+
+Compact Disc + Graphics. An extension of the CD audio format contains
+a limited amount of graphics in subcode channels. This disc works in
+all audio players but the graphics portion is only available in a
+special CD+G or Karaoke player.
+
+@item CD-i
+@cindex CD-i
+
+Compact Disc Interactive. An extension of the CD format designed
+around a set-top computer that connects to a TV to provide interactive
+home entertainment, including digital audio and video, video games,
+and software applications. Defined by the ``Green Book'' standard.
+@uref{http://www.icdia.org/}. CD-i for video and video music has
+largely (if not totally) been superceded by VCDs.
+
+@item CD-i Bridge
+@cindex CD-i Bridge
+
+A standard allowing CD-ROM XA discs to play on CD-i.  Kodak PhotoCDs
+are CD-XA Bridge discs.
+
+@item CD-ROM
+@cindex CD-ROM
+
+Compact Disc Read Only Memory or ``Yellow Book'' describe in Standards
+ISO/IEC 10149. The data stored on it can be either in the form of
+audio, computer or video files.
+
+@item CD-ROM Mode 1 and Mode2
+
+The Yellow Book specifies two types of tracks, Mode 1 and Mode 2. Mode
+1 is used for computer data and text and has an extra error correction
+layer. Mode 2 is for audio and video data and has no extra correction
+layer. CD-ROM/XA An expansion of the CD-ROM Mode 2 format that allows
+both computer and audio/video to be mixed in the same track.
+
+@item CD Text
+@cindex CD Text
+
+CD Text is a technology developed by Sony Corporation and Philips
+Electronics in 1996 that allows storing in an audio CD and its tracks
+information such as artist name, title, songwriter, composer, or
+arranger. Commercially available audio CDs sometimes contain CD Text
+information.
+
+@item CD XA
+@cindex CD XA
+
+CD-ROM EXtended Architecture. A modification to the CD-ROM
+specification that defines two new types of sectors.  CD-ROM XA was
+developed jointly by Sony, Philips, and Microsoft, and announced in
+August 1988. Its specifications were published in an extension to the
+Yellow Book.  CD-i, Photo CD, Video CD and CD-EXTRA have all
+subsequently been based on CD-ROM XA.
+
+CD-XA defines another way of formatting sectors on a CD-ROM, including
+headers in the sectors that describe the type (audio, video, data) and
+some additional info (markers, resolution in case of a video or audio
+sector, file numbers, etc).
+
+The data written on a CD-XA is consistent with and can be in ISO-9660
+file system format and therefore be readable by ISO-9660 file system
+translators. But also a CD-I player can also read CD-XA discs even if
+its own `Green Book' file system only resembles ISO 9660 and isn't
+fully compatible. 
+
+@item Command Packet
+@cindex Command Packet
+
+The data structure that is used to issue an ATAPI command. The same
+thing as a SCSI Command Descriptor Block (CDB).
+
+@item FSF
+@cindex FSF
+
+Free Software Foundation, @uref{http://www.fsf.org/}
+
+@item GNU
+@cindex GNU
+
+@acronym{GNU} is not @acronym{UNIX}, @uref{http://www.gnu.org/}
+
+@item IDE
+
+Integrated Drive Electronics. This is a commonly used interface for
+hard disk drives and CD-ROM drives. It is less expensive than SCSI,
+but offers slightly less in terms of performance.
+
+@item ISO
+@cindex ISO
+
+International Standards Organization. 
+
+@item ISO 9660
+@cindex ISO 9660
+
+The ISO 9660 is an operating-system independent filesystem format for
+CD-ROM media and DVD-ROMs. It was standardized in 1988 and replaced the
+High Sierra standard for the logical format on CD-ROM media (ISO 9660
+and High Sierra are identical in content, but the exact format is
+different).
+
+There are several specification levels. In Level 1, file names must be
+in the 8.3 format (no more than eight characters in the name, no more
+than three characters in the suffix) and in capital letters. Directory
+names can be no longer than eight characters. There can be no more
+than eight nested directory levels. Level 2 and 3 specifications allow
+file names up to 32 characters long.
+
+ECMA-119
+(@uref{http://www.ecma-international.org/publications/standards/Ecma-119.htm}
+is the European specification which is identical to ISO 9660.
+ISO 13490 is basically ISO 9660 with multisession support.
+
+@item Joliet extensions
+@cindex Joliet extensions
+
+This ISO-9660 upward-compatible standard was developed for Windows 95
+and Windows NT by Microsoft as an extension of ISO 9600 which allows
+the use of Unicode characters and supports file names up to 64
+characters.
+
+See @uref{http://bmrc.berkeley.edu/people/chaffee/jolspec.html} for
+the Joliet Specification.
+
+The name Joliet comes from the city in Illinois (U.S) that the
+standard was defined.
+
+@item LBA
+@cindex LBA
+
+Logical Block Addressing. Mapped integer numbers from CD Red Book
+Addressing MSF.  The starting sector is -150 and ending sector is
+449849, which correlates directly to MSF: 00:00:00 to 99:59:74.
+Because an LBA is a single number it is often easier to work with in
+programming than an MSF.
+
+@item Lead in
+@cindex lead in
+
+The area of a CD where the Table Of Contents (TOC) and CD Text are
+stored.  I think it is supposed to be around 4500 (1 min) or more
+sectors in length.  On a CDR(W) the lead-in length is variable,
+because each manufacturer will have a different starting position
+indicated by the ATIP start of lead-in position that is recorded in
+the ATIP groove on the disk.
+
+@item LSN
+@cindex LSN
+
+Logical Sector Number. Mapped integer numbers from CD Red Book
+Addressing MSF.  The starting sector is 0 and ending sector is 449699,
+which correlates to MSF: 00:00:00 to 99:59:74.  Because an LSN is a
+single number it is often easier to work with in programming than an
+MSF. Because it starts at 0 rather than -150 as is the case of an LBA
+it can be represented as an unsigned value.
+
+@item MCN
+@cindex MCN
+
+Media Catalog Number. A identification number on an audio CD.  Also
+called a UPC. Another identification number is ISRC.
+
+@item MMC
+@cindex MMC (Multimedia Commands)
+
+MMC (Multimedia Commands). A SCSI programming specification made by
+the SCSI committee T10 organization @url{http://www.t10.org/}.  MMC
+are raw commands for communicating with CDROM drives, CD-Rewriters,
+DVD-Rewriters, etc.
+
+Many manufacturers have adopted this standard and it also applies to
+ATAPI versions of their drives.
+
+@item Mixed Mode CD
+@cindex Mixed Mode CD
+
+A Mixed Mode is a CD that contains tracks of differing CD-ROM Mode
+formats. In particular the first track may contain both computer data
+(Yellow Book) CD ROM data while the remaining tracks are audio or
+video data. Video CD's can be Mixed Mode CDs. 
+
+@item Multisession 
+@cindex Multisession 
+
+A way of writing to a CD that allows more data to be
+added to readable discs at a later time.
+
+@item Nero NRG format file
+@cindex Nero NRG, CD-Image format
+
+A proprietary CD image file format use by a popular program for
+Microsoft Windows, Ahead Nero. The specification of this format is
+not to our knowlege published. 
+
+@item Rock Ridge Extensions
+@cindex Rock Ridge extensions
+
+An extension to the ISO-9660 standard which adds POSIX information to files.
+
+@item SCSI 
+@cindex SCSI 
+
+Small Computer System Interface.  A set of ANSI standard electronic
+interfaces (originally developed at Apple Computer) that allow
+personal computers to communicate with peripheral hardware such as
+CD-ROM drives, disk drives, printers, etc.
+
+@item SCSI CDB
+@cindex SCSI CDB
+
+SCSI Command Descriptor Block. The data structure that is used to
+issue a SCSI command. 
+
+@item SCSI Pass Through Interface.
+@cindex SCSI Pass Through Interface.
+
+Yet another way of issuing MMC commands for accessing a CD-ROM. As
+with MMC or ASPI, the CD-ROM doesn't necessarily have to be a
+SCSI-attached drive. See also @acronym{MMC} and @acronym{ASPI}.
+
+@item Session
+
+A fully readable complete recording that contains one or more tracks
+of computer data or audio on a CD.
+
+@item SVCD
+@cindex Super VCD (SVCD)
+
+Super @acronym{VCD} 
+
+An improvement of Video CD 2.0 specification which includes most
+notably a switch from @acronym{MPEG}-1 (constant bit rate encoding) to
+@acronym{MPEG}-2 (variable bit rate encoding) for the video stream.
+
+Also added was higher video-stream resolution, up to 4 overlay
+graphics and text (@dfn{OGT}) sub-channels for user switchable
+subtitle displaying, closed caption text, and command lists for
+controlling the @acronym{SVCD} virtual machine.
+
+See @uref{http://www.dvdrhelp.com/svcd}
+
+@item TOC
+@cindex TOC (CD Table of Contents)
+
+(Compact Disc) Table of Contents. The TOC contains the starting track
+number, last track number individual track starting time, and some
+track flags (copy protection, linear audio preemphasis, track format:
+CDDA or data).  Every CD must have at least 1 TOC, the first TOC is
+always recorded at the start of the CD (lead-in area).  A
+multi-session CD may have several TOCs.
+
+@item Track 
+@cindex track
+
+A unit of data of a CD. The size of a track can vary; it can occupy
+the entire contents of the CD. Most CD standards however require that
+tracks have a 150 frame (or ``2 second'') lead-in gap.
+
+@item VCD
+@cindex Video CD (VCD)
+
+The Video Compact Disc (@dfn{Video CD} or @dfn{VCD}) is a standardized
+digital video storage format. It is based on the commonly available
+Compact Disc technology, which allows for low-cost video authoring.
+Video CD's can be played in most @acronym{DVD} standalone player,
+dedicated VCD players and finally, modern Personal Computers with
+multimedia support.
+
+A Video CD is made up of @acronym{CD-ROM XA} sectors,
+i.e. @acronym{CD-ROM} mode 2 form 1 & 2 sectors. Non-@acronym{MPEG} data
+is stored in mode 2 form 1 sectors with a user data area of 2048 byte,
+which have a similiar L2 error correction and detection
+(@acronym{ECC}/@acronym{EDC}) to @acronym{CD-ROM} mode 1 sectors. While
+realtime @acronym{MPEG} streams is stored in @acronym{CD-ROM} mode 2
+form 2 sectors, which by have no L2 @acronym{ECC}, yield a ~14% greater
+user data area consisting of 2324 bytes@footnote{actually raw mode 2
+sectors have a 2336 byte user data area, but parts of it are used for
+error codes and headers when using the mode 2 form 1 or form 2
+configurations.}
+
+@uref{http://www.dvdrhelp.com/vcd}
+
+@item Win32 ASPI
+@cindex ASPI
+
+The ASPI interface specification was developed by Adaptec for 
+sending commands to a SCSI host adapter (such as those controlling CD
+and DVD drives) and used on Window 9x/NT and later. Emulation for
+ATAPI drives was added so that the same sets of commands worked those
+even though the drives might not be SCSI nor might there even be a
+SCSI controller attached.
+
+However in Windows NT/2K/XP, Microsoft provides their Win32 ioctl
+interface, and has take steps to make using ASPI more inaccessible
+(e.g. requiring adminstrative access to use ASPI).
+
+See also @acronym{MMC}
+
+@item Win32 ioctl driver
+
+Ioctl (Input Output ConTroLs). A Win32 function, implemented in all
+Microsoft Windows.  It is used for sending commands to devices using
+defined codes and structures.
+
+@item XA
+@cindex XA
+
+See @acronym{CD-ROM XA}
+
+@end table
diff --git a/doc/libcdio.texi b/doc/libcdio.texi
new file mode 100644
index 00000000..8f83414f
--- /dev/null
+++ b/doc/libcdio.texi
@@ -0,0 +1,2421 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename libcdio.info
+@include version.texi
+@settitle GNU @code{libcdio}: Compact Disc Input and Control Library
+@c %**end of header
+
+@c Karl Berry informs me that this will add straight quotes in 
+@c typewriter text.
+@c See the "Inserting Quote Characters" node in the Texinfo manual
+@set txicodequoteundirected
+@set txicodequotebacktick
+
+@copying
+This manual documents @code{libcdio}, the GNU CD Input and Control
+Library.
+
+Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008 Rocky
+Bernstein and Herbert Valerio Riedel.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@paragraphindent 0
+@exampleindent 0
+
+@set libcdio @code{libcdio}
+@set program @kbd{libcdio}
+
+@c A macro for defining terms variables.
+@macro term{varname}
+@c @cindex{\varname\}
+@emph{\varname\}
+@end macro
+
+@dircategory Software libraries
+@direntry
+* libcdio: (libcdio).           GNU Compact Disc Input and Control Library.
+@end direntry
+
+@titlepage
+@title GNU @code{libcdio}
+@subtitle GNU Compact Disc Input and Control Library
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Rocky Bernstein et al. (@email{bug-libcdio@@gnu.org})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU @value{libcdio}
+
+This manual documents @value{libcdio}, the GNU CD Input and Control
+Library.
+
+@menu
+* History::           How this came about
+* Previous Work::     The problem and previous work
+* Purpose::           What is in this package (and what's not)
+* CD Formats::        A tour through the CD-specification spectrum
+* CD Image Formats::  A tour through various CD-image formats
+* CD Units::          The units that make up a CD
+* How to use::        Okay enough babble, lemme at the library!
+* Utility Programs::  Diagnostic programs that come with this library
+* CD-ROM Access and Drivers::     CD-ROM access and drivers
+* Internal Program Organization:: Looking under the hood
+
+Appendices
+* ISO-9660 Character Sets::
+* Glossary::          
+* GNU Free Documentation License::
+
+Indices
+* General Index::       Overall index
+@end menu
+@end ifnottex
+
+@node History
+@chapter History
+
+As a result of the repressive Digital Millennium Copyright Act (DMCA)
+I became aware of Video CD's (VCD's). Video CD's are not subject to
+the DMCA and therefore enjoy the protection afforded by copyright but
+no more. But in order for VCD's to be competitive with DVD's, good
+tools (including GPL tools) are needed for authoring and playing
+them. And so through VCD's I became aware of the excellent Video CD
+tools by Herbert Valerio Riedel which form the @kbd{vcdimager} package.
+
+Although vcdimager is great for authoring, examining and extracting
+parts of a Video CD, it is not a VCD player. And when I looked at the
+state of Video CD handling in existing VCD players: @code{xine},
+@code{MPlayer}, and @code{vlc}, I was a bit disappointed. None handled
+playback control, menu selections, or playing still frames and
+segments from track 1.
+
+Version 0.7.12 of vcdimager was very impressive, however it lacked
+exportable libraries that could be used in other projects. So with the
+blessing and encouragement of Herbert Valerio Riedel, I took to
+extract and create libraries from this code base. The result was two
+libraries: one to extract information from a VCD which I called
+libvcdinfo, and another to do the reading and control of a VCD. Well,
+actually, at this point I should say that a Video CD is really just
+Video put on a existing well-established Compact Disc or CD format. So
+the library for this is called @value{libcdio} rather than
+@kbd{libvcdio}.
+
+While on the topic of the name @value{libcdio}, I should also explain that
+the library really doesn't handle writing or output (the final "o" in
+the name). However it was felt that if I put @code{libcdi} that might be
+confused with a particular CD format called CD-I.
+
+Later on, the ISO-9660 filesystem handling component from
+@kbd{vcdimager} was extracted, expanded and made a separate
+library. Next the ability to add MMC commands was added, and then
+CD paranoia support. And from there, the rest is history.
+
+@node Previous Work
+@chapter The problem and previous work
+
+If around the year 2002 you were to look at the code for a number of
+free software CD or media players that work on several platforms such as
+vlc, MPlayer, xine, or xmms to name but a few, you'd find the code to
+read a CD sprinkled with conditional compilation for this or that
+platform. That is there was @emph{no} OS-independent programmer
+library for CD reading and control even though the technology was over
+10 years old; yet there are media players which strive for OS
+independence.
+
+One early CD player, @kbd{xmcd} by Ti Kan, was I think a bit better
+than most in that it tried to @emph{encapsulate} the kinds of CD
+control mechanisms (SCSI, Linux ioctl, Toshiba, etc.) in a "CD Audio
+Device Interface Library" called @code{libdi}.  However this library is for
+Audio CD's only and I don't believe this library has been used outside
+of xmcd.
+
+Another project, Simple DirectMedia Layer also encapsulates CD
+reading. 
+
+@quotation
+SDL is a library that allows you portable low-level access to a video
+framebuffer, audio output, mouse, and keyboard. With SDL, it is easy
+to write portable games which run on ...
+@end quotation
+
+Many of the media players mentioned above do in fact can make use of
+the SDL library but for @emph{video} output only. Because the encapsulation
+is over @emph{many} kinds of I/O (video, joysticks, mice, as well as CD's),
+I believe that the level of control provided for CD a little bit
+limited. (However to be fair, it may have only been intended for games
+and may be suitable for that).  Applications that just want the CD
+reading and control portion I think will find quite a bit overhead.
+
+Another related project is J@"org Schilling's SCSI library. You can
+use that to make a non-SCSI CD-ROM act like one that understands SCSI
+MMC commands which is a neat thing to do. However it is a little weird
+to have to install drivers just so you can run a particular user-level
+program. Installing drivers often requires special privileges and
+permissions and it is pervasive on a system. It is a little sad that
+along the way to creating such a SCSI library a library similar to
+@value{libcdio} wasn't created which could be used. Were that the
+case, this library certainly never would have been written.
+
+At the OS level there is the ``A Linux CD-ROM Standard'' by David van
+Leeuwen from around 1999. This defines a set of definitions and
+ioctl's that mask hardware differences of various Compact Disc
+hardware. It is a great idea, however this ``standard'' lacked
+adoption on OS's other than GNU/Linux. Or maybe it's the case that the
+standard on other OS's lacked adoption on GNU/Linux. For example on
+FreeBSD there is a ``Common Access Method'' (CAM) used for all SCSI
+access which seems not to be adopted in GNU/Linux.@footnote{And I'm
+thankful for that since, at least for MMC commands, it is
+inordinately complicated and in some places arcane.}
+
+Finally at the hardware level where a similar chaos exists, there has
+been an attempt to do something similar with the MMC (multimedia
+commands). This attempts to provide a uniform command set for CD
+devices like PostScript does for printer commands.@footnote{I wrote
+``attempts'' because over time the command set has changed and now
+there are several different commands to do a particular function like
+read a CD table of contents and some hardware understands some of the
+version of the commands set but might not others} In contrast to
+PostScript where there one in theory can write a PostScript program in
+a uniform ASCII representation and send that to a printer, for MMC
+although there are common internal structures defined, there is no
+common syntax for representing the structures or an OS-independent
+library or API for issuing MMC-commands which a programmer would need
+to use. Instead each Operating System has its own interface.  For
+example Adaptec's ASPI or Microsoft's DeviceIoControl on Microsoft
+Windows, or IOKit for Apple's OS/X, or FreeBSD's CAM. I've been
+positively awed at how many different variations and differing levels
+of complexity there are for doing basically the same thing. How easy
+it is to issue an MMC command from a program varies from easy to very
+difficult. And mastering the boilerplate code to issue an MMC command
+on one OS really doesn't help much in figuring out how to do it on
+another OS. So in @value{libcdio} we provide a common (and hopefully
+simple) API to issue MMC commands.
+
+@node Purpose
+@chapter What is in this package (and what's not)
+
+The library, @command{libcdio}, encapsulates CD-ROM reading and
+control. Applications wishing to be oblivious of the OS- and
+device-dependent properties of a CD-ROM can use this library.
+
+Also included is a library, @command{libiso9660}, for working with
+ISO-9660 filesystems, @command{libcdio_paranoia}, and
+@command{libcdio_cdda} libraries for applications which want to use
+cdparanoia's error-correction and jitter detection.
+
+Some support for disk-image types like cdrdao's TOC, CDRWIN's BIN/CUE
+and Ahead Nero's NRG format is available, so applications that use this
+library also have the ability to read disc images as though they were
+CDs.
+
+@command{libcdio} also provides a way to issue SCSI ``MultiMedia
+Commands'' (MMC).  MMC is supported by many hardware CD-ROM
+manufacturers; and in some cases where a CD-ROM doesn't understand MMC
+directly, some Operating Systems (such as GNU/Linux, Solaris, or
+FreeBSD or Microsoft Windows ASPI to name a few) provide the MMC
+emulation.@footnote{This concept of software emulation of a common
+hardware command language is common for printers such as using
+ghostscript to private postscript emulation for a non-postscript
+printer.}
+
+The first use of the library in this package are the Video CD
+authoring and ripping tools, VCDImager
+(@url{http://vcdimager.org}). See
+@url{http://www.gnu.org/software/libcdio/projects.html} for a list of
+projects using @command{libcdio}.
+
+A version of the CD-DA extraction tool cdparanoia
+(@url{http://www.xiph.org/paranoia} and its library which corrects
+for CD-ROM jitter are part of the distribution.
+
+Also included in the libcdio package is a utility program
+@command{cd-info} which displays CD information: number of tracks,
+CD-format and if possible basic information about the format.  If
+libcddb (@url{http://libcddb.sourceforge.net}) is available, the
+@command{cd-info} program will display CDDB matches on CD-DA
+discs. And if a new enough version of libvcdinfo is available (from
+the vcdimager project), then @command{cd-info} shows basic VCD
+information.
+
+Other utility programs in the libcdio package are:
+
+@table @code 
+
+@item @code{cdda-player}
+
+shows off @value{libcdio} audio and CD-ROM control commands. It can
+play a track, eject or load media and show the the status of a CD-DA
+that is might be currently played via the audio control commands.  It
+can be run in batch mode or has a simple curses-based interface.
+
+If libcddb is available or a CD has CD-Text and your CD-ROM drive
+supports CD-Text, track/album information about the CD can be shown.
+
+@item @code{cd-drive}
+
+shows what drivers are available and some basic properties of
+cd-drives attached to the system. (But media may have to be inserted
+in order to get this info.)  lists out drive capabilities
+
+@item cd-read
+performs low-level block reading of a CD or CD image,
+
+@item @code{iso-info} 
+
+displays ISO-9660 information from an ISO-9660 image. Below is some
+sample output
+
+@smallexample
+iso-info version 0.72
+Copyright (c) 2003, 2004, 2005 R. Bernstein
+This is free software; see the source for copying conditions.
+There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.
+__________________________________
+ISO 9660 image: ../test/joliet.iso
+Application: K3B THE CD KREATOR VERSION 0.11.12 (C) 2003 SEBASTIAN TRUEG AND THE K3B TEAM
+Preparer   : K3b - Version 0.11.12
+Publisher  : Rocky Bernstein
+System     : LINUX           
+Volume     : K3b data project
+Volume Set : K3b data project
+__________________________________
+ISO-9660 Information
+/:
+ Oct 22 2004 19:44  .
+ Oct 22 2004 19:44  ..
+ Oct 22 2004 19:44  libcdio
+
+/libcdio/:
+ Oct 22 2004 19:44  .
+ Oct 22 2004 19:44  ..
+ Mar 12 2004 02:18  COPYING
+ Jun 26 2004 07:01  README
+ Aug 12 2004 06:22  README.libcdio
+ Oct 22 2004 19:44  test
+
+/libcdio/test/:
+ Oct 22 2004 19:44  .
+ Oct 22 2004 19:44  ..
+ Jul 25 2004 06:52  isofs-m1.cue
+@end smallexample
+
+@item @code{iso-read} 
+
+extracts files from an ISO-9660 image.
+
+@end table
+
+At present, there is no support for writing CD's. Nor is there any
+support for reading or writing DVDs. For some of these, there are
+other libraries (e.g. @code{libdi}, @code{libscg}, or @code{libdvdread}) may be helpful.
+
+I'm not theoretically opposed to putting support like this into
+libcdio. However at present there are already many gaps in this
+package, so narrowing its scope in order to focus on these things I
+think is a good idea.
+
+@node CD Formats
+@chapter CD Formats
+
+Much of what I write in this section can be found elsewhere. See for
+example @url{http://www.pctechguide.com/08cd-rom.htm} or
+@url{http://www.pcguide.com/ref/cd/format.htm}
+
+We give just enough background here to cover Compact Discs and Compact
+Disc formats that are handled by this library.
+
+The Sony and Philips Corporations invented and Compact Disc (CD) in
+the early 1980s. The specifications for the layout is often referred
+to by the color of the cover on the specification. 
+
+@menu
+* Red Book::        Red Book (CD-DA) CD Text, CDDB
+* Yellow Book::     Yellow Book (CD-ROM Digital Data)
+* Green Book::      Green Book (CD-i)
+* White Book::      White Book (DV, Video CD)
+@end menu
+
+@node Red Book
+@section Red Book (CD-DA)
+@cindex Red Book
+
+@menu
+* CD Text::         CD Text and CD+G
+* CDDB::            Internet CD Database (CDDB)
+@end menu
+
+The first type of CD that was produced was the Compact Disc Digital
+Audio (CD-DA) or just plain ``audio CD''. The specification, ICE 60908
+(formerly IEC 908) is commonly called the ``Red Book'',
+@cite{@url{http://en.wikipedia.org/wiki/Red_Book_(audio_CD_standard)}}. Music
+CD's are recorded in this format which basically allows for around 74
+minutes of audio per disc and for that information to be split up into
+tracks. Tracks are broken up into "sectors" and each sector contains
+up to 2,352 bytes. To play one 44.1 kHz CD-DA sampled audio second, 75
+sectors are used.
+
+The minute/second/frame numbering of sectors or MSF format is based on
+the fact that 75 sectors are used in a second of playing of
+sound. (And for almost every other CD format and application the MSF
+format doesn't make that much sense).
+
+In @value{libcdio} when you you want to read an audio sector, you call 
+@code{cdio_read_audio_sector()} or @code{cdio_read_audio_sectors()}.
+
+@cindex subchannel
+In addition the the audio data ``channel'' a provision for other
+information or @term{subchannel} information) can be stored in a
+sector. Other subchannels include a Media Catalog Number (also
+abbreviated as MCN and sometimes a UPC), or album meta data (also
+called CD-Text). Karioke graphics can also be stored in a format
+called @term{CD+G}.
+
+@node CD Text
+@subsection CD Text, CD+G
+@cindex CD Text
+@cindex CD+G
+
+CD Text is an extension to the CD-DA standard that adds the ability to
+album and track meta data (titles, artist/performer names, song
+titles) and and graphical (e.g. Karaoke) information.  For an
+alternative way to get album and track meta-data see @xref{CDDB}.
+
+Information is stored in such a way that it doesn't interfere with the
+normal operation of any CD players or CDROM drives. There are two
+different parts of the CD where the data can be stored.
+
+The first place the information can be recorded is in the R-W sub
+codes in the lead in area of the CD giving a data capacity of about
+5,000 ASCII characters (or 2,500 Kanji or Unicode characters).  This
+information is stored as a single block of data and is the format used
+in virtually all of the CD Text CDs shipping today. The method for
+reading this data from a CDROM drive is covered under the Sony
+proposal to the MMC specification. The format of the data is partially
+covered in the MMC specification.
+
+The second place the information can be recorded is in the R-W sub
+codes in the program area of the CD giving a data capacity of roughly
+31MB. This information is stored in a format that follows the
+Interactive Text Transmission System (ITTS) which is the same data
+transmission standard used by such things as Digital Audio
+Broadcasting (DAB), and virtually the same as the data standard for
+the MiniDisc. Traditionally the R-W sub codes have been used for text
+and graphics in applications such as CD+G (CD w/graphics) or in the
+case of most audio CDs, not at all. The methods for reading this data
+from a CD-ROM drive is covered by the programming specs from the
+individual drive manufacturers. In the case of ATAPI drives, the
+SFF8020 spec covers the reading of the RW subcodes.
+
+Not all drives support reading the RW subcodes from the program
+area. However for those that do, @value{libcdio} provides a way to get
+at this information via @code{cdtext_get()} and its friends.
+
+@node CDDB
+@subsection Internet CD Database (CDDB)
+@cindex CDDB
+
+CDDB is an database on the Internet of of CD album/track, artist, and
+genre information similar to CD Text information. Using track
+information (number of tracks and length of the tracks), devices that
+have access to the Internet can query for meta information and
+contribute information for CD's where there is no existing
+information.  When storage is available (such as you'd expect for any
+program using @value{libcdio}, the information is often saved for
+later use when the Internet is not available; people tend request the
+same information since they via programs play the same music.
+
+Obtaining CD meta information when none is encoded in an audio CD is
+useful in media players or making ones own compilations from audio
+CDs. 
+
+There are currently two popular CDDB services on the Internet. The
+original database has been renamed Gracenote and is a profit making
+entity. FreeDB (@url{http://freedb.org} is an open source CD
+information resource that is free for developers and the public to
+use.
+
+As there already is an excellent library for handling CDDB libcddb
+(@url{http://libcddb.sourceforge.net} we suggest using that. Our
+utility program @command{cd-info} will make use it if it is available
+and it's what we use in our applications that need it.
+
+@node Yellow Book
+@section Yellow Book (CD-ROM Digital Data)
+The CD-ROM specification or the ``Yellow Book'' followed a few years
+later (Standards ISO/IEC 10149), and describes the extension of CD's
+to store computer data, i.e. CD-ROM (Compact Disk Read Only Memory).
+
+The specification in the Yellow Book defines two modes: Mode 1 and
+Mode 2.
+
+@menu
+* ISO 9660::
+* Mode 1::           Mode 1 Format
+* Mode 2::           Mode 2 Format
+@end menu
+
+@node ISO 9660
+@subsection ISO 9660
+@cindex ISO 9660
+
+@menu
+* ISO 9660 Level 1::
+* ISO 9660 Level 2::
+* ISO 9660 Level 3::
+* Joliet Extensions::
+* Rock Ridge Extensions::
+@end menu
+
+The Yellow Book doesn't specify how data is to be stored on a CD-ROM.
+It was feared that different companies would implement proprietary
+data storage formats using this specification, resulting in
+incompatible data CDs. To prevent this, representatives of major
+manufacturers met at the High Sierra Hotel and Casino in Lake Tahoe,
+NV, in 1985, to define a standard for storing data on CDs. This format
+was nicknamed High Sierra Format. In a slightly modified form it was
+later adopted as ISO the ISO 9660 standard. This standard is further
+broken down into 3 "levels", the higher the level, the more
+permissive.
+
+@node ISO 9660 Level 1
+@subsubsection ISO 9660 Level 1
+Level 1 ISO 9660 defines names in the 8+3 convention so familiar to
+MS-DOS: eight characters for the filename, a period, and then three
+characters for the file type, all in upper case. The allowed
+characters are A-Z, 0-9, ".", and "_".Level 1 ISO 9660 requires that
+files occupy a contiguous range of sectors. This allows a file to be
+specified with a start block and a count. The maximum directory depth
+is 8. For a table of the characters, see @xref{ISO-9660 Character
+Sets}.
+
+@node ISO 9660 Level 2
+@subsubsection ISO 9660 Level 2
+Level 2 ISO 9660 allows far more flexibility in filenames, but isn't
+usable on some systems, notably MS-DOS.
+
+@node ISO 9660 Level 3
+@subsubsection ISO 9660 Level 3
+Level 3 ISO-9660 allows non-contiguous files, useful if the file was
+written in multiple packets with packet-writing software.
+
+There have been a number of extensions to the ISO 9660 CD-ROM file
+format. One extension is Microsoft's Joliet specification, designed to
+resolve a number of deficiencies in the original ISO 9660 Level 1 file
+system, and in particular to support the long file names used in
+Windows 95 and subsequent versions of Windows.
+
+Another extension is the Rock Ridge Interchange Protocol (RRIP), which
+enables the recording of sufficient information to support POSIX File
+System semantics.
+
+@node Joliet Extensions
+@subsubsection Joliet Extensions
+@cindex Joliet extensions
+
+Joliet extensions were an upward-compatible extension to the ISO 9660
+specification that removes the limitation initially put in to deal
+with the limited filename conventions found in Microsoft DOS OS. In
+particular, the Joliet specification allows for long filenames and
+allows for UCS-BE (BigEndian Unicode) encoding of filenames which
+include mixed case letter, accented characters spaces and various
+symbols. 
+
+The way all of this is encoded is by adding a second directory and
+filesystem structure in addition to or in parallels to original ISO
+9600 filesystem. The root node of the ISO 9660 filesystem is found via
+the @term{Primary Volume Descriptor} or @term{PVD}. The root of the
+Joliet-encode filesystem is found in a Supplementary Volume
+Descriptor or @term{SVD} defined in the ISO 9660 specification. The
+SVD structure is almost identical to a PVD with a couple of unused
+fields getting used and with the filename encoding changed to UCS-BE.
+
+@node Rock Ridge Extensions
+@subsubsection Rock Ridge Extensions
+@cindex Rock Ridge extensions
+
+Using the Joliet Extension one overcome the limitedness of the
+original ISO-9660 naming scheme. But another and probably better
+method is to use the Rock Ridge Extension. Not only can one store a
+filename as one does in a POSIX OS, but the other file attributes,
+such as the various timestamps (creation, modification, access), file
+attributes (user, group, file mode permissions, device type, symbolic
+links) can be stored. This is much as one would do in XA attributes;
+however the two are not completely interchangeable in the information
+they store: XA does @emph{not} address filename limitations, and the
+Rock Ridge extensions don't indicate if a sector is in Mode 1 or Mode
+2 format.
+
+The Rock Ridge extension makes use of a hook that was defined as part
+of the ISO 9660 standard.
+
+@node Mode 1
+@subsection Mode 1 (2048 data bytes per sector)
+@cindex Mode 1
+Mode 1 is the data storage mode used by to store computer data. There
+are 3 layers of error correction. A Compact Disc using only this format can
+hold at most 650 MB. The data is laid out in basically the same way as
+in and audio CD format, except that the 2,352 bytes of data in each
+block are broken down further. 2,048 of these bytes are for ``real''
+data. The other 304 bytes are used for an additional level of error
+detecting and correcting code. This is necessary because data CDs
+cannot tolerate the loss of a handful of bits now and then, the way
+audio CDs can.
+
+In @value{libcdio} when you you want to read a mode1
+sector you call the @code{cdio_read_mode1_sector()} or
+@code{cdio_read_mode1_sectors()}.
+
+@node Mode 2
+@subsection Mode 2 (2336 data bytes per sector)
+@cindex Mode 2
+Mode 2 data CDs are the same as mode 1 CDs except that the error
+detecting and correcting codes are omitted. So still there are 2
+layers of error correction. A Compact Disc using only this mode can
+thus hold at most 742 MB. Similar to audio CDs, the mode 2 format
+provides a more flexible vehicle for storing types of data that do not
+require high data integrity: for example, graphics and video can use
+this format. But in contrast to the Red Book standard, different modes
+can be mixed together; this is the basis for the extensions to the
+original data CD standards known as CD-ROM Extended Architecture, or
+CD-ROM XA.  CD-ROM XA formats currently in use are CD-I Bridge
+formats, Photo CD and Video CD plus Sony's Playstation.
+
+In @value{libcdio} when you you want to read a mode1
+sector you call the @code{cdio_read_mode2_sector()} or
+@code{cdio_read_mode2_sectors()}.
+
+@node Green Book
+@section Green Book (CD-i)
+@cindex Green Book
+
+This was a CD-ROM format developed by Philips for CD-i (an obsolete
+embedded CD-ROM application allowing limited user user interaction
+with films, games and educational applications). The format is ISO
+9660 compliant and introduced mode 2 form 2 addressing. It also 
+contains XA (Extended Architecture) attributes.
+
+Although some Green Book discs contain CD-i applications which can
+only be played on a CD-i player, others have films or music
+videos. Video CDs in Green-Book format are labeled "Digital Video on
+CD." The Green Book for video is largely superseded by White book
+CD-ROM which draws on this specification.
+
+
+@node White Book
+@section White Book (DV, Video CD)
+@cindex Green Book
+
+The White Book was released by Sony, Philips, Matsushita, and JVC in
+1993, defines the Video CD specification. The White Book is also known
+as Digital Video (DV). 
+
+A Video CD contains one data track recorded in CD-ROM XA Mode 2 Form
+2. It is always the first track on the disc (Track 1). The ISO-9660
+file structure and a CD-i application program are recorded in this
+track, as well as the Video CD Information Area which gives general
+information about the Video Compact Disc. After the data track, video
+is written in one or more subsequent tracks within the same
+session. These tracks are also recorded in Mode 2 Form 2. 
+
+In @value{libcdio} when you you want to read a mode2 format 2 audio
+sector you call the @code{cdio_read_mode2_sector()} or
+@code{cdio_read_mode2_sectors()} setting @code{b_form2} to @code{true}.
+
+@node CD Image Formats
+@chapter CD Image Formats 
+
+@menu
+* CDRDAO TOC Format::           
+* CDRWIN BIN/CUE Format::              
+* NRG Format::              
+@end menu
+
+In both the @command{cdrdao} and bin/cue formats there is one meta-file with
+extensions @code{.toc} or @code{.cue} respectively and one or more
+files (often with the extension @code{.bin}) which contains the
+content of tracks. The format of the track data is often
+interchangeable between the two formats.  For example, in
+@value{libcdio}'s regression tests we make use of this to reduce the
+size of the test data and just provide alternate meta-data files
+(@code{.toc} or @code{.cue}).
+
+In contrast to the first two formats, the NRG format consists of a
+single file. This has the advantage of being a self-contained
+unit: in the other two formats it is possible for the meta file to
+refer to a file that can't be found. A disadvantage of the NRG format
+is that the meta data can't be easily viewed or modified say in a text
+file as it can be with the first two formats. In conjunction with this
+disadvantage is another disadvantage that the format is not
+documented, so how @value{libcdio} interprets an NRG image is based on
+inference. It is recommended that one of the other forms be used
+instead of NRG where possible.
+
+@node CDRDAO TOC Format
+@section CDRDAO TOC Format
+
+This is @command{cdrdao}'s CD-image description format. Since this
+program is GPL and everything about it is in the open, it is the
+preferred format to use. (Alas, at present it isn't as well supported
+in @value{libcdio} as the BIN/CUE format.)
+
+The @emph{toc}-file describes what data is written to the media in the
+@acronym{CD-ROM}; it allows control over track/index positions,
+pre-gaps and sub-channel information.  It is a text file, so a text
+editor can be used to create, view or modify it.
+
+The @cite{cdrdao(1) manual page}, contains more information about this
+format.
+
+@subsection CDRDAO Grammar
+
+Below are the lexical tokens and grammar for a cdrdao TOC. It was
+taken from the cdrdao's pacct grammar; the token and nonterminal names
+are the same.
+
+@example
+#lexclass START
+#token Eof		"@@"
+#token                  "[\t\r\ ]+"
+#token Comment          "//~[\n@@]*"
+#token                  "\n"       
+#token BeginString      "\""       
+#token Integer          "[0-9]+"
+#tokclass AudioFile     @{ "AUDIOFILE" "FILE" @}
+
+#lexclass STRING
+#token EndString        "\""
+#token StringQuote      "\\\""
+#token StringOctal      "\\[0-9][0-9][0-9]"
+#token String           "\\"
+#token String           "[ ]+"
+#token String           "~[\\\n\"\t ]*"
+@end example
+
+@example
+
+<toc>  ::= ( "CATALOG" <string> | <tocType> )* @{ <cdTextGlobal> @} 
+           ( <track> )+ Eof 
+
+<track> ::= "TRACK" <trackMode> 
+    @{ <subChannelMode> @}
+    (  "ISRC" <string> | @{ "NO" @} "COPY" | @{ "NO" @} "PRE_EMPHASIS" 
+    | "TWO_CHANNEL_AUDIO"  | "FOUR_CHANNEL_AUDIO" )*
+    @{ <cdTextTrack>  @}
+    @{ "PREGAP" <msf> @}
+    ( <subTrack> | "START" @{ msf @} | "END" @{ msf @} )+
+    ( "INDEX" <msf> )*
+
+<subTrack> ::= 
+     AudioFile <string> @{ "SWAP"  @} @{ "#" <sLong>  @}  <samples>
+     | "DATAFILE" <string> @{ "#" <sLong> @{ <dataLength> @} @}
+     | "FIFO" <string> <dataLength> 
+     | "SILENCE" <samples> 
+     | "ZERO" @{ dataMode  @} @{ <subChannelMode>  @} <dataLength> 
+  
+
+<string> ::=  BeginString ( String | StringQuote | StringOctal )+ 
+            EndString
+
+<stringEmpty> ::= BeginString ( String | StringQuote | StringOctal )*
+                EndString
+
+<uLong> ::= Integer 
+
+<sLong> ::= Integer 
+
+<msf> ::= Integer ":" Integer ":" Integer 
+
+<samples> ::= <msf> | <uLong>
+
+<dataLength> ::= <msf> | <uLong>
+
+<dataMode> ::=  "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2" 
+     | "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX"
+
+<trackMode> ::= "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2"
+     | "MODE2_RAW"  | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX"
+
+<subChannelMode> ::= "RW" | "RW_RAW"
+
+<tocType> ::= "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I"
+
+<packType> ::= "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER"  
+     | "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2"  
+     | "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" |
+     "ISRC" | "SIZE_INFO"
+
+<binaryData> ::=  "@{"
+    @{ Integer ( "," Integer  )* @}
+    "@}"
+         
+<cdTextItem> ::= <packType>  ( <stringEmpty> | <binaryData> )
+ 
+<cdTextBlock> ::=  "LANGUAGE" Integer "@{" ( <cdTextItem> )* "@}"
+
+<cdTextLanguageMap> ::= 
+    "LANGUAGE_MAP" "@{"
+    ( Integer  ":" (  Integer | "EN"  ) )+
+    "@}"
+
+<cdTextTrack> ::=  "CD_TEXT" "@{" ( <cdTextBlock> )*  "@}"
+
+<cdTextGlobal> ::= "CD_TEXT" "@{" @{ <cdTextLanguageMap> @} ( <cdTextBlock> )* "@}"
+@end example
+
+
+
+@node  CDRWIN BIN/CUE Format
+@section CDRWIN BIN/CUE Format
+@cindex BIN/CUE, CD Image Format
+
+The format referred to as @emph{CDRWIN BIN/CUE Format} in this manual
+is a popular CD image format used in the @acronym{PC} world. Not
+unlike @command{cdrdao}'s TOC file, the @emph{cue} file describes the
+track layout, i.e. how the sectors are to be placed on the CD
+media. The @emph{cue} file usually contains a reference to a file
+traditionally having the @file{.bin} extension in its filename, the
+@emph{bin} file. This @emph{bin} file contains the sector data payload
+which is to be written to the CD medium according to the description
+in the @emph{cue} file.
+
+The following is an attempt to describe the subset of the @file{.cue}
+file syntax used in @value{libcdio} and vcdimager in an EBNF-like
+notation:
+
+@subsection BIN/CUE Grammar
+
+@example
+@cartouche
+<cue-document> ::= +( <file-line> +<track-expr> )
+
+<digit> ::= "0" | "1" ... "8" | "9"
+<number> ::= +<digit>
+<msf> ::= <digit><digit> ":" <digit><digit> ":" <digit><digit>
+
+<file-line> ::= "FILE" <pathname-expr> <file-type> <EOL>
+
+<pathname-expr> ::= [ "\"" ] <pathname-str-without-spaces> [ "\"" ] 
+                  | "\"" <pathname-str> "\""  
+
+<file-type> ::= "BINARY" 
+
+<track-expr> ::= <track-line> [ <flag-line> ]
+                 [ <pregap-line> ] *<index-line> [ <postgap-line> ]
+
+<flag-line> ::= "FLAGS" *<flag-type> <EOL>
+<flag-type> ::= "DCP"
+
+<track-line> ::= "TRACK" <number> <track-type> <EOL>
+
+<pregap-line> ::= "PREGAP" <msf> <EOL>
+
+<index-line> ::= "INDEX" <number> <msf> <EOL>
+
+<postgap-line> ::= "POSTGAP" <msf> <EOL>
+
+<track-type> ::= "AUDIO" | "MODE1/2048" | "MODE1/2352" 
+               | "MODE2/2336" | "MODE2/2352"
+
+<comment-line> ::= "REM" *<char> <EOL>
+@end cartouche
+@end example
+
+@node  NRG Format
+@section NRG Format
+@cindex Nero NRG, CD-Image format
+
+The format referred to as @emph{NRG Format} in this manual is another
+popular CD image format. It is available only on Nero software
+on a Microsoft Windows Operating System. It is proprietary and not
+generally published, so the information we have comes from guessing
+based on sample CD images. So support for this is incomplete and using
+this format is not recommended.
+
+Unlike @command{cdrdao}'s TOC file the BIN/CUE format everything is
+contained in one file. that one can edit Meta information such as the
+number of tracks and track format is contained at the end of the
+file. This information is not intended to be edited through a text
+editor.
+
+@node CD Units
+@chapter The units that make up a CD
+
+@menu
+* Tracks::   Tracks
+* Sectors::  Block addressing (MSF, LSN, LBA)
+* Pre-gaps::  Track pre-gaps
+@end menu
+
+@node Tracks
+@section tracks --- disc subdivisions
+@cindex track
+@cindex gaps
+
+In this section we describe CD properties and terms that we make use
+of in @value{libcdio}.
+
+A CD is formatted into a number of @term{tracks}, and a CD can hold at
+most 99 such tracks. This is defined by @code{CDIO_CD_MAX_TRACKS} in
+@file{cdio/sector.h}. Between some tracks CD specifications require a
+``2 second'' in gap (called a @term{lead-in gap}. This is unused space
+with no ``data'' similar to the space between tracks on an old
+phonograph. The word ``second'' here really refers to a measure of
+space and not really necessarily an amount of time. However in the
+special case that the CD encodes an audio CD or CD-DA, the amount of
+time to play a gap of this size will take 2 seconds.
+
+@cindex lead out
+The beginning (or inner edge) of the CD is supposed to have a ``2
+second'' lead-in gap and there is supposed to be another ``2 second''
+@term{lead-out} gap at the end (or outer edge) of the CD.
+
+People have discovered that they can put useful data in the @term{lead-in}
+and @term{lead-out} gaps, and their equipment can read this, violating
+the standards but allowing a CD to store more data.
+
+In order to determine the number of tracks on a CD and where they
+start, commands are used to get this table-of-contents or @term{TOC}
+information. Asking about the start of the @term{lead-out track}
+gives the amount of data stored on the Compact Disk. To make it easy
+to specify this leadout track, special constant 0xAA (decimal 170) is
+used to indicate it. This is safe since this is higher than the
+largest legal track position. In @value{libcdio},
+@code{CDIO_CDROM_LEADOUT_TRACK} is defined to be this special value.
+
+@node Sectors
+@section block addressing (MSF, LSN, LBA)
+@cindex MSF
+@cindex LSN
+@cindex LBA
+@cindex sectors
+@cindex frames
+
+A track is broken up into a number of 2352-byte @emph{blocks} which we
+sometimes call @emph{sectors} or @emph{frames}. Whereas tracks may
+have a gap between them, a block or sector does not. (In
+@value{libcdio} the block size constant is defined using
+@code{CDIO_CD_FRAMESIZE_RAW}).
+
+A Compact Disc has a limit on the number of blocks or sectors.  This
+values is defined by constant @code{CDIO_CD_MAX_LSN} in
+@file{cdio/sector.h}.
+
+One can addressing a block in one of three formats. The oldest format
+is by it's minute/second/frame number, also referred to as @term{MSF}
+and written in time-like format MM:SS:FF (e.g. 30:01:40). It is best
+suited in audio (Red Book) applications. In @value{libcdio}, the type
+@code{msf_t} can be used to declare variables to hold such
+values. Minute, second and frame values are one byte @emph{and stored
+BCD notation}.@footnote{Perhaps this is a @value{libcdio} design
+flaw. It was originally done I guess because it was convenient for
+VCDs.} There are @value{libcdio} conversion routines
+@code{cdio_from_bcd8()} and @code{cdio_to_bcd8()} to convert the
+minute, second, and frame values into or out of integers. If you want
+to print a field in a BCD-encoded MSF, one can use the format
+specifier @code{%x} @emph{(not @code{%d})} and things will come out
+right.
+
+In the MSF notation, there are 75 ``frames'' in a ``second,'' and the
+familiar (if awkward) 60 seconds in a minute. @emph{Frame} here is
+what we called a @emph{block} above. The CD specification defines
+``frame'' to be @emph{another} unit which makes up a block. Very
+confusing. A frame is also sometimes called a sector, analogous to
+hard-disk terminology.
+
+Even more confusing is using this time-like notation for an address or
+for a length. Too often people confuse the MSF notation this with an
+amount of time. A ``second'' (or @code{CDIO_CD_FRAMES_PER_SEC} blocks)
+in this notation is only a second of playing time for something
+encoded as CD-DA. It does @emph{not} necessarily represent the amount
+time that it will take to play a of Video CD---usually you need more
+blocks than this. Nor does it represent the amount of data used to
+play a second of an MP3---usually you need fewer blocks than this. It
+is also not the amount of time your CD-ROM will take to read a
+``second'' of data off a Compact Disc: for example a 12x CD player
+will read 12x @code{CDIO_CD_FRAMES_PER_SEC}
+@code{CDIO_CD_FRAMSIZE_RAW}-byte blocks in a one second of time.
+
+When programming, unless one is working with a CD-DA (and even here,
+only in a time-like fashion), is generally more cumbersome to use an
+MSF rather than a LBA or LSN described below, since subtraction of two
+MSF's has the awkwardness akin to subtraction using Roman Numerals.
+
+Probably the simplest way to address a block is to use its @term{LSN}
+or ``logical sector number.'' This just numbers the blocks usually
+from 0 on. @emph{fix me: LSNs can be negative up to the pregap size?}
+The Lead-in and Lead-out gaps described above have LSNs just like any
+other space on a CD. The last unit of address is a @term{LBA}. It is
+the same as a LSN but the 150 blocks associated with the initial
+lead-in is are not counted. So to convert a LBA into an LSN you just
+add 150. Why the distinction between LBA and LSN? I don't know,
+perhaps this has something to do with ``multisession'' CDs.
+
+@node Pre-gaps
+@section track pre-gaps -- @acronym{CD-DA} discs and gaps
+@cindex CD-DA
+@cindex gaps
+@cindex lead in
+@cindex lead out
+@cindex pre-gap
+@cindex Q sub-channel
+
+Gaps are possibly one of the least understood topics in audio discs.
+In the case of @acronym{CD-DA} discs, standards require a silent 2
+second gap before the first audio track and after the last audio track
+(in each session.)  These are respectively referred to as
+@term{lead-in} and @term{lead-out} gaps.  No other gaps are required.
+It is important not to confuse the required @term{lead-in} and
+@term{lead-out} gaps with the optional track @term{pre-gap}s.  Track
+@term{pre-gap}s are the gaps that may occur between audio tracks.
+Typically, track @term{pre-gap}s are filled with silence so that the
+listener knows that one song has ended, and the next will soon begin.
+However, track @term{pre-gap}s do not have to contain silence.  One
+exception is an audio disc of a live performance.  Because the
+performer may seamlessly move from one piece of the performance to the
+next, it would be unnatural for the disc to contain silence between
+the two pieces.  Instead, the track number updates with no
+interruption in the performance.  This allows the listener to either
+hear the entire performance without unnatural interruptions, or to
+conveniently skip to certain pieces of the performance.  Finally, some
+@acronym{CD-DA} discs--whose behavior will be described below--lack
+track @term{pre-gap}s altogether although they must still include the
+@term{lead-in} and @term{lead-out} gaps.
+
+In order to understand the track @term{pre-gap}s that occur between
+audio tracks, it is necessary to understand how CD players display the
+track number and time.  Embedded in each block of audio data is
+non-audio information known as the @term{Q sub-channel}.  The
+@term{Q sub-channel} data tells the CD player what track number and time
+it should display while it is playing the block of audio data in which
+the @term{Q sub-channel} data is embedded.  Near the end of some
+tracks, the @term{Q sub-channel} may instruct the CD player to update
+the track number to the next track, and display a count down to the
+next track, often starting at -2 seconds and proceeding to zero.  This
+is known as an audio track @term{pre-gap}.  It may either contain
+silence, or as previously discussed--in the case of live
+performances--it may contain audio.  Almost as often as not, there is
+no @term{pre-gap} whatsoever.  Regardless, an audio track
+@term{pre-gap} is purely determined by the contents of the
+@term{Q sub-channel}, which is embedded in each audio sector.  This has
+some interesting implications for the track forward button.
+
+When the track forward button is pressed on a CD player, the CD player
+advances to the next track, skipping that track's @term{pre-gap}.
+This is because the CD player uses the starting address of the track
+from the disc's table of contents (TOC) to determine where to start
+playing a track when either the track forward or track backward
+buttons are pressed.  So to hear a @term{pre-gap} for track 4, the
+listener must either listen to track 3 first, or use the track forward
+or backward buttons to go to track 4, then use the seek backward
+button to back up into track 4's @term{pre-gap}, which is really part
+of track 3, at least according to the TOC.  Track 1 @term{pre-gap}s
+are especially interesting because some commercial discs have audio
+hidden before the beginning of the first track!  The only way to hear
+this hidden audio with a standard player is to use the seek backward
+button as soon as track 1 begins playing!
+
+Audio track @term{pre-gap}s may be specified in a couple of different
+ways in the popular cue file format.  The first way of specifying a
+@term{pre-gap} is to use the @command{PREGAP} command.  This will
+place a @term{pre-gap} containing silence before a track.  The second
+way of specifying a @term{pre-gap} is to give a track an
+@command{INDEX 00} as well as the more normal @command{INDEX 01}.
+@command{INDEX 01} will be used to specify the start of the track in
+the disc's TOC, while @command{INDEX 00} will be used to specify the
+start of the track's @term{pre-gap} as recorded in the @term{Q sub-channel}.
+@command{INDEX 00} is ordinarily used for specifying
+track @term{pre-gap}s that contain audio rather than silence.  Thus,
+the cue file format may be used to specify track @term{pre-gap}s with
+silence or audio, depending on whether the @command{PREGAP} or
+@command{INDEX 00} commands are specified.  If neither type of
+@term{pre-gap} is specified for a track, no @term{pre-gap} is created
+for that track, which merely means the absence of @term{pre-gap}
+information in the @term{Q sub-channel}, and the lack of a short count
+down to the next track.
+
+Various @acronym{CD-DA} ripping programs take various approaches to
+track @term{pre-gap}s.  Some ripping programs ignore track
+@term{pre-gap}s altogether, relying solely on the disc's TOC to
+determine where tracks begin and end.  If a disc is ripped with such a
+program, then re-burned later, the resulting disc will lack track
+@term{pre-gap}s, and thereby lack the playback behavior of counting
+down to the next track.  Other ripping programs detect track
+@term{pre-gap}s and record them in the popular cue file format among
+others.  Such ripping programs sometimes allow the user to determine
+whether track @term{pre-gap}s will be appended to the prior track or
+pre-pended to the track to which they "belong".  Note that if a
+ripping program is ignorant of track @term{pre-gap}s, the track
+@term{pre-gap}s will be appended to the prior track, because that is
+where the disc's TOC puts them.  Thus, there are many different ways
+an application may chose to deal with track @term{pre-gap}s.
+Consequently, @kbd{libcdio} does not dictate the policy a ripping
+program should use in dealing with track @term{pre-gap}s.  Hence,
+@kbd{libcdio} provides the @code{cdio_get_track_pregap_[lba|lsn]()}
+interfaces to allow the application to deal with track @term{pre-gap}s
+as it sees fit.
+
+Note that the @code{cdio_get_track_pregap_[lba|lsn]()} interfaces
+currently only provide information for CDRDAO TOC, CDRWIN BIN/CUE, and
+NRG images.  Getting the track @term{pre-gap}s from a CD drive is a
+more complicated problem because not all CD drives support reading the
+@term{Q sub-channel} @emph{directly} at @emph{high} speed, and there is no
+interface to determine whether or not a drive supports this optional
+feature, aside from trying to read the @term{Q sub-channel}, and
+possibly incurring IO errors.  However, all drives @emph{do} support reading
+the @term{Q sub-channel} @emph{indirectly} while playing an audio disc by
+asking the drive for the current position.  Unfortunately, this occurs
+at normal playback speed, and requires a certain settling time after
+the disc starts playing.  Thus, using this @emph{slow} interface
+requires a more sophisticated algorithm, such as binary search or some
+heuristic, like backing up progressively from the end of the prior
+track to look for the next track's @term{pre-gap}.  Note that CD
+drives seek @emph{slow}ly, so it is better to simply use a drive that
+can read the @term{Q sub-channel} directly at @emph{high} speed, and
+avoid complicated software solutions.  (Not to mention that if the
+user has an older system with an analog audio cable hooked up between
+their soundboard and their drive, and a ripping program uses the
+@emph{slow} interface, the user will hear bits of the audio on the
+disc!)  Consequently, because there is no good universal solution to
+the problem of reading the @term{Q sub-channel} from a drive,
+@kbd{libcdio} currently leaves this problem up to the application, a
+problem which is readily approachable through either @kbd{libcdio}'s
+MMC interface or @kbd{libcdio}'s cdda interface.  For an example of
+one such application, see @url{https://gna.org/projects/cued/}.
+
+The preceding section on track @term{pre-gaps} and @acronym{CD-DA} was
+contributed by Robert William Fuller (@email{hydrologiccycle@@gmail.com}).
+
+@node How to use
+@chapter How to use
+
+The @value{libcdio} package comes with a number of small example
+programs in the directory @file{example} which demonstrate different
+aspects of the library and show how to use the library. The source
+code to all of the examples here are contained on the package.
+
+Other sources for examples would be the larger utility programs
+@command{cd-drive}, @command{cd-info}, @command{cd-read},
+@command{iso-info}, and @command{iso-read} which are all in the
+@file{src} directory of the @value{libcdio} package.  See also
+@xref{Utility Programs}.
+
+@menu
+* 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
+* Example 4::        use libiso9660 to extract a file from an ISO-9660 image
+* Example 5::        list CD-Text and CD disc mode info
+* Example 6::        run a MMC INQUIRY command
+* Example 7::        using the CD Paranoia library for CD-DA reading
+* All sample programs:: list of all programs in the example directory
+@end menu
+
+@node Example 1
+@section Example 1: list out tracks and LSNs
+Here we will give an annotated example which can be found in the
+distribution as @file{example/tracks.c}.
+
+@smallexample
+ 1: #include <stdio.h>
+ 2: #include <sys/types.h>
+ 3: #include <cdio/cdio.h>
+ 4: int
+ 5: main(int argc, const char *argv[])
+ 6: @{
+ 7:  CdIo_t *p_cdio = cdio_open ("/dev/cdrom", DRIVER_DEVICE);
+ 8:  track_t first_track_num = cdio_get_first_track_num(p_cdio);
+ 9:  track_t i_tracks        = cdio_get_num_tracks(p_cdio);
+10:  int j, i=first_track_num;
+11:
+12:  printf("CD-ROM Track List (%i - %i)\n", first_track_num, i_tracks);
+13
+14:  printf("  #:  LSN\n");
+15:  
+16:  for (j = 0; j < i_tracks; i++, j++) @{
+17:    lsn_t lsn = cdio_get_track_lsn(p_cdio, i);
+18:    if (CDIO_INVALID_LSN != lsn)
+19:      printf("%3d: %06d\n", (int) i, lsn);
+20:  @}
+21:  printf("%3X: %06d  leadout\n", CDIO_CDROM_LEADOUT_TRACK, 
+22:         cdio_get_track_lsn(p_cdio, CDIO_CDROM_LEADOUT_TRACK));
+23:  cdio_destroy(p_cdio);
+24:  return 0;
+25: @}
+@end smallexample 
+
+Already from the beginning on line 2 we see something odd. The
+@code{#include <sys/types.h>} is needed because @value{libcdio}
+assumes type definitions exist for @code{uint32_t}, @code{uint16_t}
+and so on.  Alternatively you change line 2 to:
+
+@smallexample
+#define HAVE_SYS_TYPES_H
+@end smallexample 
+
+and @code{<cdio/cdio.h>} will insert line 2. If you use GNU autoconf
+to configure your program, add @code{sys/types.h} to
+@code{AC_HAVE_HEADERS} and @emph{it} will arrange for
+@code{HAVE_SYS_TYPES_H} to get defined. If you don't have
+@code{<sys/types.h>} but have some other include that defines these
+types, put that instead of line 2. Or you could roll your own
+typedefs. (Note: In the future, this will probably get ``fixed'' by
+requiring glib.h.)
+
+Okay after getting over the hurdle of line 2, the next line pretty
+straightforward: you need to include this to get cdio definitions. One
+of the types that is defined via line 3 is @code{CdIo_t} and a pointer
+that is used pretty much in all operations. Line 6 initializes the
+variable @code{cdio} which we will be using in all of the subsequent
+libcdio calls. It does this via a call to @code{cdio_open()}. 
+
+The second parameter of @code{cdio_open} is DRIVER_UNKNOWN. For any
+given installation a number of Compact Disc device drivers may be
+available. In particular it's not uncommon to have several drivers
+that can read CD disk-image formats as well as a driver that handles
+some CD-ROM piece of hardware. Using DRIVER_UNKNOWN as that second
+parameter we let the library select a driver amongst those that are
+available; generally the first hardware driver that is available is
+the one selected. 
+
+If there is no CD in any of the CD-ROM drives or one does not have
+access to the CD-ROM, it is possible that @value{libcdio} will find a
+CD image in the directory you run this program and will pick a
+suitable CD-image driver. If this is not what you want, but always
+want some sort of CD-ROM driver (or failure if none), then use
+DRIVER_DEVICE instead of DRIVER_UNKNOWN.
+
+Note that in contrast to what is typically done using ioctls to read a
+CD, you don't issue any sort of CD-ROM read TOC command---that is all
+done by the driver. Of course, the information that you get from
+reading the TOC is often desired: many tracks are on the CD, or what
+number the first one is called. This is done through calls on lines 8
+and 9.
+
+For each track, we call a cdio routine to get the logical sector
+number, @code{cdio_get_track_lsn()} on line 17 and print the track
+number and LSN value. Finally we print out the ``lead-out track''
+information and we finally call @code{cdio_destroy()} in line 23 to
+indicate we're done with the CD.
+
+@node Example 2
+@section Example 2: list drivers available and default CD device 
+
+One thing that's a bit hoaky in Example 1 is hard-coding the name of
+the device used: @code{/dev/cdrom}. Although often this is the name of
+a CD-ROM device on GNU/Linux and possibly some other Unix derivatives,
+there are many OSs for which use a different device name.
+
+In the next example, we'll let the driver give us the name of the CD-ROM
+device that is right for it. 
+
+@smallexample
+ 1: #include <stdio.h>
+ 2: #include <sys/types.h>
+ 3: #include <cdio/cdio.h>
+ 4: int
+ 5: main(int argc, const char *argv[])
+ 6: @{
+ 7:   CdIo_t *p_cdio = cdio_open (NULL, DRIVER_DEVICE);
+ 8:   driver_id_t driver_id;
+ 9:  
+10:  if (NULL != p_cdio) @{
+11:    printf("The driver selected is %s\n", cdio_get_driver_name(p_cdio));
+12:    printf("The default device for this driver is %s\n\n", 
+13:           cdio_get_default_device(p_cdio));
+14:    cdio_destroy(p_cdio);
+15:  @} else @{
+16:    printf("Problem in trying to find a driver.\n\n");
+17:  @}
+18:
+19:  for (driver_id=CDIO_MIN_DRIVER; driver_id<=CDIO_MAX_DRIVER; driver_id++)
+20:    if (cdio_have_driver(driver_id))
+21:      printf("We have: %s\n", cdio_driver_describe(driver_id));
+22:    else
+23:      printf("We don't have: %s\n", cdio_driver_describe(driver_id));
+24:  return 0;
+25: @}
+@end smallexample
+
+
+@node Example 3
+@section Example 3: figure out what kind of CD (image) we've got
+
+In this example is a somewhat simplified program to show the use of
+@command{cdio_guess_cd_type()} to  figure out the kind of CD image
+we've got. This can be found in the distribution as @file{example/sample3.c}.
+
+@smallexample
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+#include <stdio.h>
+#include <string.h>
+#include <sys/types.h>
+#include <cdio/cdio.h>
+#include <cdio/cd_types.h>
+
+static void
+print_analysis(cdio_iso_analysis_t cdio_iso_analysis, 
+	       cdio_fs_anal_t fs, int first_data, unsigned int num_audio, 
+	       track_t i_tracks, track_t first_track_num, CdIo_t *cdio)
+@{
+  switch(CDIO_FSTYPE(fs)) @{
+  case CDIO_FS_AUDIO:
+    break;
+  case CDIO_FS_ISO_9660:
+    printf("CD-ROM with ISO 9660 filesystem");
+    if (fs & CDIO_FS_ANAL_JOLIET) @{
+      printf(" and joliet extension level %d", cdio_iso_analysis.joliet_level);
+    @}
+    if (fs & CDIO_FS_ANAL_ROCKRIDGE)
+      printf(" and rockridge extensions");
+    printf("\n");
+    break;
+  case CDIO_FS_ISO_9660_INTERACTIVE:
+    printf("CD-ROM with CD-RTOS and ISO 9660 filesystem\n");
+    break;
+  case CDIO_FS_HIGH_SIERRA:
+    printf("CD-ROM with High Sierra filesystem\n");
+    break;
+  case CDIO_FS_INTERACTIVE:
+    printf("CD-Interactive%s\n", num_audio > 0 ? "/Ready" : "");
+    break;
+  case CDIO_FS_HFS:
+    printf("CD-ROM with Macintosh HFS\n");
+    break;
+  case CDIO_FS_ISO_HFS:
+    printf("CD-ROM with both Macintosh HFS and ISO 9660 filesystem\n");
+    break;
+  case CDIO_FS_UFS:
+    printf("CD-ROM with Unix UFS\n");
+    break;
+  case CDIO_FS_EXT2:
+    printf("CD-ROM with Linux second extended filesystem\n");
+	  break;
+  case CDIO_FS_3DO:
+    printf("CD-ROM with Panasonic 3DO filesystem\n");
+    break;
+  case CDIO_FS_UNKNOWN:
+    printf("CD-ROM with unknown filesystem\n");
+    break;
+  @}
+  switch(CDIO_FSTYPE(fs)) @{
+  case CDIO_FS_ISO_9660:
+  case CDIO_FS_ISO_9660_INTERACTIVE:
+  case CDIO_FS_ISO_HFS:
+    printf("ISO 9660: %i blocks, label `%.32s'\n",
+	   cdio_iso_analysis.isofs_size, cdio_iso_analysis.iso_label);
+    break;
+  @}
+  if (first_data == 1 && num_audio > 0)
+    printf("mixed mode CD   ");
+  if (fs & CDIO_FS_ANAL_XA)
+    printf("XA sectors   ");
+  if (fs & CDIO_FS_ANAL_MULTISESSION)
+    printf("Multisession");
+  if (fs & CDIO_FS_ANAL_HIDDEN_TRACK)
+    printf("Hidden Track   ");
+  if (fs & CDIO_FS_ANAL_PHOTO_CD)
+    printf("%sPhoto CD   ", 
+		      num_audio > 0 ? " Portfolio " : "");
+  if (fs & CDIO_FS_ANAL_CDTV)
+    printf("Commodore CDTV   ");
+  if (first_data > 1)
+    printf("CD-Plus/Extra   ");
+  if (fs & CDIO_FS_ANAL_BOOTABLE)
+    printf("bootable CD   ");
+  if (fs & CDIO_FS_ANAL_VIDEOCD && num_audio == 0) @{
+    printf("Video CD   ");
+  @}
+  if (fs & CDIO_FS_ANAL_SVCD)
+    printf("Super Video CD (SVCD) or Chaoji Video CD (CVD)");
+  if (fs & CDIO_FS_ANAL_CVD)
+    printf("Chaoji Video CD (CVD)");
+  printf("\n");
+@}
+
+int
+main(int argc, const char *argv[])
+@{
+  CdIo_t *p_cdio = cdio_open (NULL, DRIVER_UNKNOWN);
+  cdio_fs_anal_t fs=0;
+  
+  track_t i_tracks;
+  track_t first_track_num;
+  lsn_t start_track;          /* first sector of track */
+  lsn_t data_start =0;        /* start of data area */
+
+  int first_data = -1;        /* # of first data track */
+  int first_audio = -1;       /* # of first audio track */
+  unsigned int num_data  = 0; /* # of data tracks */
+  unsigned int num_audio = 0; /* # of audio tracks */
+  unsigned int i;
+
+  if (NULL == p_cdio) @{
+    printf("Problem in trying to find a driver.\n\n");
+    return 1;
+  @}
+
+  first_track_num = cdio_get_first_track_num(p_cdio);
+  i_tracks      = cdio_get_num_tracks(p_cdio);
+
+  /* Count the number of data and audio tracks. */
+  for (i = first_track_num; i <= i_tracks; i++) @{
+    if (TRACK_FORMAT_AUDIO == cdio_get_track_format(p_cdio, i)) @{
+      num_audio++;
+      if (-1 == first_audio) first_audio = i;
+    @} else @{
+      num_data++;
+      if (-1 == first_data)  first_data = i;
+    @}
+  @}
+
+  /* try to find out what sort of CD we have */
+  if (0 == num_data) @{
+    printf("Audio CD\n");
+  @} else @{
+    /* we have data track(s) */
+    int j;
+    cdio_iso_analysis_t cdio_iso_analysis; 
+
+    memset(&cdio_iso_analysis, 0, sizeof(cdio_iso_analysis));
+    
+    for (j = 2, i = first_data; i <= i_tracks; i++) @{
+      lsn_t lsn;
+      track_format_t track_format = cdio_get_track_format(p_cdio, i);
+      
+      lsn = cdio_get_track_lsn(p_cdio, i);
+      
+      switch ( track_format ) @{
+      case TRACK_FORMAT_AUDIO:
+      case TRACK_FORMAT_ERROR:
+	break;
+      case TRACK_FORMAT_CDI:
+      case TRACK_FORMAT_XA:
+      case TRACK_FORMAT_DATA: 
+      case TRACK_FORMAT_PSX: 
+	;
+      @}
+      
+      start_track = (i == 1) ? 0 : lsn;
+      
+      /* save the start of the data area */
+      if (i == first_data) 
+	data_start = start_track;
+      
+      /* skip tracks which belong to the current walked session */
+      if (start_track < data_start + cdio_iso_analysis.isofs_size)
+	continue;
+      
+      fs = cdio_guess_cd_type(p_cdio, start_track, i, &cdio_iso_analysis);
+      
+      print_analysis(cdio_iso_analysis, fs, first_data, num_audio,
+		     i_tracks, first_track_num, p_cdio);
+      
+      if ( !(CDIO_FSTYPE(fs) == CDIO_FS_ISO_9660 ||
+	     CDIO_FSTYPE(fs) == CDIO_FS_ISO_HFS  ||
+	     CDIO_FSTYPE(fs) == CDIO_FS_ISO_9660_INTERACTIVE) )
+	/* no method for non-ISO9660 multisessions */
+	break;	
+    @}
+  @}
+  cdio_destroy(p_cdio);
+  return 0;
+@}
+@end smallexample
+
+@node Example 4
+@section Example 4: use libiso9660 to extract a file from an ISO-9660 image
+
+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
+is @command{iso-read}, part of this distribution.
+
+@smallexample
+/* This is the ISO 9660 image. */
+#define ISO9660_IMAGE_PATH "../"
+#define ISO9660_IMAGE ISO9660_IMAGE_PATH "test/copying.iso"
+
+#define LOCAL_FILENAME "copying"
+
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+
+#include <sys/types.h>
+#include <cdio/cdio.h>
+#include <cdio/iso9660.h>
+
+#include <stdio.h>
+
+#ifdef HAVE_ERRNO_H
+#include <errno.h>
+#endif
+#ifdef HAVE_STRING_H
+#include <string.h>
+#endif
+#ifdef HAVE_UNISTD_H
+#include <unistd.h>
+#endif
+#ifdef HAVE_SYS_TYPES_H
+#include <sys/types.h>
+#endif
+
+#define my_exit(rc)				\
+  fclose (p_outfd);				\
+  free(p_statbuf);				\
+  iso9660_close(p_iso);				\
+  return rc;					\
+
+int
+main(int argc, const char *argv[])
+@{
+  iso9660_stat_t *p_statbuf;
+  FILE *p_outfd;
+  int i;
+  
+  iso9660_t *p_iso = iso9660_open (ISO9660_IMAGE);
+  
+  if (NULL == p_iso) @{
+    fprintf(stderr, "Sorry, couldn't open ISO 9660 image %s\n", ISO9660_IMAGE);
+    return 1;
+  @}
+
+  p_statbuf = iso9660_ifs_stat_translate (p_iso, LOCAL_FILENAME);
+
+  if (NULL == p_statbuf) 
+    @{
+      fprintf(stderr, 
+	      "Could not get ISO-9660 file information for file %s\n",
+	      LOCAL_FILENAME);
+      iso9660_close(p_iso);
+      return 2;
+    @}
+
+  if (!(p_outfd = fopen (LOCAL_FILENAME, "wb")))
+    @{
+      perror ("fopen()");
+      free(p_statbuf);
+      iso9660_close(p_iso);
+      return 3;
+    @}
+
+  /* Copy the blocks from the ISO-9660 filesystem to the local filesystem. */
+  for (i = 0; i < p_statbuf->size; i += ISO_BLOCKSIZE)
+    @{
+      char buf[ISO_BLOCKSIZE];
+
+      memset (buf, 0, ISO_BLOCKSIZE);
+      
+      if ( ISO_BLOCKSIZE != iso9660_iso_seek_read (p_iso, buf, p_statbuf->lsn 
+						   + (i / ISO_BLOCKSIZE),
+						   1) )
+      @{
+	fprintf(stderr, "Error reading ISO 9660 file at lsn %lu\n",
+		(long unsigned int) p_statbuf->lsn + (i / ISO_BLOCKSIZE));
+	my_exit(4);
+      @}
+      
+      
+     fwrite (buf, ISO_BLOCKSIZE, 1, p_outfd);
+      
+     if (ferror (p_outfd))
+        @{
+          perror ("fwrite()");
+          my_exit(5);
+        @}
+    @}
+  
+  fflush (p_outfd);
+
+  /* Make sure the file size has the exact same byte size. Without the
+     truncate below, the file will a multiple of ISO_BLOCKSIZE.
+   */
+  if (ftruncate (fileno (p_outfd), p_statbuf->size))
+    perror ("ftruncate()");
+
+  my_exit(0);
+@}
+@end smallexample
+
+@node Example 5
+@section Example 5: list CD-Text and disc mode info
+
+Next a program to show using @command{libcdio} to list CD-TEXT data.
+This can be found in the distribution as @file{example/cdtext.c}.
+
+@smallexample
+/* Simple program to list CD-Text info of a Compact Disc using libcdio. */
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+#include <stdio.h>
+#include <sys/types.h>
+#include <cdio/cdio.h>
+#include <cdio/cdtext.h>
+
+
+static void 
+print_cdtext_track_info(CdIo_t *p_cdio, track_t i_track, const char *message) @{
+  const cdtext_t *cdtext    = cdio_get_cdtext(p_cdio, 0);
+  if (NULL != cdtext) @{
+    cdtext_field_t i;
+    
+    printf("%s\n", message);
+    
+    for (i=0; i < MAX_CDTEXT_FIELDS; i++) @{
+      if (cdtext->field[i]) @{
+        printf("\t%s: %s\n", cdtext_field2str(i), cdtext->field[i]);
+      @}
+    @}
+  @}
+  
+@}
+    
+static void 
+print_disc_info(CdIo_t *p_cdio, track_t i_tracks, track_t i_first_track) @{
+  track_t i_last_track = i_first_track+i_tracks;
+  discmode_t cd_discmode = cdio_get_discmode(p_cdio);
+
+  printf("%s\n", discmode2str[cd_discmode]);
+  
+  print_cdtext_track_info(p_cdio, 0, "\nCD-Text for Disc:");
+  for ( ; i_first_track < i_last_track; i_first_track++ ) @{
+    char psz_msg[50];
+    sprintf(msg, "CD-Text for Track %d:", i_first_track);
+    print_cdtext_track_info(p_cdio, i_first_track, psz_msg);
+  @}
+@}
+
+int
+main(int argc, const char *argv[])
+@{
+  track_t i_first_track;
+  track_t i_tracks;
+  CdIo_t *p_cdio;
+  cdio = cdio_open (NULL, DRIVER_UNKNOWN);
+  i_first_track = cdio_get_first_track_num(p_cdio);
+  i_tracks      = cdio_get_num_tracks(p_cdio);
+
+  if (NULL == p_cdio) @{
+    printf("Couldn't find CD\n");
+    return 1;
+  @} else @{
+    print_disc_info(p_cdio, i_tracks, i_first_track);
+  @}
+
+  cdio_destroy(p_cdio);
+  
+  return 0;
+@}
+@end smallexample 
+
+@node Example 6
+@section Example 6: Using MMC to run an @code{INQURY} command
+
+Now a program to show issuing a simple MMC command
+(@code{INQUIRY}). This MMC command retrieves the vendor, model and
+firmware revision number of a CD drive. For this command to work,
+usually a CD to be loaded into the drive; odd since the CD itself is
+not used.
+
+This can be found in the distribution as @file{example/mmc1.c}.
+
+@smallexample
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+#include <stdio.h>
+#include <sys/types.h>
+#include <cdio/cdio.h>
+#include <cdio/scsi_mmc.h>
+#include <string.h>
+
+/* Set how long to wait for MMC commands to complete */
+#define DEFAULT_TIMEOUT_MS 10000
+
+int
+main(int argc, const char *argv[])
+@{
+  CdIo_t *p_cdio;
+
+  p_cdio = cdio_open (NULL, DRIVER_UNKNOWN);
+
+  if (NULL == p_cdio) @{
+    printf("Couldn't find CD\n");
+    return 1;
+  @} else @{
+    int i_status;                  /* Result of MMC command */
+    char buf[36] = @{ 0, @};         /* Place to hold returned data */
+    scsi_mmc_cdb_t cdb = @{@{0, @}@};  /* Command Descriptor Buffer */
+
+    CDIO_MMC_SET_COMMAND(cdb.field, CDIO_MMC_GPCMD_INQUIRY);
+    cdb.field[4] = sizeof(buf);
+
+    i_status = scsi_mmc_run_cmd(p_cdio, DEFAULT_TIMEOUT_MS, 
+				&cdb, SCSI_MMC_DATA_READ, 
+				sizeof(buf), &buf);
+    if (i_status == 0) @{
+      char psz_vendor[CDIO_MMC_HW_VENDOR_LEN+1];
+      char psz_model[CDIO_MMC_HW_MODEL_LEN+1];
+      char psz_rev[CDIO_MMC_HW_REVISION_LEN+1];
+      
+      memcpy(psz_vendor, buf + 8, sizeof(psz_vendor)-1);
+      psz_vendor[sizeof(psz_vendor)-1] = '\0';
+      memcpy(psz_model,
+	     buf + 8 + CDIO_MMC_HW_VENDOR_LEN, 
+	     sizeof(psz_model)-1);
+      psz_model[sizeof(psz_model)-1] = '\0';
+      memcpy(psz_rev,
+	     buf + 8 + CDIO_MMC_HW_VENDOR_LEN +CDIO_MMC_HW_MODEL_LEN,
+	     sizeof(psz_rev)-1);
+      psz_rev[sizeof(psz_rev)-1] = '\0';
+
+      printf("Vendor: %s\nModel: %s\nRevision: %s\n",
+	     psz_vendor, psz_model, psz_rev);
+    @} else @{
+      printf("Couldn't get INQUIRY data (vendor, model, and revision\n");
+    @}
+  @}
+  
+  cdio_destroy(p_cdio);
+  
+  return 0;
+@}
+@end smallexample 
+
+@node Example 7
+@section Example 7: Using the CD Paranoia library for CD-DA reading
+
+@smallexample
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+
+#include <cdio/cdda.h>
+#include <cdio/cd_types.h>
+#include <stdio.h>
+
+#ifdef HAVE_STDLIB_H
+#include <stdlib.h>
+#endif
+
+int
+main(int argc, const char *argv[])
+@{
+  cdrom_drive_t *d = NULL; /* Place to store handle given by cd-paranoia. */
+  char **ppsz_cd_drives;   /* List of all drives with a loaded CDDA in it. */
+
+  /* See if we can find a device with a loaded CD-DA in it. */
+  ppsz_cd_drives = cdio_get_devices_with_cap(NULL, CDIO_FS_AUDIO, false);
+
+  if (ppsz_cd_drives) @{
+    /* Found such a CD-ROM with a CD-DA loaded. Use the first drive in
+       the list. */
+    d=cdio_cddap_identify(*ppsz_cd_drives, 1, NULL);
+  @} else @{
+    printf("Unable find or access a CD-ROM drive with an audio CD in it.\n");
+    exit(1);
+  @}
+
+  /* Don't need a list of CD's with CD-DA's any more. */
+  cdio_free_device_list(ppsz_cd_drives);
+
+  /* We'll set for verbose paranoia messages. */
+  cdio_cddap_verbose_set(d, CDDA_MESSAGE_PRINTIT, CDDA_MESSAGE_PRINTIT);
+
+  if ( 0 != cdio_cddap_open(d) ) @{
+    printf("Unable to open disc.\n");
+    exit(1);
+  @}
+
+  /* Okay now set up to read up to the first 300 frames of the first
+     audio track of the Audio CD. */
+  @{ 
+    cdrom_paranoia_t *p = cdio_paranoia_init(d);
+    lsn_t i_first_lsn = cdio_cddap_disc_firstsector(d);
+
+    if ( -1 == i_first_lsn ) @{
+      printf("Trouble getting starting LSN\n");
+    @} else @{
+      lsn_t   i_cursor;
+      track_t i_track    = cdio_cddap_sector_gettrack(d, i_first_lsn);
+      lsn_t   i_last_lsn = cdio_cddap_track_lastsector(d, i_track);
+
+      /* For demo purposes we'll read only 300 frames (about 4
+	 seconds).  We don't want this to take too long. On the other
+	 hand, I suppose it should be something close to a real test.
+       */
+      if ( i_last_lsn - i_first_lsn > 300) i_last_lsn = i_first_lsn + 299;
+
+      printf("Reading track %d from LSN %ld to LSN %ld\n", i_track, 
+	     (long int) i_first_lsn, (long int) i_last_lsn);
+
+      /* Set reading mode for full paranoia, but allow skipping sectors. */
+      paranoia_modeset(p, PARANOIA_MODE_FULL^PARANOIA_MODE_NEVERSKIP);
+
+      paranoia_seek(p, i_first_lsn, SEEK_SET);
+
+      for ( i_cursor = i_first_lsn; i_cursor <= i_last_lsn; i_cursor ++) @{
+	/* read a sector */
+	int16_t *p_readbuf=cdio_paranoia_read(p, NULL);
+	char *psz_err=cdio_cddap_errors(d);
+	char *psz_mes=cdio_cddap_messages(d);
+
+	if (psz_mes || psz_err)
+	  printf("%s%s\n", psz_mes ? psz_mes: "", psz_err ? psz_err: "");
+
+	if (psz_err) free(psz_err);
+	if (psz_mes) free(psz_mes);
+	if( !p_readbuf ) @{
+	  printf("paranoia read error. Stopping.\n");
+	  break;
+	@}
+      @}
+    @}
+    cdio_paranoia_free(p);
+  @}
+
+  cdio_cdda_close(d);
+
+  exit(0);
+@}
+@end smallexample 
+
+Those who are die-hard cdparanoia programmers will notice that the
+@value{libcdio} paranoia names are similar but a little bit
+different. In particular instead of @code{paranoia_read} we have above
+@code{cdio_paranoia_read} and instead of @code{cdda_open} we have
+@code{cdio_cddap_open}.
+
+This was done intentionally so that it is possible for the original
+paranoia program can co-exist both in source code and linked libraries
+and not conflict with @value{libcdio}'s paranoia source and libraries.
+
+In general in place of any paranoia routine that begins
+@code{paranoia_}, use @code{cdio_paranoia_} and in place of any
+paranoia routine that begins @code{cdda_}, use @code{cdio_cddap_}. But
+for a limited time @value{libcdio} will accept the old paranoia names
+which may be useful for legacy paranoia code. The way this magic works
+is by defining the old paranoia name to be the @value{libcdio} name.
+
+In the unusual case where you do want to use both the original
+paranoia and @value{libcdio} routines in a single source, the C
+preprocessor symbol @code{DO_NOT_WANT_PARANOIA_COMPATIBILITY} can be
+@code{define}'d and this disables the @code{#define} substitution done
+automatically. The may still be a problem with conflicting structure
+definitions like @code{cdrom_drive_t}.
+
+@node All sample programs
+@section A list of all sample programs in the @code{example} directory
+
+The @code{example} directory contains some simple examples of the use
+of the @value{libcdio} library.
+
+A larger more-complicated example are the @command{cd-drive},
+@command{cd-info}, @command{cd-read}, @command{iso-info} and
+@command{iso-info} programs in the @command{src} directory.
+
+Descriptions of the sample are as follows...
+
+@table @code 
+
+@item @code{cdchange.c}
+
+A program to test if a CD has been changed since the last change test.
+
+@item @code{cdtext.c}
+
+A program to show CD-Text and CD disc mode info.
+
+@item @code{drives.c}
+
+A program to show drivers installed and what the default CD-ROM drive
+is and what CD drives are available.
+
+@item @code{eject.c}
+
+A program eject a CD from a CD-ROM drive and then close the door again.
+
+@item @code{isolist.c}
+
+A program to show using @code{libiso9660} to list files in a
+	directory of an ISO-9660 image.
+
+@item @code{C++/isolist.cpp}
+
+The same program as @code{isolist.c} written in C++.
+
+@item @code{iso2.c}
+
+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++.
+
+@item @code{isofuzzy.c}
+
+A program showing fuzzy ISO-9660 detection/reading.
+
+@item @code{mmc1.c}
+
+A program to show issuing a simple MMC command (@code{INQUIRY}).
+
+@item @code{C++/mmc1.cpp}
+
+The same program as @code{mmc1.c} written in C++.
+
+@item @code{mmc2.c}
+
+A more involved MMC command to list CD and drive features from a
+SCSI-MMC @code{GET_CONFIGURATION} command.
+
+@item @code{mmc2a.c}
+
+Prints MMC @command{MODE_SENSE} page 2A parameters. 
+Page 2a are the CD/DVD Capabilities and Mechanical Status.
+
+@item @code{C++/mmc2.cpp}
+
+The same program as @code{mmc2.c} written in C++.
+
+@item @code{paranoia.c}
+
+A program to show using libcdio's version of the CD-DA paranoia. 
+
+@item @code{paranoia2.c}
+
+A program to show using libcdio's version of the CD-DA paranoia
+library. But in this version, we'll open a cdio object before calling
+paranoia's open. I imagine in many cases such as media players this
+may be what will be done since, one may want to get CDDB/CD-Text info
+beforehand. 
+
+@item @code{tracks.c}
+
+A simple program to list track numbers and logical sector numbers of a
+Compact Disc using @value{libcdio}.
+
+@item @code{sample2.c}
+
+A simple program to show drivers installed and what the default CD-ROM
+drive is.
+
+@item @code{sample3.c}
+
+A simple program to show the use of @code{cdio_guess_cd_type()}.  Figures out
+the kind of CD image we've got.
+
+@item @code{sample4.c}
+
+ A slightly improved sample3 program: we handle cdio logging and take
+an optional CD-location.
+
+@item @code{udf1.c}
+
+A program to show using libudf to list files in a directory of an UDF
+image.
+
+@item @code{udf2.c}
+
+A program to show using libudf to extract a file from an UDF image.
+
+@end table
+
+@node Utility Programs
+@chapter Diagnostic programs: @command{cd-drive}, @command{cd-info}, @command{cd-read}, @command{iso-info}, @command{iso-read}
+
+@menu
+* cd-drive::       list out CD-ROM drive information
+* cd-info::        list out CD or CD-image information
+* cd-read::        read blocks of a CD or CD image
+* iso-info::       list out ISO-9600 image information
+* iso-read::       extract a file from an ISO 9660 image
+@end menu
+
+@node cd-drive
+@section @samp{cd-drive}
+
+@samp{cd-drive} lists out drive information, what features drive
+supports, and information about what hardware drivers are available.
+
+@node cd-info
+@section @samp{cd-info}
+
+@samp{cd-info} will print out the structure of a CD medium which could
+either be a Compact Disc in a CD ROM or an CD image. It can try to
+analyze the medium to give characteristics of the medium, such as how
+many tracks are in the CD and the format of each track, whether a CD
+contains a Video CD, CD-DA, PhotoCD, whether a track has an ISO-9660
+filesystem.
+
+@node cd-read
+@section @samp{cd-read}
+
+@samp{cd-info} can be used to read blocks a CD medium which could
+either be a Compact Disc in a CD ROM or an CD image. You specify the
+beginning and ending LSN and what mode format to use in the reading.
+
+@node iso-info
+@section @samp{iso-info}
+
+@samp{iso-info} can be used to print out the structure of an ISO 9660 
+image.
+
+@node iso-read
+@section @samp{iso-read}
+
+@samp{iso-read} can be used to extract a file in an ISO-9660 image.
+
+@node CD-ROM Access and Drivers
+@chapter CD-ROM Access and Drivers
+
+@menu
+* MMC::  ``SCSI'' Multimedia Commands (MMC)
+* GNU/Linux:: GNU/Linux ioctl
+* Microsoft:: Microsoft Windows ioctl and ASPI
+* Solaris:: Solaris ATAPI and SCSI
+* FreeBSD:: FreeBSD ioctl and CAM
+* OS X::  OSX (non-exclussive access)
+@end menu
+
+@node MMC
+@section Multimedia Commands (MMC)
+
+In contrast to the rest of the sections in this chapter, MMC
+(Multimedia commands) is not a driver per se, although many of the
+CD-ROM drivers do in fact issue MMC commands. MMC commands
+gives (in theory) a broad and uniform way to access a CD-ROM drive.
+
+If your CD-ROM drive understands MMC commands this is probably gives
+the most flexibility in control. SCSI and ATAPI CD-ROM devices
+generally support a fairly large set of MMC commands.
+
+The name ``SCSI MMC'' is often found in the literature in
+specifications and on the Internet. The ``SCSI'' part is probably a
+little bit misleading because a drive can understand ``SCSI MMC''
+commands but not use a SCSI interface---ATAPI CD-ROMs are one such
+broad class of examples. In fact there are drivers to ``encapsulate''
+non-SCSI drives or a non-MMC-compliant drives and make them act like
+MMC drives. I believe that many OS SCSI ``pass-through'' mechanisms do
+roughly the same thing.
+
+The name ``SCSI MMC'' is no doubt due to the fact that these commands
+grew out of the SCSI command set and thus were bundled in them. 
+
+For clarity and precision we will use the term ``MMC'' rather than
+``SCSI MMC''.
+
+One of the problems with MMC is that there are so many different
+``standards''. In particular there are MMC
+@url{ftp://ftp.t10.org/t10/drafts/mmc/}, MMC 2
+@url{ftp://ftp.t10.org/t10/drafts/mmc2/}, MMC 3
+@url{ftp://ftp.t10.org/t10/drafts/mmc3/}, MMC 4
+@url{ftp://ftp.t10.org/t10/drafts/mmc4/}, and MMC 5
+@url{ftp://ftp.t10.org/t10/drafts/mmc5/} standards several ``drafts''
+for each standard. The good news about ATAPI drives is that they too
+understand some sort of MMC subset. The bad news (as I understand
+it) is that they do not understand any full MMC command set.
+
+Another problem with the MMC commands related to the variations in
+standards is the variation in the commands themselves and there are
+perhaps two or three ways to do many of the basic commands like read a
+CD frame.
+
+There seems to be a fascination with the number of bytes a command
+takes in the MMC-specification world. (Size matters?) So often the
+name of an operation will have a suffix with the number of bytes of
+the command (actually in MMC jargon this is called a ``CDB''
+@cindex CDB (Command Descriptor Block)
+or command descriptor block). So for example there is a 6-byte ``MODE
+SELECT'' often called ``MODE SELECT 6'' and a 10-byte ``MODE SELECT''
+often called ``MODE SELECT 10''. Presumably the 6-byte command came
+first and it was discovered that there was some deficiency causing the
+longer command. In @value{libcdio} where there are two formats we add
+the suffix in the name, e.g. @code{CDIO_MMC_GPCMD_MODE_SELECT_6} or
+@code{CDIO_MMC_GPCMD_MODE_SELECT_10}.
+
+If the fascination and emphasis in the MMC specifications of CDB size
+is a bit odd, equally so is the fact that this too often has bled
+through at the OS programming API. However in @value{libcdio}, you
+just give the opcode in @code{scsi_mmc_run_cmd()} and we'll do the
+work to figure out how many bytes of the CDB are used.
+
+Down the line it is hoped that @value{libcdio} will have a way to
+remove a distinction between the various alternative and
+alternative-size MMC commands. In @code{cdio/scsi-mmc.h} you will
+find a little bit of this for example via the routine
+@code{scsi_mmc_get_drive_cap()}. However much more work is needed.
+
+@node GNU/Linux
+@section GNU/Linux
+
+The GNU/Linux uses a hybrid of methods. Somethings are done vai ioctl
+and some things via MMC. GNU/Linux has a rather nice and complete
+ioctl mechanism. On the other hand, the MMC mechanism is more
+universal.  There are other ``access modes'' listed which are not
+really access modes and should probably be redone/rethought.  They are
+just different ways to run the read command. But for completeness
+These are ``READ_CD'' and ``READ_10''.
+
+@node Microsoft
+@section Microsoft Windows ioctl and ASPI
+
+There are two CD drive access methods on Microsoft Windows platforms:
+ioctl and ASPI. 
+
+The ASPI interface specification was developed by Adaptec for 
+sending commands to a SCSI host adapter (such as those controlling CD
+and DVD drives) and used on Window 9x/NT and later. Emulation for
+ATAPI drives was added so that the same sets of commands worked those
+even though the drives might not be SCSI nor might there even be a
+SCSI controller attached.
+
+However in Windows NT/2K/XP, Microsoft provides their Win32 ioctl
+interface, and has taken steps to make using ASPI more inaccessible
+(e.g. requiring administrative access to use ASPI).
+
+
+@node Solaris
+@section Solaris ATAPI and SCSI
+
+There is currently only one CD drive access methods in Solaris: SCSI
+(called ``USCSI'' or ``user SCSI'' in Solaris). There used to be an
+ATAPI method and it could be resurrected if needed. USCSI was
+preferred since on newer releases of Solaris and Solaris environments
+one would needs to have root access for ATAPI.
+
+@node FreeBSD
+@section FreeBSD ioctl and CAM
+
+There are two CD drive access methods on Solaris: ioctl and CAM
+(common access method). CAM is preferred when possible, especially on
+newer releases. However CAM is right now sort of a hybrid and includes
+some ioctl code.
+
+More work on this driver is needed. Volunteers? 
+
+@node OS X
+@section OS X (non-exclusive access)
+
+A problem with OS/X is that if the OS thinks it understands the drive
+it gains exclusive access to it and thus prevents a library like this
+to get non-exclusive access. 
+
+Currently @value{libcdio} access the CD-ROM non-exclusively. However
+in order to be able to issue MMC, the current belief is that
+exclusive access is needed. Probably in a future @value{libcdio},
+there will be some way to specify which kind of access is desired
+(with the inherent consequences of each).
+
+More work on this driver is needed. Volunteers?
+
+@node Internal Program Organization
+@chapter Internal Program Organization
+
+@subsection file organization
+
+Here is a list of @value{libcdio} directories.
+
+@itemize
+
+@item @code{include/cdio}
+
+This contains the headers that are public. One that will probably be
+used quite a bit is @code{<cdio/cdio.h>}.
+
+@item @code{lib}
+
+Code for installed libraries. See below for further breakout
+
+@item @code{lib/driver}
+
+Code for various OS-specific CD-ROM drivers, image drivers, and
+common MMC routines. 
+
+This code comprises @code{libcdio.a} (or the shared version of it).
+
+@item @code{lib/iso9660}
+
+Code for to extract or query ISO-9660 images.
+
+This code comprises @code{libiso9660.a} (or the shared version of it).
+
+@item @code{lib/paranoia}
+
+This is from cdparanoia. It is the OS- and hardware- dependent code to
+detect and correct jitter for CD-DA CDs.
+
+@item @code{lib/cdda_interface}
+
+This is also from cdparanoia. It is the OS- and hardware- independent
+code to detect and correct jitter for CD-DA CDs.
+
+@item @code{doc}
+
+A home for fine documentation such as this masterpiece.
+
+@item @code{example}
+
+Here you will find various small example programs using
+@value{libcdio} which are largely for pedagogical purposes. You might
+be able to find one that is similar to what you want to do that could
+be extended. In fact some these are contain the kernel ideas behind of
+some of the larger programs in @file{src}.
+
+@item @code{src}
+
+Various stand-alone utility programs. See below.
+
+@item @code{src/paranoia}
+
+@value{libcdio}'s version of @code{cdparanoia}. Except for the fact
+that the back-end CD-reading code has been replaced by
+@value{libcdio}'s routines the code is pretty much identical. 
+
+@item @code{test}
+
+Regression tests
+
+@end itemize
+
+@subsection @samp{libcdio}
+
+@value{libcdio} exports one opaque type @code{CdIo_t}. Internally this
+a structure containing an enumeration for the driver, a structure
+containing function pointers and a generic ``environment'' pointer
+which is passed as a parameter on a function call. See
+@file{lib/driver/cdio_private.h}. The initialization routine for each
+driver sets up the function pointers and allocates memory for the
+environment. When a particular user-level cdio routine is called (e.g
+@code{cdio_get_first_track_num} for lib/driver/track.c), the
+environment pointer is passed to a device-specific routine which will
+then cast this pointer into something of the appropriate type.
+
+Because function pointers are used, there can be and is quite a bit
+of sharing of common routines. Some of the common routines are found
+in the file @file{lib/driver/_cdio_generic.c}. 
+
+Another set of routines that one is likely to find shared amongst
+drivers are the MMC commands. These are located in
+@file{lib/driver/scsi_mmc.c}. 
+
+There is not only an attempt to share functions but we've tried to create
+a generic CD structure @code{generic_img_private_t} of file
+@file{lib/driver/generic.h}. By putting information into a common
+structure, we increase the likelihood of being able to have a common
+routine to perform some sort of function. 
+
+The generic CD structure would also be useful in a utility to convert
+one CD-image format to another. Basically the first image format is
+``parsed'' into the common internal format and then from this
+structure it is not parsed.
+
+@subsection @samp{libiso9660}
+
+To be completed....
+
+@subsection Coding Conventions
+
+In @value{libcdio} there are a number of conventions used. If you
+understand some of these conventions it may facilitate understanding
+the code a little. 
+
+@subsubsection namespace names
+
+For the most part, the visible external @value{libcdio} names follow
+conventions so as not to be confused with other applications or
+libraries. If you understand these conventions, there will be little
+or no chance that the names you use will conflict with @value{libcdio}
+and @code{libiso9660} and vice versa.
+
+All of the external @value{libcdio} C routines start out with
+@code{cdio_}, e.g. @code{cdio_open}; as a corollary, the
+@value{libcdio} CD-Paranoia routines start @code{cdio_cddap_},
+e.g. @code{cdio_cddap_open}.  @code{libiso9660} routines start
+@code{iso9660_}, e.g. @code{iso9660_open}.
+
+@value{libcdio} C-Preprocessor names generally start @code{CDIO_}, for
+example @code{CDIO_CD_FRAMESIZE_RAW}; @code{libiso9660}
+C-preprocessor names start @code{ISO9660_},
+e.g. @code{ISO9660_FRAMESIZE}.
+
+@subsubsection suffixes (type and structure names)
+
+A few suffixes are used in type and structure names:
+
+@itemize
+
+@item @code{_e}
+
+An enumeration tag. Generally though the same name will appear with the
+@code{_t} suffix and probably that should be used instead.
+
+@item @code{_s}
+
+A structure tag. Generally though the same name will appear with the
+@code{_t} suffix and probably that should be used instead.
+
+@item @code{_t}
+
+A type suffix. 
+
+@end itemize
+
+@subsubsection prefixes (variable names)
+
+A number of prefixes are used in variable names here's what they mean
+
+@itemize
+@item @code{i_}
+
+An integer type of some sort. A variable of this ilk one might find
+being iterated over in @code{for} loops or used as the index of an
+array for example.
+
+@item @code{b_}
+
+A Boolean type of some sort. A variable of this ilk one might find
+being in an @code{if} condition for example.
+
+@item @code{p_}
+
+A pointer of some sort. A variable of this ilk, say
+@code{p_foo} one is like likely to see @code{*p_foo} or
+@code{p_foo->...}.
+
+@item @code{pp_}
+
+A pointer to a pointer of some sort. A variable of this ilk, say
+@code{pp_foo} one is like likely to see @code{**p_foo} or
+@code{p_foo[x][y]} for example
+
+@item @code{psz_}
+
+A @code{char *} pointer of some sort. A variable of this ilk, say
+@code{psz_foo} may be used in a string operation. For example
+@code{printf(%s\n", psz_foo)} or @code{strdup(psz_foo)}.
+
+@item @code{ppsz_}
+
+A pointer to a @code{char *} pointer of some sort. A variable of this
+ilk, say @code{ppsz_foo} is used for example to return a list of
+CD-ROM device names
+
+@end itemize
+
+There are a some other naming conventions. Generally if a routine
+name starts @code{cdio_}, e.g. @code{cdio_open}, then it is an
+externally visible routine in @code{libcdio}. If a name starts
+@code{iso9660_}, e.g. @code{iso9660_is_dchar} then it is an externally
+visible routine in @code{libiso9660}. If a name starts
+@code{scsi_mmc_}, e.g. @code{scsi_mmc_get_discmode}, then it is an
+externally visible MMC routine. (We don't have a separate library for
+this yet.
+
+Names using entirely capital letters and that start @code{CDIO_} are
+externally visible @code{#defines}.
+
+
+@node ISO-9660 Character Sets
+@appendix ISO-9660 Character Sets
+
+For a description of where are used see @xref{ISO 9660 Level 1}.
+
+@menu
+* ISO646 d-Characters::         
+* ISO646 a-Characters::         
+@end menu
+
+@node ISO646 d-Characters
+@appendixsec ISO646 d-Characters
+
+@example
+  | 0 1 2 3 4 5 6 7 
+--+-----------------
+0 |       0   P     
+1 |       1 A Q     
+2 |       2 B R     
+3 |       3 C S     
+4 |       4 D T     
+5 |       5 E U     
+6 |       6 F V     
+7 |       7 G W     
+8 |       8 H X     
+9 |       9 I Y     
+a |         J Z     
+b |         K       
+c |         L       
+d |         M       
+e |         N       
+f |         O _     
+@end example
+
+@node ISO646 a-Characters
+@appendixsec ISO646 a-Characters
+
+@example
+  | 0 1 2 3 4 5 6 7
+--+-----------------
+0 |       0   P                    
+1 |     ! 1 A Q                    
+2 |     " 2 B R                    
+3 |       3 C S                    
+4 |       4 D T                    
+5 |     % 5 E U                    
+6 |     & 6 F V                    
+7 |     ' 7 G W                    
+8 |     ( 8 H X                    
+9 |     ) 9 I Y                    
+a |     * : J Z                    
+b |     + ; K                      
+c |     , < L                      
+d |     - = M                      
+e |     . > N                      
+f |     / ? O _                    
+@end example
+
+@node Glossary
+@appendix Glossary
+
+@include glossary.texi
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@cindex FDL, GNU Free Documentation License
+
+@include fdl.texi
+
+@node General Index
+@unnumbered General Index
+@printindex cp
+
+@bye