[jsword-devel] Updates

[Joe Walker]

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!"

> The problem with KeyList extending Key is that it is not a true ISA 
> relationship. From examining the code for the usage of a Key, a Key 
> describes one location in a book and the length of a  Key is from that 
> location to the next sequentially larger key. And a KeyList is simply 
> an ordered list of possibly non-contiguous Keys. The order is not 
> limited to order by sequence, but it usually is used in that way.

The Node example you've mentioned would generally distinguish between 
leaf and branch nodes using a property rather than inheritance. This 
would leave us removing Key and just using KeyList (and then probably 
calling it something less confusing, maybe even Key!)

Using inheritance leaves you having lots of overridden methods like 
add(Key) and add(KeyList) and so on.

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

> Within the code, there are places that need a list of references and a 
> couple of places that need individual references.
>
> When I looked at OSIS 2, I noticed that the definition of verse 
> boundaries was deliberately fuzzy. A translation may collect one or 
> more biblical verses into a single OSIS verse. It may also split a 
> biblical verse into two or more OSIS verses ( 1.6a, 1.6b, 1.6c, ...). 
> I guess it is a recognition that verses were added after the Bible was 
> written and while they have been canonicalized, some "translations" 
> (e.g. the Message and other paraphrases) do not adhere to them. And 
> some for typographical reasons, refine them further by splitting them.


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 understand that Theophilos has done a good deal of work in trying to 
sort out a coding scheme that lets everyone point at the same verse, and 
enables cross-language parallel Bible display.

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.

> Since we are ultimately mapping a particular book's markup into OSIS, 
> it seems reasonable to consider the OSIS definition.
>
> In looking at the actual definition of Key, it has two parts name and 
> parent. In the code, getParent is used in one and only one place and 
> that is in ReferencePane which is in "limbo". The notion of parent is 
> not actually that of a parent in the sense that it forms a tree. The 
> code does set the parent via various constructors, but in each case it 
> has a key being a member of a list. But in all cases the list is not a 
> member of another list. Thus 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?

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.

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.

> 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.

Joe.