1 files changed, 64 insertions, 37 deletions

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 %}