aboutsummaryrefslogtreecommitdiff
path: root/src/hydrilla/proxy/self_doc/packages.html.jinja
diff options
context:
space:
mode:
authorWojtek Kosior <koszko@koszko.org>2022-10-28 20:15:30 +0200
committerWojtek Kosior <koszko@koszko.org>2022-10-28 20:15:30 +0200
commit43ed7392cdfc734a4304284906b9d0d503381841 (patch)
tree5d78662357507aac0820825a8ace0859c395779d /src/hydrilla/proxy/self_doc/packages.html.jinja
parent2a622842c38f1f9df2aee6af28bf9932d05a2ef0 (diff)
downloadhaketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.tar.gz
haketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.zip
[proxy] make it possible to export embedded documentation as standalone .html files and include these in the binary release tarball
Diffstat (limited to 'src/hydrilla/proxy/self_doc/packages.html.jinja')
-rw-r--r--src/hydrilla/proxy/self_doc/packages.html.jinja218
1 files changed, 0 insertions, 218 deletions
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja
deleted file mode 100644
index 23e6f45..0000000
--- a/src/hydrilla/proxy/self_doc/packages.html.jinja
+++ /dev/null
@@ -1,218 +0,0 @@
-{#
-SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
-
-Documentation page describing the concept of packages 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 %} Packages {% endblock %}
-
-{% block main %}
- {{ big_heading('Packages in Haketilo') }}
-
- {% call section() %}
- {% call paragraph() %}
- Users can modify web pages by creating, installing and enabling
- <span class="bold">packages</span>.
- A package associates {{ doc_page_link('URL patterns', 'url_patterns') }}
- with payloads (i.e. sets of scripts) that can be injected to pages.
- For instance, if an enabled package associates pattern
- <code>https://example.com/***</code> with a script that adds a big
- "Hello world!" text to the page, this package shall cause "Hello world!"
- to appear on pages under <code>example.com</code>.
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Packages and libraries') }}
-
- {% call paragraph() %}
- To make mapping custom JavaScript applications and their dependencies to
- web pages more manageable, Haketilo defines its own concept of "packages"
- and "libraries".
- {% endcall %}
-
- {% call unordered_list() %}
- {% call list_entry() %}
- package - Also called <span class="bold">mapping</span>.
- It associates URL patterns with libraries.
- {% endcall %}
- {% call list_entry() %}
- library - Sometimes also referred to as
- <span class="bold">resource</span>.
- Defines a set of scripts that can be injected together into a page.
- It can also name other libraries as its dependencies.
- When injecting scripts of a given library into some page, Haketilo will
- first inject scripts of all libraries depended on.
- {% endcall %}
- {% endcall %}
-
- {% call paragraph() %}
- It's ultimately a package that provides concrete functionality to the end
- user and that can be enabled or disabled.
- For this reason, a casual user does not even need to be aware of the
- existence of libraries.
- Haketilo UI advanced interface features need to be enabled on the
- {{ hkt_link('settings page', 'home.home') }} for installed libraries to be
- viewable.
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Installing') }}
-
- {% 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') }} 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.
- This only happens after they are explicitly enabled or automatically
- enabled (if the user configured Haketilo to do this).
- {% endcall %}
-
- {% call paragraph() %}
- For convenience, users can also create simple packages
- {{ hkt_link('directly in Haketilo UI', 'import.items_import') }}.
- A simple form can be used to quickly define a standalone script payload
- for a set of URL patterns. As of Haketilo 3.0 only simple (i.e.
- single-library) payloads can be created this way.
- {% endcall %}
-
- {% call paragraph() %}
- It is also possible to import packages from files.
- For this, a directory of serveable mappings and reasources - as produced
- by Hydrilla builder and used by Hydrilla server - has to be put into a ZIP
- archive.
- It can then be uploaded to Haketilo via its
- {{ hkt_link('import page', 'import.items_import') }}.
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Uninstalling') }}
-
- {% call paragraph() %}
- Haketilo tracks dependencies between packages and libraries and
- automatically determines which of them are no longer needed.
- These are called <span class="bold">orphans</span> and if present, can be
- removed from the {{ hkt_link('settings page', 'home.home') }}.
- A version of package or library that is not being used but is still
- available from an active repository is not considered an orphan. It
- automatically becomes one when the repository either stops advertising it
- as available or gets removed by the user from
- {{ hkt_link('the repositories list', 'repos.repos') }}.
- {% endcall %}
-
- {% call paragraph() %}
- When advanced UI features are enabled, it is additionally possible to
- manually uninstall any single package that is not in use at a given
- moment.
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Package contents') }}
-
- {% call paragraph() %}
- Each package has an <span class="bold">identifier</span> (built from a
- restricted set of characters), a <span class="bold">long name</span>, a
- <span class="bold">description</span>, a <span class="bold">version</span>
- and almost always a list of <span class="bold">license files</span> and a
- set of <span class="bold">URL patterns mapped to libraries</span>.
- In addition there might also be other pieces of information such as
- required permissions.
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Enabling/disabling') }}
-
- {% call paragraph() %}
- The user can put package in any of 3 possible states.
- It can be either <span class="bold">enabled</span>,
- <span class="bold">disabled</span> or
- <span class="bold">not configured</span>.
- {% endcall %}
-
- {% call paragraph() %}
- An enabled package always has its payloads injected on pages matched by
- their patterns (unless some more specific pattern takes precedence on the
- given page as described on the
- {{ doc_page_link('policy selection page', 'policy_selection') }}).
- {% endcall %}
-
- {% call paragraph() %}
- A disabled package is always ignored.
- It has to be manually re-enabled for Haketilo to take it into account
- again.
- {% endcall %}
-
- {% call paragraph() %}
- Finally, a package that is neither explicitly enabled nor disabled can be
- treated differently depending on user's choice on the
- {{ hkt_link('settings page', 'home.home') }}.
- It is possible to have Haketilo
- {% endcall %}
-
- {% call unordered_list() %}
- {% call list_entry() %}
- automatically inject such packages' payloads on mathing pages,
- {% endcall %}
- {% call list_entry() %}
- prompt the user on matching pages asking whether the package should be
- enabled or
- {% endcall %}
- {% call list_entry() %}
- completely ignore non-configured packages.
- {% endcall %}
- {% endcall %}
- {% endcall %}
-
- {% call section() %}
- {{ medium_heading('Handling multiple versions') }}
-
- {% call paragraph() %}
- It is possible to have many versions of the same package or library
- installed.
- When this is the case, Haketilo by default uses the newest versions it
- can.
- Additionally, if certain package is enabled, its page also allows the user
- to configure its <span class="bold">pinning</span>.
- A package can be
- {% endcall %}
-
- {% call unordered_list() %}
- {% call list_entry() %}
- pinned to use a particular version,
- {% endcall %}
- {% call list_entry() %}
- 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).
- {% endcall %}
- {% endcall %}
- {% endcall %}
-{% endblock main %}