[taler-docs] branch master updated: tos rendering design doc

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new f88e32c  tos rendering design doc
f88e32c is described below

commit f88e32c24f218e00db6334920421cd305f077421
Author: Florian Dold <address@hidden>
AuthorDate: Thu Apr 23 16:17:08 2020 +0530

    tos rendering design doc
---
 design-documents/000-template.rst      | 23 +++++++++-
 design-documents/003-tos-rendering.rst | 84 ++++++++++++++++++++++++++++++++++
 design-documents/index.rst             |  1 +
 3 files changed, 107 insertions(+), 1 deletion(-)

diff --git a/design-documents/000-template.rst 
b/design-documents/000-template.rst
index c969f86..f620248 100644
--- a/design-documents/000-template.rst
+++ b/design-documents/000-template.rst
@@ -1,4 +1,25 @@
 Template
 ########
 
-FIXME: define template
+Summary
+=======
+
+Motivation
+==========
+
+Requirements
+============
+
+Proposed Solution
+=================
+
+Alternatives
+============
+
+Drawbacks
+=========
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / 
personal communication.)
diff --git a/design-documents/003-tos-rendering.rst 
b/design-documents/003-tos-rendering.rst
new file mode 100644
index 0000000..c945654
--- /dev/null
+++ b/design-documents/003-tos-rendering.rst
@@ -0,0 +1,84 @@
+Design Doc 003: ToS rendering
+#############################
+
+Summary
+=======
+
+This document describes how terms of service (ToS) as well as other "legal
+agreement documents" are served, represented and rendered.
+
+Motivation
+==========
+
+Different exchanges and backup/sync providers each have their custom legal
+agreement documents.  As we don't know all providers and they are not centrally
+registered anywhere, these documents can't be hardcoded into wallet
+applications.  Instead, these service providers expose endpoints that allow
+downloading the latest version of these legal agreement documents.
+
+These documents must be rendered on a variety of platforms in a user-friendly
+way.
+
+Proposed Solution
+=================
+
+The service providers can output legal agreements in various formats,
+determined via the ``"Accept: "`` request header.  The format provider **must**
+support the ``text/plain`` mime type.  The format provider **should** support
+the ``text/markdown`` mime type.  Except for styling and navigation, the
+content of each format of the same legal agreement document **should** be the
+same.
+
+Legal documents with mime type ``text/markdown`` **should** confirm to the
+`commonmark specification <https://commonmark.org/>`__.
+
+When wallets render ``text/markdown`` legal documents, they **must** disable
+embedded HTML rendering.  Wallets **may** style the markdown rendering to 
improve
+usability.  For example, they can make sections collabsible or add a 
nagivation side-bar
+on bigger screens.
+
+It is recommended that the ``text/markdown`` document is used as the "master
+document" for generating the corresponding legal agreement document in other
+formats.  However, service providers can also provide custom versions with more
+appropriate styling, like a logo in the header of a printable PDF document.
+
+Alternatives
+============
+
+We considered and rejected the following alternatives:
+
+* Use only plain text.  This is not user-friendly, as inline formatting (bold,
+  italic), styled section headers, paragraphs wrapped to the screen size,
+  formatted lists and tables are not supported.
+
+* Use HTML.  This has a variety of issues:
+
+  * Service providers might provide HTML that does not render nicely on the
+    device that our wallet application is running on.
+  * Rendering HTML inside the application poses security risks.
+
+* Use a strict subset of HTML.  This would mean we would have to define some
+  standardized subset that all wallet implementations support, which is too
+  much work.  Existing HTML renderers (such as Android's ``Html.fromHTML``)
+  support undocumented subsets that lack features we want, such as ordered
+  lists.  Defining our own HTML subset would also make authoring harder, as it
+  forces authors of legal agreement documents to author in our HTML subset, as
+  conversion tools from other format will not generate output in our HTML
+  subset.
+
+* Use reStructuredText (directly or via Sphinx).  This at first looks like an
+  obvious choice for a master format, since Taler is already using 
reStructuredText
+  for all its documentation.  But it doesn't work out well, since the only 
maintained
+  implementation of a parser/renderer is written in Python.  Even with the 
Python implementation
+  (docutils / Sphinx), we can't convert ``.rst`` to Markdown nicely.
+
+Drawbacks
+=========
+
+* Markdown parsing / rendering libraries can be relatively large.
+
+Discussion / Q&A
+================
+
+* Should the legal agreement endpoints have some mechanism to determine what
+  content types they support?
diff --git a/design-documents/index.rst b/design-documents/index.rst
index 609cc2d..4f3732a 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -12,3 +12,4 @@ and protocol.
   000-template
   001-new-browser-integration  
   002-wallet-exchange-management
+  003-tos-rendering

-- 
To stop receiving notification emails like this one, please contact
address@hidden.