[taler-docs] branch master updated: fix RST warnings

[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 5d3aef5  fix RST warnings
5d3aef5 is described below

commit 5d3aef5d035c1a78c930b44d19485396d190e09e
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Jun 23 23:12:59 2020 +0200

    fix RST warnings
---
 anastasis.rst             | 29 ++++++++++++++---------------
 core/api-common.rst       |  8 ++++++++
 core/api-exchange.rst     |  3 ++-
 core/api-merchant.rst     | 37 ++++++++++++++++++-------------------
 core/api-sync.rst         |  4 +++-
 developers-manual.rst     | 31 ++++++++++++++++++-------------
 taler-auditor-manual.rst  | 22 +++++++++++-----------
 taler-merchant-manual.rst |  6 +-----
 taler-nfc-guide.rst       | 13 ++++++-------
 9 files changed, 81 insertions(+), 72 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index c27b66d..d0012c7 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -255,16 +255,16 @@ individual **key share**, we use different salts ("erd" 
and "eks" respectively).
     (iv_i, key_i) = HKDF(key_id, nonce_i, "eks", [optional data], keysize + 
ivsize)
     (encrypted_key_share_i, aes_gcm_tag_i) = AES256_GCM(key_share_i, key_i, 
iv_i)
 
-**encrypted_recovery_document**: The encrypted **recovery document** which 
contains the escrow methods, policies 
+**encrypted_recovery_document**: The encrypted **recovery document** which 
contains the escrow methods, policies
 and the encrypted **core secret**.
 
-**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used 
for the encryption of the *recovery document*. 
+**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used 
for the encryption of the *recovery document*.
 Nonce must contain the string "ERD".
 
 **optional data**: Key material that optionally is contributed from the 
authentication method to further obfuscate the key share from the escrow 
provider.
 
-**encrypted_key_share_i**: The encrypted **key_share** which the escrow 
provider must release upon successful authentication.  
-Here, **i** must be a positive number used to iterate over the various **key 
shares** used for the various **escrow methods** 
+**encrypted_key_share_i**: The encrypted **key_share** which the escrow 
provider must release upon successful authentication.
+Here, **i** must be a positive number used to iterate over the various **key 
shares** used for the various **escrow methods**
 at the various providers.
 
 **nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used 
for the encryption of the *key share*. **i** must be
@@ -356,7 +356,7 @@ Obtain salt
   **Response:**
 
   Returns a `SaltResponse`_.
-  
+
   .. _SaltResponse:
   .. ts:def:: SaltResponse
 
@@ -509,7 +509,7 @@ In the following, UUID is always defined and used according 
to `RFC 4122`_.
   Upload a new version of the customer's encrypted recovery document.
   While the document's structure is described in JSON below, the upload
   should just be the bytestream of the raw data (i.e. 32 bytes nonce followed
-  by 16 bytes tag followed by the encrypted document). 
+  by 16 bytes tag followed by the encrypted document).
   If request has been seen before, the server should do nothing, and otherwise 
store the new version.
   The body must begin with a nonce, an AES-GCM tag and continue with the 
ciphertext.  The format
   is the same as specified for the response of the GET method. The
@@ -644,8 +644,7 @@ In the following, UUID is always defined and used according 
to `RFC 4122`_.
 
     }
 
-.. _manage-truth:
-
+.. _Truth:
 
 Managing truth
 ^^^^^^^^^^^^^^
@@ -692,7 +691,7 @@ charge per truth operation using GNU Taler.
       // Contains the information of an interface `EncryptedKeyShare`, but 
simply
       // as one binary block (in Crockford Base32 encoding for JSON).
       key_share_data: []; //bytearray
-    
+
       // Key share method, i.e. "security question", "SMS", "e-mail", ...
       method: string;
 
@@ -720,7 +719,7 @@ charge per truth operation using GNU Taler.
 .. http:get:: /truth/$UUID[?response=$RESPONSE]
 
   Get the stored encrypted key share. If $RESPONSE is specified by the client, 
