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

1 files changed, 51 insertions, 39 deletions

diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 1449c9f8..33e0f8e5 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -78,16 +78,18 @@ Architecture overview
 The Taler software stack for a merchant consists of the following main
 components:
 
--  frontend
-   A frontend which interacts with the customer’s browser. The frontend
+.. index:: frontend
+
+-  A frontend which interacts with the customer’s browser. The frontend
    enables the customer to build a shopping cart and place an order.
    Upon payment, it triggers the respective business logic to satisfy
    the order. This component is not included with Taler, but rather
    assumed to exist at the merchant. This tutorial describes how to
    develop a Taler frontend.
 
--  backend
-   A Taler-specific payment backend which makes it easy for the frontend
+.. index:: backend
+
+-  A Taler-specific payment backend which makes it easy for the frontend
    to process financial transactions with Taler. For this tutorial, you
    will use a public sandbox backend. For production use, you must
    either set up your own backend or ask another person to do so for
@@ -210,7 +212,7 @@ 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 read the :doc:`core/api-merchant` reference
 manual for details.
 
 A minimal Python snippet for creating an order would look like this:
@@ -269,8 +271,7 @@ Given the order ID, the status of a payment can be checked with the
 by the customer, ``/private/orders/$ORDER_ID`` will give the frontend a URL
 (under the name ``payment_redirect_url``) that will trigger the customer’s
 wallet to execute the payment. This is basically the
-``https://example.com/orders/$ORDER_ID/`` URL we discussed above. Note
-that
+``https://example.com/orders/$ORDER_ID/`` URL we discussed above.
 
 Note that the best way to obtain the ``payment_redirect_url`` is to check the
 status of the payment, even if you know that the user did not pay yet.  There
@@ -379,7 +380,7 @@ may then want to read it on a different device, possibly one that
 does not even have a Taler wallet installed.
 
 Naturally, at this point the customer would at first still be prompted to pay
-for the article again. If the customer then opens the taler://-link in the
+for the article again. If the customer then opens the ``taler://`` link in the
 wallet that did previously pay for the article (for example by scanning the QR
 code on the desktop with the Android App), the wallet will claim the contract,
 detect that the fulfillment URL is identical to one that it already has made a
@@ -493,7 +494,7 @@ be paid for exactly the same product by each customer. Taler supports
 this model by allowing the mechant to check whether the “payment
 receipt” is available on the user’s current device. This prevents users
 from easily sharing media access by transmitting a link to the
-fulfillment page. Of course sophisticated users could share payment
+fulfillment page. Of course, sophisticated users could share payment
 receipts as well, but this is not as easy as sharing a link, and in this
 case they are more likely to just share the media directly.
 
@@ -550,74 +551,84 @@ describes each of the fields in depth.
 Financial amounts are always specified as a string in the format
 ``"CURRENCY:DECIMAL_VALUE"``.
 
+.. index:: amount
 
 amount
    Specifies the total amount to be paid to the merchant by the
    customer.
-   .. index:: amount
+
+.. index:: fees
+.. index:: maximum deposit fee
 
 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.
-   .. index:: fees
-   .. index:: maximum deposit fee
+   specified using the same triplet used for ``amount``.
+
+.. index:: fees
+.. index:: maximum wire fee
 
 max_wire_fee
    Maximum wire fee accepted by the merchant (customer share to be
-   divided by the ’wire_fee_amortization’ factor, and further reduced if
-   deposit fees are below ’max_fee’). Default if missing is zero.
-   .. index:: fees
-   .. index:: maximum wire fee
+   divided by the ``wire_fee_amortization`` factor, and further reduced if
+   deposit fees are below ``max_fee``). Default if missing is zero.
+
+.. index:: fees
+.. index:: maximum fee amortization
 
 wire_fee_amortization
    Over how many customer transactions does the merchant expect to
    amortize wire fees on average? If the exchange’s wire fee is above
-   ’max_wire_fee’, the difference is divided by this number to compute
+   ``max_wire_fee``, the difference is divided by this number to compute
    the expected customer’s contribution to the wire fee. The customer’s
    contribution may further be reduced by the difference between the
