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

[Troy A. Griffitts]

Hey Chris,
	I'm not sure you understood or answered any of my concerns.

	o	You addressed your previous email to frontend developers informing 
them of your markup changes.  From this, I was under the impression that 
you actually thought frontend developers needed to know about your 
markup in the new modules-- which they should not, IMO.

	What I get from your reply is that we can modify the OSIS* filters to 
render the markup in the same way as all the other modules, right?  If 
so, then can you please update all of our filters to handle your new 
markup in at least as "user interpretable" as the other modules, e.g.

"Text of verse 13 [14. Text of non-KJV verse 14]"



> 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).

er, no...
the number 2 was not the pinnicle of my argument.  ONE way, was the 
indended point I was trying to make-- with a parenthetical exception for 
the hack we currently use for non-KJV conformant schemes.

Introducing a <verse> tag passed to the frontend was my issue.


> 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.

OK, from this statement, I am under the impression that we don't have an 
issue.  Your intention is to handle these in filters, and NOT pass the 
<verse> tag to the frontend, right (unless, of course the frontend 
decides they want their custom filters to pass it thru)?

The summary of my issue is that frontend developers should not break or 
be forced to introduce new code because of the markup you introduced in 
your new modules.  If they must, then we need to discuss and justify.


>>     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.


Ok, but this NOT the way the engine operates currently and if we change 
it, we need to talk about it.

One of the key benefits of our engine is the ability to say:

"Hey give me John 3:16 from the KJV; and oh, by the way, give it to me 
in HTML"

and NOT CARE how that happens.


> 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.

With the exception that the end user can still human interpret the verse 
division.  Aside from rendering, our hack still displays these verses 
with something humanly intelligible, e.g. " [14. ....]"

>>     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.

Agreed.


 > I've always considered alterations to the standard
> and publishing non-conformant documents to be extremely harmful to the 
> standard.

Again, agreed; but fail to see the pertinence.


> As long as we don't expose non-standard uses to the public, 
> the damage is minimized, though.

minimized? or non-existant?


> But at the same time, I don't see much 
> difference between resp as an element and resp as an attribute

The specifics of the KJV resp usage are not as simple as changing it to 
an attribute.  Patrick has considered our usage and may update the spec. 
(may have already updated...)



> or 
> between "<title type="x-preverse">...</title>..." and 
> "<title>...</title><verse>...</verse>" (except, of course, that the 
> latter are actually based on the spec).

Except that this is a CHANGE to the frontend developers and NEEDS TO BE 
CONSISTENT ACROSS ALL MODULES, EVEN NON-OSIS MODULES, if we decide to 
make this change.  If we decide to change the mechanism for all SWORD 
apps to render ALL verse numbers-- which is what you are doing-- then it 
requires more than a: "Hey, by the way..." email.

...that's my only point.