Made a try to get doxygen portal page readable by html dl lists

trunk/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
+
+<dl>
+<dd>./bootstrap  (needed if you downloaded from SVN)
+<dd>./configure
+<dd>make
+</dl>
+
+To make the libraries accessible for running resp. developing applications 
+
+<dl>
+<dd>make install
+</dl>
+
+
+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:
+
+   <dl>
+   <dd>1. Initialize the library.
+   <dd>2. Depends on wether you know the persisten drive address in advance
+      <dl>
+      <dd>If yes:
+      <dd>2a. Aquire this drive alone and directly by function
+          burn_drive_scan_and_grab() and be done until step 5
+      <dd>If no address known yet:
+      <dd>2b. Scan for available Drives..
+      </dl>
+   <dd>3b. Choose a Drive for reading/writing and inquire its persistent address.
+   <dd>4b. Shut down library, re-initialize it and like in step 2a aquire the
+       chosen drive by function burn_drive_scan_and_grab()
+   <dd>5. Fill in the options for the operation.
+   <dd>6. Wait for the operation to complete, displaying status along the way
+      if desired.
+   <dd>7. Release the Drive.
+   <dd>8. Destroy the library instance. (If you're done working with the library.)
+   </dl>
+
+   @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.<br>
+    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
+<dl>
+<dd>Usage: test/libburner
+  <dl>
+  <dd>  [--drive <address>|<driveno>|"-"]
+  <dd>  [--verbose <level>] [--blank_fast|--blank_full]
+  <dd>  [--burn_for_real|--try_to_simulate] [--stdin_size <bytes>]
+  <dd>  [<imagefile>|"-"]
+  </dl>
+<dd>Examples
+  <dl>
+  <dd> A bus scan (needs rw-permissions to see a drive): test/libburner --drive -
+  <dd> Burn a file to drive chosen by number:
+  <dl><dd> test/libburner --drive 0 --burn_for_real my_image_file</dl>
+  <dd> Burn a file to drive chosen by persistent address:
+  <dl><dd> test/libburner --drive /dev/hdc --burn_for_real my_image_file</dl>
+  <dd> Blank a used CD-RW (is combinable with burning in one run):
+  <dl><dd> test/libburner --drive 0 --blank_fast</dl>
+  <dd> Burn a compressed afio archive on-the-fly, pad up to 700 MB:
+  <dl><dd> ( cd my_directory ; find . -print | afio -oZ - ) | \
+      <dd> test/libburner --drive /dev/hdc --burn_for_real --stdin_size 734003200  - </dl>
+  <dd>To be read from *not mounted* CD via: afio -tvZ /dev/hdc
+  <dd> Program tar would need a clean EOF which our padded CD cannot deliver.
+  </dl>
+*/