SWORD Module Source Discovery and Module Updating - Revision history

Scribe at 23:30, 13 March 2021

2021-03-13T23:30:48Z

Scribe at 23:20, 13 March 2021

2021-03-13T23:20:40Z

Scribe at 23:13, 13 March 2021

2021-03-13T23:13:33Z

Scribe at 23:07, 13 March 2021

2021-03-13T23:07:28Z

Scribe: SWORD Module Remote Installation Source Repository Discovery and Module Updating

2021-03-13T22:54:05Z

SWORD Module Remote Installation Source Repository Discovery and Module Updating

New page

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically. Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them. There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application. The steps can generally be list as these; more details about each can be found below:

0. Warn user about the risks of detection and ask them to enable Remote Source features.
1. Query CrossWire to obtain the list of known publishers of SWORD material.
2. Query each publisher for a list of available resources.

==== Installation ====

3. Download required files for the resource.
4. Check to see if the module is enciphered and obtain that code from the user.

==== Update ====

5. Refresh resource list obtained in step #2.
6. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
7. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
8. Uninstall the module.
9. Install the updated module.

Each of these steps has a simple method available to the programmer from the SWORD engine.

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation. Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users. This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

<nowiki>
-=+* WARNING *+=- -=+* WARNING *+=-

Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users.

IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.

Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable. Many repositories
contain wonderfully useful content. These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.

If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no]

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.

== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]

== 2. Query each publisher for a list of available resources.

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP. There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.

== 3. Present available resources to user.

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module.

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV

== 5. Install the module.

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 4. Check to see if the module is enciphered and obtain that code from the user.

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use. Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 5. Refresh resource list obtained in step #2.

== 6. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version. Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.

== 7. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.

== 8. Uninstall the module.

To uninstall the KJV module:

installmgr -u KJV

== 9. Install the updated module.

installmgr -ri "CrossWire" KJV

@@ Line 5: / Line 5: @@
 The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically.  Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them.  There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application.  The steps can generally be list as these; more details about each can be found below:
-{{ordered list|start=0
+<ol start="0">
-| Warn user about the risks.
+<li>Warn user about the risks.</li>
-| Query CrossWire to obtain the list of known publishers of SWORD materials.
+<li>Query CrossWire to obtain the list of known publishers of SWORD materials.</li>
-| Query each publisher for a list of available resources.
+<li>Query each publisher for a list of available resources.</li>
-}}
+</ol>
 ==== Installation ====
-{{ordered list|start=3
+<ol start="3">
-| Present available resources to user.
+<li>Present available resources to user.</li>
-| Display the detail for a selected module.
+<li>Display the detail for a selected module.</li>
-| Install the module.
+<li>Install the module.</li>
-| Check to see if the module is enciphered and obtain that code from the user.
+<li>Check to see if the module is enciphered and obtain that code from the user.</li>
-}}
+</ol>
 ==== Update ====
-{{ordered list|start=7
+<ol start="7">
-| Refresh resource list obtained in step #2.
+<li>Refresh resource list obtained in step #2.</li>
-| Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
+<li>Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.</li>
-| Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
+<li>Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.</li>
-| Uninstall the module.
+<li>Uninstall the module.</li>
-| Install the updated module.
+<li>Install the updated module.</li>
-}}
+</ol>
 Each of these steps has a simple method available to the programmer from the SWORD engine.

@@ Line 5: / Line 5: @@
 The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically.  Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them.  There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application.  The steps can generally be list as these; more details about each can be found below:
-# Warn user about the risks.
+{{ordered list|start=0
-# Query CrossWire to obtain the list of known publishers of SWORD materials.
+| Warn user about the risks.
-# Query each publisher for a list of available resources.
+| Query CrossWire to obtain the list of known publishers of SWORD materials.
 ==== Installation ====
-# Present available resources to user.
+{{ordered list|start=3
-# Display the detail for a selected module.
+| Present available resources to user.
-# Install the module.
+| Display the detail for a selected module.
-# Check to see if the module is enciphered and obtain that code from the user.
+| Install the module.
 ==== Update ====
-# Refresh resource list obtained in step #2.
+{{ordered list|start=7
-# Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
+| Refresh resource list obtained in step #2.
-# Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
+| Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
-# Uninstall the module.
+| Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
-# Install the updated module.
+| Uninstall the module.
 Each of these steps has a simple method available to the programmer from the SWORD engine.

@@ Line 3: / Line 3: @@
 The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically.  Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them.  There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application.  The steps can generally be list as these; more details about each can be found below:
-. Warn user about the risks of detection and ask them to enable Remote Source features.
+. Warn user about the risks.
-. Query CrossWire to obtain the list of known publishers of SWORD material.
+. Query CrossWire to obtain the list of known publishers of SWORD materials.
 . Query each publisher for a list of available resources.
 ==== Installation ====
-. Download required files for the resource.
+. Present available resources to user.
-. Check to see if the module is enciphered and obtain that code from the user.
+. Display the detail for a selected module.
 ==== Update ====
 . Refresh resource list obtained in step #2.
 . Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
 . Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
 . Uninstall the module.
 . Install the updated module.
 Each of these steps has a simple method available to the programmer from the SWORD engine.
@@ Line 26: / Line 28: @@
 CrossWire has a policy to always warn users before enabling Remote Module Installation.  Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users.  This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:
-<nowiki>
+ <nowiki>
                  -=+* WARNING *+=- -=+* WARNING *+=-
@@ Line 67: / Line 69: @@
 The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)
-[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]
+[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf|https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]
-== 2. Query each publisher for a list of available resources.
+== 2. Query each publisher for a list of available resources. ==
 To get a list of available publishers of remote SWORD module sources
@@ Line 86: / Line 88: @@
-== 3. Present available resources to user.
+== 3. Present available resources to user. ==
 To display resources available from a publisher, e.g., from the "CrossWire" source:
@@ Line 92: / Line 94: @@
 installmgr -rl "CrossWire"
-== 4. Display the detail for a selected module.
+== 4. Display the detail for a selected module. ==
 To display the details for a module, e.g., the KJV available from CrossWire:
@@ Line 98: / Line 100: @@
 installmgr -rdesc "CrossWire" KJV
-== 5. Install the module.
+== 5. Install the module. ==
 To install, e.g., the KJV from CrossWire remote source repository:
@@ Line 104: / Line 106: @@
 installmgr -ri "CrossWire" KJV
-== 4. Check to see if the module is enciphered and obtain that code from the user.
+== 6. Check to see if the module is enciphered and obtain that code from the user. ==
 To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:
@@ Line 129: / Line 131: @@
 This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.
-== 5. Refresh resource list obtained in step #2.
+== 7. Refresh resource list obtained in step #2. ==
-== 6. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
+== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==
 To check for updates in, e.g., the CrossWire repository:
@@ Line 142: / Line 144: @@
-== 7. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
+== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==
 installmgr -rdesc CrossWire Nave|grep "^\[History"
@@ Line 152: / Line 154: @@
-== 8. Uninstall the module.
+== 10. Uninstall the module. ==
 To uninstall the KJV module:
@@ Line 158: / Line 160: @@
 installmgr -u KJV
-== 9. Install the updated module.
+== 11. Install the updated module. ==
 installmgr -ri "CrossWire" KJV