[sword-devel] OSIS Users Manual considered confusing

[DM Smith]

On Mar 3, 2012, at 12:30 PM, Karl Kleinpaste wrote:

> DM Smith <dmsmith at crosswire.org> writes:
>> There is ambiguity about a title that is before the first verse in a chapter.
> 
>> Titles for sections should be within a section div. This solves the
>> ambiguity problem for titles before the first verse.
> 
> Shouldn't The Standard have eliminated the ambiguity in the first place,
> rather than depending on a particular implementation to fix the
> ambiguous semantic?

I'm not sure you're wanting a reply or just wanting to rip on OSIS as a "standard."

The schema defines the syntax of what is possible, but the manual describes the semantic of the syntax. The manual, as pointed out, has errors in it. I don't know whether these have been properly communicated back. I know that I have proofread the document, but missed these. My findings were incorporated into the document.

I think the ambiguity is in SWORD, not in the standard. I guess I should have been clearer.

Osis2mod splits up an OSIS document into pieces and puts them into the module as verses. When coming to a title before the first verse it uses every contextual piece of information to do the placement. It might put it into verse 0 (a chapter heading) or into verse 1 (a section heading). What it does is well-defined, but might not match the expectations of a module encoder. Thus the entry on the wiki that I pointed to. It recommends marking book and chapter titles w/ type="book" or type="chapter" respectively. This is the proper semantic. The syntax allows otherwise. It also recommends that other titles be defined with in sections. Again, this is a proper semantic. The syntax allows otherwise.

I don't think that SWORD distinguishes chapter titles from section (pre-verse) titles stylistically. If it did the difference might be noticeable in a front-end. Otherwise in a chapter-as-a-whole there is no issue. The title will (should?) show exactly where it is encoded in the module.

But when a single verse is shown (as in a search results list) or in a parallel view, it might matter.

Do you have a suggestion on what the proper semantic should be? Or whether the OSIS schema should change to provide an unambiguous semantic?

In Him,
	DM