[sword-devel] GenBook osisID and URIs

[Chris Little]

The original private protocol syntax for Sword (which is what is 
implemented in BibleCS) is:

sword://{module}/{key(list)}

Our test page is: http://www.crosswire.org/~chrislit/testlinks.html

BibleCS configures the private protocol handler in Windows when it 
loads. There's also a Libronix-style link there. I don't recall whether 
catches those links also (but I know it won't touch the protocol 
settings for Logos if they already exist, so it won't interfere with Logos).

On Windows, the links only work in MSIE. I don't happen to know how to 
set up protocols in Firefox because it didn't really have the 
marketshare when we implemented to make it worthwhile. (It's obviously 
worthwhile now.)

I realize we're also interested in linking within Sword frontends, 
rather than between webpages and frontends, but the same system can be 
employed across both applications.

More comments follow...

DM Smith wrote:
> IIRC, what we were thinking was that it should be 
> protocol://osisRef(,osisRef)*

I don't know what value we gain by having links to multiple locations. 
It seems like we would want to break those up in the text so that the 
user can click on one or another individual link. Can you explain what 
you expect to see happen when you click a link with multiple, 
discontinuous keys.

If you have a link like sword://KJV/Mark.2.10,14 it will give you a 
verse list in BibleCS (and you can then click on the individual verses). 
  (For some reason, sword://KJV/Mark.2.10,Mark.2.14 does the same, but 
takes the verses to be Mark 2:10 and 2:2, which is probably a bug in the 
verse list parser.)

It might have made sense to use osisRefs and/or osisIDs, but I think our 
implementation predates OSIS by a few years.

> But that poses problems when one wants to specify the work because the 
> definition of a URI doesn't allow : for this use.
> e.g. sword://KJV:Gen.1.1-Gen.1.3,KJV:Gen.2.9

That's not really a problem (not that I think we should change to this 
syntax). The colon just needs to be encoded as %3A.

> And how would one specify, a parallel request?

I don't think anyone addresses that possibility currently. I'm not sure 
whether its even desirable, but as long as you're requesting the SAME 
key(s) from multiple modules, we could use something similar to what you 
suggest (extending the existing syntax):

sword://KJV,ESV/Gen 1:10-15

or

sword://KJV,ESV/Gen.1.10-Gen.1.15   in OSIS style.

> The next part of the question relates to the proper representation of a 
> GenBook key as an osisID.
> 
> If we understand '.' as OSIS's hierarchical separator, e.g. Gen.1.1 is 
> Book -> Chapter -> Verse, then a GenBook with a hierarchy to a node of A 
> -> B -> C would be "A.B.C"
> The problem is that in a GenBook, the key is generally a title, with 
> spaces and possibly periods. I was thinking a simple substitution of _ 
> for spaces and something else, perhaps '/' for periods.
> But _ and / are valid in a osisID.

I think if we keep the system of sword://{module}/{key}, then we're 
capturing everything after the first single backslash as the key. 
GenBook keys use / to divide levels of their hierarchy. We could add . 
for the same purpose, but I don't know that it has any benefit since the 
URIs aren't really OSIS anyway.

> Here is an example from Josephus (with '.' added for purposes of this 
> discussion)
> workID = Josephus
> 
> The War of The Jews. -> Book 1. -> Chapter 2. -> Section 3.
> 
> Possible osisID:
> Josephus:The_War_of_the_Jews/.Book_1/.Chapter_2/.Section_3/
> 
> While osisIDs use '.' as a path separator, URIs use '/'. So would one 
> change do the swap of '.' and '/' when representing the osisID as a URI?
> e.g.
> (Josephus)The_War_of_the_Jews./Book_1./Chapter_2./Section_3.

I think simply

sword://Josephus/The War of the Jews/Book 1/Chapter 2/Section 3

should work, or

sword://Josephus/The%20War%20of%20the%20Jews/Book%201/Chapter%202/Section%203

encoded as an URL.

> And if we do that what about Bible references, would they become 
> sword://(KJV)Gen/1/1 ? (I don't think that makes sense)

Me neither.

--Chris