[sword-devel] osisCore 2.0 docs

[Chris Little]

Wolfgang,

Well, I suppose you're entitled to your own opinion.  There are 
essentially two reasons why we have best practices for OSIS.

The first reason is to allow different levels of encoding.  For example, 
you could encode all quotations using quotation marks rather than the 
<q> element.  But doing so would not give users of your document as much 
power as if you had followed the best practice.  Nonetheless, there's 
nothing inherenly wrong with encoding with quotation marks--and there's 
no way to prevent it via a schema.

And that's the other reason for which we have best practices.  There are 
many, many practices that cannot be expressed via XML Schema, which we 
nonetheless desire that people follow.  Since we cannot mandate them via 
XML, we must specify them via prose in best practices in the manual.  
(Other varieties of schemas, like Relax NG, though perhaps more 
expressive than XML Schema, still would require that we describe best 
practices.)  As another example, you could use the ISO-639-1 language 
type to encode languages, but it wouldn't be especially useful since it 
provides codes for so few languages.  If you read the manual, you'll see 
us require the use of the IETF language type, in line with the value on 
xml:lang.  You'll also see our description of how to encode language 
codes not identified by the IETF in a consistent way, so that different 
organizations use the same codes.

I realize that OSIS may seem complex and difficult to master, but it is 
truly simpler than, for example, any modern variety of (X)HTML.  The 
fact is, we needed to build an XML language that can be used to 
represent real Bibles and all of the other literature that would be used 
along with them.  For the most part, we've got that now.  (The remaining 
issues still being worked on are primarily for more complex Bibles with 
critical apparatus/morphological tagging/etc., and those issues will be 
handled in separate modules.)  There are plenty of other Bible markup 
standards that simply could have been adopted & converted to XML syntax 
(e.g. GBF, SFM, and various proprietary formats) not to mention XML 
formats like ThML & XSEM that could have been converted to XML Schema 
and extended, but the Bible Technologies Group collectively decided that 
we wanted something reasonably complete, broadly useful, and that would 
have some potential of wide adoption.

If you think Zefania doesn't need best practice statements, you're 
either making the assumption that encoders who use Zefania will somehow 
intuitively know what you were thinking as you designed the language, or 
Zefania is so simplistic as to not really be useful.

--Chris

schultz wrote:

> Chris
>
> in a former  posting  i have said that OSIS is a little bit 
> overdressed. Rules for best practices is the proof for it.
>
> Best practices must be described in the schema definition and 
> otherwise nowhere.
>
> the schema definition has to guarantee that i can finde each 
> information in an osis file, without knowing further best practices 
> rules.
>
> In my Opinion OSIS is too diffuse................... :(
>
> best wishes
> wolfgang
> http://www.zefania.de
> Home of Zefania BibleMarkup Language and  True Sharp Sword API.
>
>
>
> Chris Little schrieb:
>
>> Wolfgang,
>>
>> You should probably hold off on template files for a while, or at 
>> least wait until the manual is published, since it will describe best 
>> practices.  There are a number of items in your example that should 
>> not be emulated by others.  We hope everything will be well explained 
>> by the manual when it is released (soon).  Until then, we all have to 
>> be patient.  If you have specific questions, you can also email the 
>> osis-user list.  (See the OSIS portal for techies at WTS, linked from 
>> the main OSIS page.)
>>
>> --Chris
>