general documentation works

6 files changed, 123 insertions, 64 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index b095186e..ff347979 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -21,7 +21,7 @@
 Merchant API
 ============
 
-Before reading the API reference documentation, it is suggested to read the :ref:`merchant-arch`
+Before reading the API reference documentation, see the :ref:`merchant architecture<merchant-arch>` and :ref:`payprot`
 
 ---------------------
 The Frontent HTTP API
@@ -49,8 +49,7 @@ The Frontent HTTP API
 
 
   Send the deposit permission to the merchant. The client should POST a `deposit-permission`_
-  object. Note that ``pay_url`` is make known by the frontent to the wallet via the DOM event
-  ``taler-execute-payment``, documented in :ref:`byoffer`.
+  object.
 
   .. _deposit-permission:
   .. code-block:: tsref
@@ -110,7 +109,7 @@ The Frontent HTTP API
 
       // the signature made by the coin's private key on a `struct TALER_DepositRequestPS`. See section `Signatures` on the exchange's API page.
       coin_sig: EddsaSignature;
-  }
+    }
 
   **Success Response:**
 
@@ -214,7 +213,7 @@ The following API are made available by the merchant's `backend` to the merchant
 
   :status 200 OK:
     The wire transfer is known to the exchange, details about it follow in the body.
-    The body of the response is a `TrackTransferResponse`_.  Note that
+    The body of the response is a :ref:`TrackTransactionResponse <TrackTransferResponse>`.  Note that
     the similarity to the response given by the exchange for a /track/transfer
     is completely intended.
 
@@ -240,7 +239,7 @@ The following API are made available by the merchant's `backend` to the merchant
     The deposit request has been accepted for processing, but was not yet
     executed.  Hence the exchange does not yet have a wire transfer identifier.
     The merchant should come back later and ask again.
-    The response body is a `TrackTransactionAcceptedResponse`_.  Note that
+    The response body is a :ref:`TrackTransactionAcceptedResponse <TrackTransactionAcceptedResponse>`.  Note that
     the similarity to the response given by the exchange for a /track/transaction
     is completely intended.
 
@@ -287,9 +286,9 @@ Data such as dates, binary blobs, and other useful formats, are encoded as descr
 
 .. _instances:
 
-------------------
-Merchant Instances
-------------------
+------------------------------------------
+Merchant Instances (To be moved elsewhere)
+------------------------------------------
 
 Any backend can account for multiple bank accounts, and we call `instance` or `receiver` (interchangeably)
 any of those bank accounts. The backend needs that due to the ability we give to a merchant to route money
diff --git a/dev-exchange.rst b/dev-exchange.rst
new file mode 100644
index 00000000..4ca913ae
--- /dev/null
+++ b/dev-exchange.rst
@@ -0,0 +1,44 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU General Public License as published by the Free Software
+  Foundation; either version 2.1, or (at your option) any later version.
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+  You should have received a copy of the GNU Lesser General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Christian Grothoff
+
+========
+Exchange
+========
+
+------------
+Introduction
+------------
+TBD
+
+.. _keys:
+
+----
+Keys
+----
+TBD (do mention "starting date")
+
+---------------
+Database Scheme
+---------------
+
+The exchange database must be initialized using `taler-exchange-dbinit`.  This
+tool creates the tables required by the Taler exchange to operate.  The
+tool also allows you to reset the Taler exchange database, which is useful
+for test cases but should never be used in production.  Finally,
+`taler-exchange-dbinit` has a function to garbage collect a database,
+allowing administrators to purge records that are no longer required.
+
+The database scheme used by the exchange look as follows:
+
+.. image:: exchange-db.png
diff --git a/dev-merchant.rst b/dev-merchant.rst
new file mode 100644
index 00000000..bb809128
--- /dev/null
+++ b/dev-merchant.rst
@@ -0,0 +1,40 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU General Public License as published by the Free Software
+  Foundation; either version 2.1, or (at your option) any later version.
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+  You should have received a copy of the GNU Lesser General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Marcello Stanisci
+
+========
+Merchant
+========
+
+------------
+Introduction
+------------
+TBD
+
+.. _merchant-arch:
+------
+Design
+------
+
+TO REVIEW::
+
+  The `frontend` is the existing shopping portal of the merchant.
+  The architecture tries to minimize the amount of modifications necessary
+  to the `frontend` as well as the trust that needs to be placed into the
+  `frontend` logic.  Taler requires the frontend to facilitate two
+  JSON-based interactions between the wallet and the `backend`, and
+  one of those is trivial.
+  
+  The `backend` is a standalone C application intended to implement all
+  the cryptographic routines required to interact with the Taler wallet
+  and a Taler exchange.
diff --git a/impl-exchange.rst b/impl-exchange.rst
index 85d7aa95..7cd51ac7 100644
--- a/impl-exchange.rst
+++ b/impl-exchange.rst
@@ -134,10 +134,9 @@ Sections specifying denomination (coin) information start with "coin\_".  By con
 Univarsal keys duration
 -----------------------
 
