# Troubleshooting Bible Modules

If you ar creating a Bible module that will be shared and translated, this is similar to a shellbook, and certain criteria must be followed to avoid extra manual work on the part of the translator.

1. All Verse references (MAT 5:5) should use the English 3-letter code and English verse number specfication and be surrounded by $(). This will ensure that they show up in the vernacular in the final project. 2. All Verse References should be specified in the target versification of the user, this may mean creating multiple copies. This will avoid missing/offset verses. 3. All Verse references should be valid in that versification. 4. It should be obvious which fields should be translated and which should not be touched. ## Module Headers See Bible Modules for a copy of the official documentation. Before adding book content, you will want to choose the Versification of each module. This should follow your vernacular Bible and will include a marker indicating the target versification (i.e. \v Original or \v English). Also, you may want to choose to show verse markers or other fields (as shown in the documentation, \inc v allows verse numbers to appear in the imported text). These switches seem to be global to the Module. ## Debugging a Module See Paratext Help: "Check Bible Module" for official documentation. Paratext contains minimal debugging for your bible moule. It can check to see that the referenced verses exist in the current versification, as well as whether they have been translated. Open your bible module in the current project, and click the Check for errors and untranslated references button (to the right of the number of errors). After a moment, ParaTExt will show a list of untranslated references, broken references, and unknown tags in your module. ## Troubleshooting Bible References ### Overview Remember that Bible module defaults are English Versification, English 3-letter codes, and English verse punctuation, meaning that you should keep all Bible references in your module to the default MAT 5:4-7 format. #### Imports Tags in the format \ref MAT 5:1 will be replaced with the actual referenced text from the current project. You must use the English 3-letter code for each book, and then a space. The dividing ":" and verse continuation "-", and continuing commas (,) are the only valid punctuation. The multiple chapter em-dash (—), semicolon (;), periods (.), parentheses, and further spaces are not valid in the numerical section of a reference, and partial verse letters (i.e. 5:9a) will be ignored. See later sections for specific workarounds. #### Formatted References Tags in the format$(MAT 5:1) will be dynamically reformatted to show the vernacular book title (as chosen in Tools>Scripture Reference Settings>Book Names>Cross-References (\xt) use) and the verse references will be reformatted to follow your Scripture Reference Settings (as chosen in Tools>Scripture Reference Settings). Do not write these out manually (i.e. Matthew 5:7) unless you intend for certain references to be left in a vehicular language by the translators.

The syntax requirements for formatted references are wider. The dividing colon ":", verse continuation "-", list of verses comma (,), the multiple chapter em-dash (—), the list of chapter/book semicolon (;) are all valid. Parentheses are not valid.
(how about periods (.)?), parentheses, and further spaces are not valid in the numerical section of a reference, and partial verse letters (i.e. 5:9a) will be ignored.

### How to configure vernacular book titles (TOC1, TOC2, or TOC3)

In Recent versions of USFM, the \TOC (Table of contents) tags are deprecated. This means that the preferred way of managing abbreviations, short titles and long titles is through Tools>Scripture Reference Settings>Book Names.

### References with partial verses

Verses not split into parts in the text are usually imported completely.  Thus \ref 2CO 5:20b imports all of 5:20 if in doubt. For the benefit of the translator working with a Bible version in a different language, avoid partial verse references if possible.

### References with "custom" punctuation.

Some communities may want "custom" punctuation of verse references (i.e. Catholic Psalm chapters from NAB) that ParaTExt's Scripture Reference settings just can't handle.

For example, any reference with internal parentheses $(LUK 2:1-14,(15-20)), indicating an optional reading in a lectionary, crashes the Module parser and the reference text does not show (failing with just a closing parenthesis). If your Module requires "custom" formatting of verse references, you can do this:$(LUK) 2:1-14,(15-20). The advantage is that the Book Title is automagically replaced with the TOC2 so TOC3 specified, but the disadvantage is that ParaTExt no longer verifies the correctness of the reference.

## Versification

If your translation uses a Versification other than English, you may have to adapt your Bible Module to this versification. This is non-trivial and can be a monotonous and error-prone task to do manually as, for example, many verse numbers in Psalms change between English Bibles and French or Hebrew Bibles.

There is script developed by Matthew Lee that exists to convert a Bible module in one versification to another.

It also can be run on your current module file to verify that you have not created any "broken" or disallowed references. This Python Script can be downloaded here https://github.com/erros84/PtxModuleVersification/