[proxy] document repositories

6 files changed, 151 insertions, 8 deletions

diff --git a/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja b/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja
index e702b7f..045309b 100644
--- a/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja
+++ b/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja
@@ -63,7 +63,8 @@ code in a proprietary work, I am not going to enforce this in court.
       This functionality was deemed sufficient for most users' needs.
       With advanced features enabled the UI also allows any single package or
       library not in use to be uninstalled manually and any package or library
-      available from a repository to be installed without prior enabling.
+      available from a {{ doc_page_link('repository', 'repositories') }} to be
+      installed without prior enabling.
     {% endcall %}
   {% endcall %}
 {% endblock main %}
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja
index c27c161..23e6f45 100644
--- a/src/hydrilla/proxy/self_doc/packages.html.jinja
+++ b/src/hydrilla/proxy/self_doc/packages.html.jinja
@@ -79,9 +79,11 @@ code in a proprietary work, I am not going to enforce this in court.
     {% call paragraph() %}
       Useful packages prepared by others can be installed from Hydrilla
       repositories. The repositories can be configured
-      {{ hkt_link('through Haketilo user interface', 'repos.repos') }} and as of
-      Haketilo 3.0-beta1 need to be manually "refreshed" for new packages from
-      them to be shown in Haketilo.
+      {{ hkt_link('through Haketilo user interface', 'repos.repos') }} as
+      described on
+      {{ doc_page_link('the relevant documentation page', 'repositories') }}.
+      As of Haketilo 3.0-beta1 they need to be manually "refreshed" for new
+      packages from them to be shown in Haketilo.
       Available packages viewable on the
       {{ hkt_link('packages listing page', 'items.packages') }} are not
       immediately installed.
@@ -205,7 +207,8 @@ code in a proprietary work, I am not going to enforce this in court.
         pinned to use a particular version,
       {% endcall %}
       {% call list_entry() %}
-        pinned to use the best version from a particular repository or
+        pinned to use the best version from a particular
+        {{ doc_page_link('repository', 'repositories') }} or
       {% endcall %}
       {% call list_entry() %}
         not pinned at all (best version overall is used).