the server checks
-  if $RESPONSE matches the expected response specified before within the 
TruthUploadRequest_ (see encrypted_truth).  
+  if $RESPONSE matches the expected response specified before within the 
TruthUploadRequest_ (see encrypted_truth).
   Also, the user has to provide the correct *truth_encryption_key* with every 
get request (see below).
   When $RESPONSE is correct, the server responses with the encrypted key share.
   The encrypted key share is returned simply as a byte array and not in JSON 
format.
@@ -768,7 +767,7 @@ charge per truth operation using GNU Taler.
       //
       // HKDF for the key generation must include the
       // string "eks" as salt.
-      // Depending on the method, 
+      // Depending on the method,
       // the HKDF may additionally include
       // bits from the response (i.e. some hash over the
       // answer to the security question)
@@ -811,10 +810,10 @@ FIXME: details!
 Video identification (vid)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Requires the user to identify via video-call. The user is expected to delete 
all metadata revealing 
-information about him/her from the images before uploading them. Since the 
respective images must 
-be passed on to the video identification service in the event of password 
recovery, it must be 
-ensured that no further information about the user can be derived from them. 
+Requires the user to identify via video-call. The user is expected to delete 
all metadata revealing
+information about him/her from the images before uploading them. Since the 
respective images must
+be passed on to the video identification service in the event of password 
recovery, it must be
+ensured that no further information about the user can be derived from them.
 FIXME: details!
 
 
diff --git a/core/api-common.rst b/core/api-common.rst
index 93d6d09..272dfd6 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -267,6 +267,14 @@ Integers
   // JavaScript numbers restricted to integers
   type Integer = number;
 
+Objects
+^^^^^^^
+
+.. ts:def:: Object
+
+  // JavaScript objects, no further restrictions
+  type Object = object;
+
 Keys
 ^^^^
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 979eca8..9b18a18 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1330,11 +1330,12 @@ typically also view the balance.)
     }
 
 
+.. _exchange_refund:
+
 -------
 Refunds
 -------
 
-.. _refund:
 .. http:POST:: /coins/$COIN_PUB/refund
 
   Undo deposit of the given coin, restoring its value.
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 1c99a79..5c50709 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -325,8 +325,7 @@ Dynamic Merchant Instances
   **Response**
 
   :status 204 No content:
-    The backend has successfully removed the instance.  The response is a
-    `PostInstanceRemoveResponse`.
+    The backend has successfully removed the instance.  The body is empty.
   :status 404 Not found:
     The instance is unknown to the backend.
   :status 409 Conflict:
@@ -991,7 +990,7 @@ Payment processing
 
   The backend will return an `abort response <AbortResponse>`, which includes
   verbatim the error codes received from the exchange's
-  :ref:`refund <_refund>` API.  The frontend should pass the replies verbatim 
to
+  :ref:`refund <exchange_refund>` API.  The frontend should pass the replies 
verbatim to
   the browser/wallet.
 
   .. ts:def:: AbortRequest
@@ -1038,12 +1037,12 @@ Payment processing
     // can generate a substantially shorter response.
     interface RefundResult {
       // HTTP status of the request to the exchange.
-      exchange_http_status: integer;
+      exchange_http_status: Integer;
 
       // The full reply from the exchange. Note only actually
-      // a <RefundSuccess> if the `exchange_status` is 200, otherwise
+      // a <RefundSuccess> if the \exchange_http_status\ is 200, otherwise
       // the error message as defined by the refund API.  For
-      // aborts, the `rtransaction_id` is always 0.
+      // aborts, the \rtransaction_id\ is always 0.
       exchange_reply: RefundSuccess;
 
     }
@@ -1278,7 +1277,7 @@ Payment processing
       exchange_code?: Integer;
 
       // If available, HTTP reply from the exchange.
-      exchange_reply?: json;
+      exchange_reply?: Object;
 
       // Refund transaction ID.
       rtransaction_id: Integer;
