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

3 files changed, 39 insertions, 27 deletions

diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index c952a242..6b6eff67 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -143,6 +143,8 @@ core banking system with EBICS access to bank accounts.
 The sandbox relies on a database, which you must specify using a JDBC
 connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment
 variable, before invoking any commands.
+(If this variable is not set, ``libeufin-sandbox`` complains and exits.)
+
 Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)*
 (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``)
 are supported right now.
@@ -238,6 +240,8 @@ Connect Nexus with an EBICS account
 Nexus relies on a database, which you must specify using a JDBC
 connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment
 variable, before invoking any commands.
+(If this variable is not set, ``libeufin-nexus`` complains and exits.)
+
 Only *SQLite* (e.g. ``jdbc:sqlite:/tmp/libeufintestdb``) and *PostgreSQL (via TCP)*
 (e.g. ``jdbc:postgresql://localhost:$port/libeufintestdb?user=$username&password=$password``)
 are supported right now.
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 5f0a6ab4..3424f991 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -496,6 +496,8 @@ must then have the following options:
 -  ``DURATION_SPEND``: How long is a coin of the given type valid? Smaller
    values result in lower storage costs for the exchange.
 
+-  ``DURATION_LEGAL``: How long is the coin of the given type legal?
+
 -  ``FEE_WITHDRAW``: What does it cost to withdraw this coin? Specified
    using the same format as value.
 
@@ -505,6 +507,9 @@ must then have the following options:
 -  ``FEE_REFRESH``: What does it cost to refresh this coin? Specified using
    the same format as value.
 
+-  ``FEE_REFUND``: What does it cost to refund this coin?
+   Specified using the same format as value.
+
 -  ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two
    primes) have for this type of coin.
 
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 2070a943..e4a9d151 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -49,7 +49,7 @@ This chapter explains some basic concepts. In the
 second chapter, you will learn how to do basic payments.
 
 This version of the tutorial has examples for Python3. It uses the
-requests library for HTTP requests. Versions for other
+``requests`` library for HTTP requests. Versions for other
 languages/environments are available as well.
 
 If you want to look at some simple, running examples, check out these:
@@ -167,7 +167,7 @@ https://backend.demo.taler.net/:
 .. Note:: These are fictional merchants used for our demonstrators and
    not affiliated with or officially approved by the respective projects.
 
-All endpoints for instances offer the same API. Thus, which instance is
+All endpoints for instances offer the same API. Thus, which instance
 to be used is simply included in the base URL of the merchant backend.
 
 
@@ -193,26 +193,26 @@ field:
 .. index:: summary
 .. index:: fulfillment URL
 
--  amount: The amount to be paid, as a string in the format
+-  ``amount``: The amount to be paid, as a string in the format
    ``CURRENCY:DECIMAL_VALUE``, for example ``EUR:10`` for 10 Euros or
    ``KUDOS:1.5`` for 1.5 KUDOS.
 
--  summary: A human-readable summary for what the payment is about. The
+-  ``summary``: A human-readable summary for what the payment is about. The
    summary should be short enough to fit into titles, though no hard
    limit is enforced.
 
--  fulfillment_url: A URL that will be displayed once the payment is
+-  ``fulfillment_url``: A URL that will be displayed once the payment is
    completed. For digital goods, this should be a page that displays the
    product that was purchased. On successful payment, the wallet
    automatically appends the ``order_id`` as a query parameter, as well
-   as the ``session_sig`` for session-bound payments (discussed later).
+   as the ``session_sig`` for session-bound payments (discussed below).
 
 Orders can have many more fields, see `The Taler Order
 Format <#The-Taler-Order-Format>`__.  When POSTing an order,
 you can also specify additional details such as an override
 for the refund duration and instructions for inventory
 management. These are rarely needed and not covered in this
-tutorial; please read the :doc:`core/api-merchant` reference
+tutorial; please see the :doc:`core/api-merchant` reference
 manual for details.
 
 A minimal Python snippet for creating an order would look like this:
@@ -289,12 +289,12 @@ If the ``order_status`` field in the response is ``paid``, you will not
 get a ``payment_redirect_url`` and instead information about the
 payment status, including:
 
--  contract_terms: The full contract terms of the order.
+-  ``contract_terms``: The full contract terms of the order.
 
--  refunded: ``true`` if a (possibly partial) refund was granted for
+-  ``refunded``: ``true`` if a (possibly partial) refund was granted for
    this purchase.
 
--  refunded_amount: Amount that was refunded
+-  ``refunded_amount``: Amount that was refunded
 
 Once the frontend has confirmed that the payment was successful, it
 usually needs to trigger the business logic for the merchant to fulfill
