diff options
author | Wojtek Kosior <koszko@koszko.org> | 2022-10-28 12:03:32 +0200 |
---|---|---|
committer | Wojtek Kosior <koszko@koszko.org> | 2022-10-28 12:03:32 +0200 |
commit | edb1299c7196a6c3909f4ec3160428636197d877 (patch) | |
tree | 6a8d1cd42701d890f22bf781d254c9f04a244bcc /src/hydrilla/proxy/self_doc/script_blocking.html.jinja | |
parent | fddbbf96bf447bfb630e4a0fd67f6ba7c8c0e141 (diff) | |
download | haketilo-hydrilla-edb1299c7196a6c3909f4ec3160428636197d877.tar.gz haketilo-hydrilla-edb1299c7196a6c3909f4ec3160428636197d877.zip |
[proxy] don't use gettext for localization of doc pages; add a stub of "packages" doc page
Diffstat (limited to 'src/hydrilla/proxy/self_doc/script_blocking.html.jinja')
-rw-r--r-- | src/hydrilla/proxy/self_doc/script_blocking.html.jinja | 92 |
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 %} |