[sword-devel] linking syntax

[Jonathan Morgan]

On Sat, Nov 29, 2008 at 2:53 PM, Greg Hellings <greg.hellings at gmail.com> wrote:
> On Sat, Nov 29, 2008 at 12:16 AM, Chris Little <chrislit at crosswire.org> wrote:
>> If we may take a moment to actually discuss development...
>> I think we may have a problem....
>>
>> Troy A. Griffitts wrote:
>>> support for external links:
>>>
>>> There is currently no programmatic features in the engine which help or
>>> hinder external links.  Historically there has been a common conceptual
>>> agreement that a 'reference' is to that of a 'general Bible'.
>>>
>>> This needs to change, we all agree.
>>>
>>> The agreed extension is to:
>>> implement support for the key prefix on OSIS tag <reference
>>> osisRef="module:key"> syntax.
>>>
>>> use the prefix to specify a sword module.
>>> determine a set of meta modules like:
>>> bible:
>>> strong:
>>> self:
>>>
>>> default the prefix, if absent to 'bible:' so current modules still work.
>>>
>>> None of this requires engine changes, but rather that we extend the
>>> historical conceptual idea of a reference beyond bible:key.
>>
>> Meanwhile, the OSIS manual says:
>> <QUOTE>
>> A reference element was used in the note example above. To refresh your
>> memory, here is just the reference element part of that example:
>>
>> <reference osisRef="Ezra.4.6">Ezra 4:6<reference>
>>
>> Note there is no osisWork prefix, that is no 'name:' in from of
>> 'Ezra.4.6' in the osisRef attribute. That may be for one of two reasons:
>> First, that is being supplied by the osisWork default, i.e., it is a
>> reference in this work. Or, the osisWork prefix may have been set by the
>> the workPrefix element in the header element of the document.
>>
>> In either case, if you want to point to another text, you must declare
>> that in a work element and use the value of the osisWork attribute from
>> it to make references to it.
>> </QUOTE>
>>
>> The two positions appear to be in conflict with respect to the default
>> workID. The spec says the default workID is either specified by the
>> header or the current document. Troy suggests that the default should
>> always be Bible:. I think my own encoding practice, when it even makes a
>> difference, follows the manual's standard.
>>
>> So, do we follow Troy's suggestion and take default to be Bible: when no
>> workID is specified? Or do we follow the OSIS spec?
>>
>> I have a feeling the former is probably the more pragmatic approach,
>> precisely because it doesn't break existing content (though I'm not sure
>> either approach would break anything in the public repository). But we
>> need to make a decision on this for our own encoding, importer, and
>> documentation purposes.
>
> Currently the importers pretty much ignore all content in the header
> of the document.  My suggestion, some time back, to help encourage
> more broad OSIS support, was to provide either an argument to the
> importers or an XSLT that would take metadata from the header of the
> document and output a basic .conf file based off of that.  That would
> give them a help on getting the necessary information in the .conf
> file put together and also encourage them to learn the OSIS format
> well enough to understand things like that interaction between the
> default works and the references.
>
> I'd prefer we conform to the OSIS spec, especially if it breaks none
> of the current content.  Information like the default work/reference,
> etc, could be placed in the .conf file, so that the module storage
> format doesn't need to be changed, and we can define defaults if none
> appear (like current modules, etc).

I'm afraid there are two different possible "default work/reference",
and I assume you are talking about the OSIS one.  Here's my take:
1. The current Bible / user preferred Bible.  This is user preference.
2. The OSIS one.  This requires the module creator to choose a default.

I think the first one is better, because in most cases references are
references to "the Bible" not references to "a particular Bible" (e.g.
if my dictionary says something occurs or is mentioned in Genesis 5:9,
then it probably occurs in Genesis 5:9 in any version).  Because of
this, giving it in the user preferred version is a much better option,
IMHO.  The user should have control of as much as we can let them
have, since they are the ones using the module right now (not the
module creator).

Jon