[sword-devel] OSIS Users Manual considered confusing

[Matěj Cepl]

On 3.3.2012 15:18, Troy A. Griffitts wrote:
> So, what was your question? :)

There are many, but the one specific to my original post (and yes, one 
should never write email messages in anger) is simple: how should I code 
chapter with its title?

What I mean, is that I really didn't meant to personally offend anybody 
and I can imagine that number of people spent endless hours on producing 
this document. Still, in the circles I work in (I am a programmer at Red 
Hat) what you described is called “a standard by committee” and it is 
usually meant as (almost) an actionable offense.

> Any one of us could have technically designed the OSIS standard better.

Obviously, that's what's conveyed in the “a standard by committee” term.

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

I am not sure why I should be humble, when noticing that as a user of 
this standard I found it very much lacking in what exactly is expected 
from any standard: setting unequivocal rules about how to create an 
inter-operable product with the expectation that somebody else using 
documents produced by my software will be able to use them without a 
problem.

Again, no personal offense meant, and I don't doubt specific knowledge 
of anybody involved in creating OSIS standard.

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

Of course, it is better to have this than nothing. No doubt about that.

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

By “masses” you mean I hope ABS, USB, Wycliffe et al. not us poor 
suckers, who would like to use OSIS standard for helping to make it 
widely used?

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

Right. That was exactly what I was asking about (in the end of my 
original message) ... whether such thing exists from the authors of OSIS 
or as de facto standard from its implementors.

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

OK, so duly noted ... there isn't widely held agreement even on this 
list on this (see e.g., I found in the list couple of clear statements 
in the opposite direction ... although, thinking about it, I don't see 
anything more natural on paragraphs which are arbitrarily put there now 
by the publishers (am I right?) than on chapter/verse structure put 
there couple of centuries ago. Neither of which has anything to do with 
the original writers of Bible (are there any supporters of divine 
inspiration of paragraph marks around?).

Best,

Matěj