[sword-devel] External links

[Chris Little]

Karl Kleinpaste wrote:
> Sean Healy <jalopeura at hotmail.com> writes:
>> 1) Is this only to other dictionaries, or is it also possible to link to 
>> commentaries and general books?

It should work fine within dictionaries, to other dictionaries, and to 
other books of other types. Additionally, there's nothing to prevent you 
from writing other non-dictionary books in TEI. It's probably even a 
good idea to encode all non-Bibles & non-commentaries in TEI.

>> 2) Is it possible to have such a link from a bible or commentary?

Yes, but you'll need to use the OSIS syntax, e.g. <reference 
osisRef="work:reference">some text</reference>, where work is the module 
name (what appears within [ and ] in the .conf) and reference is the 
Sword key value (e.g. Gen 1:1 for a Bible or /Book/Section/Subsection 
for a GenBook--BUT appropriately encoded for an osisRef, thus Gen.1.1 or 
Book.Section.Subsection respectively). I'm not sure whether we've 
explicitly defined the mapping from osisRef to Sword key for non-Bible 
references, however.

>> 3) Do any of the front-ends actually support any of this?

I would guess that none actually implement support for linking between 
modules correctly, chiefly because there's not much content that links 
to other modules. More such content would probably encourage a more 
complete & correct implementation by the frontend developers. (Then 
again, maybe I'm wrong and some frontends already support these 
reference tags.)

>> 4) Do any current modules use any of this?

I can't think of any TEI modules that use this syntax for external 
linking. I will probably use it for the new Strong's lexicons (likely 
due by the end of the week)--at least for linking between them.

> The URL syntax sword://ModuleName/KeyAppropriateToThatModule exists, and
> some of the UIs do it.  GnomeSword has supported it for a long time.
> 
> I use it heavily in some personally-generated modules to link from a
> commentary into a genbook (e.g. NETnote->Josephus), and internally in
> some dictionaries.

The private protocol syntax was chiefly designed & implemented for 
linking into Sword frontends from webpages and other external programs. 
There's certainly nothing to prevent using such linking syntax within a 
document, but it seems like an abuse of XML and the standards 
themselves, given that they define ways of linking to other documents 
and we define how those links should be interpreted within Sword. In the 
case of OSIS, in particular, you can't get away with stuffing a full URI 
like sword://.../... into an osisRef anyway.

This only pertains to document encoding, however. If, as a frontend 
developer, you want to take a link like <reference 
osisRef="work:reference">some text</reference> (or its TEI equivalent) 
and transform it to HTML <a href="sword://work/reference"> via render 
filters and then handle the linking through the private protocol 
handler, that seems perfectly sensible to me.

>> Specifically, I'm wondering whether I would be able to link to a general 
>> book from a bible footnote (or from a commentary). For example, if the 
>> footnote (or commentary) mentions something from Josephus, would it be 
>> possible to make a link that goes directly to the relevant passage?
> 
> If you have the proper section naming for Josephus, yes:
> 
> sword://Josephus/%2FThe+Antiquities+of+the+Jews%2FBook+1%2FChapter+8%2FSection+1"
> 
> I've been told that my encoding is overstated, but it works as it is.

Unfortunately, our Josephus module is rather horrid and in dire need of 
a remake. And what's worse, there exists a standard reference system for 
Josephus, that we would probably want to use for linking to it 
(actually, more than one, but for the Whiston translation there is one). 
Ultimately, you would want to encode a link to the above reference as 
<reference osisRef="Josephus:Ant.1.8.2">some text</reference>. Linking 
with that would require remaking the module with keys like /Ant/1/8/2. 
And I'm not sure how people would feel about that. And, again, the above 
syntax would not work within an osisRef attribute.

--Chris