[sword-devel] OSIS:What is the future? Who is using it now?

[DM Smith]

L.Allan-pbio wrote:
>> Please, any of you that have the time, read the manual and provide 
>> revisions and comments. As they are actively working on OSIS 2.5, now 
>> is a good time.
>
> Based on your reading, would the upgraded osis spec be usable to 
> prepare a module that could be used to generate a printable Sharing 
> Bible tract, for example? Back in late 2004, I tried to use osis 2.x 
> to prepare such a tract.

This really is a multi-faceted question:
1) Can OSIS be used to represent a particular kind of document?
    I find that OSIS is able to represent pretty much any document that 
you wish, except perhaps a dictionary.

2) Can a SWORD module be created from such a document?
    Yes. But not all the software is present to create such a module.
    Specifically, different types of modules have different input format.
    osis2mod understands Book, Chapter and Verse (BCV)
    and can create a bible or commentary module from that.
    If you are writing a commentary, it should not be using the <verse> 
element for comments,
    but an element that refers to a verse, i.e. idiv with 
annotateRef="osisRef to
    verses under discussion" and annotateType="commentary". To get your 
document
    ready for input would require a fairly trivial program to transform 
it (e.g. xslt).

    I have not written a gen book or a dictionary, but there are 
specific input formats
    for those that can be generated using xslt or some other kind of 
transformer. The
    general format is an index marker followed by text.

    Other than BCV oriented material, each index should refer to 
something that
    is well-formed in whatever format you wish (GBF, ThML, PlainText, OSIS).
    The key to all of this is that the SWORD API is very fortunately 
very dumb
    when it comes to the content of an "entry", it merely grabs 
everything belonging
    to the key and hands it to one or more filters.

3) What OSIS elements support the creation of a general book SWORD module?
    For structure, it is the <div> element. For the index it is the 
<index> element.
    The index element is used to mark points in the document that are 
interesting.
    And it supports different arbitrary kinds of indices, and each kind 
can be flat
    or hierarchical up to 4 levels deep.

4) What OSIS elements support the generation of a printed document?
    I am not very experienced here. The OSIS manual gives some guidance 
here.
    With the <milestone> element you can represent all kinds of "print 
registration"
    marks, such as page breaks, line breaks. It is also possible to 
represent different
    formats, such as a specific size of tract, booklet, paper, screen, 
.... Different
    registration marks are needed for different targets.

5) Is there software that can be used to generate a printed document?
    XSL-FO and FOP can be used to generate a PDF. This is what we plan
    to use for JSword, but we just haven't gotten there yet.

6) Are there any XSL-FO/FOP examples to follow to convert an OSIS
    document?
    None that I am aware of. Though there are lot's of tutorials on how to
    use XSL-FO and FOP.
>> From then until now, I don't think the osis spec changed materially (not 
> including the upcoming spec).

I don't know what has changed from "then" as I have not been interested in
understanding the differences between earlier OSIS and current OSIS. For
the most part an older OSIS document is fully OSIS 2.1 compliant.

The biggest difference between then and now with regard to output control
is that the <lb/> element can now be used almost everywhere.

The other biggest difference has been the improvements in the manual and
our understanding of OSIS (well at least mine.) OSIS is not difficult but it
did not have a good tutorial. When the manual is finished, it will go a long
way toward that.

>
> The idea was to have a format from which transforms could be used to 
> generate webpages and matching .pdf's for printing duplexed bi-fold 
> output. The content was roughly 2/3rds Bible verses and 1/3 "prose". 
> My impression was that if it could be done, the markup of the osis 
> itself wouldn't be all that different from preparing a General Book 
> ... lots of verses, but not any versification structure.
> http://www.bibleinverse.org/sharingbibles/sb12/Sb2FrontPage.html  (draft)

Correct.

>
> At that time, it seemed osis wasn't appropriate because that 
> functionality wasn't available yet, at least based on the feedback I 
> got from the osis list. Has that changed?

I don't think I was on that list, so I am not sure whether it has been added
or whether it was a knowledge gap.

>
> The more general question would be ... is the upgraded spec 
> appropriate for things like commentaries and "General Books" such as 
> SAOA, SME, and/or "The Practice the Presence of God"? 

See above.

> Does it have capabilites for "page markup" to guide a transform for 
> printing?

I did not mention it above, but the philosophy of OSIS is that of XML in 
general:
Use xml to markup document structure.
Use stylesheets for presentation.

There need to be sufficient markup in xml for stylesheets to work. The 
primary mechanism for xhtml is the class attribute. It seems that type 
and subType can be used for this purpose, but I'm not sure if it is 
intended in this fashion.

>
> Or am I uninformed and is osis not intended for that kind of module? 
> Was the "missing pieces" more a matter of transforms? Can GBF do a 
> General Book? Can osis be used to convert much of the content of CCEL 
> which uses (mostly?) ThmL?

I have compared GBF and ThML to OSIS and JSword maps them to OSIS.

I think that the missing piece to everything that you want to do is XSL.

>
> If not, is such capability envisioned for osis 2.5 or subsequent 
> versions?