5 files changed, 349 insertions, 139 deletions

diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja
new file mode 100644
index 0000000..a9bedc5
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/packages.html.jinja
@@ -0,0 +1,41 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing the concept of packages in Haketilo.
+
+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 %} Packages {% endblock %}
+
+{% block main %}
+  {{ big_heading('Packages in Haketilo') }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      blah blah
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('blah blah') }}
+
+    {% call paragraph() %}
+      more blah blah...
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
index 4d9b251..687d2bd 100644
--- a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
+++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
@@ -20,71 +20,90 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "doc_base.html.jinja" %}
 
-{% block title %}{{ _('doc.policy_selection.title') }}{% endblock %}
+{% block title %} Policy selection {% endblock %}
 
 {% block main %}
-  {{ big_heading(_('doc.policy_selection.h_big')) }}
+  {{ big_heading('Page policy selection') }}
 
   {% call section() %}
     {% call paragraph() %}
-      {{ _('doc.policy_selection.intro') }}
+      When a web page is opened, Haketilo is capable of either
       {% call unordered_list() %}
         {% call list_entry() %}
-          {{ _('doc.policy_selection.enabled_payload_case') }}
+          blocking page's own scripts and
+          {{ doc_page_link('injecting payload', 'packages') }}
+          configured by the user,
         {% endcall %}
         {% call list_entry() %}
-          {{ _('doc.policy_selection.auto_payload_case') }}
+          blocking page's own scripts and injecting an automatically-chosen
+          payload that is usable with the page,
         {% endcall %}
         {% call list_entry() %}
-          {{ _('doc.policy_selection.ask_payload_case') }}
+          presenting a dialog asking whether to enable an automatically-chosen
+          payload that is usable with the page,
         {% endcall %}
         {% call list_entry() %}
-          {% set fmt = _('doc.policy_selection.block_js_case_{blocking_link}') %}
-          {% set link_text = _('doc.policy_selection.html.block_js_case.blocking_link_text') %}
-          {% set link = doc_page_link(link_text|e, 'script_blocking') %}
-          {{ fmt.format(blocking_link=link)|safe }}
+          {{ doc_page_link('blocking', 'script_blocking') }} page's own scripts
+          or
         {% endcall %}
         {% call list_entry() %}
-          {{ _('doc.policy_selection.allow_js_case') }}
+          allowing page's own scripts to execute normally (i.e. not modifying
+          the page in any meaningful way).
         {% endcall %}
       {% endcall %}
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.policy_selection.h_medium.precedence')) }}
+    {{ medium_heading('Policy precedence') }}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.policy_selection.html.precedence_general_{patterns_link}') %}
-      {% set link_text = _('doc.policy_selection.precedence_general.patterns_link_text') %}
-      {% set link = doc_page_link(link_text|e, 'url_patterns') %}
-      {{ fmt.format(patterns_link=link)|safe }}
+      User configures Haketilo's behavior by defining script-blocking and
+      -allowing rules and by adding and enabling packages. Each rule and each
+      package payload has a {{ doc_page_link('URL pattern', 'url_patterns') }}.
+      This pattern determines which pages the policy is compatible with.
+      Patterns also have well-defined specificity. When multiple rules and
+      packages are combatible with given page's URL, the one with the most
+      specific pattern "wins". In case of a tie, payload injection is assumed to
+      take precedence over rule application.
     {% endcall %}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.policy_selection.html.precedence_nonenabled_{settings_link}') %}
-      {% set link_text = _('doc.policy_selection.precedence_nonenabled.settings_link_text') %}
-      {% set link = hkt_link(link_text|e, 'home.home') %}
-      {{ fmt.format(settings_link=link)|safe }}
+      In the absence of suitable rules and enabled packages, Haketilo may
+      consider non-enabled packages that are suitable for use on the
+      currently-visited site. It will either inject package payload
+      automatically, ask the user whether to enable the package or ignore it
+      completely. The user can switch between these 3 behaviors on the Haketilo
+      {{ hkt_link('settings page', 'home.home') }}. Packages that were
+      explicitly marked as disabled will always be ignored. Pattern specificity
+      is also taken into account in case of multiple packages.
     {% endcall %}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.policy_selection.html.precedence_fallback_{settings_link}') %}
-      {% set link_text = _('doc.policy_selection.precedence_fallback.settings_link_text') %}
-      {% set link = hkt_link(link_text|e, 'home.home') %}
-      {{ fmt.format(settings_link=link)|safe }}
+      When absolutely no explicit policy appears suitable for given page,
+      Haketilo will apply its default script handling behavrior. Whether
+      JavaScript is blocked or allowed by default is also determined by user's
+      choice on the {{ hkt_link('settings page', 'home.home') }}.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }}
+    {{ medium_heading('Special cases') }}
 
     {% call paragraph() %}
