[sword-devel] Getting stuff done (Re: External links)

[Jonathan Morgan]

On Wed, Nov 26, 2008 at 11:36 AM, Troy A. Griffitts
<scribe at crosswire.org> wrote:
> A few probably-abrasive (pre-apologies) comments on this thread.

...

> 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.
>
> This is a frontend change.  Just as gnomesword decomposes a reference
> from ThML sword://module/key, it should also decompose a reference from
> OSIS module:key and accommodate the meta modules above accordingly... as
> should all frontends.
>
> Now, the engine COULD definitely be extended to HELP the frontend
> developers decompose these keys by pushing a common concept from our
> frontends of 'user preferred strong dictionary', 'user preferred Bible',
> etc. down into the engine, and then adding a 'module' component to a
> key.  This could have the effect of letting our verse parser take care
> of the prefix and hand back a ListKey of entries each with appropriate
> module components filled in.  But this is just a first thought of how we
> can help frontend developers support extending the reference concept.
>
> The fact is, currently MOST frontends, when they see a reference pull up
> the user's preferred Bible and show the reference.  This logic needs to
> change in the frontends.

I don't disagree with this, though I believe in general that the link
should be shown in the user's preferred Bible.  The only cases you
should need to refer to a particular version as far as I am aware is
where you are commenting on a peculiarity of that version or on its
particular text (if they are quoting part of the text inline or
relying on particular words from the text then that is probably also a
good reason).  Anything else and you are probably doing the wrong
thing (because in general we should be interested in the user's
preferences, not the module author's, since the user is actually using
the module).  Here are a couple of hypotheticals:
1. The module author believes that the KJV is the one true version,
and will always link to the KJV, even though it is not necessarily the
best or most comprehensible translation.

2. The module author links to some English Bible that seems best
suited to the task, while the reader reads their native language
better than English and wants to read it in their native language.

If the module referred to isn't installed then it should also fall
back to the user's preferred Bible (or more sensibly to the currently
selected Bible, however you determine that).  Possibly no matter what
the reference points to, if it is a Biblical reference it should allow
you to open in the current window (or any of the current windows if
you have more than one Bible window open), maybe using a right-click
menu on the hyperlink.

For applications that have only one current Bible window, switching
the Bible displayed in that window just because a module author said
to could be very disruptive (imagine if it switched to a Bible without
an OT and they later thought that the OT had been lost, or if it
switched to a Bible without Strong's Numbers or morphology when they
were using those).  Similarly, if an application pulls up a new window
just to display that reference it is likely to be disruptive, possibly
breaking up a carefully configured layout, and I contend still has a
reasonably high chance of not being what the user wanted (though it
may be what the module author wanted).

As far as I know, referring to other, non-Biblical modules has never
been supported, and I am pretty sure there has been discussion on this
list that has said that it is necessary to work this out (feel free to
correct me on this, of course).  I don't even know if it is possible
to refer to the current work, which is obviously a reasonable thing to
want to do (e.g. for a dictionary, hyperlink "see also OTHER ARTICLE"
to me:OTHER ARTICLE), but again I believe it was said that this isn't
supported, and I am not aware of any module that does it.

So, short summary of what I think is needed, and am not aware of having:
1. Clear documentation of what the work ID is (is it just the module
name?  Will we need to support any mappings based on existing OSIS
documents that refer to things with names different from module names?
(Josephus and various commentaries probably being the most likely
candidates for such references))

2. Support for linking within the current module (you could use the
module name, but I am sure that there should be a better way of making
it clear that it is an internal link, and it wouldn't surprise me if
OSIS supported it).

3. Definition of what key looks like for dictionaries and genbooks (I
presume it is the OSIS gen.2.2 style reference for Bibles?)

With that we can move on with OSIS without having people say "There is
supposed to be a right way, but it isn't really supported."

Jon