Compiling Version Databases

38 Compiling Version Databases

Clicking on this button will open the Database Compiler Window. This can also be done by selecting Tools | Version Database Compiler from the Main Menu. The Version Database Compiler is a tool which you can use to add your own Bible versions to BibleWorks.

Overview

In BibleWorks versions 5 and later, you can create your own Bible versions. After being compiled, user-created Bible versions are identical in format to the Bible versions that are shipped with BibleWorks. They can be searched, displayed, and copied to the clipboard just like any other version database. This is good news for translators and missionaries who can now harness the full power of BibleWorks for their translation projects.

You can also create Greek or Hebrew morphology Bible versions. If you create your own morphology version, you can tag words any way you desire, but for the Analysis Window to work properly with them you must use the BibleWorks coding schemes (see An Overview of Morphological Coding Schemes ).

To create your own Bible version all you have to do is follow a few simple guidelines. The basic process involves three steps:

§ You must create a properly formatted text file containing your new version.

§ You must create a Database Definition File by filling in a few simple items in the Version Database Compiler Window.

§ You must compile and install the version (this step is totally automated).

The following sections describe the steps you need to follow in detail.

Step 1: Creating a text file containing your new Bible version

To create a Bible version for the BibleWorks compiler, you will need to create a text file containing the text of the Bible version you are adding. The guidelines that you must follow for producing this file are simple, but they must be followed carefully for the process to work. The text file must be formatted according to the following rules:

1. Each verse must appear on a single line. Verses must be terminated by a carriage return/linefeed and cannot contain tab characters. There should be no blank lines in the file but you can put comments on a line if you begin the line with two forward slashes. These lines will be ignored.

2. A verse may not be longer than 32KB.

3. Each verse must be preceded by its Bible reference using the BibleWorks three-letter standard abbreviation. See Book Name Abbreviations for more information.

4. The books do not have to be in any particular order, but we recommend that you follow the standard BibleWorks order shown in the Book Name Abbreviations section. Ordering within a book however must be strictly by chapter and verse.

For example, the first few lines of the KJV version in this format would look like this:

Gen 1:1 In the beginning God created the heaven and the earth.
Gen 1:2 And the earth was without form, and void; and ...
Gen 1:3 And God said, Let there be light: and there was light.

If you want to start with a blank text file with one Bible reference per line and nothing but the references, you can use the Text Export window to produce a template file. See Exporting Large Sections of Bible Text. Open the Database Export Window (click Tools | Export Database) and select an existing Bible version that uses the same book, chapter, and verse scheme as your custom Bible version. If there is no existing Bible version that uses exactly the same book, chapter, and verse scheme as your custom Bible version, pick an existing Bible version with a similar scheme. Then check the Save as template (references only) checkbox and do the export. This will give you a blank file to start with.

After creating your Bible version, you will need to define a custom verse mapping to correctly synchronize your custom Bible version with the other Bible versions. See Verse Maps Options for more details. If your version is mapped like an existing one, you can just make a copy of the VMF file of that version.

If you want to see examples of files in the correct format you can also use the Exporter to export a full version and then examine it in a text editor. Note that if you use the exporter, text intended for use with the Version Database Compiler must be in ASCII text for non-Greek/Hebrew versions and in CCAT format for Greek and Hebrew versions.

Once you have the new version text file in the proper format, copy it to your BibleWorks directory in the USERDB subdirectory. This is where new databases are compiled.

Step 2: Creating a Database Definition File (DDF)

Once you have created the text file containing your Bible version, formatted with a single verse per line with each line beginning with the Bible reference, you are ready to import the Bible version. You need to create a DDF file that describes the version to BibleWorks so it will know how to compile it. Do this by opening the Version Database Compiler Window and answering a few simple questions. The answers you give are stored in a file with the extension DDF. To make changes later and recompile the database all you have to do is open the DDF file in the Version Database Compiler Window.

To open the Compiler click on thebutton or select Tools | Version Database Compiler from the Main Menu.

The options in the Version Database Compiler Window are laid out and numbered in logical order. You should just go through the four steps in order one at a time. At a bare minimum you must specify the following:

