1 files changed, 125 insertions, 0 deletions
diff --git a/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja
new file mode 100644
index 0000000..c0a5275
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja
@@ -0,0 +1,125 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing how Haketilo blocks scripts.
+
+This file is part of Hydrilla&Haketilo.
+
+Copyright (C) 2022 Wojtek Kosior
+
+Dual licensed under
+* GNU General Public License v3.0 or later and
+* Creative Commons Attribution Share Alike 4.0 International.
+
+You can choose to use either of these licenses or both.
+
+
+I, Wojtek Kosior, thereby promise not to sue for violation of this
+file's licenses. Although I request that you do not make use of this
+code in a proprietary work, I am not going to enforce this in court.
+#}
+{% extends "doc_base.html.jinja" %}
+
+{% block title %} Script blocking {% endblock %}
+
+{% block main %}
+  {{ big_heading('Script blocking in Haketilo') }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      Modern web browsers allow sites to execute software on users'
+      devices. This software is usually written in a language called JavaScript
+      and abbreviated as JS. It can serve various purposes - from small
+      enhancements to deployment of heavy applications inside the
+      browser. Because Haketilo aims to give users control over their web
+      browsing, one of its supported features is blocking of JavaScript
+      execution on per-page and per-site basis.
+    {% endcall %}
+
+    {% call paragraph() %}
+      Besides the casual script-blocking discussed here, Haketilo also blocks
+      page's JavaScript when injecting the user-specified
+      {{ doc_page_link('script payloads', 'packages') }}. That functionality is
+      described on its own documentation page.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Configuring script blocking') }}
+
+    {% call paragraph() %}
+      User can
+      {{
+        hkt_link('define script-blocking and -allowing rules', 'rules.rules')
+      }}
+      using {{ doc_page_link('URL patterns', 'url_patterns') }}. Each such rule
+      tells Haketilo to either block or allow scripts on pages matched by its
+      pattern. Rules with more specific patterns can override those with less
+      specific ones as described on the
+      {{ doc_page_link('policy selection page', 'policy_selection') }}.
+    {% endcall %}
+
+    {% call paragraph() %}
+      As an example, if we want all scripts on english Wikipedia pages to be
+      blocked, we can add a blocking rule with
+      pattern <code>https://en.wikipedia.org/***</code>. If we then wanted to
+      make an exception just for the "List of emoticons" page, we could create
+      an additional allowing rule with
+      <code>https://en.wikipedia.org/wiki/List_of_emoticons</code> as its
+      pattern. It would take effect on that page while all the other english
+      Wikipedia pages would still have their scripts blocked.
+    {% endcall %}
+
+    {% call paragraph() %}
+      It is also possible to configure whether scripts should be blocked by
+      dafault on pages where no explicit rule and no payload is used. The
+      relevant option can be found on Haketilo
+      {{ hkt_link('settings page', 'home.home') }}.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Use with other script-blocking tools') }}
+
+    {% call paragraph() %}
+      Various browsers and browser extension can also be configured to block
+      JavaScript. Haketilo works independently of those tools. If the user
+      desires to have scripts on certain page to execute normally, both Haketilo
+      and other tools must be configured to allow that.
+    {% endcall %}
+
+    {% call paragraph() %}
+      Unlike most similar tools, Haketilo operates outside the web browser. As a
+      result, it is relatively unlikely for Haketilo to cause these to
+      malfunction. At the same time, it is relatively easy to have another
+      script blocker break some Haketilo functionality (e.g. its
+      {{ doc_page_link('popup', 'popup') }}).
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Technical details') }}
+
+    {% call paragraph() %}
+      From technical point of view, Haketilo, as of version 3.0, blocks
+      JavaScript by altering the Content-Security-Policy (abbreviated CSP)
+      headers in HTTP responses. The original CSP directives sent by site are
+      retained, with exception of those which would result in CSP violation
+      reports being sent. Haketilo's own script-blocking directives are then
+      added to produce the final CSP which user's web browser eventually sees.
+    {% endcall %}
+
+    {% call paragraph() %}
+      The above means that neither the scripts that would be blocked by page's
+      own rules nor those that are blocked by Haketilo are going to cause CSP
+      reports to be sent.
+    {% endcall %}
+
+    {% call paragraph() %}
+      In addition, even when a page has JavaScript nominally blocked, Haketilo
+      3.0 may nevertheless inject into it its own script responsible for making
+      the popup available. The CSP is then modified appropriately to allow only
+      that script to run.
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}