Projects:Go Bible/Go Bible Creator

New page under construction.

Introduction

Go Bible Creator is a tool for converting Bible texts into Go Bible Java ME applications that can be loaded onto suitable mobile phones. Go Bible Creator is a Java application and requires Java SE (Runtime Environment).

Before running Go Bible Creator

Before Go Bible Creator can be used you will need to obtain or create suitable input text containing the Bible translation or Bible version.

Input file formats

Go Bible Creator can now handle input text in each of the following formats:

• OSIS – a single XML file using OSIS format
• ThML – a single XML file using ThML format
• USFM – multiple text files using USFM format
• XHTML-TE – a single XHTML file using an extended HTML format for the SIL Translation Editor

All the input files must be Unicode text encoded as UTF-8 (without BOM).

For use with Go Bible Creator, an OSIS must be of the container type, not the milestone type.

A sample ThML file for the book of Hebrews is provided. Further ThML files may be downloaded from CCEL.

The developer must ensure that permission has been obtained in writing for using any copyrighted material as input text.

Preprocessing

It is often the case that some preprocessing will be required to ensure that the input text is compatible for use with Go Bible Creator. It should not be assumed that input text files obtained directly from third parties will meet the exacting requirements.

Running Go Bible Creator

GoBibleCreator is run with the following command line and by default would be run from the directory containing the GoBibleCreator.jar file:

java -Xmx128m -jar GoBibleCreator.jar [PathToCollectionsFile | PathToXMLfile]+

Enhanced techniques

It is possible to specify the location for the GoBibleCreator.jar file as follows, in this example by means of a suitably defined environment variable:

java -Xmx128m -jar %GBC_PATH%\GoBibleCreator.jar ...

Windows users can redirect the generated messages by sending standard output and error output to suitably named log files:

java -Xmx128m -jar %GBC_PATH%\GoBibleCreator.jar %1 1>.\java.log 2>.\error.log

In the above example, it is assumed that %1 is a passed parameter. This technique can be readily adapted by Unix users.

Windows users can also test for success or failure by examining the errorlevel value. Here is what I have in my Windows command file called MakeGoBible.cmd :

REM Using a defined environment variable and command line parameter
java -Xmx128m -jar %GBC_PATH%\GoBibleCreator.jar %1 1>.\java.log 2>.\error.log
if not errorlevel 1 goto end 
start .\error.log
start .\java.log
:end
rem pause

To use this technique with multiple files, simply replace the command line parameter %1 by %1 %2 %3 %4 %5 %6 %7 %8 %9

Or make a more complex script (i.e. using shift) to capture the outputs after each file is processed.

Tip: For Windows users, it is best to avoid using paths containing a space, which gets confused as a parameter delimiter.

Required parameters

For Java

-xmx128m

Go Bible Creator loads the entire source text file[s] into memory and therefore requires the -Xmx128m parameter to increase the total memory available in Java to 128MB.

-jar

This tells Java to process the GoBibleCreator.jar file as a jar file.

For GoBibleCreator

PathToCollectionsFile

Go Bible Creator can optionally process multiple files at once by specifying several PathToCollectionsFiles on the command line.

PathToXMLfile

This is a alternative use of GoBibleCreator described further below. This secondary use appertains only to input files in either OSIS or ThML formats.

Invoking GoBibleCreator with an XML file as the specified parameter does not generate any JAD/JAR files, only a new collections.txt file prefilled with extracted book names. To produce the JAD/JAR files you would need to run GoBibleCreator again but this time with the collections.txt file as the only parameter. However, you would normally need to manually edit the Collections.txt file before doing that.

Optional parameters

There are two optional parameters for GoBibleCreator:

-d PathToMainSourceTextDirectory

Specifies a source text directory where all Source-Text folders will be relative to. See below for more details on the Source-Text property in the "collections text" file.

-u

Update option: Using this option Go Bible Creator will update existing JAR files if they exist rather than create new ones. The source text will not be parsed nor will new Bible data be generated however everything else will be updated including the GoBibleCore, book names, UI properties, JAD file, manifest, etc. This option is useful if the source text hasn't changed and there hasn't been any change to the Go Bible Data Format, as it will be much quicker to process each collection. This option first makes a backup copy of the original JAD and JAR files.

Collections text files

To produce the JAD and JAR files run GoBibleCreator with a suitable "collections text" file. This example uses the Hebrews collections.txt file included with GoBibleCreator:

java -Xmx128m -jar GoBibleCreator.jar Hebrews/Collections.txt

GoBibleCreator will generate JAD and JAR files and place them in the same directory as the specified collections text file.

The format and content of a "collections text" file is described further below. Typically, the developer will need to carefully construct a collections text file (using a suitable text editor) in order to obtain all the required properties and features of the created Go Bible application[s].

Notes

1. Any suitable filename may be chosen for a "collections text" file; it does not have to be called collections.txt
2. Collections text files may optionally contain blank lines and remark lines. Remark lines must begin with //
3. Collections text files must be Unicode text files that should be encoded as UTF-8 without BOM. If the BOM is included inadvertently, the first line will not be correctly processed (unless it happens to be a blank line).
4. Collections text files may specify more than one collection of books. This is useful when the developer wishes to provide split collections in addition to one for a complete Bible.

