edits and comments on essay store example, #4169

1 files changed, 22 insertions, 7 deletions

diff --git a/example-essay-store.rst b/example-essay-store.rst
index a780cdc2..ccbf7b5f 100644
--- a/example-essay-store.rst
+++ b/example-essay-store.rst
@@ -1,12 +1,16 @@
 ..
   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/>
 
@@ -27,16 +31,27 @@ This demonstrator's code is hosted at `git://taler.net/merchant-frontends/talerf
 implemented in Python.
 
 The essay store, available at https://blog.demo.taler.net, is such that its homepage
-is a list of titles from buyable articles and each title links to an `offering URL`. 
-In particular, the offering URL has the following format:
+is a list of titles from buyable articles and each title links to an `offer URL`.
+In particular, the offer URLs have the following format:
 
   `https://blog.demo.taler.net/essay/article_title`
 
-As for the fulfillment URL, it matches the initial part of an offering URL, but contains also
-those parameters needed to reconstruct the contract, which are `tid` (transaction id) and `timestamp`.
-So a fulfillment URL looks like:
+The offer URLs trigger the expected interaction with the wallet.
+  FIXME: describe where the contract is generated!
+  FIXME: give the pay URL.
+
+For the essay store, the fulfillment URL matches the initial part of
+an offering URL, but contains the additional parameters needed to
+reconstruct the contract, in this case the `tid` (transaction id) and
+a `timestamp`. Hence, a fulfillment URL for the essay store looks like:
 
   `https://blog.demo.taler.net/essay/article_title?tid=3489&timestamp=8374738`
 
-We did not need to include any further details in the fulfillment URL because most of them
-do not change in the time, and for simplicity all the articles have the same price.
+This is sufficient for the simple essay store, as we do not need any further
+details to reconstruct the contract.  In particular, the essay store
+assumes for simplicity that all the articles have the same price forever.
+
+We note that Taler does not require that offer and fulfillment URL
+have this kind of relationship. In fact, it is perfectly acceptable
+for the fulfillment URL to be hosted on a different server under a
+differnt domain name.