diff --git a/doc/comments b/doc/comments index 0b9d490..6208185 100644 --- a/doc/comments +++ b/doc/comments @@ -6,101 +6,46 @@ @section intro Introduction Libburnia is an open-source project for reading, mastering and writing -optical discs. +optical discs. This page is about its capability to handle optical media. For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD+R/DL, DVD-RW, -DVD-R, BD-RE. +DVD-R, BD-R, BD-RE. -Not supported yet are DVD-R/DL, HD-DVD, BD-R (blue ray). Testers for -DVD-R/DL are wanted, though. BD-R programming efforts would be made -if an interested tester contacts us. +Not supported yet are DVD-R/DL. Testers wanted. -The project comprises of several more or less interdependent parts which -together strive to be a usable foundation for application development. -These are libraries, language bindings, and middleware binaries which emulate -classical (and valuable) Linux tools. +Our scope is currently Linux 2.4 and 2.6, or FreeBSD . For ports to other +systems we would need : login on a development machine resp. a live OS on CD +or DVD, advise from a system person about the equivalent of Linux sg or FreeBSD +CAM, volunteers for testing of realistic use cases. -Our scope is currently Linux 2.4 and 2.6 only. For ports to other systems -we would need : login on a development machine resp. a live OS on CD or DVD, -advise from a system person about the equivalent of Linux sg or FreeBSD CAM, -volunteers for testing of realistic use cases. +libburn is the library by which preformatted data get onto optical media. +Its code is independent of cdrecord. Its DVD capabilities are learned from +studying the code of dvd+rw-tools and MMC-5 specs. No code but only the pure +SCSI knowledge has been taken from dvd+rw-tools, though. -We have a well tested code base for burning data and audio CDs and many DVD -types. The burn API is quite comprehensively documented and can be used to -build a presentable application. -We have a functional binary which emulates the core use cases of cdrecord in -order to prove that usability, and in order to allow you to explore libburn's -scope by help of existing cdrecord frontends. +cdrskin is a limited cdrecord compatibility wrapper for libburn. +cdrecord is a powerful GPL'ed burn program included in Joerg Schilling's +cdrtools. cdrskin strives to be a second source for the services traditionally +provided by cdrecord. Additionally it provides libburn's DVD/BD capabilities, +where only -sao is compatible with cdrecord. +cdrskin does not contain any bytes copied from cdrecord's sources. +Many bytes have been copied from the message output of cdrecord runs, though. +See cdrskin/README for more. -ISO 9660 filesystems with Rock Ridge and Joliet extensions can be created -and manipulated quite freely. This capability together with our burn capability -makes possible a single binary application which covers all steps of image -composition, updating and writing. Quite unique in the Linux world. +The burn API example of libburn is named test/libburner.c . The API for media +information inquiry is demonstrated in test/telltoc.c . +Explore these examples if you look for inspiration. -@subsection components The project components (list subject to growth, hopefully): - -- libburn is the library by which preformatted data get onto optical media. - It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or - /dev/srM or /dev/hdX (e.g. on kernel 2.6). - libburn is the foundation of our cdrecord emulation. Its code is - independent of cdrecord. Its DVD capabilities are learned from - studying the code of dvd+rw-tools and MMC-5 specs. No code but only - the pure SCSI knowledge has been taken from dvd+rw-tools, though. - -- libisofs is the library to pack up hard disk files and directories into a - ISO 9660 disk image. This may then be brought to CD via libburn. - libisofs is to be the foundation of our upcoming mkisofs emulation. - -- libisoburn is an add-on to libburn and libisofs which coordinates both and - also allows to grow ISO-9660 filesystem images on multi-session - media as well as on overwriteable media via the same API. - All media peculiarities are handled automatically. - -- cdrskin is a limited cdrecord compatibility wrapper for libburn. - cdrecord is a powerful GPL'ed burn program included in Joerg - Schilling's cdrtools. cdrskin strives to be a second source for - the services traditionally provided by cdrecord. Additionally it - provides libburn's DVD/BD capabilities, where only -sao is - compatible with cdrecord. - cdrskin does not contain any bytes copied from cdrecord's sources. - Many bytes have been copied from the message output of cdrecord - runs, though. - See cdrskin/README for more. - -- xorriso is an application of all three libraries which creates, loads, - manipulates and writes ISO 9660 filesystem images with - Rock Ridge extensions. Manipulation is not only adding or - overwriting of files but also deletion, renaming, and attribute - changing. An incremental backup feature is provided. - See xorriso/README for more - -- "test" is a collection of application gestures and examples given by the - authors of the library features. The burn API example of libburn - is named test/libburner.c . The API for media information inquiry is - demonstrated in test/telltoc.c . - Explore these examples if you look for inspiration. - -We strive to be a responsive upstream. - -Our libraries are committed to maintain older feature sets in newer versions. -This applies to source code headers (API) as well as to linkable objects (ABI). -The only exception from this rule is about non-release versions x.y.*[13579] -which are allowed to introduce new features, change those new features in -any way and even may revoke such new features before the next release of -x.y.*[02468]. As soon as it is released, a feature is promised to persist. - -SONAMES: +SONAME: libburn.so.4 (since 0.3.4, March 2007), -libisofs.so.6 (since 0.6.2, February 2008), -libisoburn.so.1 (since 0.1.0, February 2008). - @section using Using the libraries + @section using Using libburn Our build system is based on autotools. User experience tells us that you will need at least autotools version 1.7. -To build libburn and its subprojects it should be sufficient to go into -its toplevel directory and execute +To build libburn and its companion applications go into its toplevel directory +and execute - ./bootstrap (needed if you downloaded from SVN) @@ -112,29 +57,24 @@ To make the libraries accessible for running resp. developing applications - make install -Both libraries are written in C language and get built by autotools. -Thus we expect them to be useable by a wide range of Linux-implemented -languages and development tools. - @section libburner Libburner libburner is a minimal demo application for the library libburn (see: libburn/libburn.h) as provided on http://libburnia-project.org . -It can list the available devices, can blank a CD-RW or DVD-RW and -can burn to recordable CD and recordable single layer DVD. +It can list the available devices, can burn to recordable CD, DVD, or BD, +can blank a CD-RW or DVD-RW, and can format unformatted DVD-RW, BD-R, or BD-RE. It's main purpose, nevertheless, is to show you how to use libburn and also to serve the libburnia team as reference application. libburner does indeed -define the standard way how above three gestures can be implemented and -stay upward compatible for a good while. +define the standard way how above gestures can be implemented and stay upward +compatible for a good while. @subsection libburner-help Libburner --help 
 Usage: test/libburner
        [--drive 
||"-"]  [--audio]
-       [--blank_fast|--blank_full|--format_overwrite]
-       [--try_to_simulate]
+       [--blank_fast|--blank_full|--format]  [--try_to_simulate]
        [--multi]  [|"-"]
 Examples
 A bus scan (needs rw-permissions to see a drive):
@@ -147,8 +87,8 @@ Blank a used CD-RW (is combinable with burning in one run):
   test/libburner --drive /dev/hdc --blank_fast
 Blank a used DVD-RW (is combinable with burning in one run):
   test/libburner --drive /dev/hdc --blank_full
-Format a DVD-RW to avoid need for blanking before re-use:
-  test/libburner --drive /dev/hdc --format_overwrite
+Format a DVD-RW, BD-RE or BD-R:
+  test/libburner --drive /dev/hdc --format
 Burn two audio tracks (to CD only):
   lame --decode -t /path/to/track1.mp3 track1.cd
   test/dewav /path/to/track2.wav -o track2.cd