-   ’max_fee’ and the sum of the actual deposit fees. Optional, default
-   value if missing is 1. 0 and negative values are invalid and also
+   ``max_fee`` and the sum of the actual deposit fees. Optional, default
+   value if missing is 1. Zero and negative values are invalid and also
    interpreted as 1.
-   .. index:: fees
-   .. index:: maximum fee amortization
+
+.. index:: pay_url
 
 pay_url
    Which URL accepts payments. This is the URL where the wallet will
    POST coins.
-   .. index:: pay_url
+
+.. index:: fulfillment URL
 
 fulfillment_url
    Which URL should the wallet go to for obtaining the fulfillment, for
    example the HTML or PDF of an article that was bought, or an order
    tracking system for shipments, or a simple human-readable Web page
    indicating the status of the contract.
-   .. index:: fulfillment URL
+
+.. index:: order ID
 
 order_id
    Alphanumeric identifier, freely definable by the merchant. Used by
    the merchant to uniquely identify the transaction.
-   .. index:: order ID
+
+.. index:: summary
 
 summary
    Short, human-readable summary of the contract. To be used when
    displaying the contract in just one line, for example in the
    transaction history of the customer.
-   .. index:: summary
 
 timestamp
    Time at which the offer was generated.
 
+.. index:: payment deadline
+
 pay_deadline
    Timestamp of the time by which the merchant wants the exchange to
    definitively wire the money due from this contract. Once this
    deadline expires, the exchange will aggregate all deposits where the
-   contracts are past the refund_deadline and execute one large wire
+   contracts are past the ``refund_deadline`` and execute one large wire
    payment for them. Amounts will be rounded down to the wire transfer
    unit; if the total amount is still below the wire transfer unit, it
    will not be disbursed.
-   .. index:: payment deadline
+
+.. index:: refund deadline
 
 refund_deadline
    Timestamp until which the merchant willing (and able) to give refunds
@@ -625,24 +636,24 @@ refund_deadline
    the payment in escrow at least until this deadline. Until this time,
    the merchant will be able to sign a message to trigger a refund to
    the customer. After this time, it will no longer be possible to
-   refund the customer. Must be smaller than the pay_deadline.
-   .. index:: refund deadline
+   refund the customer. Must be smaller than the ``pay_deadline``.
+
+.. index:: product description
 
 products
    Array of products that are being sold to the customer. Each entry
    contains a tuple with the following values:
-   .. index:: product description
 
    description
       Description of the product.
 
    quantity
-      Quantity of the items to be shipped. May specify a unit (``1 kg``)
+      Quantity of the items to be shipped. May specify a unit (e.g. ``1 kg``)
       or just the count.
 
    price
       Price for quantity units of this product shipped to the given
-      delivery_location. Note that usually the sum of all of the prices
+      ``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
       unavailable.
@@ -678,7 +689,7 @@ products
 
 merchant
    address
-      This should give a label in the locations map, specifying where
+      This should give a label in the ``locations`` map, specifying where
       the merchant is located.
 
    name
@@ -686,9 +697,11 @@ merchant
       business.
 
    jurisdiction
-      This should give a label in the locations map, specifying the
+      This should give a label in the ``locations`` map, specifying the
       jurisdiction under which this contract is to be arbitrated.
 
+.. index:: location
+
 locations
    Associative map of locations used in the contract. Labels for
    locations in this map can be freely chosen and used whenever a
@@ -697,17 +710,16 @@ locations
    the customer or the merchant), it only needs to be listed (and
    transmitted) once, and can otherwise be referred to via the label. A
    non-exhaustive list of location attributes is the following:
-   .. index:: location
 
    name
-      receiver name for delivery, either business or person name.
+      Receiver name for delivery, either business or person name.
 
    country
       Name of the country for delivery, as found on a postal package,
-      i.e. “France”.
+      e.g. “France”.
 
    state
-      Name of the state for delivery, as found on a postal package, i.e.
+      Name of the state for delivery, as found on a postal package, e.g.
       “NY”.
 
    region