PR#27: Update manual to version 7.17. - librejs

librejs

#27 Update manual to version 7.17.

Merged 5 years ago by quidam. Opened 5 years ago by gioma1.

gioma1/librejs documentation into master

Added dependencies and testing sections.

hackademix • 5 years ago

6fadce1

Update manual to version 7.17.

hackademix • 5 years ago

2aeaa93

docs/librejs.info

file modified

+80 -41

		`@@ -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 @@`
		`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 @@`
		`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 @@`
		`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 @@`
		`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 @@`
		`},`
		`'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 @@`
		`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 @@`
		`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 @@`

		`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 @@`


		`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`

docs/man.texi

file modified

+69 -26

		`@@ -111,8 +111,8 @@`
		`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 @@`

		`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 @@`
		`@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 @@`
		`@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 @@`

		`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 @@`

		`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.`

docs/version.texi

file modified

+3 -4

		`@@ -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`

gioma1 commented 5 years ago

Updated manual sources, especially regarding build / debugging instructions, and generate the librejs.info which is tracked in the sources repository as well.
I'm gonna also generate from the updated man.texi the other output formats found in the CVS repository, which appear to have been generated using makeinfo on the man.texi source for LibreJS version 6.0.3, and attach a patch to update it too.