[jsword-devel] Key issues

[DM Smith]

On May 17, 2008, at 3:02 PM, Brian Fernandes wrote:

> DM,
>
> Thanks for asking and summarizing from the many, many replies on
> sword-devel.
>
>>
>> The direction given by sword-devel:
>> The protocol should be sword:// not bible:// to be follow the  
>> standard
>> that the other Sword projects follow.
>>
>> bible:// indicates that we are working with a Bible, but is  
>> misleading
>> when using non-bible modules.
>
> I have added preliminary support for "sword://" to FireBible. Right  
> now
> the xsl file (simple.xsl) will still produce "bible://" links but that
> should be easily fixable (maybe JSword 1.0.8 is a good time to make  
> the
> change?) There are now some legacy problems I need to work out, so
> "bible://" may be supported for some time too.

It's not all that hard but there is a URL handler in the code that  
would need to be changed too.

Today, we use different protocols for the different kinds of works.

I believe in "release often". This time the release took longer to let  
several different translation efforts complete. We should be back on  
track for more frequent releases.


>
>>
>> After the protocol the suggestion is to have the module name  
>> followed by
>> a / and then the reference, as in:
>> sword://KJV/Gen.1.1
>
> This sounds good.
>
> Is it safe to assume that for any path with more than one segment, the
> first segment will be the module name?

I think that's safe. If it is not a Bible module, then it has to have  
the module name or the key has to be interpretable as specifically  
being a particular kind of key, e.g. G3588, would be a Strong's  
number; and 05.23, would be May 23 in a devotional. (Those are the  
only two special keys I know)

>
>
> So if we get a URL like sword://Gen.1.1, with just a single segment
> "Gen.1.1", then the code should try to look it up in the
> default/active bible, just like it does now.

You might try detecting Strong's numbers and go to the default  
Strong's Dictionary, based on the G|H prefix.

You might try detecting daily devotional keys and go to the default  
Daily Devotional.

>
>
> However, I have also seen URLs like this: sword://gen.1.1-ff/#Gen.1.9
> This is a two part path, where the first segment is clearly not the
> module. I believe this is the only exception to the rule, which we can
> get around by examining the second segment to see if it is an anchor
> reference (starting with #).

I think this is a syntax error.
Shouldn't it be?
	 sword://gen.1.1-ff#Gen.1.9
(I.e. # should focus within the current page and not be preceded by a /)

>
>
> Thoughts, any other cases for bibles in which the above is invalid?
>
> For gen books, the first segment must be the module, so any URL with
> less than one segment will be assumed to be a bible reference into the
> default/active bible.
>
>>
>> For parallel view, I suggested and several others thought well of the
>> idea that the module name is a comma separated list:
>> sword://KJV,ESV/Gen.1
>
> Perfect.
>
>>
>> For GenBooks, which have hierarchical keys, there were two  
>> suggestions:
>> 1) Use '/' as a path separator and use URL encoding for the spaces.
>> 2) Use url encoding for the '/' and for the spaces.
>
> I think using '/' unencoded should be just fine, but I have not gotten
> around to doing this yet.
>
>>
>> MacSword has a mechanism to pass features, prefixing them to the  
>> request:
>> sword://strongsNumbers&versePerLine@KJV/Gen.1
>>
>> I think it would be better to use ? at the end and then have the  
>> list as
>> this follows the URL syntax, as in:
>> sword://KJV/Gen.1?strongsNumbers=Y&versePerLine=Y
>
> Agree.
>
>
> Brian.