From ada88090ead2c3b9d0804794c5f20f9b24d1c2b1 Mon Sep 17 00:00:00 2001
From: Nik Nyby <nikolas@gnu.org>
Date: Sat, 17 Jan 2015 17:12:36 -0500
Subject: Import to new git repository

The old repository was using almost 100mb of space because of all
the unnecessary files in the history. So I've imported the code to a
new git repository. Unfortunately the history isn't viewable from this
repository anymore. To see what happened with LibreJS before 2015, see
the old Bazaar repo here: http://bzr.savannah.gnu.org/lh/librejs/
---
 doc/librejs.texi | 878 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 878 insertions(+)
 create mode 100644 doc/librejs.texi

(limited to 'doc/librejs.texi')

diff --git a/doc/librejs.texi b/doc/librejs.texi
new file mode 100644
index 0000000..2ff6271
--- /dev/null
+++ b/doc/librejs.texi
@@ -0,0 +1,878 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename librejs.info
+@include version.texi
+@settitle GNU LibreJS @value{VERSION}
+
+@copying
+This manual is for GNU LibreJS (version @value{VERSION}, @value{UPDATED}),
+a GNU IceCat extension to detect and block nonfree nontrivial
+JavaScript on webpages.
+
+Copyright @copyright{} 2011 2012 2014 Loic J. Duros
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@dircategory GNUzilla
+@direntry
+* LibreJS: (librejs).               Detect nonfree nontrivial in GNU Icecat
+@end direntry
+
+@titlepage
+@title GNU LibreJS
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Loic J. Duros  (@email{librejs@@lduros.net})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@contents
+
+
+@node Top
+@top LibreJS
+This manual is for GNU LibreJS (version @value{VERSION}, @value{UPDATED}).
+
+@menu
+* Overview::                            General purpose and information.
+* Disclaimer::                          Emphasize what LibreJS does and does not.
+* Installation::                        Installing LibreJS from source. 
+* How to Use::                          How to use LibreJS in IceCat.
+* JavaScript Detection::                How LibreJS detects nontrivial Javascript.
+* Free Licenses Detection::             List of licenses detected by LibreJS.
+* Setting Your JavaScript Free::        Information for website owners/maintainers.
+* Installation Requirements::           Requirements to build and install LibreJS.
+* LibreJS Internals::                   How LibreJS works under the hood.
+* Tests::                               Test LibreJS and better understand it.
+* GNU Free Documentation License::      Copying and sharing this documentation.
+@end menu
+
+@node Overview
+@chapter Overview
+
+@cindex overview
+GNU LibreJS ---an add-on for GNU IceCat and Mozilla Firefox--- detects
+and blocks nonfree nontrivial JavaScript while allowing its execution on
+pages containing code that is either trivial and/or free.
+
+Many websites run nontrivial JavaScript on your computer. Some use it
+for complex tasks; many use it gratuitously for minor jobs that could be
+done easily with plain HTML.  Sometimes this JavaScript code is
+malicious.  Either way, the JavaScript code is often nonfree.  For
+explanation of the issue, see "The JavaScript
+Trap"(@url{http://www.gnu.org/philosophy/javascript-trap.html}).
+
+If you care about freedom in your computing, and don't wish to let all
+and sundry make you run nonfree programs, now you can prevent it by
+using LibreJS.
+
+
+@node Disclaimer
+@chapter Disclaimer
+
+@cindex disclaimer
+
+@itemize @bullet
+@item
+LibreJS is not a security tool. Its goal is to detect nonfree nontrivial
+JavaScript, and it currently does not detect whether free or trivial
+code is malicious or not. Other free Mozilla extensions and add-ons may
+be available for this purpose.
+
+@item
+LibreJS is always a work in progress. If you find a bug, please report
+it to @email{bug-librejs@@gnu.org}.
+
+@end itemize
+
+@node Installation
+@chapter Installation
+@cindex Installation
+
+You can install LibreJS directly using a generated @file{librejs.xpi}
+file, or by building it from source.
+
+
+@section Building the Package
+After enabling the Add-on SDK, you should be able to use the @code{make}
+command to build LibreJS from source.
+
+After running @code{make}, a new file, @file{librejs.xpi} should be
+generated. This is the file that can be installed in a Mozilla browser. 
+
+@section Installing LibreJS
+To install the add-on for all users, run:
+@example 
+sudo make install
+@end example
+
+or as root:
+@example
+make install
+@end example
+
+Next time you open a Mozilla-browser as a user of your system, you
+should be notified that a new add-on (in this case, LibreJS) as been
+installed and whether to allow it to run or not.
+
+@node How to Use
+@chapter How to Use
+
+@section LibreJS in action
+
+After installing the add-on, you will see the LibreJS widget in the
+add-on bar at the bottom of the browser window.  After loading a page,
+left-click on the widget to view the deactivated JavaScript code from
+the page (both on page and external) and, if applicable, the scripts
+that were accepted.
+
+@section Complaint Feature
+
+It is very important to complain when a site has nonfree JavaScript
+code, especially if it won't work without that code.  LibreJS makes it
+easy to complain by heuristically finding where to send the complaint.
+
+When nonfree/nontrivial code is detected in a page, LibreJS attempts to
+find a relevant contact link or email for the website you are
+visiting. In order to do so, it will attempt to visit a few links from
+the current page (for instance, a link labeled ``contact'' on the same
+domain as the current page, @dots{})
+
+LibreJS detects contact pages, email addresses that are likely to be
+owned by the maintainer of the site, Twitter and identi.ca links, and
+phone numbers.
+
+After LibreJS detects any of the above, a ``Complain'' tab will appear
+on the right of your web browser. When you click on this tab, a large
+panel will appear with contact information. Ideally, at the top you will
+find the email address of the maintainer, labeled as the ``Email you
+should use''.
+
+When you complain to the website for their nonfree nontrivial
+JavaScript, provide them with the link to the JavaScript Trap essay so
+that they can get more information on what the issue is and how they can
+solve it on their own site.
+
+LibreJS includes a default subject line and body for the complaint email,
+with a link to the JavaScript Trap essay. This can be configured in the
+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, or press @kbd{Control
++ Shift + A}. 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}. 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 Complaint tab
+This specifies whether the complaint tab appears when a site is running
+nonfree JavaScript.
+
+@item Display notifications of JavaScript analysis
+This option enables an info bar of realtime JavaScript analysis.
+
+@item Complaint email subject
+Configure the default subject used in complaint emails.
+
+@item Complaint email body
+Configure the default body used in complaint emails.
+@end table
+
+@node JavaScript Detection
+@chapter JavaScript Detection
+@cindex javascript
+
+@itemize
+LibreJS considers JavaScript on a page nontrivial if any of the
+following are true:
+
+@item
+It makes an AJAX request or is loaded along with scripts that make
+an AJAX request,
+
+@item
+It loads external scripts dynamically or is loaded along with
+scripts that do,
+
+@item
+It defines functions or methods and either loads an external script
+(from HTML) or is loaded as one,
+
+@item
+It uses dynamic JavaScript constructs that are difficult to analyze
+without interpreting the program or is loaded along with scripts
+that use such constructs. These constructs are:
+@itemize
+@item
+Using the eval function
+@item
+Calling methods with the square bracket notation
+@item
+Using any other construct than a string literal with certain methods
+(@code{Obj.write}, @code{Obj.createElement}, @dots{}).
+@end itemize
+@end itemize
+
+In practice, the JavaScript code in your page may be found trivial by
+LibreJS if, as a whole:
+@itemize @bullet
+
+@item
+It does not define functions and it does not load external scripts
+(with the HTML src attribute in a @code{<script>} tag).
+
+@item
+It does not make AJAX calls.
+
+@item
+It does not load external scripts with dynamic constructs.
+
+@item
+It does not use constructs that may be used to do any of the above in
+a non-obvious way (use of the @code{eval()} method, use of square bracket
+method calls, use of concatenation with certain constructs or method
+calls, @dots{}).
+
+@end itemize
+
+However, in some instances, you may be required by LibreJS to add a
+stylized comment to JavaScript code that may be otherwise trivial.
+
+When an external file defines a function, it becomes available
+to all other external scripts. That is the case if another script
+defines a function that makes AJAX calls, when an external script
+loads other scripts dynamically (which in turn could also make AJAX
+calls, @dots{}), or when a script is written with constructs that may do
+any of these.
+
+For instance, if your page contains the following:
+@example
+<script src="jquery.js"></script>
+<script>
+$.doSomething();
+</script>
+@end example
+
+While @code{$.doSomething();} may seem trivial, you will nevertheless
+have to add a stylized license comment on your main HTML page because
+the external script (in this case jQuery) has been found to define
+methods that make AJAX calls. @code{$.doSomething()} might make an AJAX call,
+and LibreJS does not check for that.  The rule of thumb is that when you
+use a library or code that handles AJAX, JSON, JSONP, the loading of
+scripts dynamically, you should have license mentions for all your
+JavaScript files and for your main page regardless. In practice this is
+a case that happens very often with code that uses libraries.
+
+In practice also, the JavaScript code in an external file (an external
+@file{.js} file loaded on your page) may be found trivial if it does not
+define functions/methods.
+
+And in the same manner it will be considered nontrivial if AJAX calls,
+dynamic script loading, or non-obvious dynamic JavaScript constructs
+are used in another script.
+
+If your JavaScript code makes AJAX requests, it's important to get an
+accurate @dfn{Content-Type} in the response from the server. For
+example, if you're using JSON, set it to @code{application/json}.
+This is because LibreJS alters the content of @code{text/html}
+responses.
+
+@node Free Licenses Detection
+@chapter Free Licenses Detection
+@cindex freelicenses
+
+@section Detected Free Licenses
+
+In order for a file to be detected as free, the license notice should
+appear in a JavaScript file above all code, at the very top of the file.
+
+For inline JavaScript code inside @code{<script>} tags in HTML pages,
+the license notice should appear once per page as a comment inside a
+@code{<script>} tag, before all the code in that script. When the only
+inline JavaScript code is within element attributes (@code{onload},
+@code{onclick}), place the license notice in an otherwise empty
+@code{<script>} at the top of the page. This is sometimes needed when an
+external script performs AJAX calls or embeds scripts dynamically, and
+the only inline JavaScript is an event attribute making a method call,
+e.g.: @code{<body onload="methodCall('remote-data.xml');">}
+
+When people speak of the ``MIT license'' they mean either the X11 license
+or the Expat license.  Please see which license the code uses, and label
+it accordingly.
+
+Currently LibreJS checks for the following licenses:
+
+@itemize @bullet
+
+@item
+Creative Commons CC0 1.0 Universal
+@itemize @bullet
+@item
+Identifier: @samp{CC0-1.0}
+@item
+URL: @url{http://creativecommons.org/publicdomain/zero/1.0/legalcode}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt}
+@end itemize
+
+@item
+Public Domain
+@itemize @bullet
+@item
+Public domain is not a license (see
+@url{https://www.gnu.org/licenses/license-list.html#PublicDomain}). If
+you want to release your work to the public domain, the FSF recommends
+using CC0.
+@item
+Magnet Link: @indicateurl{magnet:?xt=urn:btih:e95b018ef3580986a04669f1b5879592219e2a7a&dn=public-domain.txt}
+@end itemize
+
+@item
+GNU General Public License (GPL) version 2
+@itemize @bullet
+@item
+Identifier: @samp{GNU-GPL-2.0}
+@item
+URL: @url{http://www.gnu.org/licenses/gpl-2.0.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt}
+@end itemize
+
+@item
+GNU General Public License (GPL) version 3
+@itemize @bullet
+@item
+Identifier: @samp{GNU-GPL-3.0}
+@item
+URL: @url{http://www.gnu.org/licenses/gpl-3.0.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:1f739d935676111cfff4b4693e3816e664797050&dn=gpl-3.0.txt}
+@end itemize
+
+@item
+Apache License, Version 2.0
+@itemize @bullet
+@item
+Identifier: @samp{Apache-2.0}
+@item
+URL: @url{http://www.apache.org/licenses/LICENSE-2.0}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:8e4f440f4c65981c5bf93c76d35135ba5064d8b7&dn=apache-2.0.txt}
+@end itemize
+
+@item
+GNU Lesser General Public License, version 2.1
+@itemize @bullet
+@item
+Identifier: @samp{GNU-LGPL-2.1}
+@item
+URL: @url{http://www.gnu.org/licenses/lgpl-2.1.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:5de60da917303dbfad4f93fb1b985ced5a89eac2&dn=lgpl-2.1.txt}
+@end itemize
+
+@item
+GNU Lesser General Public License, version 3
+@itemize @bullet
+@item
+Identifier: @samp{GNU-LGPL-3.0}
+@item
+URL: @url{http://www.gnu.org/licenses/lgpl-3.0.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:0ef1b8170b3b615170ff270def6427c317705f85&dn=lgpl-3.0.txt}
+@end itemize
+
+@item
+GNU Affero General Public License, version 3
+@itemize @bullet
+@item
+Identifier: @samp{GNU-AGPL-3.0}
+@item
+URL: @url{http://www.gnu.org/licenses/agpl-3.0.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:0b31508aeb0634b347b8270c7bee4d411b5d4109&dn=agpl-3.0.txt}
+@end itemize
+
+@item
+Boost Software License
+@itemize @bullet
+@item
+URL: @url{http://www.boost.org/LICENSE_1_0.txt}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:89a97c535628232f2f3888c2b7b8ffd4c078cec0&dn=Boost-1.0.txt}
+@end itemize
+
+@item
+BSD 3-Clause License
+@itemize @bullet
+@item
+URL: @url{http://opensource.org/licenses/BSD-3-Clause}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:c80d50af7d3db9be66a4d0a86db0286e4fd33292&dn=bsd-3-clause.txt}
+@end itemize
+
+@item
+Eclipse Public License 1.0
+@itemize @bullet
+@item
+Identifier: @samp{EPL-1.0}
+@item
+URL: @url{http://www.eclipse.org/legal/epl-v10.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:4c6a2ad0018cd461e9b0fc44e1b340d2c1828b22&dn=epl-1.0.txt}
+@end itemize
+
+@item
+Mozilla Public License 2.0
+@itemize @bullet
+@item
+Identifier: @samp{MPL-2.0}
+@item
+URL: @url{http://www.mozilla.org/MPL/2.0}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:3877d6d54b3accd4bc32f8a48bf32ebc0901502a&dn=mpl-2.0.txt}
+@end itemize
+
+@item
+Expat License (sometimes called the MIT license)
+@itemize @bullet
+@item
+Identifier: @samp{Expat}
+@item
+URL: @url{http://www.jclark.com/xml/copying.txt}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt}
+@end itemize
+
+@item
+X11 License
+@itemize @bullet
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:5305d91886084f776adcf57509a648432709a7c7&dn=x11.txt}
+@end itemize
+
+@item
+XFree86 License
+@itemize @bullet
+@item
+Identifier: @samp{Modified-BSD}
+@item
+URLs:
+@url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3}
+@url{http://www.xfree86.org/current/LICENSE4.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:12f2ec9e8de2a3b0002a33d518d6010cc8ab2ae9&dn=xfree86.txt}
+@end itemize
+
+@item
+FreeBSD License
+@itemize @bullet
+@item
+URL: @url{http://www.freebsd.org/copyright/freebsd-license.html}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:87f119ba0b429ba17a44b4bffcab33165ebdacc0&dn=freebsd.txt}
+@end itemize
+
+@item
+The ISC License
+@itemize @bullet
+@item
+URL: @url{https://www.isc.org/downloads/software-support-policy/isc-license/}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:b8999bbaf509c08d127678643c515b9ab0836bae&dn=ISC.txt}
+@end itemize
+
+@item
+Artistic License 2.0
+@itemize @bullet
+@item
+URL: @url{http://www.perlfoundation.org/artistic_license_2_0}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:54fd2283f9dbdf29466d2df1a98bf8f65cafe314&dn=artistic-2.0.txt}
+@end itemize
+
+@item
+CPAL 1.0
+@itemize @bullet
+@item
+Identifier: @samp{CPAL-1.0}
+@item
+URL: @url{http://opensource.org/licenses/cpal_1.0}
+@item
+Magnet link: @indicateurl{magnet:?xt=urn:btih:84143bc45939fc8fa42921d619a95462c2031c5c&dn=cpal-1.0.txt}
+@end itemize
+
+@end itemize
+
+@section Undetected Free Licenses
+If you are using a free license that isn't detected by LibreJS and isn't
+listed in the previous section, please send a message to
+@email{bug-librejs@@gnu.org} regarding this license, where code released under
+this license can be found, and where to find the license text and
+information.
+
+Many free licenses are listed in this page:
+@url{http://www.gnu.org/licenses/license-list.html}
+
+
+@node Setting Your JavaScript Free
+@chapter Setting Your JavaScript Free
+
+The first step is releasing your JavaScript under a free license. If
+you are already using a free library, or you're not using any
+third-party libraries, it might only take a few minutes.
+
+All JavaScript code on a web page (inline, on-page, and external) shares
+a common scope. Thus, code is generally either rejected or accepted as a
+whole by LibreJS. If some JavaScript code is found to be nontrivial and
+nonfree, then most of the time, all the the rest is discarded as well.
+
+On your website, take a look at your HTML source. You can identify
+distinct pieces of JavaScript that might be free and some other that are
+nonfree.
+
+@emph{Tip}: By running LibreJS on your page, you will get a list of all the
+JavaScript that was blocked. This gives you an overview of the
+JavaScript in your page.
+
+Imagine a page that contains several pieces of JavaScript from various
+sources:
+@itemize @bullet
+@item
+On top, within the @code{<head>} tag, it includes jQuery
+
+@item
+Then, some JavaScript code that you have written
+
+@item
+At the bottom, a JavaScript-based Facebook widget
+
+@item
+Also, there's some analytics tracking code
+@end itemize
+
+
+@table @dfn
+@item JavaScript that is already free
+First, you must ensure that the library is free. If the file contains
+a copyright and a license notice, you won't need to look any further.
+But if there's no mention of the license, or if it's too brief, you'll
+have to look for a COPYING or LICENSE file within the original library's
+source package, or on the library's official website.
+
+@item Your own JavaScript
+The free license given to your code should be compatible with the rest
+of the JavaScript on a page. A good way to check is to read up on
+them: @url{http://www.gnu.org/licenses/license-list.html}
+
+@item Nonfree JavaScript
+This might be the case with an analytics tracker, social media
+widgets, and code that runs ads. Removing these pieces of code from your
+site is required to have the rest accepted as free. There are
+often alternatives to nonfree libraries or to third-party services:
+
+@itemize @bullet
+
+@item
+If you have used nonfree third-party code as the base to write your own
+code, try to find a free alternative.
+
+@item
+If you're using a third-party service such as an analytics service,
+replace it with a free alternative like Piwik.
+
+@item
+If you can't find free JavaScript that has already been developed,
+write it yourself! Who knows, your own solution might be the start of
+a brilliant project!
+@end itemize
+
+@end table
+
+@section JavaScript Web Labels
+One way to make your website work with LibreJS is by defining a
+JavaScript Web Labels table.
+
+A JavaScript Web Labels table is informative to both site visitors and
+the LibreJS program. You make a Web Labels table on a new HTML page
+that's linked to from your main page. The table lists each of your
+site's JavaScript files, that file's corresponding human-readable source
+file, and the canonical url of its free license.
+
+When using a JavaScript Web Labels table for your own files, it's
+important to put a copying permission statement at the top of each source
+file listed in right-most column of the Web Labels table. For info on how
+properly release your code as free software, see
+@url{https://www.gnu.org/licenses/gpl-howto.html}. Future versions of
+LibreJS will require a copying permission statement or other license
+notice for source files listed in a Web Labels table.
+
+More information on JavaScript Web Labels is detailed here:
+@url{https://www.gnu.org/software/librejs/free-your-javascript.html#step3}
+and here:
+@url{https://www.gnu.org/licenses/javascript-labels.html}.
+
+@subsection Specifying multiple licenses for a single JavaScript file
+
+If you compile or concatenate your JavaScript into a single file, the
+source files you're combining may be released under different licenses.
+You can specify multiple licenses for the file in a JavaScript Web Labels
+table, like this:
+
+@verbatim
+<table id="jslicense-labels1">
+    <tr>
+        <td><a href="all.min.js">all.min.js</a></td>
+        <td>
+            <a href="http://www.gnu.org/licenses/gpl-3.0.html"
+                >GNU-GPL-3.0-or-later</a>
+            <br />
+            <a href="http://www.apache.org/licenses/LICENSE-2.0"
+                >Apache-2.0</a>
+        </td>
+        <td>
+            <a href="gpl-script.js">gpl-script.js</a>
+            <br />
+            <a href="apache-script.js">apache-script.js</a>
+        </td>
+    </tr>
+</table>
+@end verbatim
+
+The @code{<br />} tags just make the table more understandable when
+looking at the rendered version of it on the license page. They aren't
+required by LibreJS.
+
+If all the licenses contained in the second column are recognized by
+LibreJS to be free licenses, then LibreJS will allow the file in the
+first column to be run.
+
+@section Adding a stylized comment in your JavaScript files and on your page
+See a ``Convention for releasing free JavaScript programs'' in the
+JavaScript Trap @url{http://www.gnu.org/philosophy/javascript-trap.html}
+
+Adding this notice will ensure LibreJS will find the JavaScript file to
+be free. The @code{@@licstart} and @code{@@licend} lines at the
+beginning and end of the stylized comment are necessary to make a clear
+statement that the _entire code_ in the file is free. This means that
+you must ensure that no nonfree code was carelessly appended at the end
+of the file.
+
+In the main HTML page, the license notice covers JavaScript contained
+in all @code{<script>} tags with on-page code and the inline
+JavaScript (in event attributes such as onload, onclick, etc, @dots{}).
+Since external files have their own stylized comment, they are
+not covered by the notice in the main HTML page. Make sure to identify
+all the licenses available. LibreJS will only ensure it matches a
+notice of an allowed license once, so the order does not matter, but
+the responsibility is on you to make sure all code is under the free
+licenses mentioned between @code{@@licstart} and @code{@@licend}.
+
+You should make @emph{only} one @code{@@licstart} @code{@@licend}
+comment in your page, since it pertains to the entire code on page
+across all @code{<script>} tags and inline html attributes.
+
+@unnumbered
+When you use the JavaScript Web Labels method, you should still include a
+license notice at the top of each of your source files. This ensures that
+if someone copies the file and uses it for something else, the license
+remains intact.
+    
+For more info on making your JavaScript LibreJS-compliant, see this web
+page: @url{https://www.gnu.org/software/librejs/free-your-javascript.html}
+
+@node Installation Requirements
+@appendix Installation Requirements
+
+
+@appendixsec Mozilla Browser
+
+You will need one of the many flavors of the Mozilla browser to use
+LibreJS. It can be installed on the following:
+
+GNU IceCat,  Mozilla Firefox, Trisquel Abrowser, Debian Iceweasel.
+
+LibreJS works on these browsers starting from version 29. We
+recommend that you use the latest version of your Mozilla browser.
+LibreJS has been tested extensively on multiple GNU/Linux distributions,
+but it is compatible any operating system as long as you're using a
+compatible Mozilla browser.
+
+@appendixsec Mozilla's Add-on SDK
+LibreJS uses the Mozilla Add-on SDK (Software Development Kit), a
+set of APIs and tools to create add-ons for Mozilla browsers.
+
+You do not need the Add-on SDK to use LibreJS xpi file or to install it
+using the packaged version, but it is required in order to package the
+LibreJS source code into an xpi file using @code{make}. If you would like
+to run the tests for LibreJS or make changes to the source files, you
+will need the Add-on SDK as well. For the ``make'' command to work
+properly, you must have the @code{cfx} command available on your system
+from the command line.
+
+The latest tarball for the Add-on SDK is available at:
+
+@url{https://ftp.mozilla.org/pub/mozilla.org/labs/jetpack/jetpack-sdk-latest.tar.gz}
+
+Instructions on how to get it working are available here:
+
+@url{https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/tutorials/installation.html}
+
+In order to use @code{make} with LibreJS source, however, it is ideal to
+have @code{cfx} available at all times and for all users.
+
+An easy way to do this is to extract the contents of the tarball and to
+place the files inside @file{/usr/lib/addon-sdk} and then creating a
+symbolic link in @file{/usr/bin}, as follows:
+
+@example 
+sudo ln -s /usr/lib/addon-sdk/bin/cfx /usr/bin/cfx
+@end example
+
+The @code{cfx} command will then be available to all users.
+
+The Add-on SDK is released under the Mozilla Public License 2.0.
+
+@node LibreJS Internals
+@appendix LibreJS Internals
+
+LibreJS intercepts HTTP responses and rewrites their contents after
+analyzing JavaScript within them. It does not remove script nodes and
+attributes from the page, but instead ``deactivates'' them by modifying
+the @code{type} and @code{src} attributes on script elements and by
+moving the contents of inline JavaScript attributes such as onClick
+into harmless attributes.
+
+LibreJS detects the most common cases using the HTTP response method
+described above, but in extremely rare cases, or when running code
+locally, LibreJS cannot detect JavaScript during the response stage.
+
+To remedy this issue, and as a final safeguard, LibreJS takes a look
+at the scripts that are about to be executed while the browser engine is
+parsing the page. If the script is not found in a list of accepted
+scripts populated earlier, the execution will be prevented. This is to
+ensure content types that are not regular HTML (binhex with HTML in it,
+@dots{}) and JavaScript do not fall through the cracks and get executed.
+
+@node Tests
+@appendix Tests
+
+
+In order to better understand how LibreJS works, you can try to visit
+these pages with LibreJS installed and enabled and see how they are
+being processed:
+
+@itemize @bullet
+
+@item
+@url{http://lduros.net/assets/librejs/tests/trivial-inline-trivial-external/}
+This page contains trivial on-page JavaScript code, and an external
+script that contains trivial JavaScript code.  Therefore, all JavaScript
+is being executed.
+
+
+@item
+@url{http://lduros.net/assets/librejs/tests/trivial-inline-nontrivial-external/}
+The on-page script here is trivial and uses a built-in method, but the
+external script in this page is nontrivial (defines a function.)  The
+external script is blocked, the inline script is executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/nontrivial-inline-trivial-external/}
+This page contains nontrivial code on page, and trivial code in its
+external page.  All JavaScript is @emph{removed} from the page, and the
+external script is never analyzed, since the nontrivial conditions are
+already met in the page.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/free-inline-free-external/}
+This page contains free on-page (GPL 3) JavaScript, and free external
+Javascript. Therefore all JavaScript is being executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/free-inline-nonfree-nontrivial-external/}
+This page contains free on-page JavaScript. The external script contains
+nonfree nontrivial JavaScript (AJAX request). The free code that is
+inline is executed, but the external file is blocked.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/intrinsec-event/} This page
+contains trivial on-page code, with an intrinsic event in an html
+attribute (onload).  All JavaScript is being executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/trivial-inline-free-external-defines-function/}
+This page contains on-page trivial JavaScript (only makes a window alert
+and loads an external script using the html <script> tag with the src
+attribute. The external script is free (GPL v3), and since it is only
+nontrivial because it defines a function, the on-page trivial code is
+allowed to use it.  All JavaScript is being executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/trivial-inline-free-external-writes-script/}
+This page contains trivial on-page JavaScript code, and loads an
+external script that is free. Since no function is defined, the external
+script is being analyzed. The external script is free. Trivial here is
+not allowed because the external script, although free, writes a
+script. The inline trivial script should also have a free license notice
+for it to be interpreted.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/shelltypist/demo/real-life-example-with-jquery-free.html}
+This is a real-life example of a small jQuery plugin. The on-page
+JavaScript code has a free license. The jQuery external file has a free
+licensed. The shelltypist.js file has a free license as well. All
+licenses are defined between @code{@@licstart} and @code{@@licend}. All
+JavaScript is executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/shelltypist/demo/same-page-without-free-license.html}
+This is the same page than the previous example, except it does not have
+a free license for the main HTML page on-page script. While the actual
+code there is trivial, since jQuery defines methods that make use of
+AJAX, trivial code is not allowed, and no JavaScript is executed.
+
+@item
+@url{http://lduros.net/assets/librejs/tests/test-labels/} This page
+contains JavaScript (jQuery minified) that does not have proper license
+information in the file, as it has no @code{@@licstart} @code{@@licend}
+comment. It would be considered nonfree, however, the page itself uses
+the JavaScript Web Labels method. On the page itself, you will find a
+link labeled ``JavaScript License Information'', which leads to a page
+that contains a properly formatted table with the required data on the
+external JavaScript file. LibreJS visits this link and determines the
+version of jQuery linked from the original page is the one listed there,
+and flags it as free. All JavaScript is executed (and the title should
+turn green.)
+
+@end itemize
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+
+@bye
-- 
cgit v1.2.3