[proxy] add an index page to the documentation

3 files changed, 131 insertions, 60 deletions

diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
index cca1d01..dd8fdb0 100644
--- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
+++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: hydrilla 2.0\n"
 "Report-Msgid-Bugs-To: koszko@koszko.org\n"
-"POT-Creation-Date: 2022-10-28 14:42+0200\n"
+"POT-Creation-Date: 2022-10-28 19:21+0200\n"
 "PO-Revision-Date: 2022-02-12 00:00+0000\n"
 "Last-Translator: Wojtek Kosior <koszko@koszko.org>\n"
 "Language: en_US\n"
@@ -459,11 +459,17 @@ msgstr ""
 "extension but has since been made into an HTTP proxy. It is built on top "
 "of the popular <a href=\"https://mitmproxy.org/\">mitmproxy</a>."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:56
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:53
+msgid "web_ui.home.html.see_haketilo_doc_{url}"
+msgstr ""
+"Helpful information concerning use of this tool can be found in "
+"Haketilo's <a href=\"{url}\">embedded documentation</a>."
+
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:62
 msgid "web_ui.home.heading.configuring_browser_for_haketilo"
 msgstr "Configuring the browser for Haketilo"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:60
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:66
 msgid "web_ui.home.html.to_add_certs_do_xyz"
 msgstr ""
 "Haketilo proxy works by modifying data exchanged by your browser and web "
@@ -475,177 +481,177 @@ msgstr ""
 "href=\"http://mitm.it\">this page</a> and add it to your operating "
 "system, browser or both."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:67
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:73
 msgid "web_ui.home.heading.options"
 msgstr "Global options"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:70
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:76
 msgid "web_ui.home.mapping_usage_mode_label"
 msgstr "Package usage mode"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:81
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:87
 msgid "web_ui.home.packages_are_used_when_enabled"
 msgstr ""
 "Hektilo is currently configured to only use packages that were explicitly"
 " enabled."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:84
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:90
 msgid "web_ui.home.user_gets_asked_whether_to_enable_package"
 msgstr ""
 "Hektilo is currently configured to ask whenever a package is found that "
 "could be used for the current site."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:88
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:94
 msgid "web_ui.home.packages_are_used_automatically"
 msgstr ""
 "Hektilo is currently configured to automatically use packages that are "
 "available for the current site."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:95
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:101
 msgid "web_ui.home.use_enabled_button"
 msgstr "Use when enabled"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:98
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:104
 msgid "web_ui.home.use_question_button"
 msgstr "Ask whether to use"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:101
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:107
 msgid "web_ui.home.use_auto_button"
 msgstr "Use automatically"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:108
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:114
 msgid "web_ui.home.script_blocking_mode_label"
 msgstr "Default scripts treatment"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:116
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:124
 msgid "web_ui.home.scripts_are_allowed_by_default"
 msgstr ""
 "By default Haketilo currently allows JavaScript sent by websites to the "
 "browser to execute."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:119
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:127
 msgid "web_ui.home.scripts_are_blocked_by_default"
 msgstr ""
 "By default Haketilo currently blocks JavaScript sent by websites to the "
 "browser from executing."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:123
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:131
 msgid "web_ui.home.allow_scripts_button"
 msgstr "Allow scripts"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:124
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:132
 msgid "web_ui.home.block_scripts_button"
 msgstr "Block scripts"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:135
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:143
 msgid "web_ui.home.advanced_features_label"
 msgstr "Advanced features"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:143
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:153
 msgid "web_ui.home.user_is_advanced_user"
 msgstr "Interface features for advanced users are currently enabled."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:146
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:156
 msgid "web_ui.home.user_is_simple_user"
 msgstr "Interface features for advanced users are currently disabled."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:153
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:163
 msgid "web_ui.home.user_make_advanced_button"
 msgstr "Enable"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:156
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:166
 msgid "web_ui.home.user_make_simple_button"
 msgstr "Disable"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:164
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:174
 msgid "web_ui.home.orphans_label"
 msgstr "Orphans"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:170
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:180
 msgid "web_ui.home.orphans_to_delete_{mappings}"
 msgstr "Haketilo is holding some unused packages that can be removed ({mappings})."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:174
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:184
 msgid "web_ui.home.orphans_to_delete_exist"
 msgstr "Haketilo is holding some unused libraries that can be removed."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:178
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:188
 msgid "web_ui.home.orphans_to_delete_{mappings}_{resources}"
 msgstr ""
 "Haketilo is holding some unused items that can be removed (packages: "
 "{mappings}; libraries: {resources})."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:187
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:197
 msgid "web_ui.home.prune_orphans_button"
 msgstr "Prune orphans"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:198
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:208
 msgid "web_ui.home.popup_settings_label"
 msgstr "Popup settings"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:214
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:224
 msgid "web_ui.home.configure_popup_settings_on_pages_with"
 msgstr "Configure popup settings on pages with"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:220
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:230
 msgid "web_ui.home.popup_settings_jsallowed_button"
 msgstr "JS allowed"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:221
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:231
 msgid "web_ui.home.popup_settings_jsblocked_button"
 msgstr "JS blocked"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:222
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:232
 msgid "web_ui.home.popup_settings_payloadon_button"
 msgstr "Payload used"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:272
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:282
 msgid "web_ui.home.popup_no_button"
 msgstr "Disable popup"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:275
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:285
 msgid "web_ui.home.popup_yes_button"
 msgstr "Enable popup"
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:285
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:295
 msgid "web_ui.home.jsallowed_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where native JS has been allowed to execute. This is a convenience that "
 "comes at a price of greater risk of user fingerprinting."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:287
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:297
 msgid "web_ui.home.jsallowed_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages with their native JS allowed. This setting is less convenient but "
 "decreases the risk of user fingerprinting."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:293
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:303
 msgid "web_ui.home.jsblocked_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where native JS has been blocked from executing."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:295
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:305
 msgid "web_ui.home.jsblocked_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages where native JS has been blocked from executing."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:301
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:311
 msgid "web_ui.home.payloadon_popup_yes"
 msgstr ""
 "Haketilo currently makes it possible to open its popup window on pages "
 "where payload is used."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:303
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:313
 msgid "web_ui.home.payloadon_popup_no"
 msgstr ""
 "Haketilo currently does not make it possible to open its popup window on "
 "pages where payload is used."
 
