From c1881dfa27515c5f79cd6f95803f2a6c6764c837 Mon Sep 17 00:00:00 2001 From: Daira Emma Hopwood Date: Wed, 27 Sep 2023 20:05:41 +0100 Subject: [PATCH] Add support for notes and warnings. There is currently a bug that will cause them to be rendered incorrectly if they have only one paragraph, but that doesn't matter for the usage in this PR. Signed-off-by: Daira Emma Hopwood --- css/style.css | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++ zip-guide.html | 10 +++++++ zip-guide.rst | 19 +++++++++++++ 3 files changed, 103 insertions(+) diff --git a/css/style.css b/css/style.css index f730ee31..deb7e43e 100644 --- a/css/style.css +++ b/css/style.css @@ -18,6 +18,29 @@ #index-of-zips table tr:hover { background-color: #eff1f2; } + aside.note { + background-color: #a0a0ff; + color: #111519; + } + aside.note::before { + background-color: #5858ff; + color: #000000; + } + aside.warning { + background-color: #ffb090; + color: #111519; + font-weight: 500; + } + aside.warning::before { + background-color: #ff7050; + font-weight: 600; + } + aside > p > a, a:visited { + color: #0077a1; + } + aside > p > a:hover { + color: #00455c; + } } @media (prefers-color-scheme: dark) { @@ -46,6 +69,57 @@ #index-of-zips table tr:hover { background-color: #303030; } + aside.note { + background-color: #6060e0; + color: #ffffff; + } + aside.note::before { + background-color: #3030e0; + } + aside.warning { + background-color: #e08060; + color: #ffffff; + font-weight: 700; + } + aside.warning::before { + background-color: #e05030; + font-weight: 800; + } + aside > p > a, a:visited { + color: #50e7f4; + } + aside > p > a:hover { + color: #90ffff; + } +} + +aside { + display: flex; + flex-direction: column; + gap: 1em; + padding-top: 0.15rem; + padding-left: 0.15rem; + padding-right: 0.15rem; + padding-bottom: 0; + margin-bottom: 1.5rem; +} +aside::before { + font-size: 130%; + padding-top: 0.2rem; + padding-left: 1rem; + padding-right: 0.2rem; + padding-bottom: 0.3rem; + margin-bottom: 1.2rem; +} +aside.note::before { + content: "Note"; +} +aside.warning::before { + content: "Warning"; +} +aside > p { + padding-left: 1rem; + padding-right: 1rem; } @font-face { diff --git a/zip-guide.html b/zip-guide.html index 4888799e..6244d08c 100644 --- a/zip-guide.html +++ b/zip-guide.html @@ -84,6 +84,16 @@ Pull-Request: <https://githu , so you will need to double-check that the rendering is as intended.

In general the conventions in the Zcash protocol specification SHOULD be followed. If you find this difficult, don't worry too much about it in initial drafts; the ZIP editors will catch any inconsistencies in review.

+

Notes and warnings

+ + +

Valid reStructuredText

This is optional before publishing a PR, but to check whether a document is valid reStructuredText, first install rst2html5. E.g. on Debian-based distros:

sudo apt install python3-pip pandoc perl sed
diff --git a/zip-guide.rst b/zip-guide.rst
index 847b1e62..1b87b2a2 100644
--- a/zip-guide.rst
+++ b/zip-guide.rst
@@ -160,6 +160,25 @@ In general the conventions in the Zcash protocol specification SHOULD be followe
 If you find this difficult, don't worry too much about it in initial drafts; the
 ZIP editors will catch any inconsistencies in review.
 
+Notes and warnings
+------------------
+
+.. note::
+    "``.. note::``" in reStructuredText, or "``:::info``" (terminated by
+    "``:::``") in Markdown, can be used for an aside from the main text.
+
+    The rendering of notes is colourful and may be distracting, so they should
+    only be used for important points.
+
+.. warning::
+    "``.. warning::``" in reStructuredText, or "``:::warning``" (terminated by
+    "``:::``") in Markdown, can be used for warnings.
+
+    Warnings should be used very sparingly — for example to signal that a
+    entire specification, or part of it, may be inapplicable or could cause
+    significant interoperability or security problems. In most cases, a "MUST"
+    or "SHOULD" conformance requirement is more appropriate.
+
 Valid reStructuredText
 ----------------------