Go Bible Home | News | Forum | About | Contact | Developer

Go Bible Logo

Go Bible

For the glory of our Lord Jesus Christ and the furtherance of His Kingdom.


GoBibleCreator is a tool for converting ThML and OSIS Bible texts into Go Bible Java applications that can be loaded onto phones. GoBibleCreator is a Java application and requires a Java Runtime Environment.

Download GoBibleCreator

Simply click on the link below and decompress the zip file.

Here is a description of the files in GoBibleCreator 2.2.6.zip:

  • GoBibleCreator.jar - The GoBibleCreator Java program.
  • GoBibleCore - A directory containing two GoBibleCores, one for MIDP 1.0 and another for MIDP 2.0.
  • Collections - A directory containing a sample collections file for use with Hebrews.thml.
  • Welcome.html - Documentation, same as this web page.
  • Hebrews.thml - Sample ThML file containing only the KJV book of Hebrews.

Before Running GoBibleCreator

Before GoBibleCreator can be used you will need a ThML file or an OSIS file in UTF-8 format. A sample ThML file for the book of Hebrews is provided. Other ThML files can be downloaded from CCEL.

Running GoBibleCreator

GoBibleCreator is run with the following command line from the directory containing the GoBibleCreator.jar file:

  • java -Xmx128m -jar GoBibleCreator.jar [PathToCollectionsFile | PathToXmlFile]+

To make a Go Bible collection you need to make a Collections.txt file which describes the collection and the books that will be in it. GoBibleCreator can automatically generate a Collections.txt file for you by specifying the path to the ThML/OSIS file on the command line. For example the following line will generate a Collections.txt file in the same directory as the ThML file:

  • java -Xmx128m -jar GoBibleCreator.jar Hebrews.thml

The format of the Collections.txt file is described below. Note that invoking GoBibleCreator with a ThML/OSIS file does not generate any JAD/JAR files only a Collections.txt file. To produce the JAD/JAR files you will need to run GoBibleCreator again but this time with the Collections.txt file as the only parameter. However, you will probably need to customise the Collections.txt file before doing that.

To produce the JAD and JAR files run GoBibleCreator with the Collections.txt 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 Collections.txt file.

The -Xmx128m parameter

GoBibleCreator loads the entire XML file into memory and therefore requires the -Xmx128m attribute to increase the total memory available to 128MB. GoBibleCreator can process multiple files at once by specifying multiple files on the command line.

Optional parameters

There are two optional parameters:

Specifies a source text directory where all Source-Text urls will be relative to. See below for more details on the Source-Text property in the Collections.txt file.
Update option: Using this option GoBibleCreator 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 we 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.

The Collections File

The Collections file contains the configuration of the collections. The file describes the location of the source text and each collection, which books it contains, and which chapters from each book. The Collections file must be in UTF-8 character encoding so that all character sets are supported. A simple Collections file is shown below:

  • Source-Text: ../Hebrews.thml
  • Collection: Hebrews
  • Book: Hebrews

The first line is mandatory and specifies the location of the source text used to generate this collection. The path can be relative as seen above, and is relative to the location of the Collections.txt file.

The next line indicates that a new collection named 'Hebrews' is required. This name will determine the JAD and JAR file names that are produced as well as the application name that appears on the phone. Below the Collection property are the books that will be contained within the collection. In this example, only the book of Hebrews will be added to the collection.

The collections files used to generate the collections on the Go Bible website are available in the Go Bible Google Project source code repository under the Collections directory in the trunk. You may want to use one of these as a starting point if you are looking at modifying an existing translation.

The Info Property

The Go Bible application includes an About screen which provides information to the user about the Go Bible application. The optional Info property in the Collections.txt file can be used to append additional information about the particular translation, for example:

  • Source-Text: ../Hebrews.thml
  • Info: This Collection contains the book of Hebrews from http://ccel.org.
  • Collection: Hebrews
  • Book: Hebrews

The contents of the Info property will now appear in the About screen. This is a good place to put information about the source of the translation.

Using Non-English Book Names

Most ThML files and OSIS files use English book names even though the text is in the native language. GoBibleCreator supports changing the book names using the Book-Name-Map property. A Book-Name-Map property is listed for every book whose English name must be mapped to another name, for example:

  • Source-Text: ../Hebrews.thml
  • Book-Name-Map: Hebrews, The Book of Hebrews
  • Collection: Hebrews
  • Book: Hebrews

The first string "Hebrews" is the name of the book as it appears in the XML file while the second string "The Book of Hebrews" is what will appear to the user. Note: The Book-Name-Map property does not change the usage of book names in the rest of the Collections.txt file, they must still use the XML book names.

Translating the User Interface

Most UI text in Go Bible can be replaced with text from the Collections.txt file using the UI properties. The following table lists the available UI properties and their default values:

UI propertyDefault value
UI-Goto Go to
UI-Cancel Cancel
UI-Preferences Preferences
UI-History History
UI-Search Search
UI-Search-Results Search Results
UI-Add-Bookmark Add Bookmark
UI-Bookmarks Bookmarks
UI-Exit Exit
UI-Send Send
UI-Send-SMS Send SMS
UI-Send-MMS Send MMS
UI-About About
UI-Loading Loading
UI-Save Save
UI-Font-Size Font size
UI-Small Small
UI-Medium Medium
UI-Large Large
UI-Font-Style Font style
UI-Plain Plain
UI-Bold Bold
UI-Full-Screen Full screen
UI-On On
UI-Off Off
UI-Theme Theme
UI-Themes Themes
UI-Theme-Paper Paper
UI-Theme-Computer Computer
UI-Theme-Floral Floral
UI-Theme-Natural Natural
UI-Theme-Blue Blue
UI-Theme-Sunshine Sunshine
UI-Change Change
UI-Select Select
UI-Reverse-Colours Reverse Colours
UI-Reverse-Characters Reverse Characters
UI-Book Book
UI-Books Books
UI-All All
UI-New-Testament New Testament
UI-Old-Testament Old Testament
UI-Gospels Gospels
UI-Pauls-Letters Paul's Letters
UI-Other-Letters Other Letters
UI-Books-Of-Moses Books of Moses
UI-Historical Historical
UI-Poetic Poetic
UI-Major-Prophets Major Prophets
UI-Minor-Prophets Minor Prophets
UI-Chapter Chapter
UI-Search-Text Search Text
UI-From-Book From Book
UI-To-Book To Book
UI-Stop Stop
UI-Searching Searching
UI-Found Found
UI-Please-Wait Please wait
UI-Results Results
UI-View View
UI-Delete-Bookmark Delete Bookmark
UI-Delete-Bookmark-Alert Delete the selected bookmark?
UI-Delete Delete
UI-Send-Verses Send Verses
UI-Back Back
UI-To to
UI-Select-Verses-To-Send Select verses to send
UI-Error Error
UI-Message-Too-Large-To-Be-Sent Message too large to be sent
UI-Verse-Does-Not-Exist Verse does not exist
UI-Phone-Number Phone Number
UI-Of of

Right Aligned Text

Some languages such as Arabic and Hebrews 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:

  • Source-Text: Arabic.thml
  • Language-Code: Ar
  • Align: Right
  • Collection: Hebrews
  • Book: Hebrews

The text will now appear aligned to the right of the screen and the verse numbers will also start on the right of the screen.

Splitting Books

Some phones have JAR limits that prevent some of the larger books from fitting on the phone. Nokia Series 40 MIDP 1.0 phones for example have a 64KB JAR limit. This would prevent some books such as Psalms from loading onto the phone. GoBibleCreator allows books to split up by indicating which chapters will appear in each collection. The following example creates two collections, the first contains the first 5 chapters of Hebrews and the second contains the remaining 6 chapters:

  • Source-Text: ../Hebrews.thml
  • Info: This Collection contains the book of Hebrews split in two.
  • Collection: Hebrews 1-5
  • Book: Hebrews, 1, 5
  • Collection: Hebrews 6-13
  • Book: Hebrews, 6, 13

The commas (,) are mandatory and the first number indicates the first chapter to include and the second number indicates the last chapter to include. Note that we have changed the collection name to indicate to the user which chapters are in each collection, however, any collection name can be used.

Supporting MIDP 1.0

By default GoBibleCreator produces MIDP 2.0 compatible JAD and JAR files. These files will not run on MIDP 1.0 devices. To support MIDP 1.0 devices the MIDP property needs to be defined in the Collections.txt file as follows:

  • Source-Text: ../Hebrews.thml
  • Info: This Collection will run on MIDP 1.0 phones.
  • MIDP: MIDP-1.0
  • Collection: Hebrews 1-5
  • Book: Hebrews, 1, 5
  • Collection: Hebrews 6-13
  • Book: Hebrews, 6, 13

Note that specifying MIDP 1.0 will result in only MIDP 1.0 files being produced. These files contain less functionality than the MIDP 2.0 files such as no support for fullscreen viewing or SMS.

Language Codes

Since Go Bible supports multiple translations it is possible that a user may wish to have both the KJV and Chinese translations on their phone at the same time. If the collection names are the same for both translations then the phone won't allow both to be stored simultaneously. A simple solution to this problem is to use the Language-Code property which will be appended to the name of every collection, for example:

  • Source-Text: ../Hebrews.thml
  • Info: This Collection contains the book of Hebrews split in two.
  • Language-Code: En
  • Collection: Hebrews 1-5
  • Book: Hebrews, 1, 5
  • Collection: Hebrews 6-13
  • Book: Hebrews, 6, 13

Every collection will now have 'En' appended to its name. GoBibleCreator also appends 'Go Bible' to every collection name by default so the generated application names for the above example will be 'Hebrews 1-5 En Go Bible' and 'Hebrews 6-13 En Go Bible'. It should also be noted that GoBibleCreator strips spaces from the generated JAD and JAR file names as these can cause problems on some phones. The generated file name is the collection name plus the language code. The following files would be generated for the above example:

  • Hebrews1-5En.jad
  • Hebrews1-5En.jar
  • Hebrews6-13En.jad
  • Hebrews6-13En.jar

Creating Files for WAP Download

Go Bible is most commonly downloaded from PC to phone. However, Java applications can also be downloaded via a WAP browser. This method is less commonly used since it is expensive and sometimes difficult. To ease the process of creating files for WAP download the Wap-site property can be used in the Collections.txt file. 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 site. In addition, a Welcome.html file is generated containing links to all of the JAD files. The Wap-site property contains 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 of the JAD file. WAP site example:

  • Source-Text: ../Hebrews.thml
  • Wap-site: http://wap.jolon.org/KJV/
  • Collection: Hebrews
  • Book: Hebrews


If you need any help with using GoBibleCreator please see the Go Bible Google Group.