-      {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }}
+      The sites served by Haketilo itself are exempt from all policies. These
+      are <code>http://hkt.mitm.it</code>, <code>https://hkt.mitm.it</code>
+      and <code>http://mitm.it</code>. Additionally, if Haketilo experiences an
+      internal error (e.g. because it could not parse current URL as sent in by
+      the browser), it will try to block page's JavaScript as a security
+      measure.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.policy_selection.special_cases.internal_policies') }}
+      Internally, Haketilo also has a special high-priority policy for serving
+      files used by payloads and for making its APIs accessible to payload
+      scripts. This is, however, an implementation detail and casual users need
+      not care about it nor understand these nuances.
     {% endcall %}
   {% endcall %}
 {% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/popup.html.jinja b/src/hydrilla/proxy/self_doc/popup.html.jinja
index f1a31e9..a5ad909 100644
--- a/src/hydrilla/proxy/self_doc/popup.html.jinja
+++ b/src/hydrilla/proxy/self_doc/popup.html.jinja
@@ -20,111 +20,138 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "doc_base.html.jinja" %}
 
-{% block title %}{{ _('doc.popup.title') }}{% endblock %}
+{% block title %} Popup {% endblock %}
 
 {% block main %}
-  {{ big_heading(_('doc.popup.h_big')) }}
+  {{ big_heading('Haketilo popup') }}
 
   {% call section() %}
     {% call paragraph() %}