§ The name of the DDF file. To do this, click on NEW and pick a name. It is usually best to use the same short name that you want to use for your new version identifier (see below). For illustration purposes we will assume that your version is called ABC. Then the DDF file will be called ABC.DDF.

§ The name of the raw text file that you created must be specified. It is less confusing if you also name it after the three-letter name that you have chosen. In this case it would be ABC.TXT.

§ A description of the database. This is the text that will appear in BibleWorks menus when you choose the version there.

§ A version ID. This is a short name, three or more letters in length, that you will use in BibleWorks to refer to the new version. In our case you would enter ABC. Keep in mind that if you make this name longer than three letters the database cannot be used in versions of BibleWorks prior to 7.0.

§ The language of the version. This determines which language menu the version will appear in when it is imported into BibleWorks.

§ The Content option - does it contain OT, NT or both.

§ The locale. This will determine the sorting order of the text and of word lists in BibleWorks. This will usually be the same as the language.

The remaining options may or may not be used in your version. For a first cut, you can just use the default settings for all of them. After you have tried that, you should read through all the options to see which ones might be applicable to your database. A summary of the available options is give at the end of this topic.

Step 3: Compiling and Installing the Database

The next step is to click on the Compile button to compile the database. If you check the Install After Compiling checkbox, the version will be installed after the compilation (if it is successful). But while you are experimenting, we recommend leaving this option off. If you have verses that are formatted incorrectly, you will receive an error message in the compilation text box above the Compile button.

That is really all there is to it. If the compilation fails, you will need to edit the text file and recompile. You can edit the text file by clicking on the edit button in group box number 2. This will load your text file into WordPad. If you have a better editor for correcting the text, it can be specified in the Options Window in the Option Strings tab.

What to do if the installation process does not work

Installing corrupted databases can result in a crashed program the next time you run BibleWorks. So it is important that you know how to recover from a buggy compiled version database. When you compile and install a new version, it copies several files into the Databases subdirectory of your BibleWorks directory. In the case of our example they would be:

abc.dbx	the indexed text file for your version
abc.wdc	the indexed word frequency file for the version
abc.vmf	a blank mapping file (if you have your own in the databases directory it will not be overwritten)
abc.dbu	basically a copy of the .ddf file that you created

When you start BibleWorks, it loads the information for its "native" database versions and then looks for .dbu files in the BibleWorks Database directory. For every one it finds, it will try to install an externally defined version. If for some reason your compilation produced a version that caused BibleWorks to crash during this phase, all you have to do to fix it is delete or rename the .dbu file for your new version. If that doesn't fix it, go to the BibleWorks root directory and delete the bw700.ini file and restart BibleWorks. That should get you up and running even in the case of a serious problem.

The Version Database Compiler Options

Some of the options in the Version Database Compiler will be grayed out depending on what options you pick. That is why it is important to set them in the order that they appear in the Compiler Window. For example, if you are compiling an English or Western European version, Greek and Hebrew related options will be grayed out. The options available in the Compiler Window are as follows:

Section 1 - The DDF File

§ Database Description File - This is the name of the file that will contain the Version Database Compiler settings.

§ Open - Open an existing .ddf file. The name of the file will be loaded into the Database Description File text area.

§ New - This creates a new, blank database definition file (a .ddf file).

§ Save - Saves the information currently in the Version Database Compiler window in a .ddf file.

Section 2 - The Raw Text File

§ Database Raw Text File - This is the name of the text file that contains the properly formatted Bible text.

§ Browse - Opens a window which permits you to browse and select the text file.

§ Edit - Open the text file containing the Bible version text in an editor. This editor is specified in the Tools | Options | Option Strings window. See Option Strings for more information.

Section 3a - Options Needed for All Versions

§ Description - This is the label that will appear on lists of Bibles in the various windows and menus of BibleWorks.

§ Version ID - This is the three-letter abbreviation for your Bible version. It must be unique (you cannot use an abbreviation that is used by some other Bible version in BibleWorks). See Bible Version Abbreviations for more information.

§ Content - Specifies which books of the Bible your version will contain. Pick the entry that most closely describes the books of the Bible contained in your version. The options are "OT", "NT", "OT and NT" and "Custom". Select "Custom" if the version does not contain Biblical books. This setting is used by BibleWorks to determine whether or not the new version can be displayed with normal Bible Versions.

