Merge branch 'master' of git+ssh://git.taler.net/docs

8 files changed, 116 insertions, 208 deletions

diff --git a/frags/installing-gnunet.rst b/frags/installing-gnunet.rst
new file mode 100644
index 00000000..99ff472d
--- /dev/null
+++ b/frags/installing-gnunet.rst
@@ -0,0 +1,21 @@
+Before you install GNUnet, you must download and install the dependencies
+mentioned in the previous section, otherwise the build may succeed, but could
+fail to export some of the tooling required by GNU Taler.
+
+To install GNUnet, unpack the tarball and change
+into the resulting directory, then proceed as follows:
+
+.. code-block:: console
+
+   $ ./configure [--prefix=GNUNETPFX]
+   $ # Each dependency can be fetched from non standard locations via
+   $ # the '--with-<LIBNAME>' option. See './configure --help'.
+   $ make
+   # make install
+   # ldconfig
+
+If you did not specify a prefix, GNUnet will install to ``/usr/local``,
+which requires you to run the last step as ``root``.
+The ``ldconfig`` command (also run as ``root``) makes the
+shared object libraries (``.so`` files)
+visible to the various installed programs.
diff --git a/frags/installing-taler-exchange.rst b/frags/installing-taler-exchange.rst
new file mode 100644
index 00000000..1b8e96b3
--- /dev/null
+++ b/frags/installing-taler-exchange.rst
@@ -0,0 +1,16 @@
+After installing GNUnet, unpack the GNU Taler exchange tarball,
+change into the resulting directory, and proceed as follows:
+
+.. code-block:: console
+
+   $ ./configure [--prefix=EXCHANGEPFX] \
+                 [--with-gnunet=GNUNETPFX]
+   $ # Each dependency can be fetched from non standard locations via
+   $ # the '--with-<LIBNAME>' option. See './configure --help'.
+   $ make
+   # make install
+
+If you did not specify a prefix, the exchange will install to ``/usr/local``,
+which requires you to run the last step as ``root``.  You have to specify
+``--with-gnunet=/usr/local`` if you installed GNUnet to ``/usr/local`` in the
+previous step.
diff --git a/frags/list-of-dependencies.rst b/frags/list-of-dependencies.rst
new file mode 100644
index 00000000..f0a183f2
--- /dev/null
+++ b/frags/list-of-dependencies.rst
@@ -0,0 +1,21 @@
+-  libsqlite3 >= 3.16.2
+
+-  GNU libunistring >= 0.9.3
+
+-  libcurl >= 7.26 (or libgnurl >= 7.26)
+
+-  libqrencode >= 4.0.0
+
+-  GNU libgcrypt >= 1.6
+
+-  libsodium >= 1.0
+
+-  libargon2 >= 20171227
+
+-  libjansson >= 2.7
+
+-  Postgres >= 9.6, including libpq
+
+-  GNU libmicrohttpd >= 0.9.71
+
+-  GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__)
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index eda8a796..ce93f8b1 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -162,6 +162,8 @@ manages payment initiations of the account and tracks the initiations of payment
    .. ts:def:: PaymentStatus
 
       interface PaymentStatus {
+        // Can be "BOOK" or "PDNG" ('pending').
+        status: string;
 
         // Payment unique identifier
         paymentInitiationId: string;
@@ -369,6 +371,34 @@ manages payment initiations of the account and tracks the initiations of payment
      }
 
 
+.. http:post:: {nexusBase}/bank-accounts/{acctid}/schedule
+  
+  This endpoint allows the caller to define a recurrent
+  execution of a task.
+
+  **Request**
+
+  .. ts:def:: ScheduleTask
+    
+    interface ScheduleTask {
+      name: string;
+
+      // a Unix-compatible cron pattern representing
+      // the frequency of execution of this task.
+      cronspec: string;
+
+      // Can take values "fetch" (to download the history
+      // of the requester's bank account) or "submit" (to submit
+      // any initiated payment associated to the requester's
+      // bank account).
+      type: string;
+
+      // Currently only used for "fetch" operations
+      params: { level: "REPORT" | "STATEMENT" | "ALL"};
+    }
+
+
+
 .. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId}
   
   This call returns the information related to the task associated
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst
index 0f52ed03..c3764344 100644
--- a/libeufin/concepts.rst
+++ b/libeufin/concepts.rst
@@ -47,14 +47,14 @@ for superusers.  Only superusers are allowed to create/modify other users.
 Bank Accounts
 -------------
 