@@ -302,7 +302,7 @@ the merchant’s obligations under the contract.
 
 .. Note::
    You do not need to keep querying to notice changes
-   to the order's transaction status.  The endpoint
+   to the order's transaction status.  The endpoints
    support long polling, simply specify a ``timeout_ms``
    query parameter with how long you want to wait at most
    for the order status to change to ``paid``.
@@ -328,12 +328,12 @@ The frontend can instruct the merchant backend to authorize a refund by
 
 The refund request JSON object has only two fields:
 
--  refund: Amount to be refunded. If a previous refund was authorized
+-  ``refund``: Amount to be refunded. If a previous refund was authorized
    for the same order, the new amount must be higher, otherwise the
    operation has no effect. The value indicates the total amount to be
    refunded, *not* an increase in the refund.
 
--  reason: Human-readable justification for the refund. The reason is
+-  ``reason``: Human-readable justification for the refund. The reason is
    only used by the Back Office and is not exposed to the customer.
 
 If the request is successful (indicated by HTTP status code 200), the
@@ -406,7 +406,7 @@ Note that changing the session ID to a different device requires the
 involvement of the wallet that made the payment, thus reasonably limiting the
 possibility of broadly sharing the digital purchases.  Repurchase detection is
 also *only* done for HTTP(S) fulfillment URLs. In particular, this means
-fulfillment URIs like "taler://fulfillment-success/$MESSAGE" are not
+fulfillment URIs like ``taler://fulfillment-success/$MESSAGE`` are not
 considered to identify a resource you can pay for and thus do not have to be
 unique.
 
@@ -442,24 +442,27 @@ funds available for tipping, query the ``/tip-query`` endpoint:
    ...              headers={"Authorization": "ApiKey sandbox"})
    <Response [200]>
 
-authorize tip
+.. _authorize-tip:
+
 To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields
 are recognized in the JSON request object:
 
--  amount: Amount that should be given to the visitor as a tip.
+-  ``amount``: Amount that should be given to the visitor as a tip.
 
--  instance: Merchant instance that grants the tip (each instance may
+-  ``instance``: Merchant instance that grants the tip (each instance may
    have its own independent tipping funds configured).
 
--  justification: Description of why the tip was granted. Human-readable
+-  ``justification``: Description of why the tip was granted. Human-readable
    text not exposed to the customer, but used by the Back Office.
 
--  next_url: The URL that the user’s browser should be redirected to by
+-  ``next_url``: The URL that the user’s browser should be redirected to by
    the wallet, once the tip has been processed.
 
 The response from the backend contains a ``tip_redirect_url``. The
 customer’s browser must be redirected to this URL for the wallet to pick
-up the tip. pick up tip
+up the tip.
+
+.. _pick-up-tip:
 
 This code snipped illustrates giving a tip:
 
@@ -527,7 +530,7 @@ Product Identification
 
 In some situations the user may have paid for some digital good, but the
 frontend does not know the exact order ID, and thus cannot instruct the
-wallet to reveil the existing payment receipt. This is common for simple
+wallet to reveal the existing payment receipt. This is common for simple
 shops without a login system. In this case, the user would be prompted
 for payment again, even though they already purchased the product.
 
@@ -564,7 +567,7 @@ max_fee
    This is the maximum total amount of deposit fees that the merchant is
    willing to pay. If the deposit fees for the coins exceed this amount,
    the customer has to include it in the payment total. The fee is
-   specified using the same triplet used for ``amount``.
+   specified using the same format used for ``amount``.
 
 .. index:: fees
 .. index:: maximum wire fee
@@ -652,7 +655,7 @@ products
       or just the count.
 
    price
-      Price for quantity units of this product shipped to the given
+      Price for ``quantity`` units of this product shipped to the given
       ``delivery_location``. Note that usually the sum of all of the prices
       should add up to the total amount of the contract, but it may be
       different due to discounts or because individual prices are
@@ -675,17 +678,17 @@ products
 
    delivery_date
       Time by which the product is to be delivered to the
-      delivery_location.
+      ``delivery_location``.
 
    delivery_location
-      This should give a label in the locations map, specifying where
+      This should give a label in the ``locations`` map, specifying where
       the item is to be delivered.
 
    Values can be omitted if they are not applicable. For example, if a
    purchase is about a bundle of products that have no individual prices
-   or product IDs, the product_id or price may not be specified in the
+   or product IDs, the ``product_id`` or ``price`` may not be specified in the
    contract. Similarly, for virtual products delivered directly via the
-   fulfillment URI, there is no delivery location.
+   fulfillment URI, there is no ``delivery_location``.
 
 merchant
    address