-Each key, regardless of whether it is a `signkey` or a `denom key`, has a starting date (FIXME needed elsewhere a paragraph on keys and
-how their starting time is calculated).
-The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys younger than `lookahead_provide` will be
-issued by the exchange.
+Each key, regardless of whether it is a `signkey` or a `denom key`, has a :ref:`starting date <keys>`.
+The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys whose starting date is younger than
+`lookahead_provide` will be issued by the exchange.
 
 +++++++++
 Utilities
@@ -149,33 +148,3 @@ Reserve management
 
 Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their withdrawal key.
 The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.
-
-++++++
-Design
-++++++
-
----------------
-Database Scheme
----------------
-
-The exchange database must be initialized using `taler-exchange-dbinit`.  This
-tool creates the tables required by the Taler exchange to operate.  The
-tool also allows you to reset the Taler exchange database, which is useful
-for test cases but should never be used in production.  Finally,
-`taler-exchange-dbinit` has a function to garbage collect a database,
-allowing administrators to purge records that are no longer required.
-
-The database scheme used by the exchange look as follows:
-
-.. image:: exchange-db.png
-
-
-------------------
-Key Storage Format
-------------------
-
-The exchange's key directory contains the two subdirectories `signkeys` and `coinkeys`.
-
-The directory `signkeys` contains signkey files, where the name is the start date of the respective key.
-
-The `coinkeys` directory additionaly contains a subdirectory for each coin type alias.  These contain coinkey files, where the name is again the start timestamp of the respective key.
diff --git a/impl-merchant.rst b/impl-merchant.rst
index a4b6be42..1a6271ee 100644
--- a/impl-merchant.rst
+++ b/impl-merchant.rst
@@ -13,29 +13,35 @@
   @author Marcello Stanisci
   @author Florian Dold
 
-=================================
-Merchant Reference Implementation
-=================================
+==============================
+Operating the Merchant Backend
+==============================
 
-.. _merchant-arch:
++++++++++++++
+Configuration
++++++++++++++
 
------------------------
-Architectural Overview
------------------------
+The following data and facilities have to be set up, in order to run an exchange:
 
-NOTE: this paragraph mirrors the (initial) one in the merchant's API
-section.
+* Keying
+* Currency
+* Database
+* Instances
+* Exchanges
 
-The merchant reference implementationis divided into two independent
-compontents, the `frontend` and the `backend`.
+===============================
+Operating the Merchant Frontend
+===============================
 
-The `frontend` is the existing shopping portal of the merchant.
-The architecture tries to minimize the amount of modifications necessary
-to the `frontend` as well as the trust that needs to be placed into the
-`frontend` logic.  Taler requires the frontend to facilitate two
-JSON-based interactions between the wallet and the `backend`, and
-one of those is trivial.
+Do we really want to keep this in a "how to run a Taler component" section?
+A merchant FE is not really a Taler 'component'.
 
-The `backend` is a standalone C application intended to implement all
-the cryptographic routines required to interact with the Taler wallet
-and a Taler exchange.
++++++++++++++
+Configuration
++++++++++++++
+
+The following data and facilities have to be set up, in order to run an exchange:
+
+* Backend
+* Refund deadline
+* Instances
diff --git a/index.rst b/index.rst
index 1463375d..15b06e0f 100644
--- a/index.rst
+++ b/index.rst
@@ -104,7 +104,8 @@ core components of the Taler reference implementation.
   :maxdepth: 2
 
   dev-wallet-wx
-
+  dev-exchange
+  dev-merchant
 
 ------------------
 Indices and tables