@@ -1299,8 +1298,8 @@ Payment processing
     // to the wallet and thus not included.
     interface RefundConfirmation {
 
-      // HTTP status of the exchange request, 200 required for refund 
confirmations.
-      exchange_status: 200;
+      // HTTP status of the exchange request, 200 (integer) required for 
refund confirmations.
+      exchange_status: "200";
 
       // the EdDSA :ref:`signature` (binary-only) with purpose
       // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key 
of the
@@ -1342,7 +1341,7 @@ Payment processing
     The backend refuses to delete the order.
 
 
-.. _refund:
+.. _merchant_refund:
 
 --------------
 Giving Refunds
@@ -1502,7 +1501,7 @@ Tracking Wire Transfers
     // and should probably return it here as well.
     interface WireFeeConflictDetails {
       // Numerical `error code <error-codes>`:
-      code: TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE;
+      code: "TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE";
 
       // Text describing the issue for humans.
       hint: string;
@@ -1540,7 +1539,7 @@ Tracking Wire Transfers
 
     interface TrackTransferConflictDetails {
       // Numerical `error code <error-codes>`
-      code: TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS;
+      code: "TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS";
 
       // Text describing the issue for humans.
       hint: string;
@@ -1558,15 +1557,15 @@ Tracking Wire Transfers
       // hardly needed _here_. Once we add automated reports for
       // the Taler auditor, we need to generate this data anyway
       // and should probably return it here as well.
-      exchange_transfer: TrackTransferResponse?;
+      exchange_transfer?: TrackTransferResponse;
 
       // Public key of the exchange used to sign the response to
       // our deposit request.
-      deposit_exchange_pub: EdDSAPublicKey;
+      deposit_exchange_pub: EddsaPublicKey;
 
       // Signature of the exchange signing the (conflicting) response.
-      // Signs over a `struct TALER_DepositConfirmationPS`.
-      deposit_exchange_sig: EdDSASignature;
+      // Signs over a \struct TALER_DepositConfirmationPS\.
+      deposit_exchange_sig: EddsaSignature;
 
       // Hash of the merchant's bank account the wire transfer went to
       h_wire: HashCode;
@@ -1575,10 +1574,10 @@ Tracking Wire Transfers
       h_contract_terms: HashCode;
 
       // At what time the exchange received the deposit.  Needed
-      // to verify the `exchange_sig`.
+      // to verify the \exchange_sig\.
       deposit_timestamp: Timestamp;
 
-      // At what time the refund possibility expired (needed to verify 
``exchange_sig``).
+      // At what time the refund possibility expired (needed to verify 
\exchange_sig\).
       refund_deadline: Timestamp;
 
       // Public key of the coin for which we have conflicting information.
@@ -1717,7 +1716,7 @@ Giving Customer Tips
   :status 200 OK:
     The backend is waiting for the reserve to be established. The merchant
     must now perform the wire transfer indicated in the 
`ReserveCreateConfirmation`.
-  :status 408 Timeout:
+  :status 408 Request Timeout:
     The exchange did not respond on time.
   :status 409 Conflict:
     The exchange does not support the requested wire method.
diff --git a/core/api-sync.rst b/core/api-sync.rst
index 2add73e..67d1e21 100644
--- a/core/api-sync.rst
+++ b/core/api-sync.rst
@@ -411,4 +411,6 @@ Web Security Considerations
 
 To ensure that the Taler Web extension (and others) can access the
 service despite Web "security", all service endpoints must set the
-"Access-Control-Allow-Origin: *".
+header::
+
+  Access-Control-Allow-Origin: *
diff --git a/developers-manual.rst b/developers-manual.rst
index 8c3a350..6e0bc30 100644
--- a/developers-manual.rst
+++ b/developers-manual.rst
@@ -28,7 +28,7 @@ Developer's Manual
 
 .. note::
 
-  This manual contains information for developers working on GNU Taler 
+  This manual contains information for developers working on GNU Taler
   and related components.  It is not intended for a general audience.
 
 .. contents:: Table of Contents
@@ -636,13 +636,13 @@ About Privilege Levels
 
 This is the breakdown of privilege levels in Weblate:
 
-* **Users**/**Viewers** = Can log in, view Translations  (*applies to new 
users*)
+  * **Users**/**Viewers** = Can log in, view Translations  (*applies to new 
users*)
 
-* **Reviewers** = Can contribute Translations to existing *Components*
+  * **Reviewers** = Can contribute Translations to existing *Components*
 
-* **Managers** = Can create new *Components* of existing *Projects*
+  * **Managers** = Can create new *Components* of existing *Projects*
 
-* **Superusers** = Can create new *Projects*
+  * **Superusers** = Can create new *Projects*
 
 Upgrading Privileges
 --------------------
@@ -661,20 +661,25 @@ Reference: 
https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#compone
 
 In Weblate, a *Component* is a subset of a *Project* and each Component 
contains N translations.  A Component is generally associated with a Git repo.
 
-To create a Component, log into https://weblate.taler.net/ with your *Manager* 
or higher credentials and choose **+ Add* from the upper-right corner.
+To create a Component, log into https://weblate.taler.net/ with your *Manager* 
or higher credentials and choose **+ Add** from the upper-right corner.
 
 What follows is a sort of Wizard.  You can find detailed docs at 
https://docs.weblate.org/.  Here are some important notes about connecting your 
Component to the Taler Git repository:
 
 Under *https://weblate.taler.net/create/component/vcs/*:
 
-* **Source code repository** - Generally 
``git+ssh://git@git.taler.net/<reponame>```.  Check with ``git remote -v``.
-* **Repository branch** - Choose the correct branch to draw from and commit to.
-* **Repository push URL** - This is generally 
``git+ssh://git@git.taler.net/<reponame>```  Check with ``git remote -v``.
-* **Repository browser** - This is the www URL of the Git repo's file browser. 
 Example 
``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}``
 where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items 
