[sword-devel] x-preverse

[Troy A. Griffitts]

OK, to reopen the issue (reluctantly)... :)

The problem:  When importing a document into sword, we need to slice it 
up into compartments that can be requested by a user.  Here's an example 
that demonstrates a huge majority of the use case.  Text:

...
James

Chapter 1

Testing Your Faith

1 James, a bond-servant of God and of the Lord Jesus Christ,
To the twelve tribes who are dispersed abroad: Greetings.
...


How should this text be 'compartmentalized' into storage slots in sword, 
and what is returned what a user asks for "James 1:1"?


SWORD's current solution, basically:

Testing Your Faith

1 James, a bond-servant of God and of the Lord Jesus Christ,
To the twelve tribes who are dispersed abroad: Greetings.

all goes into 'slot' James 1:1.

1 James, a bond-servant of God and of the Lord Jesus Christ,
To the twelve tribes who are dispersed abroad: Greetings.

is returned as 'verse text', and

Testing Your Faith

is returned as 'preverse text'

Currently we have wording to imply this is a 'title'

The future plan currently is to place all text preceding a verse that 
might get displayed before a verse in a more generic: <div 
type="x-preverse"> so our osis filters can easily put this entire 
section in the preverse compartment.


These are internal tags to make our processing faster and easier at 
runtime.  Arguments about their non-OSIS-compliance are moot.

Our "osis to osis" filter is meant to reverse any internal markup we do 
for osis documents.


Now, the other argument that Chris has expressed and DM has also lobbied 
for, is placing the <verse> tag at the point where preverse ends and 
verse starts...

I can't comment on how JSword strips extra text when preparing for 
searching, or how verse numbering is customized by the user and 
processed by JSword.  I can only say that SWORD can isolate clients of 
the api from processing tags when rendering.  The rendering process for 
all of our frontends is basically:

for (position module at starting verse;
      as long as I'm <= ending verse;
      increment module position) {
   ask module for preverse text and display it
   show some kind of verse numbering
   ask module for verse text and display it
}


To embed verse numbering inside output from the engine would move tag 
processing from the filters and place the burden on clients of the engine.

This would require rewrites for all frontends and I feel the better 
design is to keep the tag processing modularized and isolated inside our 
filter mechanism.

This is the reasoning for the current implementation and it is not as 
much of a 'hack' as Chris might think :)  It is a difficult problem to 
compartmentalize an annotated Biblical text and still provide a concise 
api to its content.  Not to put words into our good friend Bob at Logos, 
but I remember him also conveying, in one of our OSIS meetings early on, 
that they have markers for 'display regions' so they know how much of a 
document to display when a user asks for, e.g. "Jas.1.1.".  SWORD 
effectively does the same thing by placing the 'display region' in the 
verse, but splitting into 2 compartments: verse text, and preverse text.

To be fair, a problematic issue is still Psalm titles.  They are 
canonical and should be searched when the user does a search of the 
Biblical text, but they should be displayed before any verse number the 
application decides to show.

	-Troy.