Update documentation to include new implementation

README.md

@@ -1,14 +1,18 @@
 # Kiwix JS
 
-Kiwix is an offline Wikipedia viewer. See the official site: https://www.kiwix.org/
+Kiwix is an offline Wikipedia viewer. See the official site: https://www.kiwix.org/.
 
-This is a browser extension developed in HTML5/Javascript.
+This is a ZIM archive reader for browser extensions or add-ons, developed in HTML5/Javascript. You can get the extension from the Mozilla,
+Chrome and Edge extension stores (search for "Kiwix", or click on a badge below). There is a version implemented as an offline-first
+Progressive Web App (PWA) at https://moz-extension.kiwix.org/current/, primarily intended for use within the Mozilla Extension.
 
-You can search among the article titles, and read any of them without any Internet access.
-All the content of Wikipedia is inside your device (including the images).
-It might also work with other content in the OpenZIM format: https://wiki.openzim.org/wiki/OpenZIM , but has been only tested on the Mediawiki-based (Wikipedia, Wikivoyage, etc) and StackExchange ZIM files.
+Once you have obtained an archive (see below), you can select it in Kiwix JS, and search for article titles. No further Internet access is required to
+read the archive's content. For example, you can have the entire content of Wikipedia in your own language inside your device (including images and
+audiovisual content) entirely offline. If your Internet access is expensive, intermittent, slow, unreliable, observed or censored, you can still have
+access to this amazing repository of knowledge, information and culture.
 
