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

[Chris Little]

Troy A. Griffitts wrote:

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

Yes.  And there are two reasons for that.  The first is that most of the 
front-end developers maintain their own render filters.  Therefore 
they'll probably need to make changes.  The second is that developers 
who want to provide an improved rendering to their users can use the 
OSIS tags themselves to render verse numbers.  They're OBVIOUSLY going 
to do that with a render filter, but probably in their own filters since 
they may want to support user-configured text coloring or whatever.

>     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]"

In which way do all the other modules render verse numbers?  Like I 
said, there are three different ways at least, and you introduce a 
fourth here.  I don't wish to render verse tags to text because I don't 
think that's the correct direction in which to go (except maybe for the 
plaintext & HTML filters), but I'll certainly consider it.  If the verse 
tags go unhandled, the fallback is to simply ignore them.

I will, however, add verse number rendering in BibleCS.  And I'll listen 
to the feedback from developers working on other front-ends.  If there's 
real popular outcry, I'll make some of the other render filters render 
verse tags as text.

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

I guess my issue was that "one way" does not suffice with a fixed 
versification system, and three other ways isn't very good either.

My underlying interest here wasn't to invent a new way of rendering 
verse numbers.  My objective was to store the correct data within our 
Bible databases, including verse tags and titles in the correct 
ordering.  The fact that it allows a new way of rendering verse numbers, 
a less kludgey way of rendering titles before verse numbers, and more 
accurate OSIS->Sword module->OSIS roundtrip conversion is simply a 
side-effect that falls out of properly storing the source data.

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

Nothing breaks.  If you do nothing, you simply get titles following 
verses numbers and no markers for non-KJV verses.  It's not optimal, but 
it certainly isn't broken.

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

Actually, you're wrong.

Case in point: the <title type="x-preverse"> tag I keep mentioning.  In 
order to correctly render that, you need access to the underlying OSIS. 
  That was your hack.  Now I'm being criticized for doing the exact same 
thing--only without making changes to the underlying text.

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

Well, as long as we don't expose non-standard uses to the public, the 
damage is non-existent.  However, this is an open project, so everything 
is public, to some extent.

I guess my beef is with tools and docs that get distributed which 
encourage non-compliant usage, rely on modified versions of the OSIS 
schema, etc.  People look at those docs and the output from those tools 
and think they represent how OSIS should look--when they don't.  And 
CrossWire (though by NO means the sole perpetrator of this particular 
crime against humanity) is responsible for part of the confusion people 
have been having over OSIS.

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

Er, no, these are exactly the same in that both require that the 
front-end have some access to the underlying markup.

I guess I don't see how anything needs to be consistent across all 
modules, let alone non-OSIS modules.  At some point we need to move on 
from our old implementations, and this is a good example of something 
that needs to be improved.  I tagged the .confs with an OSISVersion key, 
BTW, which can serve (as well as anything) as a means for 
differentiating modules with verse tags from those without.

--Chris