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

9 files changed, 76 insertions, 77 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 1e7b8a0e..01e8e926 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -134,7 +134,7 @@ manages payment initiations of the account and tracks the initiations of payment
   Ask nexus to submit one prepare payment at the bank.
 
   :http:statuscode:`404 Not found`: the unique identifier **or**
-    the bank connection could not be found in the system
+  the bank connection could not be found in the system
 
 
 .. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}
@@ -178,7 +178,7 @@ manages payment initiations of the account and tracks the initiations of payment
 .. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations
 
   Ask nexus the list of initiated payments.  At this stage of the API,
-  **all** is returned: submitted and non submitted payments.
+  **all** is returned: submitted and non-submitted payments.
 
   **Response**
 
@@ -276,9 +276,9 @@ manages payment initiations of the account and tracks the initiations of payment
   **Query parameters:**
 
   * **start** start (dashed YYYY-MM-DD) date of desired payments.
-    Optional, defaults to "earliest possible" date
+    Optional, defaults to "earliest possible" date.
   * **end** end (dashed YYYY-MM-DD) date of desired payments.
-    Optional, defaults to "earliest possible" date
+    Optional, defaults to "earliest possible" date.
 
 
   **Response:** A list of `Transaction` objects.
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index f75c76e0..d848ba40 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -19,7 +19,7 @@ HTTP API
     .. ts:def:: PaymentRequest
 
      interface PaymentRequest {
-       
+
        // IBAN that will receive the payment.
        creditorIban: string;
 
@@ -37,7 +37,7 @@ HTTP API
   Host management.
 
 .. http:post:: /admin/ebics/hosts
-   
+
    Creates a new Ebics host.
 
    **Request:**
@@ -45,32 +45,31 @@ HTTP API
     .. ts:def:: EbicsHostRequest
 
      interface EbicsHostRequest {
-       
+
        // Ebics version.
        hostID: string;
 
        // Name of the host.
        ebicsVersion: string;
      }
-       
+
 
 .. http:get:: /admin/ebics/hosts
-   
-   Shows the list of all the hosts existing
-   in the system.
+
+   Shows the list of all the hosts in the system.
 
    **Response:**
 
     .. ts:def:: EbicsHostResponse
 
      interface EbicsHostResponse {
-       
+
        // shows the host IDs that are active in the system.
        // The Ebics version *is* missing, but it's still available
        // via the HEV message.
        ebicsHosts: string[];
      }
-    
+
 
 ..
   Subscriber management.
@@ -84,7 +83,7 @@ HTTP API
    .. ts:def:: SubscriberRequest
 
      interface SubscriberRequest {
-       
+
        // hostID
        hostID: string;
 
@@ -98,26 +97,25 @@ HTTP API
        systemID: string;
 
      }
-       
+
 
 .. http:get:: /admin/ebics/subscribers
 
-   Shows the list of all the subscribers existing
-   in the system.
+   Shows the list of all the subscribers in the system.
 
    **Response:**
 
     .. ts:def:: SubscribersResponse
 
      interface SubscribersResponse {
-       
+
        subscribers: Subscriber[]
      }
- 
+
     .. ts:def:: Subscriber
 
       interface Subscriber {
-        
+
         // userID
         userID: string;
 
diff --git a/libeufin/bank-transport-ebics.rst b/libeufin/bank-transport-ebics.rst
index 844b1f5c..5afdd5d6 100644
--- a/libeufin/bank-transport-ebics.rst
+++ b/libeufin/bank-transport-ebics.rst
@@ -24,26 +24,26 @@ The following steps are required to set up an EBICS bank transport:
 
 3. The LibEuFin nexus generates cryptographic key material (3 RSA key pairs).
 
-5. The nexus sends the public keys electronically to the bank's EBICS server, together with the information
+4. The nexus sends the public keys electronically to the bank's EBICS server, together with the information
    identifying the subscriber (PartnerID, UserID, SystemID).
 
-6. The user prints a document that contains the public key and hashes for all three key pairs.
+5. The user prints a document that contains the public key and hashes for all three key pairs.
    The user then signs this document and sends it to the bank (physically/scanned).
 
-7. The bank receives the letter and verifies that the keys from the letter correspond
+6. The bank receives the letter and verifies that the keys from the letter correspond
    to the electronically sent keys.  If they match, the bank sets the state of the
    subscriber to "ready".
 
-8. The user now has to wait until the bank has set the EBICS subscriber state to "ready".
+7. The user now has to wait until the bank has set the EBICS subscriber state to "ready".
    There is no in-band notification for this, but the Nexus can try downloading the bank's
    cryptographic parameters.  This will only succeed once the EBICS subscriber is set to "ready"
    by the bank.
 
-9. The user should confirm the public keys of the bank received in the previous step.
+8. The user should confirm the public keys of the bank received in the previous step.
    Typically the bank gives the value of these public keys in an out-of-band channel.
 
-10. Now the user can finally use the EBICS bank transport.  The first step after finishing
-    the setup should be to import the bank accounts accessible for this EBICS subscriber.
+9. Now the user can finally use the EBICS bank transport.  The first step after finishing
+   the setup should be to import the bank accounts accessible for this EBICS subscriber.
 
 
 Alternative ways of setting up the EBICS bank transport are:
diff --git a/libeufin/banking-protocols.rst b/libeufin/banking-protocols.rst
index 17dda0b9..8a1bc099 100644
--- a/libeufin/banking-protocols.rst
+++ b/libeufin/banking-protocols.rst
@@ -111,7 +111,7 @@ Open Bank Project
 The `Open Bank Project <https://www.openbankproject.com/>`__ provides a free software implementation of
 banking middleware that supports various APIs, including PSD2-compatible APIs (based on Berlin Group).
 
-API Docs: https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture
+API Docs: `<https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture>`__
 
 
 UK Open Banking
@@ -122,4 +122,4 @@ Open Banking is the (quite confusing!) name of a UK-based open banking initiativ
 What's nice about Open Banking is that their APIs are really close to ISO 20022, unlike many
 similar HTTP+JSON APIs.
 
-https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications
+`<https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications>`__
diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst
index 9960fe1c..5cabc48f 100644
--- a/libeufin/ebics.rst
+++ b/libeufin/ebics.rst
@@ -58,13 +58,13 @@ EBICS Glossary
 
   FTAM
     Historical predecessor protocol to EBICS (*file transfer, access and management*).
-   
+
   HEV
     The *Host EBICS Version*.  Queried by the client with an HEV request message.
 
   Human Subscriber
 
-   See :term:`Subscriber`. 
+   See :term:`Subscriber`.
 
   H004
     Host protocol version 4.  Refers to the XML Schema defined in *EBICS 2.5*.
@@ -84,7 +84,7 @@ EBICS Glossary
     The Order Number is used to match VEUs in a second upload to the original order.
     An Order Number matches the format ``[A-Z][A-Z0-9]{3}`` (and is not really a number!).
 
-    Must be unique per customer ID and per order type
+    Must be unique per customer ID and per order type.
 
   Transaction ID
     A transaction ID is a 128-bit cryptographically strong random number.
@@ -100,7 +100,7 @@ EBICS Glossary
   Partner ID
     In German, this is called "Kunden ID" (= Customer ID).
     One partner can have multiple "participants", which are identified by user IDs.
-    
+
     Practical example:  A company has one Partner ID.  Each person at the company
     that can access the company's bank accounts gets their own User ID.
     When the person is indirectly accessing the bank server (for example via
@@ -131,7 +131,7 @@ EBICS Glossary
     EBICS implements its own protocol-level segmentation of business-related messages.
     The segmentation can be seen as an alternative to the HTTP facilities of ``Accept-Ranges``.
 
-    The order data of an ebics message may not exceed 1 MB.  The segmentation applies both
+    The order data of an EBICS message may not exceed 1 MB.  The segmentation applies both
     to requests and responses.
 
   Subscriber
@@ -145,7 +145,7 @@ EBICS Glossary
     and ``UserId``.  A technical subscriber cannot sign a bank-technical request.
 
   Technical Subscriber
-   See :term:`Subscriber`. 
+    See :term:`Subscriber`.
 
   TLS
     *Transport Layer Security*.  All messages in EBICS are sent over HTTP with TLS.
@@ -178,11 +178,11 @@ Relevant Order Types
 
   BTD
     **Only EBICS3.0+**. Business Transaction Format Download.
-    Administrative order type to download a file, described in more detail by the BTF structure
+    Administrative order type to download a file, described in more detail by the BTF structure.
 
   BTU
     **Only EBICS3.0+**. Business Transaction Format Upload.
-    Administrative order type to upload a file, described in more detail by the BTF structure
+    Administrative order type to upload a file, described in more detail by the BTF structure.
 
   C52
     **Before EBICS 3.0**.  Download bank-to-customer account report (intra-day information).
@@ -193,19 +193,19 @@ Relevant Order Types
   CRZ
     Type: Download.
 
-    Fetch payment status report (pain.002)
+    Fetch payment status report (pain.002).
 
   CCC
     Type: Upload.
 
     Send SEPA Credit Transfer Initiation (pain.001) via XML container.
-    This is the DFÜ variant (Appendix 3 DFÜ-Agreement)
+    This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
 
   CCT
     Type: Upload.
 
     Send SEPA Credit Transfer Initiation (pain.001) directly.
-    This is the DFÜ variant (Appendix 3 DFÜ-Agreement)
+    This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
 
   CIZ
     Type: Download.
@@ -219,19 +219,19 @@ Relevant Order Types
     **Before EBICS 3.0, France**.  File Download.  Mainly used by France-style EBICS.
 
   HAA
-   Type: Download, Optional 
+    Type: Download, Optional.
 
-   Download order types for which there is new data available.
+    Download order types for which there is new data available.
 
   HTD
-   Type: Download
+    Type: Download.
 
-   Download information about a subscriber.  From German "Teilnehmerdaten".
+    Download information about a subscriber.  From German "Teilnehmerdaten".
 
   HKD
-   Type: Download, Optional 
+    Type: Download, Optional.
 
-   Download information about a customer (=partner).  From German "Kundendaten".
+    Download information about a customer (=partner).  From German "Kundendaten".
 
   HIA
     Transmission of the subscriber keys for (1) identification and authentication and (2)
@@ -376,7 +376,7 @@ type.  Each transaction is either an upload transaction or a download
 transaction, neither both.
 
 Uploads and downloads must proceed in segments of at most ``1 MB``.  The
-segmentation happens after (1) encryption (2) zipping and (3) base64-encoding
+segmentation happens after (1) encryption, (2) zipping, and (3) base64-encoding
 of the order data.
 
 The number of segments is always fixed starting from the first message sent
@@ -398,7 +398,7 @@ are some conditions for that:
 
 * Segment ``n`` can only be downloaded/uploaded when segments ``[0..n-1]`` have
   been downloaded/uploaded.
-* The (implementation-defined) retry counter may not be exceeded.
+* The (implementation-defined) retry limit may not be exceeded.
 
 
 Formats
@@ -407,7 +407,7 @@ Formats
 ISO 20022
 ---------
 
-ISO 20022 is XML-based and defines message format for many finance-related activities.
+ISO 20022 is XML-based and defines the message format for many finance-related activities.
 
 ISO 20022 messages are identified by a message identifier in the following format:
 
@@ -431,17 +431,17 @@ SWIFT Proprietary
 =================
 
 SWIFT Proprietary messages are in a custom textual format.
-The relevant messages are MT940 and MT942
+The relevant messages are MT940 and MT942.
 
 * MT940 contains *pre-advice*, in the sense that transactions in it might still
-  change or be reversed
-* MT942 contains the settled transactions by the end of the day
+  change or be reversed.
+* MT942 contains the settled transactions by the end of the day.
 
 SWIFT will eventually transition from MT messages to ISO20022,
 but some banks might still only give us account statements in the old
 SWIFT format.
 
-  
+
 
 Key Management
 ==============
@@ -523,11 +523,12 @@ Cryptography
 EBICS uses the XML Signature standard for signatures.  It does *not* use XML encryption.
 
 The EBICS specification doesn't directly reference the standardized URIs for the various
-signing algorithms.  Some of these URIs are defined in `<https://tools.ietf.org/html/rfc6931>`__.
+signing algorithms.  Some of these URIs are defined
+in `RFC 6931 <https://tools.ietf.org/html/rfc6931>`__.
 
-* A005 is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
+* A005 is `<http://www.w3.org/2001/04/xmldsig-more#rsa-sha256>`__.
 
-  * the ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme
+  * The ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme
     mentioned in the EBICS spec.
 
 * A006 is `<http://www.w3.org/2007/05/xmldsig-more#rsa-pss>`__ as defined in RFC 6931.
@@ -546,7 +547,7 @@ In EBICS, only **enveloped** signatures are used.
 
 In the XML Signature standard, the element for a signature is ``Signature``.  EBICS violates this
 standard by always mandating ``AuthSignature`` as the name.  ``AuthSignature`` is an alias to
-the ``SignatureType`` xsd type in the XML Schema.
+the ``SignatureType`` XSD type in the XML Schema.
 
 Canonicalization vs transforms:
  * Canonicalization refers to the processing of the ``SignedInfo`` element.
@@ -592,5 +593,3 @@ Others
 
 * `<https://wiki.windata.de/index.php?title=EBICS-Auftragsarten>`_
 * `<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_
-
-
diff --git a/libeufin/frontend.rst b/libeufin/frontend.rst
index a3ab6d54..6e9e866d 100644
--- a/libeufin/frontend.rst
+++ b/libeufin/frontend.rst
@@ -42,4 +42,4 @@ Shows activity of payments and its transaction history (WIP).
 
 /components/bank-accounts
 -------------------------
-Shows bank accounts that are imported. A bank account drawer is shown to facilitate setting up of bank accounts. Each bank account is displayed in a card to display extra details for e.g its' print document.
+Shows bank accounts that are imported. A bank account drawer is shown to facilitate setting up of bank accounts. Each bank account is displayed in a card to display extra details for e.g its print document.
diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst
index d96469d0..e45222a5 100644
--- a/libeufin/iso20022.rst
+++ b/libeufin/iso20022.rst
@@ -5,15 +5,15 @@ ISO 20022 is the standard that defines many XML messages for FinTech.  It is
 very general, and often countries/orgs define subsets (TVS, technical
 validation subset) of the schema.
 
-Documentation for message fields can be viewed at https://www.iso20022.org/standardsrepository
+Documentation for message fields can be viewed at `<https://www.iso20022.org/standardsrepository>`__.
 
 The primary syntax for ISO 20022 messages is XML.  To avoid LibEuFin clients
 having to deal with XML, we define a mapping from ISO 20022 messages into JSON.
 
 The specifics of this mapping are:
 
- * The JSON should be "idiomatic" and easy to process
- * When possible, the highly nested structures of ISO 20022 should be flattened
+ * The JSON should be "idiomatic" and easy to process.
+ * When possible, the highly nested structures of ISO 20022 should be flattened.
  * It must be possible round-trip between the LibEuFin JSON and ISO 20022
    XML messages. The mapping of message types is not 1-to-1, as some ISO 20022 messages are
    very similar and can be mapped to the same JSON structure.
@@ -36,7 +36,7 @@ Reasons for not using ISO 20022 directly are:
    to JSON, they are difficult to use due to their verbosity.
 3. Underspecification.  Messages like camt.05x leave many "degrees of freedom"
    when translating the underlying data into a message.
-4. No interoperability.  As a result of underspecification, different countries/organisations
+4. No interoperability.  As a result of underspecification, different countries/organizations
    define their own subset and interpretation rules for ISO 20022 messages.  This can
    lead to even contradictory usage rules.  An example for this is how the Swiss and EPC
    interpretations handle transaction amounts in the presence of multiple currencies.
@@ -209,4 +209,3 @@ FIXME: This is not complete yet.
      proprietaryIssuer?: string;
      proprietaryCode?: string;
    }
-
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index 122eecc6..82f1ba43 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -6,16 +6,19 @@ Nexus How-To
 Nexus is a Web service that provides a JSON abstraction layer to
 access bank accounts.  It is **not** itself a bank, but a translator
 between JSON requests and more structured banking protocols (like
-EBICS, for example.), that are offered by actual banks.
+EBICS, for example), that are offered by actual banks.
 
-This document explains how to setup Nexus to access a bank account
+This document explains how to set up Nexus to access a bank account
 via the EBICS protocol.  In order to follow all the steps below, the
 reader should already have one EBICS subscriber activated at their bank.
 
 Obtain Nexus
 ============
 Nexus belongs to the LibEuFin project, and can be downloaded via Git:
-``$ git clone git://git.taler.net/libeufin``
+
+.. code-block:: shell
+
+  $ git clone git://git.taler.net/libeufin
 
 Note that Kotlin+Gradle should already work on the host system.
 
@@ -47,7 +50,7 @@ Use the following command to *(1) run the nexus service*:
 After the startup, Nexus should have created a ``.sqlite3`` file in
 its current working directory.  Feel free to use the ``--with-db`` option
 to change the database name and path.  In future releases, the support
-for Postgresql will be provided.
+for PostgreSQL will be provided.
 
 At this point a *(2) superuser account needs to be activated
 into the system*:
@@ -58,18 +61,18 @@ into the system*:
 
 For simplicity, we'll enable the superuser to access the bank account
 via the EBICS protocol, but a API to create less privileged users is
-as well offered.
+offered as well.
 
 Nexus needs now to associate the user to a EBICS subscriber that was
 activated on the bank.  In the Nexus terminology, this is called *(3)
 creating a EBICS connection*.
 
 .. note::
-  
+
   The command line interface needs the following three values
-  to be defined into the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``,
-  and ``NEXUS_PASSWORD``.  In this example, NEXUS_USERNAME should be
-  set to ``foo``, and NEXUS_PASSWORD to the value given for its password
+  to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``,
+  and ``NEXUS_PASSWORD``.  In this example, ``NEXUS_USERNAME`` should be
+  set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password
   in step (2).
 
 .. code-block:: shell
@@ -205,7 +208,7 @@ identifies the prepared payment in the Nexus system.  It'll be needed
 in the next step, to **send the payment instructions to the bank**:
 
 .. code-block:: shell
-  
+
   libeufin-cli \
     accounts \
       submit-payment \
diff --git a/libeufin/transaction-identification.rst b/libeufin/transaction-identification.rst
index 7c737fc2..e9a7cf0e 100644
--- a/libeufin/transaction-identification.rst
+++ b/libeufin/transaction-identification.rst
@@ -16,7 +16,7 @@ ISO 20022 camt.05X
 ------------------
 
 The camt52/53/54 messages defined by ISO 20022 do not have a mandatory transaction
-identifier.  Instead if defines a handful of optional references.
+identifier.  Instead it defines a handful of optional references.
 
 Two identifiers seem to be used in practice:  The *Account Servicer Reference* and the
 *Entry Reference*.  Of these, only the *Account Servicer Reference* seems to be useful
@@ -65,7 +65,7 @@ LibEuFin intends to solve this problem in the following ways:
    the status (booked, pending, info) is examined:
 
    1. When the status is booked, an error is reported, and corresponding bank message
-      will be made available for review
+      will be made available for review.
    2. When the status is "pending" or "info", the entry will simply be ignored.
 
 In the future, this might be extended to be less restrictive: