Difference between revisions of "Frontends:URI Standard"
m (moved Frontends:URI Standard to SWORD Frontends:URI Standard: moved to category) |
David Haslam (talk | contribs) (→Proposed extension: URI Standard) |
||
(15 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | Some | + | 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 == | ||
− | == | + | === Xiphos === |
− | '''Xiphos''' handles | + | '''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. | ||
+ | --[[User:Niccarter|Niccarter]] 07:38, 14 September 2010 (UTC) | ||
+ | |||
+ | |||
+ | [[Category:SWORD Frontends|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.
Contents
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)