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.
- 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.
- 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.
- All Verse references should be valid in that versification.
- 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.
In current versions of ParaTExt, you can choose which Bible Book name to use for all of your $() tags. Under Tools>Scripture Reference Settings>Book Names>Cross-References (\xt) use, choose the desired TOC. You may need to choose View>Reload Module to see the changes.
Importing whole Chapters
It seems you cannot simply insert "\ref PSA 1", you must list the verses \ref PSA 1:1-6.
References that span multiple chapters
References bridging several chapters do work, but oddly they expect a hyphen (\ref 2CO 5:20-6:10) instead of the proper em dash (\ref 2CO 5:20—6:10), Nevertheless, you should probably split up chapters into separate /refs to break up the text or to add chapter numbers (which can not be imported). You should thus split the reference to \ref 2CO 5:20-21 and \ref 2CO 6:1-10 and add an extra \p (and maybe \c ) in between to alert the user to a change of chapter.
References with commas
References that use commas to jump verses sometimes work (\ref ACT 1:1-5,8), but don't other times do not (\ref GEN 4:26-5:1,3). (It seems to me that you are only allowed to use a "," or a "-" in a reference, and not both. ) The cause silent errors (missing text) that are hard to find without reading the text, and thus should generally be avoided in \refs, while they are fine in $()'s. Split the \refs into separate lines, and give an extra \p in between if you want to alert the reader to a jump in continuity.
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/
