What is a Bible Module?
A Bible Module is an arrangement of Scriptures and extra-biblical material for a particular product. It consists of a template with text and Biblical references in any order for creating a Scripture-based product. You view a Bible Module in an Extra book (XXA - XXF). When activated, the Bible Module will replace all of the Scripture references with the actual text from the active project. The resulting file can be printed or exported as any other Scripture book in Paratext.
Bible Modules allow for:
- Automated additions or replacements to the Scripture content
- E.g. Replace a pronoun with a name when the original context is missing.
- Discontiguous ranges of verses
You view a Bible module in an Extra book. From the View menu you may view the document as
- Unformatted Specification
Raw text, similar to unformatted mode in a normal project window.
- Standard Specification
Formatted specification text, without pulling and displaying the referenced text
- Standard Output
Formatted specification text and backslash codes with actual reference text displayed in place of the references.
- Preview Output
Formatted specification text with actual reference text displayed in place of the references.
At the top of the view, there is a status bar that shows how many of the referenced verses are found in the project.
Examples of a Bible module:
- A script for a media production (which might break the text of a book into the verse ranges which will be recorded as audio clips).
- A lectionary (which has verse ranges from various books for the selected readings in the worship services).
- A Bible story book with a mixture of Scriptures and added narrative.
Paratext does not have any built-in specification files. Two possible sources of references for a specification file are a lectionary or an audio/video script. If you need help creating a specification file, ask a computer specialist to help you.
Creating a Specification File
A specification file is an .sfm text file in UTF-8 format. The name can contain only the following: letters (A-Z a-z), digits (0-9), underscore, or space. It contains instructions for Paratext to gather and format text from your project and produce the content of the Bible module.
The specification includes lines which begin with the following special markers. Lines which begin with these special markers are special module instructions that are treated differently than standard markers for a project.
Identify the versification of references in the specification. Example: \vrs English
Include certain markers (and their text) which are excluded from the content by default: v – verse numbers f – footnotes x – cross references s – section headings Example: \inc v
Copy the markers and text for a verse (or verse range) from a project. This reference format is limited: it allows hyphen and comma (without a following space) but does not allow semicolon. Example: \ref PSA 72:1-7,18-19
Copy the verse range with no paragraph markers from the project. Example: \p \refnp LUK 1:1-4
Find text within a verse range in an ordinary book of a project and replace it with other text in the content of the module. To separate the text to find from the text to replace, type an equal sign and a greater than sign. If you need to prevent a replacement from occurring more than once, include enough surrounding context so that the text to find is unique. Example: \rep he=>Jesus
Include the content of a child module in the content of this (parent) module. Example: \mod child_module.sfm
Displaying reference names in the target language
In addition to extracting a section of text to display in the module, you can also display the reference using the book names and format of the project's Scripture reference settings.
Use $(BBB C:V) for formatted references where BBB is the three-character book abbreviation, C is the chapter number and V is the verse number. (A formatted reference can occur anywhere in the specification after the \id line. For example, in \sr section range references.) This reference format does not have the limitations of the \ref format. The reference:
- must be surrounded by parentheses
- must use the standard three-character book abbreviation
- must use the default punctuation for references (a colon to separate the chapter number and verse number, and a hyphen to separate verse numbers).
When the reference is copied to the Bible module; the standard three-character book abbreviation is replaced by the choice for cross references on the Book Names tab of the Scripture Reference Settings dialog. The default punctuation is replaced by the punctuation specified on the Reference Format tab of the Scripture Reference Settings dialog. For example, in a project where the cross reference choice is to use the book abbreviation; where the book abbreviation for the book of Revelation is Ap; where the chapter verses separator is a period, and where the range of verses separator is a hyphen, $(REV 1:1-16) will become Ap 1.1-16 in the content of the module.
To override this default behavior, use any of the following:
- $a(BBB C:V) to use the book abbreviation
- $s(BBB C:V) to use the book short name
- $l(BBB C:V) to use the book long name
Additional format codes
You may also use format markers from the project stylesheet. For example, \s (headings), \p (paragraphs), and \rem (comments)
These codes and their following text will be formatted and copied to the output.
- The \refnp marker removes all paragraph markers from the copied text. Therefore, if you want to use \refnp to copy a range of verses, you might want to break the range up into several smaller ranges of verses and precede each \refnp with a \p marker to break the verses into paragraphs manually.
- The \refnp marker can produce some unusual results when used with the \inc s option.
- Any chapter numbers are excluded from the copied project text. If the content needs chapter numbers, for each chapter number needed, the specification itself must include the \c marker followed by the chapter number. However, if the specification contains duplicate chapter numbers (for example, corresponding to multiple books), the View menu options will not display the content.