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

[Troy A. Griffitts]

Chris,
	There are a number of issues that need to be addressed if we 
change the modus operandi of verse number handling (which we are doing in 
spite of your insistence that we are not).  There are merits of using the 
verse tag to provide the verse number, and there are merits to not use the 
<verse> tag.  These are all thing which need to be discussed and WE WILL 
DISCUSS THEM before changing the modus operandi.  This will not be a 
supported behaviour in 1.5.8.


> > I was working on a new module anf run into trouble with your new module.
> > The module has titles so I think osis2mod put the title tag into each verse 
> > followed by the verse tag.
> 
> Correct.  We've always put titles into the verse that immediately 
> follows them.

and marked them as preverse text.  This should not change right now.  the
frontends already deal with preverse number text this way and will for the
1.5.8 release.  If you want your modules to be supported in 1.5.8, then
they need a section of text that is marked somehow as x-preverse that is
placed into the appropriate entryAttributes element.  You are welcome to
add a <div type="x-preverse"> if you would like, and then search for
x-preverse in the osis filters (which I believe only look for it in the
<title> element currently) and add the check for the <div>.  This should
allow all frontends to continue to operate without changes.

I'm still standing with my position that we will not support all valid 
OSIS markup in the engine.  The IMPORT code will normal the great 
diversity of OSIS markup into a normalized (even possibly extended-- gasp) 
OSIS markup that we understand.  Our filters cannot all try to handle 
every kind of osis-- from milestone pseudo-containers, to BCV vs. DP, to 
all the other anomalies that I don't have to remind you about.


> > My problem: That is nowhere supported atm.
> > If I want to implement this in BibleTime I need to know if the module includes 
> > the <verse> tags in the text itself or if it's a module prepared in the old 
> > way.
> 
> Just check the OSISVersion entry in the .conf.  The new modules are 
> tagged with OSISVersion=2.0.1.  Other OSIS modules won't have this tag 
> at all and most of them would be tagged as OSISVersion=1.1.1, if we went 
> back and added the metadata to them.  So you can assume that if 
> OSISVersion >= 2 then ALL tags from the OSIS document are supposed to be 
> in the Sword module, including <verse> tags.

this requires a frontend change, not merely a filter change,
e.g.
<title>yoyo</title>
<verse>verse text</verse>

will display as e.g. "3 YOYO 3 verse text" since the frontend adds verse 
numbers currently.


> > Basically I think we shouldn't add a new way to store/render verses because 
> > the new modules prepared this way do not work properly in all existing 
> > frontends. There's even no windows version supporting this atm.
> 
> It's not a revolutionary change.  Nothing breaks.  Everything works 
> exactly the same as it always has in every existing frontend.  All you 
> need to do in order to support verse tag rendering almost completely is 
> to render a little number for every <verse> tag following the first one 
> within a verse.  You can do this trivially with one conditional in your 
> OSIS filter.

This is not true, see above.

 
> When Daniel's new versification work is completed, we will STILL store 
> <verse> tags and hopefully frontends will use those to render the verse 
> numbers.

You are welcome to propose this, as you've tried to do, but you need to 
take the time to understand my objections, sent in previous emails, 
respect chain of approval, and schedule.  This will not be a 1.5.8 change.


> > Don't get me wrong, I think the new way is better than the old one but we 
> > shouldn't have one more way to have markup in the modules.
> 
> Changes may be unpleasant, but they are necessary if we want to make any 
> progress.

This is a valid statement.

  We can't simply drop the old way of rendering verse numbers 
> because it is used in a couple of hundred modules that would have to be 
> updated.

This is not a valid statement.  The problem is the CLIENT of the engine.  
If we decided that the client should ASSUME that the verse numbers were
rendered for them, and we changed the filters to do this (your
suggestion), then a change of all the filters (checking old and new
version of OSIS, like you suggest) would normalize the verse rendering for
the client.  The client (i.e. gnomesword, bibletime, swordweb, biblestudy,
macsword, swordreader, et. al.) would still only have 1 way to render all
verse numbers (they would assume they were rendered for them), in spite of
some modules being old and some being new.  We can't ask them to handle
another way right now (or ever).  A DIFFERENT way maybe in the future, but
not MORE ways.

	-Troy.