diff options
| -rw-r--r-- | docs/librejs.info | 121 | ||||
| -rw-r--r-- | docs/man.texi | 95 | ||||
| -rw-r--r-- | docs/version.texi | 7 |
3 files changed, 152 insertions, 71 deletions
diff --git a/docs/librejs.info b/docs/librejs.info index deed5c5..0520e19 100644 --- a/docs/librejs.info +++ b/docs/librejs.info @@ -1,6 +1,6 @@ -This is librejs.info, produced by makeinfo version 5.2 from man.texi. +This is librejs.info, produced by makeinfo version 6.5 from man.texi. -This manual is for GNU LibreJS (version 7.2, 10 February 2018), a GNU +This manual is for GNU LibreJS (version 7.17, 8 October 2018), a GNU IceCat extension to detect and block nonfree nontrivial JavaScript on webpages. @@ -23,7 +23,7 @@ File: librejs.info, Node: Top, Next: Overview, Up: (dir) LibreJS ******* -This manual is for GNU LibreJS (version 7.2, 10 February 2018). +This manual is for GNU LibreJS (version 7.17, 8 October 2018). * Menu: @@ -91,7 +91,8 @@ File: librejs.info, Node: Installation, Next: How to Use, Prev: Disclaimer, You can install LibreJS directly using a generated 'librejs.xpi' file, or by building it from source. - You can also download it from Mozilla, but due to Mozilla's review + You can also download it from +<https://addons.mozilla.org/addon/librejs/>, but due to Mozilla's review process the download isn't always up to date. @@ -120,14 +121,14 @@ will always get rejected. It is important to note that this feature recognizes which scripts are blacklisted and whitelisted based on hash. This means that even a slight difference in a script's code will cause it to be recognized as a -seperate script. +separate script. Sometimes, JavaScript will be dynamically generated so that it is different every time a website is loaded. These types of scripts cannot be whitelisted or blacklisted since they cannot be recognized. LibreJS has a default whitelist of scripts that are known to be free -but may not use the format for declaring a license that it can +but may not declare their license in a format that LibreJS can understand. 4.3 Complaint Feature @@ -159,22 +160,22 @@ in the LibreJS add-on preferences in your web browser. 4.4 Options =========== -"Whitelist" + You can manage LibreJS's preferences either from the extension's + entry in your browser's Add-ons Manager page ('about:addons') or by + clicking the LibreJS toolbar icon and then the "Settings..." + button on the top right of the popup. This will open a panel + containing a whitelist/blacklist manager and a section to configure + your complaints messages to site owners. - LibreJS lets you whitelist domain names and subdomains to bypass - the regular JavaScript check. This might be useful, for example, - if you are running your own code in a local web server. In order - to add a whitelisted domain or url, go to Tools >> Add-ons. Inside - the add-on window, click on "Extensions", and in the list, where - you see LibreJS, click on the "Preferences" button. You will see - an input field labeled "Whitelist". +"Whitelist/Blacklist" - In the field, enter comma-separated domain names. Do not enter the - protocol. For instance to whitelist all the pages of - <http://www.gnu.org> and <https://gnu.org>, enter 'gnu.org'. To - allow all subdomains from gnu.org, enter: '*.gnu.org'. This will - match such sites as <http://savannah.gnu.org> and - <http://audio-video.gnu.org>. + LibreJS lets you whitelist or blacklist domain names and + subdomains, to bypass the regular JavaScript checks. This might be + useful, for example, if you are running your own code in a local + web server, or if you don't want to waste computing resources on + script origins you already know you can't trust. librejs provides + a lists manager UI to handle both the lists on the top of its + Options panel. "Complaint email subject" Configure the default subject used in complaint emails. @@ -355,7 +356,7 @@ must be declared using a machine-readable license format. }, 'X11':{ 'URL': 'http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3', - 'Magnet link': 'magnet:?xt=urn:btih:5305d91886084f776adcf57509a648432709a7c7&dn=x11.txt' + 'Magnet link': 'magnet:?xt=urn:btih:5305d91886084f776adcf57509a648432709a7c7&dn=x11.txt' }, 'Modified-BSD':{ 'URL': 'http://www.xfree86.org/current/LICENSE4.html', @@ -381,17 +382,55 @@ File: librejs.info, Node: LibreJS Development Notes, Next: Installation Requir 8 LibreJS Development Notes *************************** -8.1 Debugging +8.1 Dependencies +================ + +LibreJS 7.17 depends on a number of Node.js-based libraries that can be +installed using the 'npm' utility: + + $ npm install acorn-loose + $ npm install jssha + $ npm install browserify + $ export PATH=$PATH:./node_modules/.bin + +8.2 Building +============ + +To build the extension run: + $ browserify main_background.js -o bundle.js + + To build the extension plus create a .xpi package run: + $ ./build.sh + + To build the extension including the automated test suite (see TEST +below) run: + $ ./build.sh -t + or + $ ./build.sh --test + + Note: this 'build.sh' script relies on no new source files being +created. + +8.3 Debugging ============= To debug LibreJS, visit the special URL 'about:debugging'. Click on 'Enable add-on debugging' then 'Load Temporary Add-on'. Navigate to LibreJS's unpacked source directory and select 'manifest.json'. - Lines 34 and 35 in 'main_background.js' control the printing of -'dbg_print()' statements. Make sure these are set to false in releases. + Lines 39 and 40 in 'main_background.js' assign two variables +controlling the verbosity of 'dbg_print()' statements. Make sure these +are set to false before building a release. + +8.4 Testing +=========== + +An automated test suite runs automatically in its own tab whenever the +extension is loaded as a "Temporary add-on" from 'about:debugging'. +Otherwise (if included in the xpi) it can be launched from the UI by +clicking the "Automated self test..." button. -8.2 Adding new whitelisted libraries +8.5 Adding new whitelisted libraries ==================================== The script index.js in './hash_script' generates the default whitelist. @@ -402,15 +441,15 @@ Run it with the following command: Then, just copy the contents of the file "output" to the appropriate place in main_background.js. -8.3 Releasing a new version +8.6 Releasing a new version =========================== Update the version number in manifest.json. - Make sure debug statements are set to felse on lines 34/35 in + Make sure debug statements are set to false on lines 39/40 in 'main_background.js'. - Then, run the build script 'build.sh'. + Then run the build script 'build.sh'. File: librejs.info, Node: Installation Requirements, Next: LibreJS Internals, Prev: LibreJS Development Notes, Up: Top @@ -426,7 +465,7 @@ LibreJS. It can be installed on the following: GNU IceCat, Mozilla Firefox, Trisquel Abrowser, Debian Iceweasel. - LibreJS works on these browsers starting from version 57. We + LibreJS works on these browsers starting from version 60. We recommend that you use the latest version of your Mozilla browser. LibreJS has been tested on a GNU/Linux distribution, but it is compatible any operating system as long as you're using a compatible @@ -932,17 +971,17 @@ their use in free software. Tag Table: -Node: Top826 -Node: Overview1820 -Node: Disclaimer2667 -Node: Installation3163 -Node: How to Use3505 -Node: JavaScript Detection7002 -Node: Free Licenses Detection8289 -Node: Setting Your JavaScript Free8760 -Node: LibreJS Development Notes14487 -Node: Installation Requirements15601 -Node: LibreJS Internals16311 -Node: GNU Free Documentation License16961 +Node: Top825 +Node: Overview1818 +Node: Disclaimer2665 +Node: Installation3161 +Node: How to Use3539 +Node: JavaScript Detection7045 +Node: Free Licenses Detection8332 +Node: Setting Your JavaScript Free8803 +Node: LibreJS Development Notes14530 +Node: Installation Requirements16612 +Node: LibreJS Internals17322 +Node: GNU Free Documentation License17972 End Tag Table diff --git a/docs/man.texi b/docs/man.texi index 5871315..a9db799 100644 --- a/docs/man.texi +++ b/docs/man.texi @@ -111,8 +111,8 @@ it to @email{bug-librejs@@gnu.org}. You can install LibreJS directly using a generated @file{librejs.xpi} file, or by building it from source. -You can also download it from Mozilla, but due to Mozilla's review -process the download isn't always up to date. +You can also download it from @url{https://addons.mozilla.org/addon/librejs/}, +but due to Mozilla's review process the download isn't always up to date. @node How to Use @chapter How to Use @@ -134,15 +134,15 @@ will always get rejected. It is important to note that this feature recognizes which scripts are blacklisted and whitelisted based on hash. This means that even a slight -difference in a script's code will cause it to be recognized as a -seperate script. +difference in a script's code will cause it to be recognized as a +separate script. -Sometimes, JavaScript will be dynamically generated so that it is -different every time a website is loaded. These types of scripts cannot +Sometimes, JavaScript will be dynamically generated so that it is +different every time a website is loaded. These types of scripts cannot be whitelisted or blacklisted since they cannot be recognized. LibreJS has a default whitelist of scripts that are known to be free but -may not use the format for declaring a license that it can understand. +may not declare their license in a format that LibreJS can understand. @section Complaint Feature @@ -172,20 +172,21 @@ LibreJS add-on preferences in your web browser. @section Options @table @dfn -@item Whitelist -LibreJS lets you whitelist domain names and subdomains to bypass the -regular JavaScript check. This might be useful, for example, if you are -running your own code in a local web server. In order to add a whitelisted -domain or url, go to Tools >> Add-ons. Inside the add-on window, click on -@dfn{Extensions}, and in the list, where you see LibreJS, click on the -@dfn{Preferences} button. You will see an input field labeled @dfn{Whitelist}. +You can manage LibreJS's preferences either from the extension's entry in your +browser's Add-ons Manager page (@code{about:addons}) or by clicking the LibreJS +toolbar icon and then the "Settings..." button on the top right of the popup. +This will open a panel containing a whitelist/blacklist manager and a section +to configure your complaints messages to site owners. -In the field, enter comma-separated domain names. Do not enter the protocol. -For instance to whitelist all the pages of @url{http://www.gnu.org} and -@url{https://gnu.org}, enter @samp{gnu.org}. To allow all subdomains from -gnu.org, enter: @samp{*.gnu.org}. This will match such sites as -@url{http://savannah.gnu.org} and @url{http://audio-video.gnu.org}. +@item Whitelist/Blacklist + +LibreJS lets you whitelist or blacklist domain names and subdomains, to bypass +the regular JavaScript checks. This might be useful, for example, if you are +running your own code in a local web server, or if you don't want to waste +computing resources on script origins you already know you can't trust. librejs +provides a lists manager UI to handle both the lists on the top of its Options +panel. @item Complaint email subject Configure the default subject used in complaint emails. @@ -407,15 +408,57 @@ Many free licenses are listed in this page: @node LibreJS Development Notes @chapter LibreJS Development Notes +@section Dependencies + +LibreJS @value{VERSION} depends on a number of Node.js-based libraries that +can be installed using the @code{npm} utility: + +@verbatim + $ npm install acorn-loose + $ npm install jssha + $ npm install browserify + $ export PATH=$PATH:./node_modules/.bin +@end verbatim + +@section Building + +To build the extension run: +@verbatim + $ browserify main_background.js -o bundle.js +@end verbatim + +To build the extension plus create a .xpi package run: +@verbatim + $ ./build.sh +@end verbatim + +To build the extension including the automated test suite (see TEST below) run: +@verbatim + $ ./build.sh -t +@end verbatim +or +@verbatim + $ ./build.sh --test +@end verbatim + +Note: this @file{build.sh} script relies on no new source files being created. + @section Debugging To debug LibreJS, visit the special URL @code{about:debugging}. Click on `Enable add-on debugging` then `Load Temporary Add-on`. Navigate to LibreJS's unpacked source directory and select @file{manifest.json}. -Lines 34 and 35 in @file{main_background.js} control the printing of -@code{dbg_print()} statements. Make sure these are set to false in -releases. +Lines 39 and 40 in @file{main_background.js} assign two variables controlling +the verbosity of @code{dbg_print()} statements. Make sure these are set to false +before building a release. + +@section Testing + +An automated test suite runs automatically in its own tab whenever the extension +is loaded as a "Temporary add-on" from @code{about:debugging}. +Otherwise (if included in the xpi) it can be launched from the +UI by clicking the "Automated self test..." button. @section Adding new whitelisted libraries @@ -431,10 +474,10 @@ place in main_background.js. Update the version number in manifest.json. -Make sure debug statements are set to false on lines 34/35 in +Make sure debug statements are set to false on lines 39/40 in @file{main_background.js}. -Then, run the build script @file{build.sh}. This +Then run the build script @file{build.sh}. @node Installation Requirements @appendix Installation Requirements @@ -447,8 +490,8 @@ LibreJS. It can be installed on the following: GNU IceCat, Mozilla Firefox, Trisquel Abrowser, Debian Iceweasel. -LibreJS works on these browsers starting from version 57. We recommend -that you use the latest version of your Mozilla browser. LibreJS has +LibreJS works on these browsers starting from version 60. We recommend +that you use the latest version of your Mozilla browser. LibreJS has been tested on a GNU/Linux distribution, but it is compatible any operating system as long as you're using a compatible Mozilla browser. diff --git a/docs/version.texi b/docs/version.texi index 7ca3e74..e300ce7 100644 --- a/docs/version.texi +++ b/docs/version.texi @@ -1,5 +1,4 @@ -@set UPDATED 10 February 2018 -@set UPDATED-MONTH February 2018 +@set UPDATED 8 October 2018 +@set UPDATED-MONTH October 2018 @set EDITION 2 -@set VERSION 7.2 - +@set VERSION 7.17 |