[jsword-devel] Module write support

[DM Smith]

One of the things that JSword has not implemented is write support for 
modules. This prevents us from using the Personal Commentary module. 
While this keeps JSword from being able to create or modify other kinds 
of modules, that has not been all that important as there are Sword 
utilities to create modules. But adding support will open the door for 
that as well.

I changed JSword's Book interface to have appropriate methods for module 
writing. These are:
boolean isWritable()
void setRawText(Key key, String rawText) throws BookException
void setAliasKey(Key alias, Key source) throws BookException

The first and second of these is pretty obvious, is the book writable 
and given a key and it's text, store it appropriately.

The third of these is not obvious, but Sword allows for one Key to alias 
another. There are three typical places that this is used:
1) Dictionaries often have synonyms be defined with one term and others 
point to the same.
2) Some bibles don't number every verse, e.g. The original Message Bible 
does not have any verse numbers and some have passages numbered in the 
margins. Aliasing allows for all verses in a passage to point to the 
singular storage location. (By the way, BibleDesktop and JSword have a 
bug here that needs to be fixed: It show the content once for each alias)
3) A chapter in a commentary may refer to a passage or chapter in a 
Bible. These commentaries are indexed as if they were a Bible, with 
heavy use of aliases.

The next thing that needs to be done is to add write support to the back 
end. It will be easiest to start with an uncompressed module. These 
generally consist of a index file and a data file. The index file 
contains entries that are key strings, seek positions and data lengths. 
The raw Bible modules, don't store the key strings as they are computed. 
The data file merely contains appended data, possibly encrypted. This 
has an interesting side effect, if a key is written to again, the index 
will be updated to point to the newly appended data. The old data will 
remain in the module, but not have any pointer to it.

Once we have write support for a raw Commentary module, we can use it 
for a Personal Commentary. The Sword module is ThML and no application 
creates content that another can use. I'd like to see JSword use OSIS 
for the content, but for a first iteration it would probably make sense 
to have it be PlainText. The upshot is that some kind of editor will be 
needed in BibleDesktop.

Anyway, my point in mentioning all of this is that I won't be able to 
get to it for quite a while. I am going on vacation for a couple of 
weeks and when I get back, I'll be working on some modules. That will 
probably take me a few months. If anyone wants to pick this up, please do.