[sword-devel] OSIS markup best practice: sanity check

[John Austin]

IBT's repository has dozens of SWORD Bible modules, and they all need to
be rebuilt for SWORD 1.7+ using OSIS module best practices (as outlined
in the extremely useful CrossWire wiki). Below are some conceivably
controversial issues. We hope to achieve excellent module functionality
with the various front-ends. So if you see something below which makes
you groan, please speak up. Otherwise, the plan is to proceed as follows:

- Missing books, chapters, or verses within a Bible's chosen v11n will
be completely left out of the OSIS file, and thus out of the module's
index. There will be no mention of them and no empty holding-places
within the OSIS file.

- There will be a Scope parameter in the .conf file, formatted as an
osisID of the specified v11n, which details the books, chapters, and
verses that are included in the entire module. The Scope param is the
only way to detect which books (etc) are available in a module without
first having to install the module, as necessary for some applications.

- Updated SFM to OSIS converters (osis-converters) will closely emulate
the markup now generated by usfm2osis.py and will utilize its
extensions. But additionally, the OSIS subType attribute will be used to
pass optional CSS classes through HTML filters to front-ends which they
can implement, or not, as desired. For instance: x-p-first (to add a
drop-cap to some particular paragraph or line-group), x-text-image (for
an image with text flowing around it) etc.. IBT is soon to begin
publishing their Children's Bibles as OSIS GenBook modules. They have
nice pictures, pretty formatting, and audio. Presentation extensibility
is necessary, and OSIS subType seems to be the best way to encode
optional presentation classes. NOTE: Front-end implementation of this
would require either simple additions to osisxhtml.cpp &
osishtmlhref.cpp (to pass subType as class) or a customized filter.

- Scripture reference tags will all specify target modules using
osisRefs like this: "ESV:Matt.1.1" (and it may be that the specified
module is not always installed, thus its av11n unknowable).

- ?? Any other concerns with IBT's modules??

God willing, these new modules will work great on the various
front-ends. Thanks for reading...
-John

[Chris Burrell]

Hi John

On the Scope parameter, I believe this was discussed and rejected.
(although JSword will have support for this, and will write a separate conf
file, should the scope be absent from the .conf file).

Chris

Post by John Austin
IBT's repository has dozens of SWORD Bible modules, and they all need to
be rebuilt for SWORD 1.7+ using OSIS module best practices (as outlined in
the extremely useful CrossWire wiki). Below are some conceivably
controversial issues. We hope to achieve excellent module functionality
with the various front-ends. So if you see something below which makes you
- Missing books, chapters, or verses within a Bible's chosen v11n will be
completely left out of the OSIS file, and thus out of the module's index.
There will be no mention of them and no empty holding-places within the
OSIS file.
- There will be a Scope parameter in the .conf file, formatted as an
osisID of the specified v11n, which details the books, chapters, and verses
that are included in the entire module. The Scope param is the only way to
detect which books (etc) are available in a module without first having to
install the module, as necessary for some applications.
- Updated SFM to OSIS converters (osis-converters) will closely emulate
the markup now generated by usfm2osis.py and will utilize its extensions.
But additionally, the OSIS subType attribute will be used to pass optional
CSS classes through HTML filters to front-ends which they can implement, or
not, as desired. For instance: x-p-first (to add a drop-cap to some
particular paragraph or line-group), x-text-image (for an image with text
flowing around it) etc.. IBT is soon to begin publishing their Children's
Bibles as OSIS GenBook modules. They have nice pictures, pretty formatting,
and audio. Presentation extensibility is necessary, and OSIS subType seems
to be the best way to encode optional presentation classes. NOTE: Front-end
implementation of this would require either simple additions to
osisxhtml.cpp & osishtmlhref.cpp (to pass subType as class) or a customized
filter.
- Scripture reference tags will all specify target modules using osisRefs
like this: "ESV:Matt.1.1" (and it may be that the specified module is not
always installed, thus its av11n unknowable).
- ?? Any other concerns with IBT's modules??
God willing, these new modules will work great on the various front-ends.
Thanks for reading...
-John
_______________________________________________
sword-devel mailing list: sword-devel at crosswire.org
http://www.crosswire.org/mailman/listinfo/sword-devel
Instructions to unsubscribe/change your settings at above page

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20140502/5b4cd22a/attachment-0001.html>

