Difference between revisions of "Alternate Versification"

Revision as of 19:08, 18 March 2009

Disclaimer: Alternate versification, though mostly implemented, is not yet complete in Sword and is by no means tested, at the time of this page's creation. The contents of this page will in some cases be correct, in some cases speculative, and possibly in some cases incorrect. We will try to keep things here updated to reflect Sword support for alternate versifications, but don't expect it to be entirely accurate until Sword 1.5.12 is released (or even 1.5.13).

Introduction

As of SWORD 1.5.11, there is only one supported versification: The KJV Old and New Testaments. This is represented in canon.h as a fixed, hard-coded system.

Alternate versifications mean ultimately to allow Bible texts with arbitrary canon or versification schemes to coexist peacefully on the same SWORD installation and (ultimately) to map cleanly between each other via cross references or parallel display.

Alternate versification is also known as dynamic versification and has been abbreviated as v11n, av11n and dv11n. (There are 11 letters between v and n in versification.)

There are technically 2 routes to support this under development:

1. ripping out the hardcoded KJV canon.h offsets and replacing them with VerseMgr, which allows registration of canon.h-like v11n systems.
2. genbook Bibles

Both have been under development and 2 requires 1. 1 is nearly done and included in Sword 1.5.12. 2 will not be supported by Sword 1.5.12.

Overview

Up until 1.5.11, the canon and the versification were hard coded into the engine in the form of the file canon.h, which offered book names and chapter + verse offsets to the engine. The new approach is that:

1. Each Bible module will carry a .conf entry identifying its versification from an supported list of versification systems. Absent this identification, the versification system will default to "KJV" for backward compatability.
2. The engine will have, for each major canon and versification variety, a new header file similar to the previous canon.h.
3. On system start, the engine will load, for each open KJV-divergent module, the relevant data presented in the relevant canon_{Versification].h into a table held in memory.
4. Subsequently, the relevant module will be accessible via the usual methods - which have not changed from 1.5.11.
5. What does not work anymore is to assume that a book or chapter has a set (fixed) number of verses. Instead, 1.5.12 introduces new methods VerseKey::getChapterMax() and VerseKey::getVerseMax() to provide the relevant information for a given module--replacing VerseKey::books[testament][book].chapmax and .versemax members.
6. Similarly VerseKey::getBookName() and VerseKey::getBookAbbrev() replace the previous const char *name and const char *prefAbbrev respectively.
7. At a later stage (>1.5.12) the engine will allow for GenBook Bibles to automatically create arbitrary versification tables on the fly.
8. The final step (in >1.5.12) will be to allow mappings between versification schemes to allow cross-referencing and parallel display of corresponding passages.

Canon Header Files

GenBook Bibles

GenBook Bibles are Bibles stored in GenBook format. They are accessed via VerseKey, which in turn calls TreeKey.

The role of GenBook Bibles will mainly be to allow alternative versifications and canons over and above those provided by alternative canon header files.

SWORD Versification Tools

The primary versification tools are:

• v11nsys.pl – Converts a v11n spec into a SWORD canon header file.
• osis2mod – The -v11n flag allows one to build a Bible or commentary SWORD module with a versification other than the KJV.
• imp2vs – The -v11n flag allows one to build a Bible or commentary SWORD module with a versification other than the KJV.

Note: These are under development and may not work as expected until v11n is fully implemented.

API Changes

Front End Problems

How to Create Modules with Alternative Versifications

1. Set the relevant entries in the configuration file Configuration file
2. If your module uses a versification or canon not yet present in SWORD you might have to create a canon header file. Sword tools contains relevant scripts. Please be aware that we will not hard code every versification under the sun but only select and important ones. If your scheme is not one of those you will need to go down the route of a GenBook Bible. Discuss on sword-devel what you are planning to do and you will get appropriate advice.
3. The importers will work as usual. You'll specify a versification for the text to the import utility (imp2vs or osis2mod). It will pass the v11n value to the SWText constructor, which will instruct it to use the specified v11n.
4. Append will also work as usual. Append pertains to whether a text is overwritten or appended to, so its use can affect the stored order of verses, but won't affect where the engine thinks they belong for access/display purposes.
5. Each v11n will specify a book order, so different traditions that vary with respect to book order would have to be represented by different v11n definitions.

Modules Requiring Alternate Versification

• Ohienko Ukrainian translation.
  The existing module had discarded the original Ukrainian verse numbers. ua4ever has recently made an OSIS file in the KJV order, but with the original Ukrainian verse references in parentheses. Download RAR file from [1]. For related discussions, see [2]. Registration and login is required.

Resources

• Harry Plantinga's Mapping of Alternate Versifications - a useful examination of various versification systems, based on data supplied by SIL, but due to numerous errors probably not a prospective source of data for Sword