[sword-devel] New Modules (front-end developers: please read)

[Chris Little]

Troy,

Troy A. Griffitts wrote:

>     I think we need more discussion before changing modus oparandi on 
> verse rendering for all clients of the API.
> 
>     A few bylaws we've adhered to which are valuable to the users of the 
> engine:
> 
>     o    A client of the engine should only have to render Bible verse 
> numbers in 1 way (possibly 2-- for an exception like alternate 
> versification-- I think done with footnotes thusfar); we shouldn't 
> expect them to have checks in their code for a variety of methods.

I'm unaware of any clients that use any method other than reading the 
VerseKey of an entry.  So that makes this only the second method (ergo 
"possibly" okay under your rubric).

There's absolutely no standardization, within Sword, regarding the 
encoding of alternate versification.  I can think of at least three 
different methods, only one of which is a footnote.  However, now we 
have the information encoded in a standard form so that it can be 
transformed to footnotes or chap:verse-style references by the render 
filters.

>     o    We shouldn't expect a client to know the base markup (even 
> OSIS).  We do the hard work to hand them something they've requested on 
> init of the lib (previously by subclassing SWMgr and applying 
> appropriate filters, and now with your newer SWMarkupMgr, which more 
> nicely isolates them from the plethora of filter combinations).

Personally, I have no problem with requiring clients to know something 
about OSIS.  However, I never said they did needed to in order to use 
embedded <verse> elements.

<verse> elements can be transformed into whatever render format that a 
specific client expects.  And failing that, you end up with no numbers 
for alternate versifications, which is basically what we have now.

>     I think these are valuable things which we might be violating with 
> your latest changes.  Is there a way to provide filtering in OSIS* 
> filters to retain these benefits?
> 
>     Up until now, I've had the personal opinion that we should normalize 
> OSIS modules to our internal OSIS methods of markup, so filters could 
> all expect constructs in the document to be encoded consistently.  We 
> have a filter OSISOSIS (which is a silly name) which is intended to 
> filter 'our OSIS' markup back to the 'original OSIS' markup of the 
> document.  It is used primarily to remove non-conformant tags like 
> <resp> in our KJV module, or any other thing we might add to help our 
> rendering process, but doesn't either conform to the OSIS standard or 
> recommended guidelines, like restore x-preverse titles to their original 
> positions.

I've always been of the opinion that we should follow the OSIS standard 
as much as possible.  I've always considered alterations to the standard 
and publishing non-conformant documents to be extremely harmful to the 
standard.  As long as we don't expose non-standard uses to the public, 
the damage is minimized, though.  But at the same time, I don't see much 
difference between resp as an element and resp as an attribute or 
between "<title type="x-preverse">...</title>..." and 
"<title>...</title><verse>...</verse>" (except, of course, that the 
latter are actually based on the spec).

--Chris