commit 234205297e8a94bb589eff205e7396c6646c445b
parent 0634443ccfbff2eee1d16e3ab14310612e5659ff
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 20 Jul 2023 17:09:04 +0200
document new TOS/PP generation logic
Diffstat:
8 files changed, 277 insertions(+), 105 deletions(-)
diff --git a/conf.py b/conf.py
@@ -421,6 +421,13 @@ man_pages = [
1,
),
(
+ "manpages/taler-terms-generator.1",
+ "taler-terms-generator",
+ "create legal policy documents for services",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
"manpages/taler-exchange-closer.1",
"taler-exchange-closer",
"close idle reserves",
diff --git a/frags/legal.rst b/frags/legal.rst
@@ -0,0 +1,183 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2023 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+
+The service has well-known API endpoints to return its legal conditions to the
+user in various languages and various formats. This section describes how to
+setup and configure the legal conditions.
+
+
+Terms of Service
+----------------
+
+The service has an endpoint "/terms" to return the terms of service (in legal
+language) of the service operator. Client software show these terms of
+service to the user when the user is first interacting with the service.
+Terms of service are optional for experimental deployments, if none are
+configured, the service will return a simple statement saying that there are
+no terms of service available.
+
+To configure the terms of service response, there are two options
+in the configuration file for the service:
+
+- ``TERMS_ETAG``: The current "Etag" to return for the terms of service.
+ This value must be changed whenever the terms of service are
+ updated. A common value to use would be a version number.
+ Note that if you change the ``TERMS_ETAG``, you MUST also provide
+ the respective files in ``TERMS_DIR`` (see below).
+- ``TERMS_DIR``: The directory that contains the terms of service.
+ The files in the directory must be readable to the service
+ process.
+
+
+Privacy Policy
+--------------
+
+The service has an endpoint "/pp" to return the terms privacy policy (in legal
+language) of the service operator. Clients should show the privacy policy to
+the user when the user explicitly asks for it, but it should not be shown by
+default. Privacy policies are optional for experimental deployments, if none
+are configured, the service will return a simple statement saying that there
+is no privacy policy available.
+
+To configure the privacy policy response, there are two options
+in the configuration file for the service:
+
+- ``PRIVACY_ETAG``: The current "Etag" to return for the privacy policy.
+ This value must be changed whenever the privacy policy is
+ updated. A common value to use would be a version number.
+ Note that if you change the ``PRIVACY_ETAG``, you MUST also provide
+ the respective files in ``PRIVACY_DIR`` (see below).
+- ``PRIVACY_DIR``: The directory that contains the privacy policy.
+ The files in the directory must be readable to the service
+ process.
+
+
+Legal policies directory layout
+-------------------------------
+
+The ``TERMS_DIR`` and ``PRIVACY_DIR`` directory structures must follow a
+particular layout. You may use the same directory for both the terms of
+service and the privacy policy, as long as you use different ETAGs. Inside of
+the directory, there should be sub-directories using two-letter language codes
+like "en", "de", or "jp". Each of these directories would then hold
+translations of the current terms of service into the respective language.
+Empty directories are permitted in case translations are not available.
+
+Then, inside each language directory, files with the name of the value set as
+the ``TERMS_ETAG`` or ``PRIVACY_ETAG`` must be provided. The extension of each
+of the files should be typical for the respective mime type. The set of
+supported mime types is currently hard-coded in the service, and includes
+".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present,
+the service may show a warning on startup.
+
+Example
+^^^^^^^
+
+A sample file structure for a ``TERMS_ETAG`` of "tos-v0" would be:
+
+- TERMS_DIR/en/tos-v0.txt
+- TERMS_DIR/en/tos-v0.html
+- TERMS_DIR/en/tos-v0.pdf
+- TERMS_DIR/en/tos-v0.epub
+- TERMS_DIR/en/tos-v0.md
+- TERMS_DIR/de/tos-v0.txt
+- TERMS_DIR/de/tos-v0.html
+- TERMS_DIR/de/tos-v0.pdf
+- TERMS_DIR/de/tos-v0.epub
+- TERMS_DIR/de/tos-v0.md
+
+If the user requests an HTML format with language preferences "fr" followed by
+"en", the service would return ``TERMS_DIR/en/tos-v0.html`` lacking a version in
+French.
+
+
+Generating the Legal Terms
+--------------------------
+
+The ``taler-terms-generator`` script can be used to generate directories with
+terms of service and privacy policies in multiple languages and all required
+data formats from a single source file in ``.rst`` format and GNU gettext
+translations in ``.po`` format.
+
+To use the tool, you need to first write your legal conditions in English in
+reStructuredText (rst). You should find a templates in
+``$PREFIX/share/terms/*.rst`` where ``$PREFIX`` is the location where you
+installed the service to. Whenever you make substantive changes to the legal
+terms, you must use a fresh filename and change the respective ``ETAG``. The
+resulting file must be called ``$ETAG.rst`` and the first line of the file should be the title of the document.
+
+Once you have written the ``$ETAG.rst`` file in English, you can
+generate the first set of outputs:
+
+.. code-block:: shell-session
+
+ $ taler-terms-generator -i $ETAG
+
+Afterwards, you should find the terms in various formats for all configured
+languages (initially only English) in ``$PREFIX/share/terms/``. The generator
+has a few options which are documented in its man page.
+
+
+Adding translations
+-------------------
+
+Translations must be available in subdirectories
+``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po``.
+To start translating, you first need to add a new
+language:
+
+.. code-block:: shell-session
+
+ $ taler-terms-generator -i $ETAG -l $LANGUAGE
+
+Here, ``$LANGUAGE`` should be a two-letter language
+code like ``de`` or ``fr``. The command will generate
+a file ``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po``
+which contains each English sentence or paragraph
+in the original document and an initially empty
+translation. Translators should update the ``.po``
+file. Afterwards, simply re-run
+
+.. code-block:: shell-session
+
+ $ taler-terms-generator -i $ETAG
+
+to make the current translation(s) available to the
+service.
+
+.. note::
+
+ You must restart the service whenever adding or updating legal documents or their translations.
+
+
+Updating legal documents
+------------------------
+
+When making minor changes without legal implications, edit the ``.rst`` file,
+then re-run the step to add a new language for each existing translation to
+produce an updated ``.po`` file. Translate the sentences that have changed and
+finally run the generator (without ``-l``) on the ETAG (``-i $ETAG``) to
+create the final files.
+
+When making major changes with legal implications, you should first rename (or
+copy) the existing ``.rst`` file and the associated translation files to a new
+unique name. Afterwards, make the major changes, update the ``.po`` files,
+complete the translations and re-create the final files. Finally, do not
+forget to update the ``ETAG`` configuration option to the new name and to
+restart the service.
diff --git a/frags/semver.rst b/frags/semver.rst
@@ -23,4 +23,3 @@ For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x
as the MAJOR version matches. A MAJOR version of 0 indicates experimental
development, and you are expected to always run all of the *latest* releases
together (no compatibility guarantees).
-
diff --git a/manpages/taler-terms-generator.1.rst b/manpages/taler-terms-generator.1.rst
@@ -0,0 +1,66 @@
+taler-terms-generator(1)
+########################
+
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-terms-generator** - generate legal terms for GNU Taler services
+
+
+Synopsis
+========
+
+**taler-terms-generator**
+[**-a** *AUTHOR*]
+[**-C** *COPYRIGHT*]
+[**-h**]
+[**-i** *INPUT*]
+[**-l** *LANGUAGE*]
+[**-o** *OUTPUT*]
+[**-p** *PAPER*]
+[**-t** *TITLE*]
+
+
+Description
+===========
+
+**taler-terms-generator** is a command-line tool to create terms of service
+ and privacy policy files in various file formats and languages from a
+ reStructuredText (".rst") input. It can be used to generate the responses
+ various GNU Taler services serve under the ``/terms`` and ``/pp`` endpoints.
+
+**-a** *AUTHOR*
+ set the author information to the given AUTHOR in the meta-data of various generated outputs.
+
+**-C** *COPYRIGHT*
+ set the copyright information to the given COPYRIGHT in the meta-data of various generated outputs.
+
+**-h** \| **--help**
+ Prints a compiled-in help text.
+
+**-l** *LANGUAGE*
+ Add the given *LANGUAGE* to the list of translations for the current *INPUT*. *LANGUAGE* must be a two-letter language code (like "de" or "it"). This will generate or update the respective ".po" files to translate the *INPUT* terms to this *LANGUAGE*.
+
+**-o** *OUTPUT*
+ Specifies where to write the output. This should be the directory where the service expects to find the generated resources. Unless you changed the default configuration, you probably do not have to specify this value.
+
+**-p** *PAPER*
+ Specifies the paper format for generated PDF documents. Can be "a4" or "letter".
+
+**-t** *TITLE*
+ Overrides the document title. By default, the title will be set to the contents of the first line of the *INPUT* ".rst" file.
+
+
+See Also
+========
+
+taler-config(1), taler.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
@@ -457,6 +457,12 @@ used when configuring the exchange' database:
CONFIG = postgres:///exchangedemo
+Legal conditions for using the service
+--------------------------------------
+
+.. include:: frags/legal.rst
+
+
.. _AuditorDeployment:
Deployment
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
@@ -234,56 +234,10 @@ commands.
providers or for new types of addresses.
-Terms of Service
-----------------
-
-The exchange has an endpoint "/terms" to return the terms of service
-(in legal language) of the Challenger operator.
-
-To configure the terms of service response, there are two options
-in the ``[challenger]`` section:
-
-- ``TERMS_ETAG``: The current "Etag" to return for the terms of service.
- This value must be changed whenever the terms of service are
- updated. A common value to use would be a version number.
- Note that if you change the ``TERMS_ETAG``, you MUST also provide
- the respective files in ``TERMS_DIR`` (see below).
-- ``TERMS_DIR``: The directory that contains the terms of service.
- The files in the directory must be readable to the ``challenger-httpd``
- process.
-
-The ``TERMS_DIR`` directory structure must follow a particular layout.
-First, inside of ``TERMS_DIR``, there should be sub-directories using
-two-letter language codes like "en", "de", or "jp". Each of these
-directories would then hold translations of the current terms of
-service into the respective language. Empty directories are
-permitted in case translations are not available.
-
-Then, inside each language directory, files with the name of the
-value set as the ``TERMS_ETAG`` must be provided. The extension of
-each of the files should be typical for the respective mime type.
-The set of supported mime types is currently hard-coded in the
-exchange, and includes HTML, PDF and TXT files. If other files are
-present, Challenger may show a warning on startup.
-
-
-Example
-^^^^^^^
-
-A sample file structure for a ``TERMS_ETAG`` of "v1" would be:
-
-- TERMS_DIR/en/v1.txt
-- TERMS_DIR/en/v1.html
-- TERMS_DIR/en/v1.pdf
-- TERMS_DIR/de/v1.txt
-- TERMS_DIR/de/v1.html
-- TERMS_DIR/de/v1.pdf
-- TERMS_DIR/fr/v1.pdf
-
-If the user requests an HTML format with language preferences "fr" followed by "en",
-Challenger would return ``TERMS_DIR/en/v1.html`` lacking an HTML version in
-French.
+Legal conditions for using the service
+--------------------------------------
+.. include:: frags/legal.rst
Database Configuration
----------------------
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -1280,64 +1280,15 @@ Such a Wire Gateway configuration can be tested with the following commands:
Legal Setup
===========
-This chapter describes how to setup certain legal aspects of
-a GNU Taler exchange. Users that just want to set up an
-exchange as an experiment without legal requirements can
-safely skip these steps.
+This chapter describes how to setup certain legal aspects of a GNU Taler
+exchange. Users that just want to set up an exchange as an experiment without
+legal requirements can safely skip these steps.
-Terms of Service
-----------------
+Legal conditions for using the service
+--------------------------------------
-The exchange has an endpoint "/terms" to return the terms of service
-(in legal language) of the exchange operator. The wallet will show
-those terms of service to the user when the user is first withdrawing
-coins. Terms of service are optional for experimental deployments,
-if none are configured, the exchange will return a simple statement
-saying that there are no terms of service available.
-
-To configure the terms of service response, there are two options
-in the ``[exchange]`` section:
-
-- ``TERMS_ETAG``: The current "Etag" to return for the terms of service.
- This value must be changed whenever the terms of service are
- updated. A common value to use would be a version number.
- Note that if you change the ``TERMS_ETAG``, you MUST also provide
- the respective files in ``TERMS_DIR`` (see below).
-- ``TERMS_DIR``: The directory that contains the terms of service.
- The files in the directory must be readable to the exchange
- process.
-
-The ``TERMS_DIR`` directory structure must follow a particular layout.
-First, inside of ``TERMS_DIR``, there should be sub-directories using
-two-letter language codes like "en", "de", or "jp". Each of these
-directories would then hold translations of the current terms of
-service into the respective language. Empty directories are
-permitted in case translations are not available.
-
-Then, inside each language directory, files with the name of the
-value set as the ``TERMS_ETAG`` must be provided. The extension of
-each of the files should be typical for the respective mime type.
-The set of supported mime types is currently hard-coded in the
-exchange, and includes HTML, PDF and TXT files. If other files are
-present, the exchange may show a warning on startup.
-
-Example
-^^^^^^^
-
-A sample file structure for a ``TERMS_ETAG`` of "v1" would be:
-
-- TERMS_DIR/en/v1.txt
-- TERMS_DIR/en/v1.html
-- TERMS_DIR/en/v1.pdf
-- TERMS_DIR/de/v1.txt
-- TERMS_DIR/de/v1.html
-- TERMS_DIR/de/v1.pdf
-- TERMS_DIR/fr/v1.pdf
-
-If the user requests an HTML format with language preferences "fr" followed by "en",
-the exchange would return ``TERMS_DIR/en/v1.html`` lacking an HTML version in
-French.
+.. include:: frags/legal.rst
KYC Configuration
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -931,6 +931,12 @@ Apache
Customization
=============
+Legal conditions for using the service
+--------------------------------------
+
+.. include:: frags/legal.rst
+
+
Mustach HTML Templates
----------------------
