[sword-devel] 1 bug left for 1.5.8

[Chris Little]

Okay, I've taken a look at the test.osis.xml file Christopher posted in 
the bug tracker and found the following. This is based on a module 
compiled with osis2mod (from SVN) and the same module inspected in 
BibleCS 1.5.8pre3, as well as the module exported with mod2osis & 
mod2imp (from SVN).

(Quoting from Matthew chapter 1 in the document test file:)
 > This is a test file to show off the problems encountered with Sword
 > OSIS2Mod and Sword for windows rendering. In the examples below I've
 > used '[' and ']' in the place of '<' and '>'
 > This file was written using XMLSpy and validated successfully against 
 > osisCore.2.0.1.xsd

Just to confirm, it also validates in oXygen.

 > This file is split up into several chapters each showing a different
 > behaviour. The contents of each chapter is described below:
 > 0) Introduction test:
 > chapter 0: introduction which contains multiple parapgraphs is not
 > rendered properly (some RTF rubbish)

Works/renders fine in 1.5.8pre3. Maybe the problem has already been 
corrected.

 > 1) Paragraph tests: additionally chapterTitle in chapters 2-4 is just
 > ignored...

The chapterTitle attribute on <chapter> elements is preserved by 
osis2mod, but ignored by the engine. I have no idea what this attribute 
is for, but would guess it is something we forgot to remove when we 
changed how titles are done. In any case, the correct way to encode all 
titles that occur in the text would be with <title>.

 > chapter 2: paragraph markers outside of verse tags (paragraphs enclose
 > verse tags) - resulting a complete mess in Sword for Windows RTF

It's unattractive but not RTF gibberish, so I suspect this has already 
been fixed.

 > chapter 3: paragraph markers inside verses, with construct like this:
 > [verse s][p]text[/p][p][verse e][verse s]text[/p][p][verse e]. This is
 > the workaround for problems introduced in chapter 2.
 > chapter 4: paragraph markers completelly embeded into verses - all [p]
 > and [/p] markers are inside the verse tags. Also considered by me as a
 > woraround to problems in chapter 2

Workarounds are bad.

 > 2) notes/xrefs problems:
 > chapter 5: xrefs crossing paragraph boundaries

This is also just the problem above that was fixed.

 > 3) problems with div's and titles
 > chapter 6: div and title ignored if placed before the chapter start
 > tag

This is correct, but where should content between two chapters go? 
Should it go in the introduction to the following chapter?

 > chapter 7: two separate divs and titles inside a chapter - possibly
 > missing newline after the div end tag

This is just a criticism of rendering style, so not really a bug. And 
it's a criticism specific to BibleCS. Short answer: no, div should not 
generate paragraph breaks.

Best practice OSIS requires a structure of:
<div type="book"> with other div types embedded in that, notably <div 
type="section">. But the lowest level of the primary OSIS hierarchy is 
<p>. <p> should and does generate paragraph breaks. It never allows 
embedding of <div>s, so <p> should be the lowest level always. (This 
ignores simple Bibles without any paragraph structure, just 
book/chapter/verse.)

 > chapter 8 and 9: div spanning two chapters - almost ok

Same issue as chapter 7.

 > chapter 10: div and title just after the chapter start tag - also
 > almost correct

Same issue as chapter 7, also. But there is also a problem here with 
osis2mod. It's making two copies of <title> elements that occur before 
the first verse. (One in the chapter intro, one in the verse 1 preverse 
title.) It is only the second of these that is being rendered. Instead, 
perhaps we should render the intro content and eliminate any preverse 
titles in verse 1. This is an osis2mod and/or frontend issue (not API).

 > chapter 11: two embedded divs just after the chapter start results in
 > first title missing

The preverse code is only grabbing the previous title, so only the last 
title is rendered. Implementing the above would fix this.

 > chapter 12: two embedded divs in the middle of the chapter - the
 > titles are in the wrong order

Again it's the preverse code. It's only grabbing the previous title to 
put IT before the verse number. All remaining titles will appear in 
proper order. (For German-speakers, it's just like verb-second. Only the 
very last verb in a clause gets promoted to the second position in the 
clause. :)

 > chapter 13: three embedded divs just after the chapter start - two
 > sections missing and verses concatenated

This one is the encoder's fault. :) All of the verses have the same 
osisID (Matt.13.1), so they are concatenated into that verse. Aside from 
the behavior parallel to chapter 11, osis2mod is functioning correctly.

 > chapter 14: three embedded divs in the middle of the chapter - wrong
 > titles order

Same as 12.

 > chapter 15: a note in the title - not rendered as a note!

The data is correct, the rendering (in BibleCS) is incorrect.

 > 4) Various tests
 > chapter 16: test of alternative passages

<rdg> isn't handled, but it also isn't very interesting. I'll make a 
note to add a handler in the filters, but all it will do is italicize 
the contents.

<rdg> is not for alternative passages, just alterate readings. So you 
wouldn't have "<note type="alternative"><catchWord>something</catchWord> 
<rdg>First version of the text</rdg> <rdg>Second version of the 
text</rdg></note>" and expect there to be a toggle between the two 
readings. The primary reading occurs in the text (and possibly in the 
<catchWord>).

The OSIS 2.1 draft manual gives the following example of intended usage:

<verse osisID="NRSV.Song.2.1">I am a rose<note 
osisRef="NRSV.Song.2.1 at s[rose]">Heb <rdg>crocus</rdg></note> of Sharon, 
a lily of the valleys.</verse>



Thanks for going to the trouble of writing the test file. I'll continue 
to use it to test until we get the import & rendering improved. It 
illustrated a lot of areas where both osis2mod and BibleCS could use 
some work, but I don't think any of the items need to hold up the 
release of 1.5.8 (the API). I would recommend we attend to the osis2mod 
and BibleCS problems before releasing them. (I realize that much of the 
BibleCS code responsible for its deficiencies is in the OSIS2RTF filter, 
which is technically part of the API, but I don't think this is used by 
anything other than BibleCS, so I wouldn't see a problem with releasing 
1.5.8 with a buggy OSIS2RTF, so long as it gets fixed before the next 
BibleCS itself is released.)

--Chris