003-tos-rendering.rst (4576B)
1 DD 03: ToS rendering 2 #################### 3 4 Summary 5 ======= 6 7 This document describes how terms of service (ToS) as well as other "legal 8 agreement documents" are served, represented and rendered. 9 10 Motivation 11 ========== 12 13 Different exchanges and backup/sync providers each have their custom legal 14 agreement documents. As we don't know all providers and they are not centrally 15 registered anywhere, these documents can't be hardcoded into wallet 16 applications. Instead, these service providers expose endpoints that allow 17 downloading the latest version of these legal agreement documents. 18 19 These documents must be rendered on a variety of platforms in a user-friendly 20 way. 21 22 Proposed Solution 23 ================= 24 25 Internationalization 26 -------------------- 27 28 The server will parse the ``Accept-Languages`` request header to determine 29 which language the user will most likely want to read the terms of service 30 in. If multiple languages are given, the server will check against the 31 available languages and return the one with the highest preference. 32 33 Additionally, the server will return an ``Avail-Languages`` header which 34 details what other langauges the terms of service are available in. The 35 user interface in the wallet should then allow the user to switch to one 36 of these alternatives using some language switcher. 37 38 39 Encoding 40 -------- 41 42 43 The service providers can output legal agreements in various formats, 44 determined via the ``"Accept: "`` request header. The format provider **must** 45 support the ``text/plain`` mime type. The format provider **must** support 46 the ``text/markdown`` mime type. Except for styling and navigation, the 47 content of each format of the same legal agreement document **should** be the 48 same. 49 50 Legal documents with mime type ``text/markdown`` **should** confirm to the 51 `commonmark specification <https://commonmark.org/>`__. 52 53 When wallets render ``text/markdown`` legal documents, they **must** disable 54 embedded HTML rendering. Wallets **may** style the markdown rendering to improve 55 usability. For example, they can make sections collabsible or add a navigation side-bar 56 on bigger screens. 57 58 It is recommended that the ``text/markdown`` document is used as the "master 59 document" for generating the corresponding legal agreement document in other 60 formats. However, service providers can also provide custom versions with more 61 appropriate styling, like a logo in the header of a printable PDF document. 62 63 Markdown Conventions 64 -------------------- 65 66 The ``text/markdown`` document **should** follow 67 the `commonmark spec <https://spec.commonmark.org/0.28/>`__. 68 Main headlines (level 1) and their following content (until the next main headline) 69 will be shown as expandable sections in wallets. 70 71 The document **must** begin with a main headline: 72 73 .. code-block:: 74 75 # First Headline 76 77 or 78 79 .. code-block:: 80 81 First Headline 82 ============== 83 84 Alternatives 85 ============ 86 87 We considered and rejected the following alternatives: 88 89 * Use only plain text. This is not user-friendly, as inline formatting (bold, 90 italic), styled section headers, paragraphs wrapped to the screen size, 91 formatted lists and tables are not supported. 92 93 * Use HTML. This has a variety of issues: 94 95 * Service providers might provide HTML that does not render nicely on the 96 device that our wallet application is running on. 97 * Rendering HTML inside the application poses security risks. 98 99 * Use a strict subset of HTML. This would mean we would have to define some 100 standardized subset that all wallet implementations support, which is too 101 much work. Existing HTML renderers (such as Android's ``Html.fromHTML``) 102 support undocumented subsets that lack features we want, such as ordered 103 lists. Defining our own HTML subset would also make authoring harder, as it 104 forces authors of legal agreement documents to author in our HTML subset, as 105 conversion tools from other format will not generate output in our HTML 106 subset. 107 108 * Use reStructuredText (directly or via Sphinx). This at first looks like an 109 obvious choice for a master format, since Taler is already using reStructuredText 110 for all its documentation. But it doesn't work out well, since the only maintained 111 implementation of a parser/renderer is written in Python. Even with the Python implementation 112 (docutils / Sphinx), we can't convert ``.rst`` to Markdown nicely. 113 114 Drawbacks 115 ========= 116 117 * Markdown parsing / rendering libraries can be relatively large. 118 119 Discussion / Q&A 120 ================ 121 122 * Should the legal agreement endpoints have some mechanism to determine what 123 content types they support?