[sword-devel] Pre-verse hack Was: Re: Small problem with section headers in an OSIS module

[DM Smith]

On Nov 30, 2008, at 12:00 AM, Chris Little wrote:

> Tom Cornell wrote:
>

<snip/>

>> My markup looks like this, basically:
>>
>> ...
>> </div>
>> <div type="section">
>> <title>The Section Title</title>
>> <verse sID="..." .../>...<verse eID="..."/>
>> ...
>> </div>
>
> This markup is definitely correct.
>
>
>
> More long-term, DM and I are in agreement that we need to change the  
> way
> we handle storage of OSIS documents within modules. We feel we need to
> get away from the pre-verse hacks that you'll notice in the output  
> from
> mod2imp. And we feel we need to do a better job of preserving all of  
> the
> data in a document (including the <verse> tags themselves).
>
> When I committed a new version of osis2mod 3-4 years ago that did  
> all of
> this (in a way that neither harmed existing nor future data) it was
> roundly rejected and reverted. I'm still convinced that preservation,
> including storing <verse>, is the only solution to certain of our
> problems. And I'm hoping that DM and I can convince the naysayers of  
> the
> merits of that position.

The pre-verse hack is that the <title>...</title> is yanked out of  
line and prepended to the following verse using the following construct:
<title type="section" subType="x-preverse">...</title>
(That is we add type="section" and subTuype="x-preverse" to the title  
element. This may be lossy.

The other part of the preverse hack is that SWORD modules do not  
contain the <verse> tag.

The SWORD engine uses this to do two things:
1) Handle headings. Currently only <title> is allowed in this x- 
preverse div.
2) Know where to place the verse number.

Any changes to the SWORD engine will still need to handle existing  
modules.

Chris, Troy and I are in agreement that this needs to change. There  
are two proposed solutions:
1) Change osis2mod to output the tags in the order that they occur,  
either appending them to the prior verse or prepending them to the  
following verse and also output the verse start and end tags.
2) Extend the pre-verse hack to include more than just title. All  
inter-verse tags are output in the order they appear, either appended  
to the prior verse or placed into a preverse div and the preverse div  
is prepended as before.
<div sID="xxxx" type="section" subType="x-preverse"/>
     ... inter-verse stuff before the title that belongs with this  
verse...
     <title>...</title>
     ... inter-verse stuff after the title ...
<div eID="xxx">

(Note: osis2mod performs some transformations. For example, it  
transforms all container elements into their milestoned form. OSIS  
does not allow <p> to be milestoned, so <lb type="x-begin-paragraph"/>  
and <lb type="x-end-paragraph"/> are used as rough equivalents.)

A related aspect of osis2mod is the identification of introductory  
material. I'll write about this separately.

Chris and I would like to see that osis2mod is a lossless  
transformation into a SWORD module, at least for the text of the Bible  
or Commentary. Today, the <verse> element and it's attributes are not  
included in the module. There are a few advantages of having it in the  
module.
1) It provides the exact placement of the verse number and renders the  
pre-verse hack entirely unnecessary. Yes the SWORD engine will still  
need to support the hack.
2) The verse tag conveys information beyond the placement of the verse  
number. Of the attributes, the n attribute is perhaps the most  
significant. The n attribute holds the verse number. While this  
typically is just a number, for some Bibles, it can give a range, e.g.  
4-7. This could be useful.
3) Whitespace does not need to be added.
4) osis2mod is greatly simplified.
5) osis2mod would be lossless.

Today, you can experiment with the <verse> tag being included in a  
module by uncommenting
//#define INCLUDE_TAGS
in osis2mod.

Having the verse tag present requires no changes to the SWORD engine.


In His Service,
	DM