[jsword-devel] Updates

[DM Smith]

See below.

Joe Walker wrote:
> DM Smith wrote:
> 
>> After writing the note, I realized that it is really long. So I 
>> thought that I would give a list of the key points.
>> 1) KeyList or Passage should be the parameter that is consistently 
>> used in the API not Key or Verse.
>> 2) Blurring makes sense for all books.
>> 3) The indexing of Bibles is lossy.
>> 4) JSword ignores the Deutrocannonical books when present.
> 
> 
> Various comments inline.
> I've chopped out various paragraphs where I completely agree rather than 
> copying the whole thing back and then saying "Me too!"

Me too!! ;-)

> Merging Key and KeyList into Key sounds like a good solution to me???

I think a simplification is needed. I think that merging is worth a try.
And if it does not work, then revert the code.

> 
>> When I looked at OSIS 2, I noticed that the definition of verse 
>> boundaries was deliberately fuzzy.
> 
> I believe it's also true that many non-English Bibles don't follow the 
> same verse/chapter divisions (Russian Bible), and don't follow the same 
> book ordering (Torah), and some Bibles add (Aprcropha) or miss out (some 
> Greek NTs) sections.
> 
> I've half mentally put it all in the post-1.0 pile, and in part also I 
> guess the drive to hide Passage behind Key[List] was part of looking 
> forward to how we solve the problem.

My point in mentioning it is not to solve it in 1.0 but to make it no
harder in post-1.0.

> 
>> Since we are ultimately mapping a particular book's markup into OSIS, 
>> it seems reasonable to consider the OSIS definition.
>>
>> The only real value to the class Key is 
>> that it provides a name. I think it would be better to get rid of the 
>> notion of parent add an interface Nameable or Titleable or something 
>> that represents that getName returns a title that can be displayed and 
>> make Key extend it. KeyList would extend Nameable but not Key. KeyList 
>> would contain Keys.
> 
> 
> 
> Not sure of the benefits of having a concept of Nameable?
I did not mean extend Nameable, I meant implement it. But that is not an 
answer to your question.


If Key and KeyList are merged, then it does not make sense to have 
Nameable. The name of a key is used in two distinctly different 
directions. It is used as a displayable title and as such should be 
internationalized. It is also used as a key into an index. That is it is 
used both as an external, user-visible name and in internal, user-hidden 
name.

Since the index is independent of a users language and locale, it cannot 
be internationalized. It is useful to make sure these two uses do not 
overlap. Nameable provides a display name for the element. For 
discussions purposes lets rename getName to getExternalName()

 From an api perspective one could change setTitle(String s) to
setTitle(Nameable n). Then setTitle would call n.getExternalName(). The
advantage is "safety" and "maintainability".

An interface Keyable would have the method getInternalName().

Anyway, I defer as it is not significant.

> 
> The ReferencePane is only in the limbo directory because it is not used 
> and currently not being worked on. However I think it is a really good 
> idea.
> The idea is to replace the complex right hand bar containing 
> dictionaries and commentaries with a single tree that contains all you 
> reference works. When you look something up in your reference bar, the 
> tree just opens at the relevant places, and the contents of the Key are 
> shown within the tree.

I saw in bugs.txt that you planned to do this. So I understand that 
limbo is stuff that is currently not used but may be a post-1.0 feature.
I am "double-minded" when it comes to code we know we may use. Do we 
maintain it as if it were used or do we ignore it until we actually get 
to using it? On the one hand by having a strategic view we make better 
design and implementation decisions now. And on the other hand we 
preserve complexities that may never come about as coded today.

> 
> It is mostly there except that the "tree" implemented by 
> PassageKeyFactory is flat - i.e. 
> PassageKeyFactory.getGlobalKeyList().iterate() gives you a loooong list 
> - a node for each verse in the Bible, far to big for a usable tree. It 
> needed time spent making the PassageKeyFactory more hierachical, so we'd 
> probably start with groups of books, then books then chapters (maybe 
> splitting Psalms up into 5 books) and then to verses.
> I decided to make this post 1.0 simply because I feel like I'm in danger 
> of being in perpetual beta.

I think that we are pretty close to going to 0.9.8. I don't know what 
changes that you think we need to make beyond what is bugs.txt, but the 
code looks pretty solid. I think that we have to do some data 
validation, but that is about it.

> 
>> While I am on the subject of the indexes, they are lossy. This can be 
>> easily seen in the view source's original tab. There is no markup 
>> around the verse. Also, if you take the start and length of one verse 
>> and add them you will find that it may not mark the start of the next 
>> verse as contained in the index. Between v1start + v1length and 
>> v2start is markup and/or content. You can see it in the KJV w/ Strong's.
> 
> 
> I don't think there is a requirement for it to be this way is there? 
> It's just that that is the way all implementations currently do it.
> You are right that this would probably be faster, less lossy an better 
> for OSIS optimization.

I don't know if Sword can handle the verse if it is not. Does Sword 
assume that there is no markup surrounding the original? So using a 
contrived example, today's indexing produces something like:
	Jesus wept.
	where offset is x and length is 11.
Rather than:
	<verse id="Jn.20.11">Jesus wept.</verse>
	where offset is x - 21 and length is 40.
Will this work in all consumers of the module?