§ Version # - This is a version number field. We recommend you keep the version number between 7000 and 7999 to tie your version to Version 7 of BibleWorks.

§ Language - This is the language group describing the language of the text of the Bible version. This determines in what language menu in BibleWorks your version will appear.

Section 3b. - Options for Greek and Hebrew Only

§ Morph Coding - For Greek or Hebrew versions, this specifies which of the BibleWorks morphology coding schemes you are going to use. These coding schemes are described in the Morphological Coding Schemes section. If you are not using any morphology codes, simply select None. For example, pure text versions would not use a coding scheme.

§ Companion - Enter the name that you will use to refer to this version in BibleWorks. Each Version in BibleWorks has a short name, three or more letters long, used to reference the version in BibleWorks. For example, the WTT and the WTM are companion texts to each other, and the GNT and GNM are companion texts to each other. Text Versions do not have to have companions, but Morphology Versions must have companions. If it does not have one leave the option blank. Keep in mind that this name will be typed a lot so it should be short. Also remember that if the version name is longer than three letters the database cannot be used in versions of BibleWorks prior to 7.0.

§ Display Only - If you check this box the version will not be searchable. This is mainly for debugging. If you have compiled a version and searching does not work properly you can still use it for display purposes by checking this box.

§ Transliteration - Check this box if the version is a transliterated Hebrew version. Transliterated Greek is not yet supported.

Section 3c. - Options for All Versions Except Greek and Hebrew

§ Notes
This option specifies whether or not your Bible text contains footnotes. The options are:

§ No Notes
Select this option if your text contains simple Biblical text with no notes or extraneous material.

§ Embedded Notes
If you select this option you can embed translator notes in the text enclosed in {curly braces}. Text marked in this way will not be indexed. It will be invisible until you click on the Notes Button in BibleWorks.

§ End Notes
If you select this option you can attach notes to the end of each verse in your database, enclose in {curly braces}. Text marked in this way will not be indexed. It will appear in the Analysis Window when your mouse cursor is on the verse that has the end notes.

You can include formatting information in the note by using an SGML-like markup language. The supported tags are as follows:

<b>...</b>	bolded text
<i>...</i>	italicized text
<h>...</h>	Hebrew text
<g>...</g>	Greek text
<gb>...</gb>	bolded Greek text
<sup>...</sup>	superscripted text
<sub>...</sub>	subscripted text
<ee>...</ee>	Eastern European text
<sym>...</sym>	bwsymbol.ttf font text
<cyr>...</cyr>	Cyrillic text
<wing>...</wing>	Wingdings text
<p>	inserts a line break

§ Apostrophe
In some languages (like English), if a word ends with an "s" and is followed by an apostrophe, the meaning of the apostrophe may appear ambiguous to BibleWorks. BibleWorks may not be able to determine if the apostrophe is to be treated as an end quote, or as an apostrophe denoting the plural possessive. In some non-English languages the apostrophe serves entirely different purposes. Sometimes it is ignored. Sometimes it is an integral part of the word. The Apostrophe options tell BibleWorks how to handle apostrophes. The options are:

o Check for possessive
If this option is checked BibleWorks will attempt to analyze the context and if it appears to be a possessive marker the apostrophe will be kept with the word.

o Keep always
Apostrophes will always be treated as integral parts of the words they occur in.

o Treat as blank always
Apostrophes will be treated as blanks and not indexed as parts of words.

o Ignore always
Apostrophes will be ignored. They will be displayed but removed from words before the words are indexed. When searching for the words you will not enter the spostrophe.

o Keep if Internal
Apostrophes will be treated integral parts of words but only if there is a non-blank letter before and after.

§ Dash Character - There are problems with dashes that are similar to those with apostrophes. It is not always possible to tell if a dash is punctuation or part of a word. These options help BibleWorks to resolve the ambiguity:

o Keep if internal
If a dash has alphanumeric text on each side of it, the dash will be treated as a part of the word. Otherwise it will be treated as a blank.

o Treat as blank
All dashes will be treated as blanks for indexing purposes.