[DM Smith]

- There will be a Scope parameter in the .conf file, formatted as an osisID of the specified v11n, which details the books, chapters, and verses that are included in the entire module. The Scope param is the only way to detect which books (etc) are available in a module without first having to install the module, as necessary for some applications.

You must mean osisRef. This would allow "Gen-Rev" and "Gen.1.1-Gen.1.3". The osisIDs for these would be "Gen Exod Lev ... Rev" and "Gen.1.1 Gen.1.2 Gen.1.3", respectively.

Also note that an osisRef has a book order based on the v11n.

Question regarding Scope: Will it include chapter 0 and verse 0. (i.e. presence of headings and introductions)?

For JSword, as Chris noted, we plan to have a sidecar conf for each module that will act as a cache for computed settings and module preferences/settings (e.g. Cipher, Font). This will be one of them. It is very expensive on a phone to compute an accurate book list.

We've been discussing having a separate BookScope in addition, as we need to know the list of books independently of the verses that the books contain. This would merely be an optimization of the Scope.

I'd like to know more how you envision a frontend using the Scope field prior to installing the module.

In Him,
DM

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20140502/8d868544/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4145 bytes
Desc: not available
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20140502/8d868544/attachment.p7s>

[Chris Burrell]

The book list was implemented at same time as scope in jsword.

Post by John Austin
- There will be a Scope parameter in the .conf file, formatted as an
osisID of the specified v11n, which details the books, chapters, and verses
that are included in the entire module. The Scope param is the only way to
detect which books (etc) are available in a module without first having to
install the module, as necessary for some applications.
You must mean osisRef. This would allow "Gen-Rev" and "Gen.1.1-Gen.1.3".
The osisIDs for these would be "Gen Exod Lev ... Rev" and "Gen.1.1 Gen.1.2
Gen.1.3", respectively.
Also note that an osisRef has a book order based on the v11n.
Question regarding Scope: Will it include chapter 0 and verse 0. (i.e.
presence of headings and introductions)?
For JSword, as Chris noted, we plan to have a sidecar conf for each module
that will act as a cache for computed settings and module
preferences/settings (e.g. Cipher, Font). This will be one of them. It is
very expensive on a phone to compute an accurate book list.
We've been discussing having a separate BookScope in addition, as we need
to know the list of books independently of the verses that the books
contain. This would merely be an optimization of the Scope.
I'd like to know more how you envision a frontend using the Scope field
prior to installing the module.
In Him,
DM
_______________________________________________
sword-devel mailing list: sword-devel at crosswire.org
http://www.crosswire.org/mailman/listinfo/sword-devel
Instructions to unsubscribe/change your settings at above page

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.crosswire.org/pipermail/sword-devel/attachments/20140502/ba733911/attachment.html>

[David Haslam]

New configuration properties require documenting properly.

i.e. In http://crosswire.org/wiki/DevTools:conf_Files

If there are caveats about usage, these can be covered as section notes
using the <ref>...</ref> syntax.

David





--
View this message in context: http://sword-dev.350566.n4.nabble.com/OSIS-markup-best-practice-sanity-check-tp4653926p4653935.html
Sent from the SWORD Dev mailing list archive at Nabble.com.

[Nic Carter]

- Scripture reference tags will all specify target modules using osisRefs like this: "ESV:Matt.1.1" (and it may be that the specified module is not always installed, thus its av11n unknowable).

Will this affect backwards compatibility? What advantage is there in specifying which Bible to open? I can see the point for Commentaries and other modules, but not so much for Bibles. What is the intended behaviour if, say, the ESV isn't installed and someone taps on the "ESV:Matt.1.1" reference?

Thanks, ybic
nic... :)