[jsword-devel] Alternate Versification

[DM Smith]

SWORD is adding the ability to have other versifications (v11n) than  
the hard-coded KJV v11n. We need to add this to JSword, too.

There are some of ways that one v11n can differ from another:
1) Additional books - E.g. Apocrypha/Deuterocanonical
2) Different order of books - E.g. Hebrew Tanakh.
3) Different "long" names for the books. E.g. 1-4 Kings.
4) Different number of chapters in a book. E.g. Some only have 3  
chapters in Malachi, with all of KJV's chapter 4 at the end.
5) Different number of verses in a chapter. E.g. Many have 3 John 1:15
6) Different numbering of the verses. E.g. The titles in the Psalms  
come before verse 1 in the KJV, but are verse 1 in the KJV.

There may be others.

The issue of mapping (#6) is not being addressed at this time.

In the module's conf, a module will have a new entry
Versification=KJV
which if absent, will default to the KJV.

New v11n include:
KJVA
Leningrad
Tanakh
NRSV
NRSVA

Some others that may be added before too long:
Luther
Vulgate
Original - a combination of the Tanakh, Apocrypha (possibly from the  
LXX) and GNT.

For more details, see: http://crosswire.org/wiki/Alternate_Versification/System_Identification

Enough of the preamble. We need to change JSword and it will break all  
existing programs: Bible Desktop, Alkitab, FireBible, and ones we  
haven't been told about.

I would like it if we can do this with a minimum of problems.

I have been following the development of Lucene and I like their  
model. To do a break like this, they:
1) Add new classes and/or methods.
2) Mark affected classes and methods as deprecated, pointing each  
deprecation to the new code.
After a release containing both the new code and the deprecated code,  
they have another release that removes those deprecations.

Would this work for us?

Next question is that of design. Most of it will be in  
o.c.jsword.versification:
1) Each of the new v11n systems is hard-coded into the SWORD engine  
for maximal lookup speed. There is no startup cost, but it increases  
the core size of the program. We can do something similar, or we can  
put the definition into resource files and read them in on first need.  
I'm leaning to the latter.

2) There is a strong notion of a book having a fixed ordinal value.  
Currently, there is no accommodation for extra books.
This affects most of the classes in o.c.j.versification.

2.1) OSISNames has an ordered list of books and does not include the  
apocrypha. There are conversions to and from an OSIS name and a book  
number. I think we can keep this with the addition of the book numbers.

2.2) BookNames is a localized representation of a book number and has  
hard-coded integer values for Gen-Rev (1..66). I think these numbers  
need to move to OSISNames, perhaps as an enumeration OSISBookNumber.  
And BookNames should take an OSIS name or an OSISBookNumber to do the  
lookup.

2.3) SectionNames likewise would be change to take an OSIS name or an  
OSISBookNumber to do the lookup. For the purposes of Advanced Search  
in BibleDesktop, there would need to be some kind of getRange(int  
section) that would need to be added. I think it might be good to  
change this to an enumeration, too.)

2.4) BibleInfo is the most problematic as it really is KJVBibleInfo  
and now we need a BibleInfo for each v11n scheme. I think we need a  
VersificationManager that given a v11n name, it will return a  
BibleInfo specific to that v11n. It too is indexed by book number, but  
in this case, it will need to be the ordinal position of the book in  
that system and not the OSISBookNumber. It might be good to add an  
iterator of the books in BibleInfo that returns OSISBookNumber.


2.5) BookName knows it's book number. Hmm.

The whole notion of a book having an integer value might cause non- 
obvious breakages if we change it's semantic. I'm inclined to break  
the notion of book numbers entirely so that all using code needs to  
change. But still, I'd like it to be as simple a migration as possible.

I'd really like input.

Together in Christ,
	DM