[osis-core] How to enocode references to scripture text within a scripture portion.

[Todd Tillinghast]

This is an issue that has come up from three different sources all
trying to create documents that have text themselves but include blocks
of scripture text as a majority of the content.

I don't think it makes sense for a number of reasons for the scripture
text itself to be copied into these documents, but rather that a
reference be made to the text that should be expanded when presented.

But there is a need to allow for both <references> (or other elements)
that don't imply text that would likely be expanded when presented and
others that don't carry that meaning.

QUESTION: Can we make an official statement of how this should be done
and include it in the users manual?

>From my perspective the following are the reasonable alternatives:
1) An empty <q osisRef="???"/> element (with no sID and eID attributes
that would make it a start or end of a milestone container) indicates
that the content specified by the osisRef is to be expanded by the
rendering/process.

2) We determined that for commentaries, devotionals, and Bible studies
that <reference type="annotateRef" osisRef="..."/> is a reference to the
text that is the subject of current text AND that it is left up to the
rendering process (if any) to determine if/how it wants to render the
text indicated by the osisRef attribute or not.  We also determined that
there must be an ancestor element of the <reference type="annotateRef"
osisRef="..."> with an annotateRef attribute and that the osisRef value
must be a subset of the annotateRef value.

We could extend this behavior to "scripture portions" as well.

Examples follow:
Case 1:
<div>
   <title>The Christmas Store</title>
   <p>some text... and possibly a figure</p>
   <q osisRef="Luke.2.6-Luke.2.14"/>
   <p>some more text... </p>
</div>

Case 2:
<div annotateRef="Luke.2.6-Luke.2.14>
   <title>The Christmas Store</title>
   <p>some text... and possibly a figure</p>
   <reference type="annotateRef" osisRef="Luke.2.6-Luke.2.14"/>
   <p>some more text... </p>
</div>


Naturally these documents could specify translation specific osisRef
values if desired while others would leave the reference generic and be
able to render the same text and vary the imbedded scripture translation
when rendering.

The benefit of the <q osisRef="..."/> is that it could be used as a
descendant of an element with "annotateRef" attribute an not be required
to be the subject of the annotation, but this also creates two similar
ways to do the same/similar thing.

I see the merits of both strategies.

Can we officially adopt one of these two strategies and put it in users
manual?

Todd