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