-If your Internet access is expensive/rare/slow/unreliable/watched/censored, you still can browse this amazing repository of knowledge and culture.
+The reader also works with other content in the OpenZIM format: https://wiki.openzim.org/wiki/OpenZIM, but our main targets are Mediawiki-based
+content (Wikipedia, Wikivoyage, Wikitionary, etc.), StackExchange, Project Gutenberg and TED Talks.
 
 [![Build Status: Continuous Integration](https://github.com/kiwix/kiwix-js/workflows/CI/badge.svg?query=branch%3Amaster)](https://github.com/kiwix/kiwix-js/actions?query=branch%3Amaster)
 [![Build Status: Release](https://github.com/kiwix/kiwix-js/workflows/Release/badge.svg?query=branch%3Amaster)](https://github.com/kiwix/kiwix-js/actions?query=branch%3Amaster)
@@ -20,59 +24,86 @@ If your Internet access is expensive/rare/slow/unreliable/watched/censored, you
 
 ## Usage
 
-It uses ZIM files that you can download from https://download.kiwix.org/zim/
+Install "Kiwix JS" from your browser's add-on store. This is the best way to get the extension, because it will be kept up to date automatically. If
+you would rather not use a store, you can get a file-based version of the extension from http://download.kiwix.org/release/browsers/, but you will
+have to update this manually. Alternatively, you can bookmark or install the PWA version from https://moz-extension.kiwix.org/current/ (it will
+auto-update). To install the PWA in Chromium browsers, go to Settings -> Apps -> Install this site as an app.
 
-You have to download them separately, store them in your filesystem, and manually select them after starting the application.
-It is unfortunately not technically possible to "remember" the selected ZIM file and open it automatically (the browsers refuse that for security reasons).
+Additionally, the app requires ZIM archives that you can download from https://download.kiwix.org/zim/ or
+https://wiki.kiwix.org/wiki/Content_in_all_languages. You have to download these separately, store them in your filesystem, and manually select them
+after starting the application (or you can drag-and-drop one into the app).
 
 ## Some technical details
 
-Technically, after reading an article from a ZIM file, there is a need to "inject" the dependencies (images, css, etc). For compatibility reasons, there are several ways to do it :
+Technically, after reading an article from a ZIM file, it is necessary to "inject" the dependencies (images, css, etc). For compatibility reasons,
+there are two main ways of doing this:
 
-- the "jQuery" mode parses the DOM to find the HTML tags of these dependencies and modifies them to put the Base64 content in it. It is compatible with any browser. It works well on Mediawiki-based content but can miss some dependencies on some contents
-- the "ServiceWorker" mode uses a Service Worker to catch any HTTP request the page would send and reply with content read from the ZIM file. It is a generic and much cleaner way than jQuery mode, but it does not work on all browsers. And ServiceWorkers are currently disabled by Mozilla in Firefox extensions.
+- "JQuery" mode parses the DOM to find the HTML tags of these dependencies and modifies them to point to content we extract from the ZIM. This mode
+is compatible with any browser, but it cannot run JavaScript inside the ZIM file, so some ZIMs with dynamic content do not work well (if at all).
+However, Mediawiki-based content (e.g. Wikipedia) works fine in this mode;
+- "ServiceWorker" mode uses a Service Worker to catch any HTTP request the page may send and reply with content read from the ZIM file. It is a
+generic and much cleaner way of serving content to the browser than jQuery mode. It works in any recent browser, but not in older ones. Service
+Workers are currently disabled by Mozilla in Firefox extensions, but we use a workaround (an offline-first PWA version) as a substitute within
+the extension.
+
+You can switch between these content injection modes in Configuration.
 
 ## Compatibility
 
-This is written in HTML/javascript so it should work on many recent browser engines.
+Since the app is written in HTML/JavaScript, it should work in most recent browser engines and many older ones too, depending on the Content
+Injection mode supported by the specific browser engine.
 
 ### Officially supported platforms
 
 - Mozilla Firefox >=45 (as an extension : https://addons.mozilla.org/fr/firefox/addon/kiwix-offline/)
 - Google Chrome (or Chromium) >=58 (as an extension : https://chrome.google.com/webstore/detail/kiwix/donaljnlmapmngakoipdmehbfcioahhk)
 - Firefox OS >=1.2 (needs to be installed manually on the device with WebIDE)
 - Microsoft Edge (Chromium) >=80 (as an add-on : https://microsoftedge.microsoft.com/addons/detail/kiwix/jlepddlenlljlnnhjinfaciabanbnjbp)
-- Universal Windows Platform (UWP) >=10.0.10240 (as an HTML/JS application : see https://github.com/kiwix/kiwix-js-windows/)
+- Universal Windows Platform (UWP) >=10.0.10240, Electron and NWJS (as an HTML/JS application : see https://github.com/kiwix/kiwix-js-windows/)
 - Ubuntu Touch (as an application : https://open-store.io/app/kiwix)
 
 ### Deprecated platforms
 
-These platforms are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated :
+These platforms/browsers are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated:
 
 - Microsoft Edge Legacy >=40 (needs to run a local copy of the source code)
 - Microsoft Internet Explorer 11 (needs to run a local copy of the source code)
 
-## License
+### Limitations
+
+It is unfortunately not yet technically possible to "remember" the selected ZIM file and open it automatically (browsers do not allow that for
+security reasons). There are [versions of this app](https://www.kiwix.org/en/download/) that use frameworks like Electron, UWP or NWJS which have
+this capability. You can drag-and-drop a ZIM file into the app, which is a quick way to open an archive and switch between several archives in a
+folder.
+
+Although the app has fast title search, it cannot yet do full text search of the entire archive. This may be possible in the future.
 
-This application is released under the GPL v3 license. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file
-The source code can be found at https://github.com/kiwix/kiwix-js
+## Licence
+
+This application is released under the GPL v3 licence. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file
+The source code can be found at https://github.com/kiwix/kiwix-js.
 
 ## Unit tests
 
-Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome.
+Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server.
 
-Before running the tests, a one-time set up is needed to fetch development dependencies from the npm registry. Run `npm ci --ignore-scripts` to fetch the same versions as we use in CI.
+You can also run the UI tests with npm. Before running the tests, a one-time setup is needed to fetch development dependencies from the npm registry.
+Run `npm ci --ignore-scripts` to fetch the same versions as we use in CI. Then run `npm test` to run the tests against Chrome and Firefox headless
+(these browsers need to be installed in default locations).
 
 ## Public releases and nightly builds
 
 The browser extensions are distributed through the stores of each vendor (see links above). But the packages are also saved in https://download.kiwix.org/release/browsers/ if necessary.
 
-Some nightly builds are generated, and should only be used for testing purpose: https://download.kiwix.org/nightly/
+Some nightly builds are generated, and should only be used for testing purpose: https://download.kiwix.org/nightly/.
+
+There is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/, but this is used for development, and may be buggy,
+experimental or unstable.
 
 ## Previous versions
 
-The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (now discontinued). There was a "articles nearby" feature, that was able to find articles around your location. It has been deleted from the source code with everything related to Evopedia (but still in git history in versions<=2.0.0)
-These first versions were targeting Firefox OS (now discontinued too: we're not lucky ;-) ).
-Some Phonegap/Cordova port was started but never finished (see in git history in versions<=2.0.0).
+The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (discontinued). There was an "articles nearby" feature, that was able to find articles around your location. It has been deleted from the source code with everything related to Evopedia (but still in git history in versions<=2.0.0).
+
+These first versions were targeting Firefox OS (discontinued too: we're not lucky ;-) ).
 
-See [CHANGELOG.md](CHANGELOG.md) for the detail of previous versions.
+See [CHANGELOG.md](CHANGELOG.md) for details of previous versions.