1 files changed, 128 insertions, 0 deletions
diff --git a/src/hydrilla/proxy/self_doc/en_US/repositories.html.jinja b/src/hydrilla/proxy/self_doc/en_US/repositories.html.jinja
new file mode 100644
index 0000000..4cf6d2c
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/en_US/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 %}