-A bank account is the local representation of some bank account.
+A *bank account* is the local representation of some bank account.
 The information stored about it includes:
 
 * Local alias ("nickname") of the bank account
 * Account identification (IBAN / BIC / account holder)
 * A local mirror of the bank transaction history
 * Payment requests, i.e. payments that have been locally requested, together
-  with their state (sent or not sent, acknowledged in bank statement or not).
+  with their state (sent or not sent, acknowledged in bank statement or not)
 * Error reports (e.g. failed payment requests, bank statement items that were not understood
   by LibEuFin)
 * A default bank connection (if configured) that is used by default
@@ -63,7 +63,7 @@ The information stored about it includes:
 
 Examples:
 
-.. code:: none
+.. code-block:: console
 
   # Download latest transactions via the default bank connection and store them locally
   curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-accounts/my-acct/fetch-transactions
@@ -72,7 +72,7 @@ Bank Connections
 ----------------
 
 Bank connections connect the local LibEuFin bank account to the real bank.
-The bank connection includes the following data:
+The *bank connection* includes the following data:
 
 * Local alias ("nickname") of the bank connection
 * The type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox)
@@ -97,7 +97,7 @@ Bank connections provide the following actions:
 
 Examples:
 
-.. code:: none
+.. code-block:: console
 
   # Manually request the inter-day account report via the EBICS C52 order
   curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connections/my-ebics-testacct/ebics/download/C52
@@ -111,7 +111,7 @@ Facades
 -------
 
 Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts
-and bank connections.  Facades store the following information:
+and bank connections.  A *facade* stores the following information:
 
 * Local name of the facade
 * Facade type and options specific to the type
@@ -125,7 +125,7 @@ not conform to a certain format.
 
 Examples:
 
-.. code:: none
+.. code-block:: console
 
   # Request the Taler-specific history through the facade
   curl $AUTHEADER https://example1.libeufin.tech/facades/my-taler-wire-gw/taler/history/incoming
@@ -133,7 +133,7 @@ Examples:
 Access Control
 ==============
 
-The goal of access control in LibEuFin is to allow the following scenarios:
+The goal of *access control* in LibEuFin is to allow the following scenarios:
 
 * The Nexus can be used by multiple clients for different bank accounts/connections
   and these users can't access each other's bank accounts
@@ -150,7 +150,7 @@ Each top-level object (bank account, bank connection, facade) has a list of
 nexus users with write access, and a list of users with read access.
 
 When using a bank connection through a bank account, permission checks must
-succeed for both the bank account and the bank connection
+succeed for both the bank account and the bank connection.
 
 This works differently for facades:  A facade has a set of associated bank connections
 and bank accounts it can access.  Permissions on these associated objects
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index 52959c89..1301f637 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -131,9 +131,6 @@ components:
    only supports Postgres, but the code could be easily extended to
    support another DBMS.
 
-.. Is it correct that "The software" indicates the Auditor component of GNU
-   Taler?  Also, can we delete the last sentence?  --ttn
-
 -  The auditor Web service
 
    The auditor is expected to provide a public Web service. At this REST API,
@@ -176,10 +173,6 @@ components:
    of the report is required, as not every detail in the report is necessarily
    indicative of a problem.
 
-.. Does parallelism introduce possible non-determinism?  Can we rename the
-   taler-helper-auditor-render program w/o the trailing ".py"?  (That is an
-   implementation detail, i think.)  --ttn
-
 
 Installation
 ============
@@ -187,35 +180,10 @@ Installation
 Please install the following packages before proceeding with the
 exchange compilation.
 
--  GNU autoconf >= 2.69
-
--  GNU automake >= 1.14
-
--  GNU libtool >= 2.4
-
--  GNU autopoint >= 0.19
-
--  GNU libltdl >= 2.4
-
--  GNU libunistring >= 0.9.3
-
--  libcurl >= 7.26 (or libgnurl >= 7.26)
-
--  GNU libmicrohttpd >= 0.9.59
-
--  GNU libgcrypt >= 1.6
-
--  libjansson >= 2.7
-
--  Postgres >= 9.6, including libpq
-
--  texlive-latex-extra
+.. include:: frags/list-of-dependencies.rst
 
--  python3-jinja2
-
--  libgnunetutil (from Git)
-
--  GNU Taler exchange (from Git)
+-  GNU Taler exchange (from `download directory <http://ftpmirror.gnu.org/taler/>`__,
+   see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
 
 Except for the last two, these are available in most GNU/Linux
 distributions and should just be installed using the respective package
@@ -224,46 +192,9 @@ manager.
 The following instructions will show how to install libgnunetutil and
 the exchange (which includes the code for the auditor).
 
-Before you install libgnunetutil, you must download and install the
-dependencies mentioned above, otherwise the build may succeed but fail
-to export some of the tooling required by Taler.
+.. include:: frags/installing-gnunet.rst
 
-To download and install libgnunetutil, proceed as follows:
-
-.. code-block:: console
-
-   $ git clone https://git.gnunet.org/gnunet/
-   $ cd gnunet/
-   $ ./bootstrap
-   $ ./configure [--prefix=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-
-If you did not specify a prefix, GNUnet will install to ``/usr/local``,
-which requires you to run the last step as ``root``.
-
-To download and install the GNU Taler exchange, proceeds as follows:
-
-.. code-block:: console
-
-   $ git clone git://git.taler.net/exchange
-   $ cd exchange
-   $ ./bootstrap
-   $ ./configure [--prefix=EXCHANGEPFX] \
-                 [--with-gnunet=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-
-If you did not specify a prefix, the exchange will install to
-``/usr/local``, which requires you to run the last step as ``root``.
-Note that you have to specify ``--with-gnunet=/usr/local`` if you
-installed GNUnet to ``/usr/local`` in the previous step.
-
-.. Can we simply point to released tarballs?  --ttn
+.. include:: frags/installing-taler-exchange.rst
 
 
 Configuration
@@ -532,8 +463,6 @@ several categories of failures of different severity:
 
 - Configuration issues (such was wire fees unavailable).
 
-.. Is "to make a loss" standard jargon (new to my ears)?  --ttn
-
 
 .. _AuditorDatabaseUpgrades:
 
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 0aab7c02..942fb14e 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -214,35 +214,10 @@ risk that Taler does not try to mitigate against.
 Please install the following packages before proceeding with the
 exchange compilation.
 
--  GNU autoconf >= 2.69
+.. include:: frags/list-of-dependencies.rst
 
--  GNU automake >= 1.14
-
--  GNU libtool >= 2.4
-
--  GNU autopoint >= 0.19
-
--  GNU libltdl >= 2.4
-
--  GNU libunistring >= 0.9.3
-
--  libcurl >= 7.26 (or libgnurl >= 7.26)
-
--  GNU libmicrohttpd >= 0.9.71
-
--  GNU libgcrypt >= 1.6
-
--  libsodium >= 1.0
-
--  libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by GNU Taler)
-
--  libjansson >= 2.7
-
--  Postgres >= 9.6, including libpq
-
--  libgnunetutil (from Git)
-
--  GNU Taler exchange (from Git)
+-  GNU Taler exchange (from `download directory <http://ftpmirror.gnu.org/taler/>`__,
+   see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
 
 Except for the last two, these are available in most GNU/Linux
 distributions and should just be installed using the respective package
@@ -251,44 +226,9 @@ manager.
 The following instructions will show how to install libgnunetutil and
 the GNU Taler exchange.
 
-Before you install libgnunetutil, you must download and install the
-dependencies mentioned above, otherwise the build may succeed but fail
-to export some of the tooling required by Taler.
-
-To download and install libgnunetutil, proceed as follows:
-
-.. code-block:: console
-
-   $ git clone git://git.gnunet.org/gnunet
-   $ cd gnunet/
-   $ ./bootstrap
-   $ ./configure [--prefix=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-
-If you did not specify a prefix, GNUnet will install to ``/usr/local``,
-which requires you to run the last step as ``root``.
-
-To download and install the GNU Taler exchange, proceeds as follows:
-
-.. code-block:: console
+.. include:: frags/installing-gnunet.rst
 
-   $ git clone git://git.taler.net/exchange
-   $ cd exchange
-   $ ./bootstrap
-   $ ./configure [--prefix=EXCHANGEPFX] \
-                 [--with-gnunet=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-
-If you did not specify a prefix, the exchange will install to
-``/usr/local``, which requires you to run the last step as ``root``.
-Note that you have to specify ``--with-gnunet=/usr/local`` if you
-installed GNUnet to ``/usr/local`` in the previous step.
+.. include:: frags/installing-taler-exchange.rst
 
 Configuration
 =============
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index fda75bb8..fd64fadc 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -283,27 +283,7 @@ Installation of dependencies
 The following packages need to be installed before we can compile the
 backend:
 
--  libsqlite3 >= 3.16.2
-
--  libunistring >= 0.9.3
-
--  libcurl >= 7.26 (or libgnurl >= 7.26)
-
--  libqrencode >= 4.0.0
-
--  GNU libgcrypt >= 1.6
-
--  libsodium >= 1.0
-
--  libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by GNU Taler)
-
--  libjansson >= 2.7
-
--  Postgres >= 9.6, including libpq
-
--  GNU libmicrohttpd >= 0.9.71
-
--  GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__)
+.. include:: frags/list-of-dependencies.rst
 
 -  GNU Taler exchange (see `release announcement <https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late>`__)
 
@@ -331,27 +311,7 @@ Installing GNUnet
 
 .. index:: GNUnet
 
-Before you install GNUnet, you must download and install the dependencies
-mentioned in the previous section, otherwise the build may succeed, but could
-fail to export some of the tooling required by GNU Taler.
-
-To download and install GNUnet, unpack the tarball and change
-into the resulting directory, then proceed as follows:
-
-.. code-block:: console
-
-   $ ./configure [--prefix=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-   # ldconfig
-
-If you did not specify a prefix, GNUnet will install to ``/usr/local``,
-which requires you to run the last step as ``root``.
-The ``ldconfig`` command (also run as ``root``) makes the
-shared object libraries (``.so`` files)
-visible to the various installed programs.
+.. include:: frags/installing-gnunet.rst
 
 There is no need to actually run a GNUnet peer to use the Taler merchant
 backend -- all the merchant needs from GNUnet is a number of headers and
@@ -365,22 +325,7 @@ Installing the GNU Taler exchange
 
 .. index:: exchange
 
-After installing GNUnet, unpack the GNU Taler exchange tarball,
-change into the resulting directory, and proceed as follows:
-
-.. code-block:: console
-
-   $ ./configure [--prefix=EXCHANGEPFX] \
-                 [--with-gnunet=GNUNETPFX]
-   $ # Each dependency can be fetched from non standard locations via
-   $ # the '--with-<LIBNAME>' option. See './configure --help'.
-   $ make
-   # make install
-
-If you did not specify a prefix, the exchange will install to ``/usr/local``,
-which requires you to run the last step as ``root``.  You have to specify
-``--with-gnunet=/usr/local`` if you installed GNUnet to ``/usr/local`` in the
-previous step.
+.. include:: frags/instaling-taler-exchange.rst
 
 There is no need to actually run a Taler exchange to use the Taler merchant
 backend -- all the merchant needs from the Taler exchange is a few headers and
@@ -394,6 +339,10 @@ Installing the GNU Taler merchant backend
 
 .. index:: backend
 
+GNU Taler merchant has these additional dependencies:
+
+- libqrencode >= 4.0.0
+
 The following steps assume all dependencies are installed.
 
 First, unpack the GNU Taler merchant tarball and change into
@@ -446,6 +395,7 @@ commands:
 .. code-block:: console
 
    # apt-get install \
+     libqrencode-dev \
      libsqlite3-dev \
      libltdl-dev \
      libunistring-dev \
@@ -469,6 +419,7 @@ For more recent versions of Debian, you should instead run:
 .. code-block:: console
 
    # apt-get install \
+     libqrencode-dev \
      libsqlite3-dev \
      libltdl-dev \
      libunistring-dev \