in braces are actual variables in the string.
-* **Merge style** - *Rebase*, in line with GNU Taler development procedures
+  * **Source code repository** - Generally 
``git+ssh://git@git.taler.net/<reponame>```.  Check with ``git remote -v``.
 
-* **Translation license** - *GNU General Public License v3.0 or Later*
-* **Adding new translation** - Decide how to handle adding new translations
+  * **Repository branch** - Choose the correct branch to draw from and commit 
to.
+
+  * **Repository push URL** - This is generally 
``git+ssh://git@git.taler.net/<reponame>```  Check with ``git remote -v``.
+
+  * **Repository browser** - This is the www URL of the Git repo's file 
browser.  Example 
``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}``
 where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items 
in braces are actual variables in the string.
+
+  * **Merge style** - *Rebase*, in line with GNU Taler development procedures
+
+  * **Translation license** - *GNU General Public License v3.0 or Later*
+
+  * **Adding new translation** - Decide how to handle adding new translations
 
 How to Create a Translation
 ---------------------------
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index f5cca27..97ba2a5 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -263,7 +263,7 @@ Taler components. See for example the exchange manual for 
details on the
 configuration and the ``taler-config`` configuration tool.  This section
 discusses configuration options related to the auditor.
 
-.. _Keys:
+.. _AuditorKeys:
 
 Keys
 ----
@@ -275,7 +275,7 @@ The following values are to be configured in the section 
[auditor]:
 
 -  AUDITOR_PRIV_FILE: Path to the auditor’s private key file.
 
-.. _Serving:
+.. _AuditorServing:
 
 Serving
 -------
@@ -296,7 +296,7 @@ The following values are to be configured in the section 
[auditor]:
    for the unixpath (i.e. 660 = rw-rw—-).
 
 
-.. _Bank-account:
+.. _AuditorBank-account:
 
 Bank account
 ------------
@@ -305,7 +305,7 @@ Bank accounts for the auditor are configured in exactly the
 same way as bank accounts for the exchange. See the exchange
 documentation for details.
 
-.. _Database:
+.. _AuditorDatabaseConfiguration:
 
 Database
 --------
@@ -338,7 +338,7 @@ tables. After running this tool, the rights to CREATE or 
DROP tables
 are no longer required and should be removed.
 
 
-.. _Deployment:
+.. _AuditorDeployment:
 
 Deployment
 ==========