Contents

The following sections describe the required and optional properties that can be specified within a collections text file.

The Info property

The Info property line contains the text that is displayed in the Go Bible menu About option.

This where to record all the information needed to describe the Bible version or Bible translation, copyright information, distribution license and conditions, end user terms and conditions, and any other relevant information about the particular Go Bible applications that will be created.

The display is not formated in any way by the Go Bible menu | About option – it appears as a (scrollable or scrolling) single paragraph on the mobile phone. For Bible translations, it is sensible to include in the info line a translation of the English text in the same language as the Bible.

Example:

Info: The Holy Bible: King James Version (including the Apocrypha). This Java ME application was made by David Haslam using Go Bible Creator

I have kept this reasonably short, only so that horizontal scrolling of this wiki page is avoided. There is no size restriction on the length of text.

Go Bible software now automatically appends the Ver. number (of Go Bible Creator), followed by the Viewer Version number.

Source-Text

This property specifies the source text file name (or folder name in the case of USFM) with a path relative to the directory where the collections text file is stored.

Example 1:

Source-Text: KJV.thml

This assumes the ThML file is in the same directory as the collections text file.

Example 2:

Source-Text: .\USFM

USFM is the name of a folder containing the set of USFM files, each book being a separate file.

Source-Format

The format must now be specified using the following property:

Source-Format: [ OSIS | ThML | USFM | XHTML-TE ]

Example:

Source-Format: ThML 

Omitting this line will result in a message being sent to standard output, but no JAR or JAD files are created. The argument for this property is not case-sensitive.

Collections

A collection is a list of books under the Collection property. A collection could be as small as a single book (or even part of a book) or as large as a complete Bible.

Example:

Collection: KJV

Book: Genesis
Book: Exodus
Book: Leviticus
Book: Numbers
Book: Deuteronomy
...
...
Book: Jude
Book: Revelation

The collection name is converted to the filename for the JAR and JAD files. GoBibleCreator removes any spaces from the resulting filename.

The book names must match those within the source text file or files.

Mapping book names

Many source text files use English book names even though the text is in the native language. Go Bible Creator supports changing the book names using the Book-Name-Map property. Specify this property for every book whose (English name) must be mapped to another name, for example:

Book-Name-Map: Hebrews, The Book of Hebrews
Collection: KJV Hebrews
Book: Hebrews

Notes:

1. In the first line above, the first string "Hebrews" is the name of the book as it appears in the input file, while the second string "The Book of Hebrews" is what will be displayed on the mobile phone.
2. The Book-Name-Map property does not change the usage of book names in the rest of the collections text file, they must still specify the book names used in the source text file. The position of book name mapping is not important. The following would work just as well.

Collection: KJV Hebrews
Book: Hebrews

Book-Name-Map: Hebrews, The Book of Hebrews

To map all the book names for the whole Bible, it is usually more legible for all these lines to be grouped together in one section of the collections text file.

This feature may be used to cover various situations:

• Book names for (non-English) Bible translations (e.g. Book-Name-Map: Genesis, Genèse )
• Shorter book names than used in the source text (e.g. Book-Name-Map: Acts of the Apostles, Acts )
• Longer book names than used in the source text (e.g. Book-Name-Map: GEN, Genesis )
• Change Roman numerals in book names to ordinary numerals (e.g. Book-Name-Map: III John, 3 John )
• Case changes (e.g. Book-Name-Map: LUKE, Luke )

i.e. The book names in the source text may simply need mapping to book names that are more suitable for use in the Go Bible application.

Right Aligned Text

Some languages such as Arabic, Farsi and Hebrew are read from right to left. This also requires text to be aligned to the right rather than the left. Go Bible (by default) aligns text to the left. The alignment can be changed using the Align property. Example:

Align: Right

Creating files for WAP download

Go Bible is most commonly downloaded to a PC and then copied from PC to phone. However, Java applications can also be downloaded directly to cell phones from a WAP server. This method is less commonly used, as it is often more expensive and sometimes difficult to access. To ease the process of creating files for WAP download the optional Wap-site property can be used in the collections text file.

Example: (Syntax only – this WAP server is currently not operational.)

Wap-site: http://wap.crosswire.org/gobible/en/kjv/

If the Wap-site property is declared then a separate wap subdirectory is generated containing JAD and JAR files ready for uploading to a WAP server. In addition, a Welcome.html file is generated containing links to all of the JAD files. The Wap-site property should contain the full URL to the directory that will contain the JAD files. This URL is used within the Welcome.html file as well as for setting the MIDlet-Jar-URL property in each of the JAD files.

After running Go Bible Creator

It should not be assumed that an absence of error message means that the generated Go Bible applications are without error due to either text or markup issues.

Testing Go Bible applications

Go Bible applications should be thoroughly tested before being distributed. There are two main ways to do this: