Frontends:URI 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 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)