Difference between revisions of "Frontends:URI Standard"

From CrossWire Bible Society
Jump to: navigation, search
m (→‎Current Situation: s)
(→‎Proposed extension: URI Standard)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
Some Sword frontends handles bible: or sword: uri's. It causes necessity of existence of the standard for new and existing frontends. Bible uri standard also necessary for [[Frontends:Bookmarks_Standard|Bookmarks Standard]].
+
Some SWORD front-ends handle '''bible:''' or '''sword:''' as URIs. This necessitates having a standard for new and existing front-ends. A Bible URI standard is also necessary for [[Frontends:Bookmarks_Standard|Bookmarks Standard]].
  
 
== Current situation ==
 
== Current situation ==
  
 
=== Xiphos ===
 
=== Xiphos ===
−
'''Xiphos''' handles uri's in following format:
+
'''Xiphos''' handles URIs in following format:
−
* '''bible://KJV/Gen.1.1'''
+
* '''sword://KJV/Gen.1.1'''
−
* '''bible:///Gen.1.1''' -- an empty module between // and /
+
* '''sword:///Gen.1.1''' -- an empty module between // and / (implies use of whatever Bible module is current, or default).
−
* '''bible://Josephus//The+Antiquities+of+the+Jews/Book+1/Chapter+1/Section+4''' -- non-bible modules, the 2nd double "//" is because keys for genbooks begin with /,  so the first double slash is URL syntax, the 3rd / is the end of the module name, and the 4th / is the beginning of the genbook key
+
* '''sword://NETnote/1Cor.7.2#n3''' -- a mid-page anchor reference named "n3", typically used for footnotes; can use either ! (OSIS) or # (ThML).
−
* '''bible://WebstersLinked/EPHEMERIS''' -- dictionary references, dictionary keys have no slashes
+
* '''sword://Josephus//The+Antiquities+of+the+Jews/Book+1/Chapter+1/Section+4''' -- non-bible module. The 2nd double "//" is because keys for genbooks begin with /,  so the first double slash is URL syntax, the 3rd / is the end of the module name, and the 4th / is the beginning of the genbook key.
 +
* '''sword://WebstersLinked/EPHEMERIS''' -- dictionary references, dictionary keys have no slashes.
  
 
=== FireBible ===
 
=== FireBible ===
 +
:''This section needs adding''.
 +
 +
=== PocketSword ===
 +
'''PocketSword''' currently internally handles the standard '''sword://module/key''' URIs but doesn't yet register itself with the OS to handle links from other apps.  This needs to happen at some point!  Probably for v1.3.0, when I refactor more of the code......  As '''PocketSword''' doesn't yet handle genbooks, I haven't looked into what the URI would be for a genbook.
 +
 +
=== Alkitab ===
 +
'''Alkitab''' currently internally handles URI, however it is not exposed to user and does not yet register itself with the OS.
 +
We handle URI in the following format:
 +
 +
'''[scheme://][path/][#]fragment'''
 +
 +
* scheme = sword,bible,commentary,...
 +
* path = name of the book eg: KJV, ESV
 +
* fragment/Reference = the key eg: GEN 1 1
 +
 +
eg:
 +
* bible://Gen 1 1 // open Gen 1:1 without care which bible (probable currently open or get from user preferences)
 +
* bible://KJV/Gen 1 1 // open  Gen 1:1 in KJV bible
 +
* sword://KJV/Gen 1 1 // open Gen 1:1 in KJV book
 +
* #Gen 1 1 // this is local anchor/fragment
 +
 +
If the specified path (book) is not in the correct category, the behaviour is unspecified eg:
 +
* bible://Calvin Institute/ 
 +
 +
As we know that Calvin Institute is not a Bible category, it is a General Book category, as for now
 +
the behaviour is unspecified (not forced by the API), do as you wish. However, it is recommended
 +
to silently ignore by not displaying anything, or show an error/message dialog.
 +
 +
== Proposed extension ==
 +
 +
We ('''PocketSword''') are looking at extending the current situation to allow other applications to open a particular module/verse in our front-end (and, possibly, others?).  We're taking the current situation and adding an optional query to the end of the URI.  The query is only looked at if the module requested is empty or the module is not installed.
 +
 +
The new format would be:
 +
 +
'''sword://[optional module]/[ref, module type dependent][optional query]'''
 +
 +
where the '''optional query''' is in the form:
 +
 +
'''?type=[module type]&module=list'''
 +
 +
where
 +
* '''module type''' == 'bible' || 'commentary' || 'dictionary' || 'genbook' (etc)
 +
* '''module=list''' part is optional and means that if the supplied module isn't installed (or there is no module specified), the app will firstly bring up a list of modules of the type specified & then when the user selects a module, the verse is viewed in that module.  How this is actually done in different front-ends is up to each front-end, but that's the idea for '''PocketSword'''.
 +
 +
So, if we don't have a module specified OR the specified module isn't installed, then:
 +
* '''IF''' module=list is specified, we will bring up a list of the modules, as described above.
 +
* '''ELSE''' we will use the default module of the type specified.
 +
 +
I will email sword-devel and open it up for discussion there.
 +
--[[User:Niccarter|Niccarter]] 07:38, 14 September 2010 (UTC)
 +
  
 
[[Category:SWORD Frontends|URI Standard]]
 
[[Category:SWORD Frontends|URI Standard]]
 
[[Category:Bookmarks|URI Standard]]
 
[[Category:Bookmarks|URI Standard]]
 +
[[Category:Standards|URI Standard]]

Latest revision as of 17:50, 26 July 2012

Some SWORD front-ends handle bible: or sword: as URIs. This necessitates having a standard for new and existing front-ends. A Bible URI standard is also necessary for Bookmarks Standard.

Current situation

Xiphos

Xiphos handles URIs in following format:

  • sword://KJV/Gen.1.1
  • sword:///Gen.1.1 -- an empty module between // and / (implies use of whatever Bible module is current, or default).
  • sword://NETnote/1Cor.7.2#n3 -- a mid-page anchor reference named "n3", typically used for footnotes; can use either ! (OSIS) or # (ThML).
  • sword://Josephus//The+Antiquities+of+the+Jews/Book+1/Chapter+1/Section+4 -- non-bible module. The 2nd double "//" is because keys for genbooks begin with /, so the first double slash is URL syntax, the 3rd / is the end of the module name, and the 4th / is the beginning of the genbook key.
  • sword://WebstersLinked/EPHEMERIS -- dictionary references, dictionary keys have no slashes.

FireBible

This section needs adding.

PocketSword

PocketSword currently internally handles the standard sword://module/key URIs but doesn't yet register itself with the OS to handle links from other apps. This needs to happen at some point! Probably for v1.3.0, when I refactor more of the code...... As PocketSword doesn't yet handle genbooks, I haven't looked into what the URI would be for a genbook.

Alkitab

Alkitab currently internally handles URI, however it is not exposed to user and does not yet register itself with the OS. We handle URI in the following format:

[scheme://][path/][#]fragment

  • scheme = sword,bible,commentary,...
  • path = name of the book eg: KJV, ESV
  • fragment/Reference = the key eg: GEN 1 1

eg:

  • bible://Gen 1 1 // open Gen 1:1 without care which bible (probable currently open or get from user preferences)
  • bible://KJV/Gen 1 1 // open Gen 1:1 in KJV bible
  • sword://KJV/Gen 1 1 // open Gen 1:1 in KJV book
  • #Gen 1 1 // this is local anchor/fragment

If the specified path (book) is not in the correct category, the behaviour is unspecified eg:

  • bible://Calvin Institute/

As we know that Calvin Institute is not a Bible category, it is a General Book category, as for now the behaviour is unspecified (not forced by the API), do as you wish. However, it is recommended to silently ignore by not displaying anything, or show an error/message dialog.

Proposed extension

We (PocketSword) are looking at extending the current situation to allow other applications to open a particular module/verse in our front-end (and, possibly, others?). We're taking the current situation and adding an optional query to the end of the URI. The query is only looked at if the module requested is empty or the module is not installed.

The new format would be:

sword://[optional module]/[ref, module type dependent][optional query]

where the optional query is in the form:

?type=[module type]&module=list

where

  • module type == 'bible' || 'commentary' || 'dictionary' || 'genbook' (etc)
  • module=list part is optional and means that if the supplied module isn't installed (or there is no module specified), the app will firstly bring up a list of modules of the type specified & then when the user selects a module, the verse is viewed in that module. How this is actually done in different front-ends is up to each front-end, but that's the idea for PocketSword.

So, if we don't have a module specified OR the specified module isn't installed, then:

  • IF module=list is specified, we will bring up a list of the modules, as described above.
  • ELSE we will use the default module of the type specified.

I will email sword-devel and open it up for discussion there. --Niccarter 07:38, 14 September 2010 (UTC)

Retrieved from "https://wiki.crosswire.org/index.php?title=Frontends:URI_Standard&oldid=11901"