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