libcdio.texi: More sectioning with respect to the libraries

glossary.texi: Add Thomas Schmitt's DVD Blu-Ray and media information.

doc/glossary.texi

@@ -33,8 +33,15 @@ 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 Blu-ray Disc (BD)
+@cindex Blu-ray Disc (BD)
+Optical media with capacity of 25 GB as single layer and 50 GB
+as double layer. See also "Media models and profiles".
+
+
 @item CD
-Compact Disc
+@cindex CD
+Compact Disc. Capacity up to 900 MB. See also "Media models and profiles".
 
 @item CD-DA
 @cindex CD-DA
@@ -114,6 +121,20 @@ translators. But also a CD-I player can read CD-XA discs even if
 its own `Green Book' file system only resembles ISO 9660 and isn't
 fully compatible. 
 
+@item DVD
+@cindex DVD
+Digital Versatile Disc. Capacity up to 4.5 GB as single layer and
+8.5 GB as double layer media. See also "Media models and profiles".
+
+@item Defect management
+@cindex Defect management
+A method to compensate small amounts of bad spots on media by replacing
+them out of a pool of reserve blocks and performing address translation.
+The necessary checkreading slows down write performance by a factor of 2 or 3.
+Defect management applies by default to DVD-RAM and BD-RE. Optionally it
+can be formatted onto CD-RW and DVD+RW, where it has the name "Mount Rainier".
+Sequential BD-R can be formatted for defect management too.
+
 @item Command Packet
 @cindex Command Packet
 
@@ -260,6 +281,70 @@ DVD-Rewriters, etc.
 Many manufacturers have adopted this standard and it also applies to
 ATAPI versions of their drives.
 
+@item Media models and profiles
+@cindex Media models and profiles
+
+MMC classifies media as models, which describe their logical structure,
+and as profiles, which describe the capabilities of the drive with the
+particular media. So both are closely related but not identical.
+
+There are three model families: CD, DVD, Blu-ray.
+CD allows special sector formats like audio as well as data
+sectors of 2048 bytes. DVD and Blu-ray only record data sectors.
+@table @dfn
+@item Non-writable media: CD-ROM, DVD-ROM, BD-ROM.
+@item Write-once media: CD-R, DVD-R, DVD+R, BD-R.
+@item Reusable media: CD-RW, DVD-RW, DVD+RW, DVD-RAM, BD-RE.
+@end table
+
+Profiles depend on drive type and media state. They are expressed as
+numbers. It is unfortunate that formatted CD-RW have the same
+profile number as unformatted ones.
+
+ROM drives often announce all media as ROM profiles.
+Some writer drives show closed sequential media as ROM profile.
+@table @dfn
+@item CD-ROM     0x08
+@item DVD-ROM    0x10
+@item BD-ROM     0x40
+@end table
+
+Sequentially recordable profiles allow multisession in most cases.
+Special burn programs are needed for writing to them.
+@table @dfn
+@item CD-R       0x09
+@item CD-RW      0x0a (unformatted)
+@item DVD-R      0x11
+@item DVD-RW     0x14 (unformatted)
+@item DVD-R DL   0x15 (double layer)
+@item DVD+R      0x1a
+@item DVD+R DL   0x2a (double layer)
+@item BD-R       0x41 (single or double layer, formatted or not)
+@end table
+They can assume three states:
+@table @dfn
+@item "Blank" is not readable but writeable from scratch
+@item "Appendable" is readable and after the readable part still writeable
+@item "Closed" is only readable
+@end table
+CD-RW and DVD-RW can be brought back to blank state,
+or they can be formatted to become overwriteable.
+
+Overwriteable profiles allow random read-write access with a
+granularity of 2 kB or 32 kB.
+One can hope for having read-write access via the normal
+POSIX operations lseek(), read(), write() of the operating system.
+@table @dfn
+@item CD-RW      0x0a (formatted)
+@item DVD-RAM    0x12
+@item DVD-RW     0x13 (formatted, 32 kB write granularity)
+@item DVD+RW     0x1a
+@item BD-R       0x42 (formatted for pseudo-random recording)
+@item BD-RE      0x43 (single or double layer)
+@end table
+BD-R profile 0x42 is defined by MMC but not implemented by the consumer
+priced Blu-ray burners as of year 2009.
+
 @item Mixed Mode CD
 @cindex Mixed Mode CD
 

doc/libcdio.texi

@@ -12,7 +12,7 @@
 @set txicodequotebacktick
 
 @copying
-This manual documents @code{libcdio}, the GNU CD Input, Output and Control
+This manual documents @code{libcdio}, the GNU CD Input, Output, and Control
 Library.
 
 Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2010 Rocky
@@ -47,7 +47,7 @@ Texts.  A copy of the license is included in the section entitled
 
 @titlepage
 @title GNU @code{libcdio}
-@subtitle GNU Compact Disc Input, Output and Control Library
+@subtitle GNU Compact Disc Input, Output, and Control Library
 @subtitle for version @value{VERSION}, @value{UPDATED}
 @author Rocky Bernstein et al. (@email{bug-libcdio@@gnu.org})
 @page
@@ -287,7 +287,7 @@ 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
+Application: K3B THE CD KREATOR VERSION 0.11.12 (C) 2003 SEBASTIAN TRUEG AND...
 Preparer   : K3b - Version 0.11.12
 Publisher  : Rocky Bernstein
 System     : LINUX           
@@ -322,17 +322,13 @@ extracts files from an ISO-9660 image.
 
 Historically, @code{libcdio} did not support write access to
 drives. In conjunction with additional work in a separate project
-@code{libburn}, Thomas Schmitt has modified @code{libcdio} to add
+@code{libburn}, Thomas Schmitt has modified @code{libcdio} to enable
-write support; @code{libburn} write audio and data CD's and reads data
+sending SCSI write commands on some of the drivers. This enables other
-CD's. It reads and write DVD's and Blu-Ray discs.
+programs like @code{libburn} to write to CD's, DVD's and Blu-Ray
+discs.
 
-Other writing libraries include (e.g. @code{libdi}, @code{libscg}, or
+For the OS drivers which are lacking write access, volunteers are
-@code{libdvdread}) may be helpful.
+welcome.
-
-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
@@ -2040,19 +2036,19 @@ MMC (Multimedia commands) is a specification which adds special SCSI
 commands for CD, DVD, Blu-Ray devices.
 
 If your optical drive understands MMC commands as most do nowadays,
-this is probably gives the most flexibility in control. SCSI and ATAPI
+this probably gives the most flexibility in control. SCSI and ATAPI
 CD-ROM devices generally support a fairly large set of MMC
-commands. Unfortunately on most Operating Systems, one may need to do
+commands. Unfortunately, on most Operating Systems one may need to do
-additional steps to allow access in this manner.
+some additional setup, such as install drivers or modules, to allow
+access in this manner.
 
 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 bus protocol---ATAPI CD-ROMs are one such
 broad class of examples. In fact there are drivers to ``encapsulate''
-non-SCSI drives on non-MMC-compliant drives and make them act like MMC
+non-SCSI drives to make them act like more like SCSI drives, such as
-drives. I believe that many Operating System SCSI ``pass-through''
+by adding SCSI address naming.
-mechanisms do roughly the same thing.
 
 For clarity and precision we will use the term ``MMC'' rather than
 ``SCSI MMC''.
@@ -2067,7 +2063,6 @@ One of the problems with MMC is that there are so many different
 @item MMC 5 --- @url{ftp://ftp.t10.org/t10/drafts/mmc5/} 
 @end itemize
 along with the several ``drafts'' of these.
-for each standard.
 
 Another problem with the MMC commands related to the variations in
 standards is the variation in the commands themselves and there are
@@ -2100,9 +2095,8 @@ find a little bit of this for example via the routine
 @code{scsi_mmc_get_drive_cap()}. However much more work is needed.
 
 Finally, in @code{libcdio} there is a driver access mode (not a
-driver) called ``MMC''. It indicates to the specific drivers to in
+driver) called ``MMC''. It tells the specific drivers to use MMC
-issue MMC commands instead of other OS-specific or native drive
+commands instead of other OS-specific mechanisms.
-commands. 
 
 @node Access Modes
 @section Access Modes
@@ -2220,7 +2214,14 @@ More work on this driver is needed. Volunteers?
 @node Internal Program Organization
 @chapter Internal Program Organization
 
-@subsection file organization
+@menu
+* File Organization::
+* Library Organization::
+* Programming Conventions::
+@end menu
+
+@node File Organization
+@section File Organization
 
 Here is a list of @value{libcdio} directories.
 
@@ -2296,6 +2297,18 @@ location @code{lib/driver}
 
 @end itemize
 
+@node Library Organization
+@section Library Organization
+
+@menu
+* libcdio::
+* libcdio_cdda:: Access to CD-DA via the CD Paranoia library
+* libcdio_paranoia:: Access to the CD Paranoia library
+* libiso9660::  Access to ISO 9660 file systems and structures
+* libudf:: Access to UDF file systems and structures
+@end menu
+
+@node libcdio
 @subsection @samp{libcdio}
 
 @value{libcdio} exports one opaque type @code{CdIo_t}. Internally this
@@ -2328,6 +2341,7 @@ 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.
 
+@node libcdio_cdda
 @subsection @samp{libcdio_cdda}
 
 This library is intended to give access CD-DA disks using Monty's
@@ -2335,6 +2349,7 @@ cd-paranoia library underneath.
 
 To be completed....
 
+@node libcdio_paranoia
 @subsection @samp{libcdio_paranoia}
 
 This library is intended to give access Monty's cd-paranoia
@@ -2342,6 +2357,8 @@ library. It is the gap detection and jitter correction part without
 the part dealing with CD-DA reading.
 
 To be completed....
+
+@node libiso9660
 @subsection @samp{libiso9660}
 
 This library is intended to give access and manipulate a ISO-9600 file
@@ -2352,6 +2369,7 @@ structures and fields that go into such an image.
 
 To be completed....
 
+@node libudf
 @subsection @samp{libudf}
 
 This library is intended to give access and manipulate a UDF file
@@ -2359,13 +2377,23 @@ image.
 
 To be completed....
 
+@node Programming Conventions
+@section Programming Conventions
+
+@menu
+* Coding Conventions::
+* Namespace Conventions::
+@end menu
+
+@node Coding Conventions
 @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
+@node Namespace Conventions
+@subsection Namespace Conventions
 
 For the most part, the visible external @value{libcdio} names follow
 conventions so as not to be confused with other applications or