-#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:308
+#: src/hydrilla/proxy/web_ui/templates/index.html.jinja:318
 msgid "web_ui.home.popup_can_be_opened_by"
 msgstr ""
 "When enabled on given page, popup dialog can be opened by typing big "
@@ -1114,34 +1120,34 @@ msgstr "Enable"
 msgid "web_ui.repos.add.title"
 msgstr "New repository"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:26
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:27
 msgid "web_ui.repos.add.heading"
 msgstr "Configure a new repository"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:28
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:32
 msgid "web_ui.repos.add.name_field_label"
 msgstr "Name"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:30
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:34
 #: src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja:68
 msgid "web_ui.err.repo_name_invalid"
 msgstr "Chosen name is not valid."
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:33
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:37
 #: src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja:72
 msgid "web_ui.err.repo_name_taken"
 msgstr "Chosen name is already in use."
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:37
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:41
 msgid "web_ui.repos.add.url_field_label"
 msgstr "URL"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:39
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:43
 #: src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja:116
 msgid "web_ui.err.repo_url_invalid"
 msgstr "Chosen URL is not vald."
 
-#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:45
+#: src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja:49
 msgid "web_ui.repos.add.submit_button"
 msgstr "Add repository"
 
@@ -1149,24 +1155,24 @@ msgstr "Add repository"
 msgid "web_ui.repos.title"
 msgstr "Repositories"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:32
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:33
 msgid "web_ui.repos.heading"
 msgstr "Manage repositories"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:36
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:39
 msgid "web_ui.repos.add_repo_button"
 msgstr "Configure new repository"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:41
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:44
 msgid "web_ui.repos.repo_list_heading"
 msgstr "Configured repositories"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:64
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:79
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:67
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:82
 msgid "web_ui.repos.package_count_{}"
 msgstr "packages: {}"
 
-#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:76
+#: src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja:79
 #: src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja:47
 msgid "web_ui.repos.local_packages_semirepo"
 msgstr "Local items"
@@ -1259,32 +1265,32 @@ msgstr "Refresh"
 msgid "web_ui.rules.add.title"
 msgstr "New rule"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:26
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:27
 msgid "web_ui.rules.add.heading"
 msgstr "Define a new rule"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:28
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:32
 msgid "web_ui.rules.add.pattern_field_label"
 msgstr "URL pattern"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:31
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:35
 #: src/hydrilla/proxy/web_ui/templates/rules/show_single.html.jinja:56
 msgid "web_ui.err.rule_pattern_invalid"
 msgstr "Chosen URL pattern is not vald."
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:36
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:40
 msgid "web_ui.rules.add.block_or_allow_label"
 msgstr "Page's JavaScript treatment"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:40
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:44
 msgid "web_ui.rules.add.block_label"
 msgstr "block"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:45
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:49
 msgid "web_ui.rules.add.allow_label"
 msgstr "allow"
 
-#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:52
+#: src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja:56
 msgid "web_ui.rules.add.submit_button"
 msgstr "Add rule"
 
diff --git a/src/hydrilla/proxy/self_doc/doc_index.html.jinja b/src/hydrilla/proxy/self_doc/doc_index.html.jinja
new file mode 100644
index 0000000..03f2231
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/doc_index.html.jinja
@@ -0,0 +1,59 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation pages index.
+
+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 %} Documentation index {% endblock %}
+
+{% block main %}
+  {{ big_heading('Haketilo embedded documentation') }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      This is the embedded documentation of Haketilo proxy.
+      It contains some basic information aimed to help new users understand how
+      the tool works.
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        {{ doc_page_link('Advanced UI features', 'advanced_ui_features') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('Packages', 'packages') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('Policy selection', 'policy_selection') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('Popup', 'popup') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('Repositories', 'repositories') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('Script blocking', 'script_blocking') }}
+      {% endcall %}
+      {% call list_entry() %}
+        {{ doc_page_link('URL patterns', 'url_patterns') }}
+      {% endcall %}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/templates/index.html.jinja b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
index 25649ff..1e498a3 100644
--- a/src/hydrilla/proxy/web_ui/templates/index.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
@@ -49,6 +49,12 @@ code in a proprietary work, I am not going to enforce this in court.
     {{ _('web_ui.home.html.haketilo_is_blah_blah')|safe }}
   </p>
 
+  <p class="has-colored-links">
+    {% set fmt = _('web_ui.home.html.see_haketilo_doc_{url}') %}
+    {% set doc_url = url_for('home.home_doc', page='doc_index') %}
+    {{ fmt.format(url=doc_url|e)|safe }}
+  </p>
+
   <div class="horizontal-separator"></div>
 
   {% if request.url.startswith('http://') %}