-      {{ _('doc.popup.intro') }}
+      Taking inspiration from user interface features of browser extensions,
+      Haketilo also offers a popup window for quick interaction with the
+      user. For technical reasons, the popup is presented as part of the web
+      page and behaves slightly differently from those some users might have
+      found in similar tools.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.popup.h_medium.operating')) }}
+    {{ medium_heading('Operating') }}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.popup.operating.html.opening_{blocking_link}_{packages_link}') %}
-      {% set blocking_link_text = _('doc.popup.operating.opening.blocking_link_text') %}
-      {% set blocking_link = doc_page_link(blocking_link_text|e, 'script_blocking') %}
-      {% set packages_link_text = _('doc.popup.operating.opening.packages_link_text') %}
-      {% set packages_link = doc_page_link(packages_link_text|e, 'packages') %}
-      {{
-        fmt.format(
-            blocking_link = blocking_link,
-            packages_link = packages_link
-        )|safe
-      }}
+      The popup dialog can be opened by typing big letters "HKT" anywhere on the
+      page. It then presents some basic information about the handling of
+      current URL. It also allows the user quickly define new
+      {{ doc_page_link('rules', 'script_blocking') }} or
+      {{ doc_page_link('payloads', 'packages') }} for it. As of Haketilo 3.0,
+      however, the actual configuration is not performed from the popup itself
+      but rather a relevant Haketilo rule/payload definition page is opened in a
+      new tab.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.popup.operating.html.closing')|safe }}
+      The dialog can be closed by clicking anywhere on the darker area around
+      it. It can then be reopened by typing "HKT" again.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.popup.h_medium.enabling')) }}
+    {{ medium_heading('Enabling/disabling') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.enabling.html.intro')|safe }}
+      Popup is unavailable by default on Haketilo special sites including
+      <code>https://hkt.mitm.it</code>. It can also be disabled independently on
     {% endcall %}
 
     {% call unordered_list() %}
       {% call list_entry() %}
-        {{ _('doc.popup.enabling.js_allowed_case') }}
+        pages with JS allowed,
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.popup.enabling.js_blocked_case') }}
+        pages with JS blocked and
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.popup.enabling.payload_case') }}
+        pages with script payload injected.
       {% endcall %}
     {% endcall %}
 
     {% call paragraph() %}
-      {% set fmt = _('doc.popup.enabling.html.rest_{settings_link}') %}
-      {% set link_text = _('doc.popup.enabling.html.rest.settings_link_text') %}
-      {% set link = hkt_link(link_text|e, 'home.home') %}
-      {{ fmt.format(settings_link=link)|safe }}
+      This can be configured on the {{ hkt_link('setings page', 'home.home') }}
+      and might be useful to users who are careful about fingerprinting.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.popup.h_medium.fingerprinting')) }}
+    {{ medium_heading('Fingerprinting considerations') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.fingerprinting_intro') }}
+      To make the popup available, Haketilo has to inject an additional script
+      to all pages. That makes it easy for pages to determine with certainty
+      that given user is running Haketilo. This has implications for privacy and
+      may also be used by a hostile site to selectively cause annoyance to
+      Haketilo users.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.popup.fingerprinting_more') }}
+      The above problems would be present regardless on pages with
+      Haketilo-injected payloads. I.e. in many cases a site could theoretically
+      find out the user is not accessing it in a normal way. However, the popup
+      also increases fingerprintability when no payload is in use and especially
+      on pages with JavaScript allowed. For this reason, the presence of popup
+      on pages has been made configurable.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.popup.fingerprinting_more_more') }}
+      It is also worth noting that as of version 3.0 Haketilo does not make
+      guarantees about the browser fingerprint. Despite best efforts, there are
+      still other aspects that might make a Haketilo user distinguishable to a
+      website even when popup is disabled.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.popup.h_medium.other_caveats')) }}
+    {{ medium_heading('Other caveats') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.other_caveats.intro') }}
+      Some other potential issues related to the popup are described below.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.popup.h_small.site_interference')) }}
+    {{ small_heading('Interference with the site') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.site_interference.text') }}
+      The popup gets injected by Haketilo into the actual web page. Although
+      care was taken to make accidental breakage unlikely, it might still happen
+      under some specific conditions.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.popup.h_small.content_blockers_interference')) }}
+    {{ small_heading('Interference with other script-blocking tools') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.content_blockers_interference.text') }}
+      The popup is driven by a piece of JavaScript code injected by Haketilo to
+      pages. Haketilo by itself makes sure neither the policies specified by the
+      page nor its own script-blocking mechanisms interfere with this particular
+      piece. In spite of that, a browser extension or web browser's own settings
+      might prevent the popup script from executing, making the dialog
+      unavailable.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.popup.h_small.url_mismatch')) }}
+    {{ small_heading('URL mismatch') }}
 
     {% call paragraph() %}
-      {{ _('doc.popup.url_mismatch.text')|safe }}
+      Sometimes a page might change parts of its address visible in browser's
+      URL bar. E.g. after opening <code>https://entraide.chatons.org/</code> in
+      the browser we might see <code>https://entraide.chatons.org/en/</code> as
+      the current address even though no reload happened. In addition, some
+      browsers hide URL's traling dash ("/") from the user. Regardless of that,
+      Haketilo's popup always presents the original URL under which the current
+      page was served. Although this the intended behavior, it might cause
+      confusion and therefore has been documented here.
     {% endcall %}
   {% endcall %}
 {% endblock main %}
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 %}
diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
index 7d2718f..f3415c5 100644
--- a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
+++ b/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
@@ -20,123 +20,210 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "doc_base.html.jinja" %}
 
-{% block title %}{{ _('doc.url_patterns.title') }}{% endblock %}
+{% block title %} URL patterns {% endblock %}
 
 {% block main %}
-  {{ big_heading(_('doc.url_patterns.h_big')) }}
+  {{ big_heading('Haketio URL patterns') }}
 
   {% call section() %}
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.intro')|safe }}
+      We want to be able to apply different rules and custom scripts for
+      different websites. However, merely specifying "do this for all documents
+      under <code>https://example.com</code>" is not enough. Single site's pages
+      might differ strongly and require different custom scripts to be
+      loaded. Always matching against a full URL like
+      <code>https://example.com/something/somethingelse</code> is also not
+      a good option. It doesn't allow us to properly handle a site that serves
+      similar pages for multiple values substituted for
+      <code>somethingelse</code>.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.url_patterns.h_medium.employed_solution')) }}
+    {{ medium_heading('Employed solution') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.wildcards_intro')|safe }}
+      Wildcards are being used to address the problem. Each payload and rule in
+      Haketilo has a URL pattern that specifies to which internet pages it
+      applies. A URL pattern can be as as simple as literal URL in which case it
+      only matches itself. It can also contain wildcards in the form of one or
+      more asterisks (<code>*</code>) that correspond to multiple possible
+      strings occurring in that place.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.wildcards_types_introduced')|safe }}
+      Wildcards can appear in URL's domain and path that follows it. These 2
+      types of wildcards are handled separately.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.url_patterns.h_small.domain_wildcards')) }}
+    {{ small_heading('Domain wildcards') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.domain_wildcards_intro')|safe }}
+      A domain wildcard takes the form of one, two or three asterisks occurring
+      in place of a single domain name segment at the beginning
+      (left). Depending on the number of asterisks, the meaning is as follows
     {% endcall %}
 
     {% call unordered_list() %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.domain_no_asterisks_example')|safe }}
+        no asterisks (e.g. <code>example.com</code>) - match domain name exactly
+        (e.g. <code>example.com</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.domain_one_asterisk_example')|safe }}
+        one asterisk (e.g. <code>*.example.com</code>) - match all domains
+        resulting from substituting <code>*</code> with a
+        <span class="bold">single</span> segment (e.g.
+        <code>banana.example.com</code> or <code>pineapple.example.com</code>
+        but <span class="bold">not</span> <code>pineapple.pen.example.com</code>
+        nor <code>example.com</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.domain_two_asterisks_example')|safe }}
+        two asterisks (e.g. <code>**.example.com</code>) - match all domains
+        resulting from substituting <code>**</code> with
+        <span class="bold">two or more</span> segments (e.g.
+        <code>monad.breakfast.example.com</code> or
+        <code>pure.monad.breakfast.example.com</code> but
+        <span class="bold">not</span> <code>cabalhell.example.com</code> nor
+        <code>example.com</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.domain_three_asterisks_example')|safe }}
+        three asterisks (e.g. <code>***.example.com</code>) - match all domains
+        resulting from substituting <code>***</code> with
+        <span class="bold">zero or more</span> segments (e.g.
+        <code>hello.parkmeter.example.com</code> or
+        <code>iliketrains.example.com</code> or <code>example.com</code>)
       {% endcall %}
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.url_patterns.h_small.path_wildcards')) }}
+    {{ small_heading('Path wildcards') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.path_wildcards_intro')|safe }}
+      A path wildcard takes the form of one, two or three asterisks occurring in
+      place of a single path segment at the end of path (right). Depending on
+      the number of asterisks, the meaning is as follows
     {% endcall %}
 
     {% call unordered_list() %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.path_no_asterisks_example')|safe }}
+        no asterisks (e.g. <code>/joke/clowns</code>) - match path exactly (e.g.
+        <code>/joke/clowns</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.path_one_asterisk_example')|safe }}
+        one asterisk (e.g. <code>/itscalled/*</code>) - match all paths
+        resulting from substituting <code>*</code> with a
+        <span class="bold">single</span> segment (e.g.
+        <code>/itscalled/gnulinux</code> or <code>/itscalled/glamp</code> but
+        <span class="bold">not</span> <code>/itscalled/</code> nor
+        <code>/itscalled/gnu/linux</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.path_two_asterisks_example')|safe }}
+        two asterisks (e.g. <code>/another/**</code>) - match all paths
+        resulting from substituting <code>**</code> with
+        <span class="bold">two or more</span> segments (e.g.
+        <code>/another/nsa/backdoor</code> or
+        <code>/another/best/programming/language</code> but
+        <span class="bold">not</span> <code>/another/apibreak</code> nor
+        <code>/another</code>)
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.html.path_three_asterisks_example')|safe }}
+        three asterisks (e.g. <code>/mail/dmarc/***</code>) - match all paths
+        resulting from substituting <code>***</code> with
+        <span class="bold">zero or more</span> segments (e.g.
+        <code>/mail/dmarc/spf</code>, <code>/mail/dmarc</code> or
+        <code>/mail/dmarc/dkim/failure</code> but
+        <span class="bold">not</span> <code>/mail/</code>)
       {% endcall %}
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.path_trailing_slash')|safe }}
+      If pattern ends <span class="bold">without</span> a trailing slash, it
+      mathes paths with any number of trailing slashes, including zero. If
+      pattern ends <span class="bold">with</span> a trailing slash, it only
+      mathes paths with one or more trailing slashes. For example,
+      <code>/itscalled/*</code> matches <code>/itscalled/gnulinux</code>,
+      <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code>
+      while <code>/itscalled/*/</code> only matches
+      <code>/itscalled/gnulinux/</code> and <code>/itscalled/gnulinux//</code>
+      out of those three.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.path_trailing_slash_priority')|safe }}
+      If two patterns only differ by the presence of a trailing slash,
+      pattern <span class="bold">with</span> a trailing slash is considered
+      <span class="bold">more specific</span>.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.path_literal_trailing_asterisks')|safe }}
+      Additionally, any path with literal trailing asterisks is matched by
+      itself, even if such pattern would otherwise be treated as wildcard
+      (e.g. <code>/gobacktoxul/**</code> matches <code>/gobacktoxul/**</code>).
+      This is likely to change in the future and would best not be relied upon.
+      Appending three additional asterisks to path pattern to represent literal
+      asterisks is being considered.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.url_patterns.h_small.protocol_wildcards')) }}
+    {{ small_heading('URL scheme wildcard') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.protocol_wildcards')|safe }}
+      <code>http://</code> and <code>https://</code> shemes in the URL are
+      matched exactly. However, starting with Haketilo 3.0, it is also possible
+      for scheme pseudo-wildcard of <code>http*://</code> to be used. Use of URL
+      pattern with this scheme is equivalent to the use of 2 separate patterns
+      starting with <code>http://</code> and <code>https://</code>,
+      respectively. For example, pattern <code>http*://example.com</code> shall
+      match both <code>https://example.com</code> and
+      <code>http://example.com</code>.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.protocol_wildcards_are_aliases')|safe }}
+      <code>http*://</code> may be considered not to be a true wildcard but
+      rather an alias for either of the other 2 values. As of Haketilo 3.0, the
+      speicificity of a URL pattern starting with <code>http*://</code> is
+      considered to be the same as that of the corresponding URL pattern
+      starting with <code>http://</code> or <code>https://</code>. In case of a
+      conflict, the order of precedence of such patterns is unspecified. This
+      behavior is likely to change in the future versions of Haketilo.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.url_patterns.h_small.wildcard_priorities')) }}
+    {{ small_heading('Wildcard pattern priorities and querying') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.priorities_intro') }}
+      In case multiple patterns match some URL, the more specific one is
+      preferred. Specificity is considered as follows
     {% endcall %}
 
     {% call unordered_list() %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.priorities_rule_path_ending')|safe }}
+        If patterns only differ in the final path segment, the one with least
+        wildcard asterisks in that segment if preferred.
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.priorities_rule_path_length')|safe }}
+        If patterns, besides the above, only differ in path length, one with
+        longer path is preferred. Neither final wildcard segment nor trailing
+        dashes account for path length.
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.priorities_rule_domain_beginning')|safe }}
+        If patterns, besides the above, only differ in the initial domain
+        segment, one with least wildcard asterisks in that segment is preferred.
       {% endcall %}
       {% call list_entry() %}
-        {{ _('doc.url_patterns.priorities_rule_domain_length')|safe }}
+        If patterns differ in domain length, one with longer domain is
+        preferred. Initial wildcard segment does not account for domain length.
       {% endcall %}
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.priorities_example1_intro')|safe }}
+      As an example, consider the URL
+      <code>http://settings.query.example.com/google/tries/destroy/adblockers//</code>.
+      Patterns matching it are, in the following order
     {% endcall %}
 
     {% call verbatim() %}
@@ -263,11 +350,13 @@ http://***.example.com/***
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.priorities_example1_note')|safe }}
+      Variants of those patterns starting with <code>http*://</code> would of
+      course match as well. They have been omitted for simplicity.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.priorities_example2_intro')|safe }}
+      For a simpler URL like <code>https://example.com</code> the patterns would
+      be
     {% endcall %}
 
     {% call verbatim() %}
@@ -278,31 +367,43 @@ https://***.example.com/***
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.html.priorities_example2_note')|safe }}
+      Variants of those patterns with a trailing dash added
+      would <span class="bold">not</span> match the URL. Also, the pattern
+      variants starting with <code>http*://</code> have been once again omitted.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ small_heading(_('doc.url_patterns.h_small.limits')) }}
+    {{ small_heading('Limits') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.limits')|safe }}
+      In order to prevent some easy-to-conduct DoS attacks, older versions of
+      Haketilo and Hydrilla limited the lengths of domain and path parts of
+      processed URLs. This is no longer the case.
     {% endcall %}
   {% endcall %}
 
   {% call section() %}
-    {{ medium_heading(_('doc.url_patterns.h_medium.alt_solution')) }}
+    {{ medium_heading('Alternative solution idea: mimicking web server mechanics') }}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.url_pattern_drawbacks') }}
+      While wildcard patterns as presented give a lot of flexibility, they are
+      not the only viable approach to specifying what URLs to apply
+      rules/payloads to. In fact, wildcards are different from how the server
+      side of a typical website decides what to return for a given URL request.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.server_behavior_mimicking_idea') }}
+      In a typical scenario, an HTTP server like Apache reads configuration
+      files provided by its administrator and uses various (virtual host,
+      redirect, request rewrite, CGI, etc.) instructions to decide how to handle
+      given URL. Perhps using a scheme that mimics the configuration options
+      typically used with web servers would give more efficiency in specifying
+      what page settings to apply when.
     {% endcall %}
 
     {% call paragraph() %}
-      {{ _('doc.url_patterns.approach_may_be_considered') }}
+      This approach may be considered in the future.
     {% endcall %}
   {% endcall %}
 {% endblock main %}