---------------------------------------------------------------------------------------
|                SimpleBurn documentation for developpers                 |
---------------------------------------------------------------------------------------



================ Program start ===============
At start time, the program loads the interface described in the 
"src/simpleburn.ui" GTKBuilder file, then detects the CD / DVD 
devices. See:
- "src/simpleburn.c": main()
- "src/common-interface.c": "addisofilter()", "initcddevices()"
- "src/common-detection.c": "listcdwriters()", "listcdreaders()",
	"listcddevices()"

The user interface has been drawn with Glade-3. The 
"src/simpleburn.glade" file is used for the design and is 
converted to the GTKBuilder format by "gtk-builder-convert".



============== Callback Handlers ===============
The callback functions are stored in the "src/callback-*.c" files 
whom name are explicit ("misc" is for detection and ejection).

All these handlers behave the same:
- check that the requested action is possible regarding the type 
of the inserted media (see detection below).
- call the "startprogress" function (see process spawning and 
progress display below)

The actions are handled by BASH scripts (stored in the "scripts" 
directory), and their names are also explicit. If something doesn't 
work as expected, try to execute the action by running the 
ad-hoc script (usage and example strings are displayed when the 
scripts are run without parameters).

Using scripts requires more memory (for the BASH interpreter), 
but it has some advantages: the actions can be performed 
without using a GUI, and it eases the tracking of bugs and 
adaptation.

There are two burning suite supported:
- CDRTools / CDRKit: (cdrecord / wodim, cdda2wav / icedax, mkisofs / genisoimage);
- LibBurnia + LibCDIO / CDParanoia (cdrskin, cd-paranoia, xorriso) + CDRDAO.
The burning suite is choosed when running CMake.



================= Detection =================
There are two available methods for device and media detection:
- LibCDIO - default detection method;
- UDev - alternative detection method.
The detection method is choosed when running CMake.

The device detection routines are stored in the "src/common-detection.c" 
file (see "listcddevices" functions). Media detection is handled by 
the "setcdinfos" function.

The media detection is done by separate programs (because 
detection is needed both by the GUI and the scripts handling 
actions). These programs are called "simpleburn-*-media-detection" 
and are stored either in the "src" or "scripts" directory.

Blanked rewritable DVDs are detected as data medias. Because of this,
filesystem type is used to determine if these medias are blank or
containing data.

The functions for file or data / audio directory size calculation are 
stored in "src/common-filesize.c".

The functions for media checking and error display are stored in 
"src/common-checks.c".


( MMC documentation can be found at: 
http://www.13thmonkey.org/documentation/SCSI/ )



======== Process spawning and progress display ========
All actions are launched by the "startprogress" function in the
"src/common-launch.c" file. This functions do the following 
actions:
- launch a thread to display total, elapsed and remaining time,
- spawn a process (the script) to execute the required operation,
- launch a thread to watch for process termination
- launch one thread to display a pulse bar 
or launch a thread to display a pulse bar (until the progress can 
be displayed) and a thread to display the progress bar (progress 
is read from process output).

The progress calculation and display is done by a standalone 
program "simpleburn-gauges" ("src/simpleburn-gauges.c") 
launched in parallel of the "cdrecord" / "cdda2wav" command by 
the scripts; ISO and video DVD extraction use BASH functions to 
display progress.



============== Submitting patches ==============
#~ - Get the current version:
#~ git clone git://git.tuxfamily.org/gitroot/simpleburn/simpleburn.git

- Send patches to Frank Endres <frankendres@tuxfamily.org>



================ Translations ================
- add a new language: cd to "po" directory and run "msginit"

- update translation files (if strings have changed): 
cd to "simpleburn" root directory and run:
	mkdir build; cd build
	cmake ..; make update_po
	cd ..; rm -rf build



============ Enabling debug information ============
Add option "-DDEBUG=ON" to cmake command line.
