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

[Troy A. Griffitts]

OK, I can't remember all my arguments for keeping the infamous 
"Pre-verse hack", but generally, the logic goes something like this:

module content is displayed in many different contexts: the obvious 
contextual display, search results, popup verse lists for x-ref, 
references, etc. parallel displays, and such.

A goal for the engine is to make easy things easy and more complicated 
things possible.

So,

SWMgr library;
SWModule &kjv = library.getModule("KJV");
kjv.setKey("jn.3.16");
cout << kjv;

should be understandable and straightforward by most any beginning C++ 
programmer.

If the programmer were expected to skip content until they found the 
<verse> tag, then it would become much more complicated.

The response would be... well, let the filters strip everything before 
the verse tag and place it in the pre-verse entryAttributes slot.

My response is: osis2mod should do this keeping the logic out of 
multiple filters and running in realtime, but instead only in one 
codebase and only once in the importer/import activity.

I'm not necessarily against retaining the n attribute of <verse>, or 
even the <verse> tag-- unless the <verse> tag becomes the place marker 
for start of canonical text, as essential has been suggested.  I 
wouldn't mind having a new entryAttributes()["verse"]["n"]["body"] = 
"3-12";  And we could pull this from a <verse n="3-12"> if left in the 
content, but THIS <verse> tag SHOULDN'T represent the MARKER WHERE 
DISPLAY SHOULD START.  In fact, if we included <verse> in the content, 
I'm quite sure we would digress to this usage, which makes things much 
more complicated per above argument.

I'm very much in favour of extending pre-verse to include all pre-verse 
content-- not just title.

Thoughts?

	-Troy.





DM Smith wrote:
> 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
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page