@@ -356,7 +356,7 @@ Web page offering the respective pairing.
 FIXME: explain how that Web page works!
 
 
-.. _Exchange:
+.. _AuditorExchange:
 
 Exchange
 --------
@@ -375,7 +375,7 @@ master public key.
    taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL
 
 
-.. _Denominations:
+.. _AuditorDenominations:
 
 Denominations
 -------------
@@ -417,7 +417,7 @@ response will contain an entry in the ``auditors`` array 
mentioning the
 auditor’s URL.
 
 
-.. _Database:
+.. _AuditorDatabaseInitialization:
 
 Database
 --------
@@ -464,7 +464,7 @@ Audit
 
 Performing an audit is done by invoking the ``taler-auditor`` and
 ``taler-wire-auditor`` tools respectively. Both tools generate JSON
-files, which can then be combined using the ``contrib/render.py''
+files, which can then be combined using the ``contrib/render.py``
 script into the TeX report.
 
 ::
@@ -487,7 +487,7 @@ anymore), this is not recommended in a production setup.
 
 
 
-.. _Database-upgrades:
+.. _AuditorDatabaseUpgrades:
 
 Database upgrades
 -----------------
@@ -510,7 +510,7 @@ historic transactions.  Hence this should not be done in a 
production system.
 
 
 
-.. _Revocations:
+.. _AuditorRevocations:
 
 Revocations
 -----------
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 245e29b..dfa6492 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1119,10 +1119,6 @@ options:
 .. [1]
    https://docs.docker.com/
 
-.. [2]
-   Supporting SEPA is still work in progress; the backend will accept
-   this configuration, but the exchange will not work with SEPA today.
-
 
 
 Diagnostics
@@ -1133,7 +1129,7 @@ topics that might be helpful to understand how the 
exchange operates,
 which files should be backed up. The information may also be helpful for
 diagnostics.
 
-.. _Database-Scheme:
+.. _MerchantDatabaseScheme:
 
 Database Scheme
 ---------------
diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst
index 2023935..88fa13d 100644
--- a/taler-nfc-guide.rst
+++ b/taler-nfc-guide.rst
@@ -45,7 +45,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
      can be opened, and give a warning if it is detected that the devices does 
not have Internet
      connectivity.
 
-   The following :http:post:`/order` request to the merchant backend creates a
+   The following :http:post:`/private/orders` request to the merchant backend 
creates a
    simple order:
 
    .. code-block:: sh
@@ -63,20 +63,20 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
       }
     EOF
     )
-    $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/order
+    $ curl -XPOST -H"$auth_header" -d "$order_req" 
"$backend_base_url"/private/orders
     {
       "order_id": "2019.255-02YDHMXCBQP6J"
     }
 
 2. The merchant checks the payment status of the order using
-   :http:get:`/check-payment`:
+   :http:get:`/private/orders/$ORDER_ID`:
 
    .. code-block:: sh
 
      $ backend_base_url=https://backend.demo.taler.net/
      $ auth_header='Authorization: ApiKey sandbox'
      $ curl -XGET -H"$auth_header" \
-        "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J"
+        "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J"
      # Response:
      {
        "taler_pay_uri": 
"taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J",
@@ -121,7 +121,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
      $ backend_base_url=https://backend.demo.taler.net/
      $ auth_header='Authorization: ApiKey sandbox'
      $ curl -XGET -H"$auth_header" \
-        "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J"
+        "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J"
      # Response:
      {
        "paid": true,
@@ -135,7 +135,7 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
      before responding with the fulfillment page.
 
      For in-store payments, the merchant must periodically check the payment 
status.
-     Instead of polling in a busy loop, the ``long_poll_ms`` parameter of 
:http:get:`/check-payment`
+     Instead of polling in a busy loop, the ``timeout_ms`` parameter of 
:http:get:`/private/orders/$ORDER_ID`
      should be used.
 
 
@@ -281,4 +281,3 @@ The request tunneling request/response JSON messages have 
the following schema:
     // May contain error details if 'status==0'
     body?: object;
   }
-

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