[taler-docs] branch master updated: document new TOS/PP generation logic

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 23420529 document new TOS/PP generation logic
23420529 is described below

commit 234205297e8a94bb589eff205e7396c6646c445b
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Jul 20 17:09:04 2023 +0200

    document new TOS/PP generation logic
---
 conf.py                              |   7 ++
 frags/legal.rst                      | 183 +++++++++++++++++++++++++++++++++++
 frags/semver.rst                     |   1 -
 manpages/taler-terms-generator.1.rst |  66 +++++++++++++
 taler-auditor-manual.rst             |   6 ++
 taler-challenger-manual.rst          |  52 +---------
 taler-exchange-manual.rst            |  61 ++----------
 taler-merchant-manual.rst            |   6 ++
 8 files changed, 277 insertions(+), 105 deletions(-)

diff --git a/conf.py b/conf.py
index 842d2023..6b1e35df 100644
--- a/conf.py
+++ b/conf.py
@@ -420,6 +420,13 @@ man_pages = [
         "GNU Taler contributors",
         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",
diff --git a/frags/legal.rst b/frags/legal.rst
new file mode 100644
index 00000000..dcecfaa0
--- /dev/null
+++ 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
index 8fc78b38..8e655315 100644
--- 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
new file mode 100644
index 00000000..d15a2166
--- /dev/null
+++ 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
index 1b23c091..6a7b9ea4 100644
--- 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
index 1497bfed..d2c28d41 100644
--- 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
index 002cefd2..e1c4c697 100644
--- 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
index c8173762..2c24a259 100644
--- 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
 ----------------------
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.