From 621f7e99adbfba1a53cc28bc72be19bc7387dbdd Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 28 Jul 2003 02:25:37 +0000 Subject: [PATCH] First feeble attempt at documentation. --- Makefile.am | 5 +- configure.ac | 5 +- doc/Makefile.am | 17 +++ doc/libcdio.texi | 298 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 320 insertions(+), 5 deletions(-) create mode 100644 doc/Makefile.am create mode 100644 doc/libcdio.texi diff --git a/Makefile.am b/Makefile.am index 0fbe78f7..28cc906f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -# $Id: Makefile.am,v 1.8 2003/04/25 21:28:39 rocky Exp $ +# $Id: Makefile.am,v 1.9 2003/07/28 02:25:37 rocky Exp $ # # Copyright (C) 2003 Rocky Bernstein # @@ -22,8 +22,7 @@ EXTRA_DIST = libpopt.m4 THANKS libcdio.spec.in -# SUBDIRS = doc include lib src test -SUBDIRS = include lib src test +SUBDIRS = doc include lib src test # pkg-config(1) related rules pkgconfigdir = $(libdir)/pkgconfig diff --git a/configure.ac b/configure.ac index ef1a094d..ec4c21ed 100644 --- a/configure.ac +++ b/configure.ac @@ -15,10 +15,10 @@ dnl along with this program; if not, write to the Free Software dnl Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA dnl 02111-1307, USA. -AC_REVISION([$Id: configure.ac,v 1.29 2003/06/13 04:47:20 rocky Exp $])dnl +AC_REVISION([$Id: configure.ac,v 1.30 2003/07/28 02:25:37 rocky Exp $])dnl AC_INIT(lib/cdio.c) AM_CONFIG_HEADER(config.h) -AM_INIT_AUTOMAKE(libcdio, 0.61) +AM_INIT_AUTOMAKE(libcdio, 0.62) AM_SANITY_CHECK @@ -292,6 +292,7 @@ AC_OUTPUT([ \ include/Makefile \ include/cdio/Makefile \ include/cdio/version.h \ + doc/Makefile \ lib/Makefile \ src/Makefile \ test/check_nrg.sh \ diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..7c85d6f4 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,17 @@ +libcdio_TEXINFOS = libcdio.texi + +%.ps.gz: %.ps + gzip -9c $< > $@ + +.texi.pdf: + texi2pdf $< + +.texi.html: + texi2html $< + +.texi.txt: + makeinfo --no-headers $< > $@ + +all-formats: libcdio.pdf libcdio.dvi libcdio.txt libcdio.ps libcdio.html + +MOSTLYCLEANFILES = libcdio.html libcdio.pdf libcdio.ps.gz diff --git a/doc/libcdio.texi b/doc/libcdio.texi new file mode 100644 index 00000000..4564e1d5 --- /dev/null +++ b/doc/libcdio.texi @@ -0,0 +1,298 @@ +\input texinfo @c -*-texinfo-*- + +@paragraphindent 0 +@exampleindent 0 + +@c %**start of header +@setfilename libcdio.info +@set libcdio @code{libcdio} + +@settitle The GNU libcdio library +@setchapternewpage on + +@ifinfo +This file documents GNU CD input and control library + +Copyright (C) Herbert Valerio Riedel @email{} and Rocky +Bernstein @email{} + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``Free Software'' and ``Free Software Needs +Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. + +(a) The Free Software Foundation's Back-Cover Text is: ``You have +freedom to copy and modify this GNU Manual, like GNU software. Copies +published by the Free Software Foundation raise funds for GNU +development.'' +@end ifinfo + +@titlepage +@title GNU libcdio library +@subtitle $Id: libcdio.texi,v 1.1 2003/07/28 02:25:37 rocky Exp $ +@author Rocky Bernstein et al. +@page + +@vskip 0pt plus 1filll + +Copyright @copyright{} 2003 Herbert Valerio Riedel +@email{} and Rocky Bernstein @email{} +@sp 1 +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``Free Software'' and ``Free Software Needs +Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. + +(a) The Free Software Foundation's Back-Cover Text is: ``You have +freedom to copy and modify this GNU Manual, like GNU software. Copies +published by the Free Software Foundation raise funds for GNU +development.'' +@end titlepage +@page + +@ifnottex +@node Top, History, (dir), (dir) + +@top The GNU Video CD Ripping Program (@value{program}) + +This file documents GNU CD input and control library + +Copyright (C) 2003 Herbert Valerio Riedel and Rocky Bernstein + +@menu +* History:: How this came about +* Purpose:: Why this library? +* CD Formats:: A tour through the CD-specification spectrum +* How to use:: Okay enough babble, lemme at the library! + +Indices +* General Index:: Overall index +@end menu +@end ifnottex + +@contents + +@node History +@chapter History + +As a result of the repressive Digital Millenium 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 libcdi that might be +confused with a particular CD format called CD-I. + +@node Purpose +@chapter The problem and previous work + +If around the year 2002 you were to look at the code for a number of +open-source 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 sprinked with conditional compilation for this or that +platform. + +One 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 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. + +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 and no doubt something similar exists on +other platforms. However this "standard" lacked adoption on OS's other +than GNU/Linux. + +The library ``The Compact Disc Input and Control Library'' 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. Some support for disk image types like BIN/CUE and NRG is +available, so applications that use this library also have the ability +to read disc images as though they were CDs. + +A sample utility for displaying CD info is included. + +@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) +* Yellow Book:: Yellow Book (CD-ROM Digital Data) +* White Book:: White Book (Video CD) +@end menu + +@node Red Book +@section Red Book +The first type of CD that was produced was the Compact Disc +Digital Audio (CD-DA) or just plain "audio CD". The specification for +that is covered in what is called the Red Book. 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 +2,352 bytes. To play one 44.1 kHz CD-DA sampled audio second, 75 +sectors are used. + +In @value{libcdio} when you you want to read an audio sector, you call the +routine @code{cdio_read_audio_sector()}. + +@node Yellow Book +@section Yellow Book +The CD-ROM specification or "Yellow Book" followed a few years later +and describes the extension of CD's to store computer data, +i.e. CD-ROM (Compact Disk Read Only Memory). + +The Yellow book CD standard defines two modes: + +@subsection Mode1 + Mode 1 is the data storage mode used by to store computer + data. 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. + +@subsection Mode2 + Mode 2 data CDs are the same as mode 1 CDs except that the error + detecting and correcting codes are omitted. This is similar to audio + CDs, i.e. 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 VideoCD plus + Sony's Playstation. + +@subsection ISO-9660 +The Yellow Book does not actually specify how data is to be stored on +or retrieved from a CD-ROM. It was feared that many different +companies would implement proprietary data storage formats using this +specification, resulting in many different incompatible data CDs. To +try to prevent this, representatives of major manufacturers met at the +High Sierra Hotel and Casino in Lake Tahoe, NV, in 1985, to come +together on a common standard for data CDs. This format was nicknamed +High Sierra Format. It was later modified slightly and adopted as ISO +standard 9660. ISO 9660 consists of several "levels": + +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. + +Level 2 ISO 9660 allows far more flexibility in filenames, but isn't +usable on some systems, notably MS-DOS. + +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 White Book +@section White Book +The White Book, finalized in 1993, defines the VideoCD specification +The White Book is also known as Digital Video (DV). A VideoCD disc +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 VideoCD Information Area which gives general +information about the VideoCD 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 routine @code{cdio_read_mode2_sector()}. + +@node How to use +@chapter How to use + +@node General Index +@unnumbered General Index +@printindex cp + +@tex +% I think something like @colophon should be in texinfo. In the +% meantime: +\long\def\colophon{\hbox to0pt{}\vfill +\centerline{The body of this manual is set in} +\centerline{\fontname\tenrm,} +\centerline{with headings in {\bf\fontname\tenbf}} +\centerline{and examples in {\tt\fontname\tentt}.} +\centerline{{\it\fontname\tenit\/},} +\centerline{{\bf\fontname\tenbf}, and} +\centerline{{\sl\fontname\tensl\/}} +\centerline{are used for emphasis.}\vfill} +\page\colophon +% Blame: doc@cygnus.com, 1991. +@end tex +@bye