From ab8707c2eddff145941d2cf173e2fcc3748fecbe Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Sun, 9 Jan 2022 15:32:37 +0000 Subject: [PATCH 01/11] Update README.md Initial edits. --- README.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 98bee1170..e8ebcbef7 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,17 @@ # 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 (Firefox), Chrome and Edge +extension stores (search for "Kiwix JS"). There is a test implementation at https://kiwix.github.io/kiwix-js/, but this is used for development, and the code +there may be buggy or unstable. -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. +For exmaple, you can have the entire content of Wikipedia in your own language inside your device (including images). -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. + +If your Internet access is expensive, intermittent, slow, unreliable, observed or censored, you can still have access to this amazing repository of knowledge and culture. [![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,14 +23,17 @@ 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" form your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. + +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). -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). +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. ## 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, there is a need to "inject" the dependencies (images, css, etc). For compatibility reasons, there are several ways to do it: - 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. From 4b3c7753f0a06e918c0f82c6eab27944796584c7 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Sun, 9 Jan 2022 16:36:01 +0000 Subject: [PATCH 02/11] Update README.md --- README.md | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index e8ebcbef7..92115c29e 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,18 @@ Kiwix is an offline Wikipedia viewer. See the official site: https://www.kiwix.org/. -This is a ZIM archive reader for browser extensions or add-ons, developed in HTML5/Javascript. You can get the extension from the Mozilla (Firefox), Chrome and Edge -extension stores (search for "Kiwix JS"). There is a test implementation at https://kiwix.github.io/kiwix-js/, but this is used for development, and the code -there may be buggy or unstable. +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"). 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. -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. -For exmaple, you can have the entire content of Wikipedia in your own language inside your device (including images). +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 exmaple, you can have the entire content of Wikipedia in your own language inside your device (including images) +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 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. +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. -If your Internet access is expensive, intermittent, slow, unreliable, observed or censored, you can still have access to this amazing repository of knowledge and culture. +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 or unstable. [![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) @@ -23,24 +25,31 @@ If your Internet access is expensive, intermittent, slow, unreliable, observed o ## Usage -Install "Kiwix JS" form your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. +Install "Kiwix JS" form your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. Alternatively, bookmark or +install the PWA version from https://moz-extension.kiwix.org/current/. To install in Chromium browsers, go to Settings -> Apps -> Install this site as +an app. -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). +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). -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. +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. ## 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: -- 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. +- 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 in 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 Service Workers are currently disabled by Mozilla in Firefox +extensions. We use a workaround (an offline-first PWA version) as a substitute within the extension. ## 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 many recent browser engines. ### Officially supported platforms @@ -48,7 +57,7 @@ This is written in HTML/javascript so it should work on many recent browser engi - 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 From 05844047dbd7fa2ead36177877d6b712d0fea848 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Sun, 9 Jan 2022 17:39:14 +0000 Subject: [PATCH 03/11] Update README.md --- README.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 92115c29e..ef9b64bab 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,6 @@ entirely offline. If your Internet access is expensive, intermittent, slow, unre 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. -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 or unstable. - [![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) [![CodeFactor](https://www.codefactor.io/repository/github/kiwix/kiwix-js/badge)](https://www.codefactor.io/repository/github/kiwix/kiwix-js) @@ -26,8 +24,8 @@ There is a test implementation of the latest code at https://kiwix.github.io/kiw ## Usage Install "Kiwix JS" form your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. Alternatively, bookmark or -install the PWA version from https://moz-extension.kiwix.org/current/. To install in Chromium browsers, go to Settings -> Apps -> Install this site as -an app. +install the PWA version from https://moz-extension.kiwix.org/current/. To install the PWA in Chromium browsers, go to Settings -> Apps -> +Install this site as an app. 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 @@ -67,10 +65,10 @@ These platforms are deprecated. We still partially test against them, and we'll - 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 +## Licence -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 +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 @@ -82,12 +80,17 @@ Before running the tests, a one-time set up is needed to fetch development depen 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) +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). -See [CHANGELOG.md](CHANGELOG.md) for the detail of previous versions. +See [CHANGELOG.md](CHANGELOG.md) for details of previous versions. From 3c1f244d6a19cf099853eb5156a535c3a5f29337 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Thu, 13 Jan 2022 09:49:42 +0000 Subject: [PATCH 04/11] Updates from review --- README.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ef9b64bab..eae7a9334 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ Chrome and Edge extension stores (search for "Kiwix"). There is a version implem https://moz-extension.kiwix.org/current/, primarily intended for use within the Mozilla Extension. 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 exmaple, you can have the entire content of Wikipedia in your own language inside your device (including images) -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 and culture. +read the archive's content. For exmaple, 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 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. @@ -23,7 +24,7 @@ The reader also works with other content in the OpenZIM format: https://wiki.ope ## Usage -Install "Kiwix JS" form your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. Alternatively, bookmark or +Install "Kiwix JS" from your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. Alternatively, bookmark or install the PWA version from https://moz-extension.kiwix.org/current/. To install the PWA in Chromium browsers, go to Settings -> Apps -> Install this site as an app. @@ -39,15 +40,15 @@ capability. 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: -- 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 in 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 Service Workers are currently disabled by Mozilla in Firefox -extensions. We use a workaround (an offline-first PWA version) as a substitute within the extension. +- "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. It is +compatible with any browser. It works well on Mediawiki-based content but can miss some dependencies in some content +- "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, but it does not work on all browsers. And Service Workers are +currently disabled by Mozilla in Firefox extensions. We use a workaround (an offline-first PWA version) as a substitute within the extension. ## Compatibility -Since the app is written in HTML/JavaScript, it should work in 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. ### Officially supported platforms @@ -60,7 +61,7 @@ Since the app is written in HTML/JavaScript, it should work in many recent brows ### 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) @@ -72,9 +73,11 @@ 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 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 @@ -82,15 +85,13 @@ The browser extensions are distributed through the stores of each vendor (see li 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. +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). +The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (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). - See [CHANGELOG.md](CHANGELOG.md) for details of previous versions. From 9c4f6e18e3cfbd7e75e4cf7eef71928d2197c174 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Thu, 13 Jan 2022 11:16:25 +0000 Subject: [PATCH 05/11] Add Contributing section --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index eae7a9334..76c62691f 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,16 @@ Kiwix is an offline Wikipedia viewer. See the official site: https://www.kiwix.org/. 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"). 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. +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. 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 exmaple, 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 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. +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) @@ -32,23 +32,27 @@ Additionally, the app requires ZIM archives that you can download from https://d 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). -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. +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. ## 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: -- "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. It is -compatible with any browser. It works well on Mediawiki-based content but can miss some dependencies in some content +- "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. It works well on Mediawiki-based content but can miss some dependencies in some content; - "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, but it does not work on all browsers. And Service Workers are currently disabled by Mozilla in Firefox extensions. 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 -Since the app is written in HTML/JavaScript, it should work in most recent browser engines and many older ones too. +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 @@ -71,6 +75,34 @@ These platforms/browsers are deprecated. We still partially test against them, a 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. +## Contributing + +If you have some development experience with HTML and JavaScript, we welcome Pull Requests on existing issues. Please look at this repository's Issue +tracker, in particular those marked "good first issue". Please follow these guidelines when contributing: + +- Ask to be assigned to an issue you wish to work on first (we have lots of back issues, some of which are no longer relevant or wanted); +- We ask you only to pick issues for which you are confident that you have a solution; +- Follow the coding style of the area you are editing, including indentation, and be consistent with quotation marks and spacing; +- Use no higher than [ECMAScript 5](https://caniuse.com/es5) - notably, do not use arrow functions or `async` functions. However, Promises *are* + supported via a polyfill; +- Do not prettify code you are not working on; +- You must test your code yourself before asking for review, like this: + - clone the repository; + - set up a local Web server (we recommend Node/NPM's [http-server](https://www.npmjs.com/package/http-server)); + - serve the root directory of the repository (e.g. `http-server .`); + - in a browser, navigate to the URL of the main `index.html` (e.g. http://localhost:8080/www/index.html); + - manually test your fix in at least Firefox and Chromium (Edge or Chrome), ideally also in IE11 or in "IE Mode" in Edge; + - be sure to test your fix in both "JQuery" mode and "Service Worker" mode (see Configuration); + - run the Unit tests (see below) in at least the above browsers. + +If your feature works and tests are passing, make a PR, describe the testing you have done, and ask for a code review. + +Please note that the app caches its own code so that it can run as an offline-first Progressive Web App. This can complicate development, because you +may not see your changes, even after you refresh the browser. In Configuration, under "Expert settings", you will find a button that allows you to do +a full app reset, which will erase the PWA. When Service Worker mode is turned on, there is also a checkbox that bypasses the App Cache. You can turn +this on if you are frequently changing code and refreshing. Remember to turn it off for final testing. You can manually delete the App Cache in +the browser's DevTools (see Application or Storage tabs). + ## Unit tests Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. From c10d17de019a492b4ad3a09e6acd72f06acfa18d Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Thu, 13 Jan 2022 11:25:04 +0000 Subject: [PATCH 06/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 76c62691f..ac6f49f58 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Progressive Web App (PWA) at https://moz-extension.kiwix.org/current/, primarily 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 exmaple, 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 and culture. +access to this amazing repository of knowledge, information 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. From 39a18c71e1359d45e8658429b5b035ef23ab65d6 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Fri, 14 Jan 2022 05:45:10 +0000 Subject: [PATCH 07/11] Updates from self-review --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ac6f49f58..0b44ad7df 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,8 @@ Please note that the app caches its own code so that it can run as an offline-fi may not see your changes, even after you refresh the browser. In Configuration, under "Expert settings", you will find a button that allows you to do a full app reset, which will erase the PWA. When Service Worker mode is turned on, there is also a checkbox that bypasses the App Cache. You can turn this on if you are frequently changing code and refreshing. Remember to turn it off for final testing. You can manually delete the App Cache in -the browser's DevTools (see Application or Storage tabs). +the browser's DevTools (see Application or Storage tabs). We also recommend you disable the browser's built-in cache, using the checkbox in the DevTools +Network tab. ## Unit tests @@ -122,8 +123,8 @@ experimental or unstable. ## Previous versions -The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (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). +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 (now discontinued too: we're not lucky ;-) ). +These first versions were targeting Firefox OS (discontinued too: we're not lucky ;-) ). See [CHANGELOG.md](CHANGELOG.md) for details of previous versions. From 0bcf073fd066dcf104d4b324d0b33bb76097df22 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Fri, 14 Jan 2022 17:20:40 +0000 Subject: [PATCH 08/11] Update README.md --- README.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0b44ad7df..032997b76 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Chrome and Edge extension stores (search for "Kiwix", or click on a badge below) Progressive Web App (PWA) at https://moz-extension.kiwix.org/current/, primarily intended for use within the Mozilla Extension. 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 exmaple, you can have the entire content of Wikipedia in your own language inside your device (including images and +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. @@ -24,28 +24,27 @@ content (Wikipedia, Wikivoyage, Wikitionary, etc.), StackExchange, Project Guten ## Usage -Install "Kiwix JS" from your browser's add-on store, or you can get it from http://download.kiwix.org/release/browsers/. Alternatively, bookmark or -install the PWA version from https://moz-extension.kiwix.org/current/. To install the PWA in Chromium browsers, go to Settings -> Apps -> -Install this site as an app. +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. 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). -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. - ## Some technical details 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: -- "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. It works well on Mediawiki-based content but can miss some dependencies in some content; +- "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, but it does not work on all browsers. And Service Workers are -currently disabled by Mozilla in Firefox extensions. We use a workaround (an offline-first PWA version) as a substitute within the extension. +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. @@ -70,6 +69,14 @@ These platforms/browsers are deprecated. We still partially test against them, a - 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) +### 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. + +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. + ## Licence This application is released under the GPL v3 licence. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file @@ -108,7 +115,7 @@ Network tab. Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. -You can also run the tests with npm. Before running the tests, a one-time setup is needed to fetch development dependencies from the npm registry. +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). From dec21703b4155e4848736e469916059f930996c0 Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Fri, 14 Jan 2022 17:31:16 +0000 Subject: [PATCH 09/11] Move contributing section to #800 --- README.md | 29 ----------------------------- 1 file changed, 29 deletions(-) diff --git a/README.md b/README.md index 032997b76..e63259303 100644 --- a/README.md +++ b/README.md @@ -82,35 +82,6 @@ Although the app has fast title search, it cannot yet do full text search of the 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. -## Contributing - -If you have some development experience with HTML and JavaScript, we welcome Pull Requests on existing issues. Please look at this repository's Issue -tracker, in particular those marked "good first issue". Please follow these guidelines when contributing: - -- Ask to be assigned to an issue you wish to work on first (we have lots of back issues, some of which are no longer relevant or wanted); -- We ask you only to pick issues for which you are confident that you have a solution; -- Follow the coding style of the area you are editing, including indentation, and be consistent with quotation marks and spacing; -- Use no higher than [ECMAScript 5](https://caniuse.com/es5) - notably, do not use arrow functions or `async` functions. However, Promises *are* - supported via a polyfill; -- Do not prettify code you are not working on; -- You must test your code yourself before asking for review, like this: - - clone the repository; - - set up a local Web server (we recommend Node/NPM's [http-server](https://www.npmjs.com/package/http-server)); - - serve the root directory of the repository (e.g. `http-server .`); - - in a browser, navigate to the URL of the main `index.html` (e.g. http://localhost:8080/www/index.html); - - manually test your fix in at least Firefox and Chromium (Edge or Chrome), ideally also in IE11 or in "IE Mode" in Edge; - - be sure to test your fix in both "JQuery" mode and "Service Worker" mode (see Configuration); - - run the Unit tests (see below) in at least the above browsers. - -If your feature works and tests are passing, make a PR, describe the testing you have done, and ask for a code review. - -Please note that the app caches its own code so that it can run as an offline-first Progressive Web App. This can complicate development, because you -may not see your changes, even after you refresh the browser. In Configuration, under "Expert settings", you will find a button that allows you to do -a full app reset, which will erase the PWA. When Service Worker mode is turned on, there is also a checkbox that bypasses the App Cache. You can turn -this on if you are frequently changing code and refreshing. Remember to turn it off for final testing. You can manually delete the App Cache in -the browser's DevTools (see Application or Storage tabs). We also recommend you disable the browser's built-in cache, using the checkbox in the DevTools -Network tab. - ## Unit tests Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. From 58d8c5c1d939207f6b02a50f77a95e1cc4b08d4c Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Fri, 14 Jan 2022 17:47:15 +0000 Subject: [PATCH 10/11] Add mention of drag-and-drop --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e63259303..ca9bf2942 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,8 @@ These platforms/browsers are deprecated. We still partially test against them, a 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. +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. From e9c3abe543fcdd9ee51884fa24a04b0c7f13a1be Mon Sep 17 00:00:00 2001 From: Jaifroid Date: Sat, 15 Jan 2022 18:40:56 +0000 Subject: [PATCH 11/11] Revert Unit tests section as it has now moved --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ca9bf2942..4020a43b5 100644 --- a/README.md +++ b/README.md @@ -85,11 +85,9 @@ The source code can be found at https://github.com/kiwix/kiwix-js. ## Unit tests -Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. +Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. -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). +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. ## Public releases and nightly builds