Programming guidelines

Please see Programming_Guidelines. For developers this is a must-read.

Documentation

Here you can find developer information about parts of BibleTime's code/architecture.

• Documentation about BibleTime's new Drag'n'Drop system
• Documentation about the module list updates

Online resources for programmers

API/Language documentation

• QT 4.4 API documentation
• KDE 4.0 API documentation
• Boost API documentation
• Sword API documentation
• The excellent SELFHTML HTML reference (german)
• Standard C++ Library documentation/user guide
• STL documentation (as a subset of the Standard C++ Library)

Other useful programming resources

• SQLite optimization FAQ
• Quick reference cards from Ada to XML, very helpful

Markup languages for Bibles and related material

A good overview is available at ebible.org. There is also a file formats overview page from Crosswire.

Most important formats

• OSIS reference and OSIS (1.1.1) quick reference card
• ThML reference
• GBF reference

Less well-known formats

For the following we'll have to collect data on how important they are, and if we should implement support for them sooner, later or not at all.

• XSEM (SIL)
• USFM (Paratext) docs
• USFX is supposed to be the XML-based successor of USFM (introduction and quick comparison to USFM and OSIS)

Resources for alternative versification systems

1. Data from CCEL
2. ScriptureChecks - there is a program to download the relevant data from the wiki.

Important Programming techniques

RAII

Resource Acquisition Is Initialisation (RAII) is a powerful technique for managing allocation and deallocation of resources that was invented and popularised by Bjarne Stroustrup, the creator of C++. It allows easier managing of resources, and is the *only* sensible way to make resources exception safe.

The following style of coding is common in much C and C++ code (including BibleTime):

{
   allocate_resources
   use_resources
   delete_resources
}

This however, is (1) error prone, because everything in delete_resources must be made to match that in allocate_resources, and if use_resources has an early exit condition it is even more difficult to program correctly; and (2) not exception safe, because use_resources might throw an exception, and the resources will be leaked.

The way RAII works, is by creating a wrapper class for each resource type, the class initializes or stores the resource in its constructor, and releases it in its destructor. Since C++ guarantees that objects will be destroyed when they fall out of scope, this will ensure that resources are freed automatically. Thus, code will look like this:

{
   allocate_resources
   use_resources
} //resources are automatically freed

We use boost::scoped_ptr from the Smart Pointers module of boost for just about any scoped resource management of this type that is needed. BibleTime developers should use the RAII technique for *all* scoped resource allocation and deallocation, as it is the only legitimate way to ensure exception safety, and thus to satisfy one of the Abraham's exception safety rules (see http://www.gotw.ca/gotw/082.htm for information on the Abraham's exception safety rules).

Very simple usage example:

CPrinter* printer = new CPrinter();
printer->printKeyTree(tree);
delete printer;

becomes:

#include "<boost/scoped_ptr.h"
...       
boost::scoped_ptr<CPrinter> printer( new CPrinter() );
printer->printKeyTree(tree);

The printer object will automatically be deleted. See this page for more information: Discussion about RAAI and auto_ptr.