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
----------------------