[sword-devel] load v11n from file

Troy A. Griffitts scribe at crosswire.org
Thu Jul 14 09:16:47 MST 2011

Dear Konstantin,

Thank you for the suggestion and enumeration of the many benefits of
having canon definitions stored outside of files.

Practically, this is easy to implement.  The entire concept of managing
versification systems is contained in this file:


which isn't very large (DM, I hope this is an encouragement to you)

If you scroll to almost the very bottom of that file, you will find an
overloaded method called:


One implementation takes an array of data which basically specifies all
books, in order, with their short name and osisID and max chapter,
then for each chapter, the number of verses.

One registerVersificationSystem takes a TreeKey and there is not yet an
implementation.  This is planned to use the TreeKey from a GenBook or
just a standalone TreeKey idx data file to load a v11n.

This data is fairly simple and reading from a location, say like

would be trivial.

A current example of the arrays we read in is here:


Again, converting this to a data file format (either the existing
supported treekey idx format, or a simple text file would be trivial.

This IMPLEMENTATION isn't where the work lies.  Externalizing v11n
systems has always been a longterm goal.

The complexities lie in detailing policies.  How do these get installed?
 Are they versioned?  Are they named?  Does every module supply its own
v11n or does it name the versification it uses and the engine looks it
up in a central repository?  If a module supplies its own system and
names it KJVA, is that system installed to a central location available
for other modules to use?  What if another system also supplies a KJVA
but it is different?  Mappings between... VerseKeys currently know which
versification system they are using (by NAME; you can ask
VerseKey::getVersificationSystem())-- and there is a mechanism in the
framework which lets VerseKeys reposition themselves to the
corresponding location from another system-- though as you know, no
implementation for this translation is yet in place.  If modules supply
their own named v11n systems, how will this affect this concept?  Will
VerseKeys live any longer outside the concept of a module if they need a
module-supplied versification?  Again, what if VerseKeys have the same
name supplied with their module v11n but differ slightly, how will this
affect the mapping system?

There are a number of headaches we need to plan around.  Again, the
implementation of reading a v11n system from a file outside of code is a
great idea.  The devil is in the details for how this will live in our
ecosystem of multiple module developers and publishing sites and various

Your use case has demonstrated once again the need to move forward with

We could move forward slowly down the path by:

1) reading privately named v11n systems from

<module_library_root>/v11ns.d/ (same as we read locales.d/)

2) delivering our offical v11ns other than KJV under v11ns.d/ along with
the same delivery of locales.d/ (at library install time). This has the
effect that just as unofficial locales can current be supplied,
unofficial v11ns could also be supplied.

3) update InstallMgr to deliver locales.d/ and v11ns.d/
This has always been planned for locales.d/, but locales.d is a much
easier situation; nothing /should/ ever break if we supply an updated
locale on top of an old one.

(1) will give you the ability to create modules and test them with your
own v11n system, but will not yet give you the ability to deliver your
module easily with existing apps.

(2) and (3) are necessary for our long term delivery of official v11n

Beyond this we need to discuss how to let module developers supply their
own system without sabotaging other modules' systems, use a v11n if it
is already installed, share their system and mappings for other modules
to use until it is supplied in the official repository, only pull from
the official repository v11ns for modules installed, etc...

Thanks for bringing up the discussion and for the suggestion.  Looking
forward to your contribution moving this forward,


On 14/07/11 12:10, Konstantin Maslyuk wrote:
> As many v11ns exist already and even more can appear i would suggest to
> add ability to load v11n from file. Module can contain one binary file
> that will be loaded by SWMgr on module initialization, this file will
> fully describe v11n and mappings.
> Advantages are that you have only v11ns you are using, module is not
> influenced by code changes in v11n. No need to make GenBook Bibles, adding
> new v11n is not problem, no need to wait new Sword release that supports
> v11n for particular module.
>>  a new v11n with one v11n's NT and another's OT, with minimal
>> additional memory overhead. We do this already, since, for all the
>> variation in the OT, there are really only two common NT v11ns: with
>> Rev 17:18 & 3John 1:15 vs. without.
>>  The v11n used for Czech sounds similar to what is supposed to be
>> employed for French Bibles.
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page

More information about the sword-devel mailing list