From 02e3cc2b8b4697d0ed5b2923ba43cc6019664361 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sun, 3 Sep 2006 16:55:46 +0000 Subject: [PATCH] Made a try to get doxygen portal page readable by html dl lists --- doc/comments_test_ts | 142 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 doc/comments_test_ts diff --git a/doc/comments_test_ts b/doc/comments_test_ts new file mode 100644 index 0000000..b7719b9 --- /dev/null +++ b/doc/comments_test_ts @@ -0,0 +1,142 @@ +/** + @author Mario Danic, Thomas Schmitt + + @mainpage Libburn Documentation Index + + @section intro Introduction + +Libburn is an open-source library for reading, mastering and writing +optical discs. For now this means only CD-R and CD-RW. + +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 and we will have a hard time to widen +this for now, because of our history. The project could need advise from or +membership of skilled kernel people and people who know how to talk CD/DVD +drives into doing things. + +We do have a workable code base for burning data CDs, though. The burn API is +quite comprehensively documented and can be used to build a presentable +application. +We do have a functional binary which emulates parts 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. + +@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/hdX (e.g. on kernel 2.6). + libburn is the foundation of our cdrecord emulation. + +- 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. + +- 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. + 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. + +- "test" is a collection of application gestures and examples given by the + authors of the library features. The main API example of libburn + is named test/libburner.c . + Explore these examples if you look for inspiration. + +We plan to be a responsive upstream. Bear with us. + + + @section using Using the libraries + +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 + +
+
./bootstrap (needed if you downloaded from SVN) +
./configure +
make +
+ +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. + +We are still practicing. + + @subsection working Working with the library + + In general, using the library to perform a process consists of the following + steps: + +
+
1. Initialize the library. +
2. Depends on wether you know the persisten drive address in advance +
+
If yes: +
2a. Aquire this drive alone and directly by function + burn_drive_scan_and_grab() and be done until step 5 +
If no address known yet: +
2b. Scan for available Drives.. +
+
3b. Choose a Drive for reading/writing and inquire its persistent address. +
4b. Shut down library, re-initialize it and like in step 2a aquire the + chosen drive by function burn_drive_scan_and_grab() +
5. Fill in the options for the operation. +
6. Wait for the operation to complete, displaying status along the way + if desired. +
7. Release the Drive. +
8. Destroy the library instance. (If you're done working with the library.) +
+ + @section libburner Libburner + + libburner is a minimal demo application for the library libburn (see: libburn.h) + as provided on http://libburn.pykix.org . It can list the available devices, can + blank a CD-RW and can burn to CD-R or CD-RW.
+ It's main purpose, nevertheless, is to show you how to use libburn and also + to serve the libburn team as reference application. libburner.c does indeed + define the standard way how above three gestures can be implemented and + stay upward compatible for a good while. + + @subsection libburner-help Libburner --help +
+
Usage: test/libburner +
+
[--drive
||"-"] +
[--verbose ] [--blank_fast|--blank_full] +
[--burn_for_real|--try_to_simulate] [--stdin_size ] +
[|"-"] +
+
Examples +
+
A bus scan (needs rw-permissions to see a drive): test/libburner --drive - +
Burn a file to drive chosen by number: +
test/libburner --drive 0 --burn_for_real my_image_file
+
Burn a file to drive chosen by persistent address: +
test/libburner --drive /dev/hdc --burn_for_real my_image_file
+
Blank a used CD-RW (is combinable with burning in one run): +
test/libburner --drive 0 --blank_fast
+
Burn a compressed afio archive on-the-fly, pad up to 700 MB: +
( cd my_directory ; find . -print | afio -oZ - ) | \ +
test/libburner --drive /dev/hdc --burn_for_real --stdin_size 734003200 -
+
To be read from *not mounted* CD via: afio -tvZ /dev/hdc +
Program tar would need a clean EOF which our padded CD cannot deliver. +
+*/