diff --git a/src/hydrilla/proxy/self_doc/repositories.html.jinja b/src/hydrilla/proxy/self_doc/repositories.html.jinja
new file mode 100644
index 0000000..4cf6d2c
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/repositories.html.jinja
@@ -0,0 +1,128 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing the concept of repositories 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 %} Repositories {% endblock %}
+
+{% block main %}
+  {{ big_heading('Repositories in Haketilo') }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ doc_page_link('Packages', 'packages') }} used to alter sites' behavior
+      can be obtained by users from Hydrilla repositories. The repositories to
+      use can be configured from the
+      {{ hkt_link('relevant Haketilo UI page', 'repos.repos') }}. When Haketilo
+      is first run, it only has one entry on that page - the official Hydrilla
+      repository with fixes for sites that normally rely on (often proprietary)
+      JavaScript.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Adding') }}
+
+    {% call paragraph() %}
+      Before experimenting with third-party repositories please bear in mind
+      that a hostile Haketilo package can cause real harm.
+      Scripts injected by Haketilo have access to data on the page, including
+      cookies and passwords you may enter.
+      Do make sure the repositories you are using are trustworthy.
+    {% endcall %}
+
+    {% call paragraph() %}
+      On the {{ hkt_link('repository addition page', 'repos.add_repo') }} the
+      user is expected to supply 2 pieces of information.
+      The <span class="bold">URL</span> of the repository and its
+      <span class="bold">name</span>.
+      The URL is supposed to be provided by repository owner.
+      Then name is only used locally and can be chosen by the user.
+      Allowed are most visible ASCII characters, with possible spaces in-betwen.
+      No 2 repositories can use the same name.
+    {% endcall %}
+
+    {% call paragraph() %}
+      As of Haketilo version 3.0 the user does not need to provide any
+      authentication data (e.g. private keys) because cryptographic signing of
+      packages is not yet supported. This may change in the future.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Removing') }}
+
+    {% call paragraph() %}
+      A repository can be deleted at any time. When this happens,
+    {% endcall %}
+
+    {% call unordered_list() %}
+      {% call list_entry() %}
+        its packages that were in use (e.g. were enabled) retain their state,
+      {% endcall %}
+      {% call list_entry() %}
+        its packages that were installed but not in use become
+        <span class="bold">orphans</span> and can be removed from the
+        {{ hkt_link('settings page', 'home.home') }} and
+      {% endcall %}
+      {% call list_entry() %}
+        its packages that were not installed are forgotten.
+      {% endcall %}
+    {% endcall %}
+
+    {% call paragraph() %}
+      A deleted repository remains viewable from the
+      {{ hkt_link('repositories management page', 'repos.repos') }} for as long
+      as some of its packages remain installed.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Operating') }}
+
+    {% call paragraph() %}
+      Before repository's contents become viewable on the
+      {{ hkt_link('packages listing page', 'items.packages') }}, it needs to be
+      <span class="bold">refreshed</span>.
+      As of Haketilo 3.0-beta1, this action needs to be triggered manually by
+      the user from the configuration page of that repository.
+      Subsequent refreshals are needed every time the user wants to pull package
+      updates.
+    {% endcall %}
+
+    {% call paragraph() %}
+      Repository's name and URL can also be changed from its configuration page.
+      The same requirements for their format hold as when adding a new
+      repository.
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading('Local items') }}
+
+    {% call paragraph() %}
+      When the users installs some additional packages without using a
+      repository, these are considered <span class="bold">local packages</span>.
+      A special "Local items" entry then appears on the
+      {{ hkt_link('repositories management page', 'repos.repos') }}. Local
+      packages that are not in use are automatically considered orhpans.
+    {% endcall %}
+  {% endcall %}
+{% endblock %}
diff --git a/src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja b/src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja
index 106af53..91c8c0d 100644
--- a/src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/repos/add.html.jinja
@@ -23,7 +23,11 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block title %} {{ _('web_ui.repos.add.title') }} {% endblock %}
 
 {% block main %}
-  <h3>{{ _('web_ui.repos.add.heading') }}</h3>
+  <h3>
+    {{ _('web_ui.repos.add.heading') }}
+    {{ hkt_doc_link('repositories') }}
+  </h3>
+
   <form method="POST">
     {{ label(_('web_ui.repos.add.name_field_label'), 'name') }}
     {% if repo_name_invalid is defined %}
diff --git a/src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja b/src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja
index 4f09ae6..0742fc1 100644
--- a/src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/repos/index.html.jinja
@@ -29,7 +29,10 @@ code in a proprietary work, I am not going to enforce this in court.
 {% endblock %}
 
 {% block main %}
-  <h3>{{ _('web_ui.repos.heading') }}</h3>
+  <h3>
+    {{ _('web_ui.repos.heading') }}
+    {{ hkt_doc_link('repositories') }}
+  </h3>
 
   <a href="{{ url_for('.add_repo') }}"
      class="green-button block-with-bottom-margin">
diff --git a/src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja b/src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja
index 9e4b869..24ec239 100644
--- a/src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/rules/add.html.jinja
@@ -23,7 +23,11 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block title %} {{ _('web_ui.rules.add.title') }} {% endblock %}
 
 {% block main %}
-  <h3>{{ _('web_ui.rules.add.heading') }}</h3>
+  <h3>
+    {{ _('web_ui.rules.add.heading') }}
+    {{ hkt_doc_link('script_blocking') }}
+  </h3>
+
   <form method="POST" action="{{ url_for('.add_rule') }}">
     {{ label(_('web_ui.rules.add.pattern_field_label'), 'pattern') }}