[sword-devel] OSIS and intros

[Kahunapule Michael Johnson]

On 7/10/25 04:21, DM Smith wrote:
> The module team has a usfm2osis.py to convert USFM to OSIS. Michael also has one. The nature of USFM is that it’s goal is presentation not OSIS’s nature of semantic markup. I don’t know how that transformation handles intro material. I’m pretty sure neither has a begin/end testament construct. It is a simple thing to manually add such after transformation if that fits with one’s workflow.

Actually, USFM's current goal is semantic, not presentational markup. Both USFM and OSIS can be abused to try to get a presentational effect without regard to the semantics, and USFM may be more often abused that way (because it is simply used far more than OSIS), but that isn't actually a legitimate flaw of the markup.

In USFM, any introductory material for the New Testament would be actually included in the beginning of Matthew, before the chapter 1 marker. Introductory material for the Old Testament would be in Genesis, or could be in the "INT" or "PRE" books.

USFM has its flaws, but USFM and its XML twin USX are the most widely used and accepted Bible translation formats world-wide, with by far the largest software support. USX, unlike OSIS, is 100% round-trip data-preserving and straight-forward equivalent. It even preserves some of USFM's quirks, unfortunately, but it is that level of compatibility and the great software support that caused it to be chosen above OSIS by the Digital Bible Library as its base format. I still use USFX as a "hub" format in Haiola, 
because it was invented before USX, is less quirky, and because it is trivial to convert between USFX, USFM, and USX.

I primarily use OSIS as a necessary step between the quadruplet formats (USFM, USX, USFX, and USJ) and Sword modules. I have not written a general importer for OSIS to convert back to the heavily-used quadruplets, because one of OSIS' greatest strengths (extreme flexibility in the way things can be encoded) is also one of its greatest weaknesses (because it makes interchange of data between people who use OSIS differently reliant on case-by-case customization of code or processes).

My work flow does not include any customization of OSIS. Indeed, if I can't handle it automatically, I don't handle it. That sounds harsh, but it actually works pretty well, not because I handle anything OSIS can do (which I don't), but because I handle what I actually encounter in real life (1,515 translations so far) that the Sword engine can also handle. That excludes a few footnotes in places OSIS doesn't allow them and a few whole Bible translations because their versifications don't fit the past 
assumptions hard-coded into the Sword engine. I never start with OSIS to create a Sword module. I always start with one of USFM, USX, or USFX. (I could easily add USJ, but I don't have any real-world test cases for that, yet.) So adding any requirement on OSIS that isn't already there would likely just break my work flow, rather than solve any problem. OSIS is bad enough without adding another incompatibility. If the concern is getting testament introductions in the right places, there are many ways to do 
it. Predicting what OSIS authors might do is kind of hard...

-- 
signature

Peace,
*/Michael Johnson/**
26 HIWALANI LOOP • MAKAWAO HI 96768-8747*• USA
mljohnson.org <https://mljohnson.org/> • eBible.org <https://eBible.org> • WorldEnglish.Bible <https://WorldEnglish.Bible> • PNG.Bible <https://PNG.Bible>
Signal/Telegram/WhatsApp/Telephone: +1 808-333-6921
Facebook: fb.me/kahunapule <https://www.facebook.com/kahunapule>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://crosswire.org/pipermail/sword-devel/attachments/20250710/64e2cd61/attachment.htm>