[sword-devel] OSIS Users Manual considered confusing

[Troy A. Griffitts]

Hey Matěj,

So, what was your question? :)


Any one of us could have technically designed the OSIS standard better.
Lack of technical expertise did not cause the issues you cite.

Nearly half the OSIS editor body is subscribed to this list, so please, 
if you have an honest question about the standard, humbly ask and know 
that there might be an answer you hadn't considered.

The reason, for example, there are 2 ways to markup Bibles: Book, 
Chapter, Verse (BCV) and Book, Section, Paragraph (BSP), is because 
there were 50+ organization providing input to the standard-- many of 
which refused to consider using the standard unless they could markup 
their data with X construct.

OSIS was more a political exercise than a technical challenge.  It is 
not the ideal standard, but it is a standard, nonetheless, with 
theoretically ABS, USB, Wycliffe, and other consortia of Bible 
translators agreeing to support the standard as, at least, an export 
format from their tools.

As a programmer, I would rather support x variations of markup within a 
single standard, than x completely different markup formats.

So, not ideal, but the best we could do to appease the masses enough to 
consent.

The hope was that we would draft the standard and then release a 'Best 
Practices' guide which was the technical ideal for the standard.

The author of the OSIS Users' Guide is not on this list (I don't 
believe), so in his absence I will defend his work and say that he put 
in countless hours taking notes to document how everyone wanted their 
markup used, and wrote the Users' Guide as a volunteer.  It's not 
perfect, and it may be inconsistent at times, and could certainly use 
improvement, but lets improve it and not tear down the initial work 
contributed.

I'm not sure if there was ever a Best Practices document released.  But 
we could certainly release one ourselves, which represents at least 
CrossWire's recommendations for OSIS markup for best results from our 
tools, and I think the effort toward building a representative document 
is already underway by Daniel and Patrick.

Hope this gives a little background.

By the way, even though a lossless transform exists between BCV and BSP 
XML hierarchies, I personally would always mark Bibles up as BCV and 
never as BSP because my mind thinks in storage 'slots' where Bible 
software needs to place each part of a document.  e.g., I need to 
retrieve John 3:16, much more often than John, Section "Jesus Talks To 
Nicodemus", Paragraph 3.

But linguists have a statement to make about the false divisions placed 
on the text by verse boundaries, and some of them feel that statement 
can be made by mandating an XML hierarchy in their translation document. 
(my frustration coming out :)  )

Troy





On 03/03/2012 02:08 PM, Matěj Cepl wrote:
> So, I have at least a little bit working version of CzeCSP and I would
> like to eliminate some kinks. One of them is using milestones v.
> containers in the text.
>
> So I have a friend who has just Nokia phone with Symbian 60 OS. By
> browsing through crosswire.org/wiki I found Go Bible as probably the
> only suitable front-end for him (am I right? Isn't there a native
> Sybmian 60 front-end?). However, when looking at
> http://www.crosswire.org/wiki/Projects:Go_Bible/Go_Bible_Creator I found
> that
>
>> For use with Go Bible Creator, an OSIS file must be of the container
>> type, not the milestone type.
>
> (does it mean only chapters as containers or also verses as ones?)
>
> And I am in this container/milestone hell again. In the first moment I
> have even written a Python script converting milestoned <verse/> based
> Bible into container <verse> based one
> (https://gitorious.org/sword/czekms-csp_bible/blobs/master/demilestonize.py),
>
> but before changing my XSLT scripts to generate back containered
> chapters I made a brutal mistake of trying to understand the proper way.
>
> By searching through the archives of this list I found that generally
> the proper way how to structure the Bible is Book-Section-Paragraph and
> chapters and verses should be just overlapping (i.e., milestoned)
> overstructure on top of this. OK. How well is this form of the OSIS
> document supported by the sword software?
>
> Then I've made a terrible mistake and opened OSIS Users Manual (OSIS
> Schema 2.1.1 on
> http://img.forministry.com/7/7B/7BB51FB8-84B3-4FF3-939ED473FA90A632/DOC/OSIS2_1UserManual_06March2006_-_with_O%27Donnell_edits.PDF
>
> linked from http://www.bibletechnologies.net/ ... that's the current
> OSIS standard, right?). There I found to my astonishment what kind of
> ... this standard is (I know, this is a Christian list, so I should mind
> my language).
>
> So on page 36 I have an example of the Bible structured with
>
> <title>text of chapter title</title>
> <chapter>
> <verse sID=""/>
> asdas
> <verse eID=""/>
> </chapter>
>
> (who in the world thought about <title> element before <chapter> one?)
>
> just on the following page we have
>
> <div type="book">
> <head>text of the book title</head>
> <chapter>
> <head>text of the chapter title</head>
> ...
> </chapter>
> </div>
>
> and yet next page we have
>
> <chapter>
> <title>text of chapter title</title>
> <verse osisID=""/>
> asdas
> </verse>
> </chapter>
>
> and finally on page 40 I see that "The chapter element has a
> chapterTitle attribute that enables users to insert a text string to be
> used as the chapter's title."
>
> I am a programmer. I can implement even very strange standards, but this
> kind of crud (sorry for my French) is really unbelievable. Do we have
> somewhere a list of what the real standard is, i.e., what has been
> actually implemented in libsword? What is generally considered an
> expected structure of the text?
>
> I see that this “standard” is from 2006. Does anybody work on actually
> making this into something sensible?
>
> Sorry for my ranting.
>
> Blessings,
>
> Matěj
>