[sword-devel] Pre-verse hack Was: Re: Small problem with section headers in an OSIS module
Troy A. Griffitts
scribe at crosswire.org
Mon Dec 1 15:23:22 MST 2008
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
SWModule &kjv = library.getModule("KJV");
cout << kjv;
should be understandable and straightforward by most any beginning C++
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.
DM Smith wrote:
> On Nov 30, 2008, at 12:00 AM, Chris Little wrote:
>> Tom Cornell wrote:
>>> My markup looks like this, basically:
>>> <div type="section">
>>> <title>The Section Title</title>
>>> <verse sID="..." .../>...<verse eID="..."/>
>> This markup is definitely correct.
>> More long-term, DM and I are in agreement that we need to change the
>> 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
>> mod2imp. And we feel we need to do a better job of preserving all of
>> 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
>> 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
> 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
> ... 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
> 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,
> sword-devel mailing list: sword-devel at crosswire.org
> Instructions to unsubscribe/change your settings at above page
More information about the sword-devel