1 files changed, 57 insertions, 35 deletions
diff --git a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
index 63b647e..c0a5275 100644
--- a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
+++ b/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
@@ -20,84 +20,106 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "doc_base.html.jinja" %}
 
-{% block title %}{{ _('doc.script_blocking.title') }}{% endblock %}
+{% block title %} Script blocking {% endblock %}
 
 {% block main %}
-  {{ big_heading(_('doc.script_blocking.h_big')) }}
+  {{ big_heading('Script blocking in Haketilo') }}
 
   {% call section() %}
     {% call paragraph() %}
-      {{ _('doc.script_blocking.intro') }}
+      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() %}
-      {% set fmt = _('doc.script_blocking.html.see_here_for_{packages_link}') %}
-      {% set link_text = _('doc.script_blocking.see_here_for.packages_link_text') %}
-      {% set link = doc_page_link(link_text|e, 'packages') %}
-      {{ fmt.format(packages_link=link)|safe }}
+      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(_('doc.script_blocking.h_medium.configuring')) }}
+    {{ medium_heading('Configuring script blocking') }}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.script_blocking.configuring.html.rules_{rules_link}_{patterns_link}_{policy_link}') %}
-      {% set rules_link_text = _('doc.script_blocking.configuring.rules.rules_link_text') %}
-      {% set rules_link = hkt_link(rules_link_text|e, 'rules.rules') %}
-      {% set patterns_link_text = _('doc.script_blocking.configuring.rules.patterns_link_text') %}
-      {% set patterns_link = doc_page_link(patterns_link_text|e, 'url_patterns') %}
-      {% set policy_link_text = _('doc.script_blocking.configuring.rules.policy_link_text') %}
-      {% set policy_link = doc_page_link(policy_link_text|e, 'policy_selection') %}
+      User can
       {{
-        fmt.format(
-            rules_link    = rules_link,
-            patterns_link = patterns_link,
-            policy_link   = policy_link
-        )|safe
+        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() %}
-      {{ _('doc.script_blocking.configuring.html.rules_example')|safe }}
+      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() %}
-      {% set fmt = _('doc.script_blocking.configuring.html.fallback_{settings_link}') %}
-      {% set link_text = _('doc.script_blocking.configuring.html.fallback.settings_link_text') %}
-      {% set link = hkt_link(link_text|e, 'home.home') %}
-      {{ fmt.format(settings_link=link)|safe }}
+      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(_('doc.script_blocking.medium_h.with_other_tools')) }}
+    {{ medium_heading('Use with other script-blocking tools') }}
 
     {% call paragraph() %}
-      {{ _('doc.script_blocking.with_other_tools.haketilo_independently') }}
+      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() %}
-      {% set fmt = _('doc.script_blocking.with_other_tools.html.breakages_{popup_link}') %}
-      {% set link_text = _('doc.script_blocking.with_other_tools.breakages.popup_link_text') %}
-      {% set link = doc_page_link(link_text|e, 'popup') %}
-      {{ fmt.format(popup_link=link)|safe }}
+      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(_('doc.script_blocking.medium_h.technical')) }}
+    {{ medium_heading('Technical details') }}
 
     {% call paragraph() %}
-      {{ _('doc.script_blocking.technical.general') }}
+      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() %}
-      {{ _('doc.script_blocking.technical.means_no_reports') }}
+      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() %}
-      {{ _('doc.script_blocking.technical.popup_script') }}
+      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 %}