o Treat as blank at end of word
Dashes will be treated as blanks if they occur at the end of a word. Otherwise they will be treated as integral.

o Use hyphenation file
BibleWorks will use a hyphenation file to resolve ambiguities. If you choose this option you must provide a hyphenation file. It should have the same name as the raw text file but with a "hyp" extension. The file should contain a list of all the VALID hyphenated words in the version. In all other words the dash will be treated as punctuation.

§ Locale - This option specifies the language locale of the version. This option determines how word lists will be sorted for the version and what keyboard layout is used. Normally it will be the same as the language parameter, though for Greek and Hebrew it is not used (because BibleWorks Greek and Hebrew fonts use custom sort routines).

§ Has Strong's Codes - If you have Strong's Codes in your text, then you should check this option. Strong's Codes should be surrounded by brackets <>.

§ Has Small Caps - Some versions have the word for YHWH in small caps. In ASCII text files this is sometimes marked by enclosing words between backwards slashes like this \Lord\. If you check this option and BibleWorks encounters text marked this way it will convert the word to all small caps.

§ Has Superscripts - This flag indicates that footnotes in the text are marked by superscripts. Footnotes marked in this way should be tagged with angle brackets like this: <N1>, <N2>, etc. See below for an example.

§ Has Italics - If words in your text are to be italicized, check this option. Italicized words should be surrounded by square brackets []. If you have this option checked, text in your database which is enclosed in square brackets will be displayed italicized.

§ Has xrefs - This flag indicates that cross references in the text are marked by superscripts. Cross-references marked in this way should be tagged with angle brackets like this: <Ra>, <Rb>, etc. See below for an example.

§ Use NAS Lexicon - This flag indicates that the lexicon used with the New American Standard should be used to render the tag definitions in the Analysis Window. All versions with Strong's Number tags use an abridged form of the BDB/Thayer lexicons which derives from the Online Bible produced by Larry Pierce. The NAS version has a numbering scheme that varies slightly from the Online Bible. You should pick the one that matches the Strong's Numbers in the version you are building. Note that non-English lexicon entries are not available if you have this option checked, and the Analysis Window "Default Strong's Language" option will have no effect.

Section 4. - Compiler Options

§ Install after compiling - When checked, this option installs the new Bible version into BibleWorks. After the Bible version has been successfully installed, you will be able to use it as if it were one of the standard Bible versions that shipped with BibleWorks.

§ Print Blank References - If this option is checked when the version is built, as a diagnostic, verses that have no text will be displayed.

§ Delete Database - Opens a window from which you can delete currently installed custom Bible versions from BibleWorks. This only removes the database from BibleWorks, but does not delete the text file or DDF file used to create the Bible version.

An Example

A good example to study while you are preparing your database is the NAS in BibleWorks. It has a lot of nice features, including Strong's Numbers, footnotes and cross references that appear in a List Box in the Analysis Window. If you are interested in duplicating this functionality we recommend that you go to the Export Utility in BibleWorks and export the NAS version as a text file to study the format of the file. Genesis 1:2 in the NAS raw form will look like this (in reality it is all on one line):

Gen 1:2 And the earth <0776> was <N1><Ra>formless <08414> and void <0922>, and <Rb>darkness <02822> was over <05921> the <N2>surface <06440> of the deep <08415>; and <Rc>the Spirit <07307> of God <0430> <Rd>was <N3>moving <07363b> over <05921> the <N2>surface <06440> of the waters <04325>. { (1) Or, [a waste and emptiness] (2) Lit., [face of] (3) Or, [hovering] (a) Jer 4:23 (b) Job 38:9 (c) Psa 104:30; Isa 40:13, Isa 40:14 (d) Deu 32:11; Isa 31:5 }

The NAS is built with the following options:

Notes: Embedded Notes

Apostrophe: Check for Possessive

Dashes: Keep if internal

Checked checkboxes: Has Strong's Codes, Has Italics, Has Small Caps, Has X-Refs, Has Superscripts

This one version fairly well illustrates the limits of what can be done in BibleWorks with user-defined, non-Greek/Hebrew versions. You should examine the sample above and see how the text fits the description of the option settings in this section. Then you will be ready to compile your own version with cross references and footnotes just like the NAS!