[sword-devel] OSIS Users Manual considered confusing

[Peter von Kaehne]

The wiki is indeed the place to look if you want to see how to create an
OSIS text which works well with our software. As one of the main module
makers, I do use the manual, but not often. The Wiki will take
precedence over the handbook any time. For us at least.

It is fairly irrelevant if there are other options of creating OSIS
texts, if you want to have a module, stick to what CrossWire supports
well or improve our filters etc. Normally it makes more sense to stick
to what is supported well.

Wrt USFX - this is simply a XML-fied form of USFM and adds very little
to the discussion. It is essentially a structureless mess, replacing
each USFM tag with a XML set of tags. If I did not have OSIS, I would go
ThML, but certainly never USFX.

Wrt USFM - this is a nice and simple format for Bible translators as
even the most technophobe can produce a decent text on the oldest
possible computer. It uses backslashed codes, mostly structural, some
(very few) representational. But it is of no use whatsoever for Bible
software such as ours. For starters, I have not yet found a single USFM
text which did not have a serious flaw in it. You can run all tests of
Paratext and Bibledit against USFM, but in the end, you are left still
with often serious problems. OSIS validation and the test tools we use
to make modules smoke most of these out and nearly all USFM texts we
have received have been improved following our feedback.

Wrt the import tools from USFM to OSIS, they are decent enough and grow
as we encounter new tags.

Wrt module production pathway, as David has said we make many modules
via a "whatever"->USFM->OSIS path. For me the main reasons are

a) that I do not need to create tools (XML transformations + creation) I
feel uncomfortable with as a non-programmer, but can restrict myself to
Perl regex scripts.

b) I usually try to get translators who used bad tools (like unstyled
MSWord) for their translations onto one of the Bible translation
packages - Bibledit or Paratext. So producing USFM is a good help for them.

Peter