Merge pull request #953 from daira/easier-math-in-rst

Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math.
zcash · Nov 19, 2024 · f3d5eb0 · f3d5eb0
2 parents 399e638 + 96dafb2
commit f3d5eb0
Show file tree

Hide file tree

Showing 71 changed files with 2,656 additions and 2,365 deletions.
diff --git a/.gitignore b/.gitignore
@@ -20,6 +20,7 @@
 *.save
 *.save.*
 *~
+*.html.temp
 
 .Makefile.uptodate
 .zipfilelist.*

diff --git a/Makefile b/Makefile
@@ -1,5 +1,7 @@
 # Dependencies: see zip-guide.rst and protocol/README.rst
 
+MARKDOWN_OPTION?=--pandoc
+
 .PHONY: all-zips all tag-release protocol all-protocol discard
 all-zips: .Makefile.uptodate
 	echo "$(patsubst zips/%,%,$(sort $(wildcard zips/zip-*.rst) $(wildcard zips/zip-*.md)))" >.zipfilelist.new
@@ -31,30 +33,18 @@ all-specs: all-zips
 discard:
 	git checkout -- 'rendered/*.html' 'README.rst' 'rendered/protocol/*.pdf'
 
-.Makefile.uptodate: Makefile edithtml.sh
+.Makefile.uptodate: Makefile render.sh
 	$(MAKE) clean
 	touch .Makefile.uptodate
 
-define PROCESSRST
-$(eval TITLE := $(shell echo '$(patsubst zips/%,%,$(basename $<))' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
-rst2html5 -v --title="$(TITLE)" $< >$@
-./edithtml.sh --rst $@
-endef
-
-define PROCESSMD
-$(eval TITLE := $(shell echo '$(patsubst zips/%,%,$(basename $<))' | sed -E 's|zip-0{0,3}|ZIP |;s|draft-|Draft |')$(shell grep -E '^(\.\.)?\s*Title: ' $< |sed -E 's|.*Title||'))
-pandoc --from=markdown --to=html $< --output=$@
-./edithtml.sh --md $@ "${TITLE}"
-endef
-
-rendered/index.html: README.rst edithtml.sh
-	$(PROCESSRST)
+rendered/index.html: README.rst render.sh
+	./render.sh --rst $< $@
 
-rendered/%.html: zips/%.rst edithtml.sh
-	$(PROCESSRST)
+rendered/%.html: zips/%.rst render.sh
+	./render.sh --rst $< $@
 
-rendered/%.html: zips/%.md edithtml.sh
-	$(PROCESSMD)
+rendered/%.html: zips/%.md render.sh
+	./render.sh $(MARKDOWN_OPTION) $< $@
 
 README.rst: .zipfilelist.current .draftfilelist.current makeindex.sh README.template $(wildcard zips/zip-*.rst) $(wildcard zips/zip-*.md) $(wildcard zips/draft-*.rst) $(wildcard zips/draft-*.md)
 	./makeindex.sh | cat README.template - >README.rst

diff --git a/edithtml.sh b/edithtml.sh
diff --git a/render.sh b/render.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if ! ( ( [ "x$1" = "x--rst" ] || [ "x$1" = "x--pandoc" ] || [ "x$1" = "x--mmd" ] ) && [ $# -eq 3 ] ); then
+    cat - <<EndOfUsage
+Usage: render.sh --rst|--pandoc|--mmd <inputfile> <htmlfile> <title>
+
+--rst     render reStructuredText using rst2html5
+--pandoc  render Markdown using pandoc
+--mmd     render Markdown using multimarkdown
+EndOfUsage
+    exit
+fi
+
+inputfile="$2"
+outputfile="$3"
+
+if ! [ -f "${inputfile}" ]; then
+    echo "File not found: ${inputfile}"
+    exit
+fi
+
+if [ "x$1" = "x--rst" ]; then
+    filetype='.rst'
+else
+    filetype='.md'
+fi
+title="$(basename -s ${filetype} ${inputfile} | sed -E 's|zip-0{0,3}|ZIP |; s|draft-|Draft |')$(grep -E '^(\.\.)?\s*Title: ' ${inputfile} |sed -E 's|.*Title||')"
+echo "    ${title}"
+
+Math1='<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">'
+Math2='<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>'
+Math3='<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>'
+ViewAndStyle='<meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="css/style.css">'
+
+cat <(
+    if [ "x$1" = "x--rst" ]; then
+        # These are basic regexps so \+ is needed, not +.
+        # We use the Unicode 💲 character to move an escaped $ out of the way,
+        # which is much easier than trying to handle escapes within a capture.
+
+        cat "${inputfile}" \
+        | sed 's|[\][$]|💲|g;
+               s|[$]\([^$]\+\)[$]\([.,:;!?)-]\)|:math:`\1\\!`\2|g;
+               s|[$]\([^$]\+\)[$]|:math:`\1`|g;
+               s|💲|$|g' \
+        | rst2html5 -v --title="${title}" - \
+        | sed "s|<script src=\"http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML\"></script>|${Math1}\n    ${Math2}\n    ${Math3}|;
+               s|</head>|${ViewAndStyle}</head>|"
+    else
+        if [ "x$1" = "x--pandoc" ]; then
+            # Not actually MathJax. KaTeX is compatible if we use the right headers.
+            pandoc --mathjax --from=markdown --to=html "${inputfile}" --output="${outputfile}.temp"
+        else
+            multimarkdown ${inputfile} -o "${outputfile}.temp"
+        fi
+
+        # Both pandoc and multimarkdown just output the HTML body.
+        echo "<!DOCTYPE html>"
+        echo "<html>"
+        echo "<head>"
+        echo "    <title>${title}</title>"
+        echo "    <meta charset=\"utf-8\" />"
+        if grep -q -E 'class="math( inline)?"' "${outputfile}.temp"; then
+            echo "    ${Math1}"
+            echo "    ${Math2}"
+            echo "    ${Math3}"
+        fi
+        echo "    ${ViewAndStyle}"
+        echo "</head>"
+        echo "<body>"
+        cat "${outputfile}.temp"
+        rm -f "${outputfile}.temp"
+        echo "</body>"
+        echo "</html>"
+    fi
+) \
+| sed \
+'s|<a href="[^":]*">Protocol Specification</a>|<span class="lightmode"><a href="https://zips.z.cash/protocol/protocol.pdf">Protocol Specification</a></span>|g;
+ s|\s*<a href="[^":]*">(dark mode version)</a>|<span class="darkmode" style="display: none;"><a href="https://zips.z.cash/protocol/protocol-dark.pdf">Protocol Specification</a></span>|g;
+ s|<a \(class=[^ ]* \)*href="\([^":]*\)\.rst\(\#[^"]*\)*">|<a \1href="\2\3">|g;
+ s|<a \(class=[^ ]* \)*href="\([^":]*\)\.md\(\#[^"]*\)*">|<a \1href="\2\3">|g;
+ s|&lt;\(https:[^&]*\)&gt;|\&lt;<a href="\1">\1</a>\&gt;|g;
+ s|src="../rendered/|src="|g;
+ s|<a href="rendered/|<a href="|g;
+ s|<a \(class=[^ ]* \)*href="zips/|<a \1href="|g' \
+| perl -p0e \
+'s|<section id="([^"]*)">\s*.?\s*<h([1-9])>([^<]*(?:<code>[^<]*</code>[^<]*)?)</h([1-9])>|<section id="\1"><h\2><span class="section-heading">\3</span><span class="section-anchor"> <a rel="bookmark" href="#\1"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h\4>|g' \
+> "${outputfile}"
diff --git a/rendered/css/style.css b/rendered/css/style.css
@@ -296,28 +296,18 @@ pre {
   font-size: 0.9375rem;
 }
 
-span.math {
-  transform: scale(1, 1.03);
-  -moz-transform: scale(1, 1.03);
-  -ms-transform: scale(1, 1.03);
-  -webkit-transform: scale(1, 1.03);
-  -o-transform: scale(1, 1.03);
-  font-size: 0.97rem;
+.katex {
+  font-size: 1.21em;
 }
 
 div.math {
-  transform: scale(1.3, 1.339);
-  -moz-transform: scale(1.3, 1.339);
-  -ms-transform: scale(1.3, 1.339);
-  -webkit-transform: scale(1.3, 1.339);
-  -o-transform: scale(1.3, 1.339);
+  transform: scale(1.42, 1.42);
   display: block;
   overflow-x: auto;
   overflow-y: hidden;
   margin: 2.6rem 1rem 2.6rem 1rem;
   text-align: center;
   padding: 0;
-  font-size: 0.97rem;
 }
 
 a, a:visited {
@@ -344,12 +334,76 @@ span.section-heading:hover + span {
   opacity: 1;
 }
 
-a.footnote_reference::before {
+a.footnote_reference::before, a.footnote-ref::before {
   content: "[";
 }
-a.footnote_reference::after {
+
+a.footnote_reference::after, a.footnote-ref::after {
+  content: "]";
+}
+
+/* {{{ rst-specific */
+#references table, #references th, #references td {
+  border: 0 none transparent;
+  font-size: 1.125rem;
+}
+
+#references table {
+  margin-left: 0;
+  margin-bottom: 0;
+}
+
+#references th {
+  padding-left: 0;
+  width: 1.9em;
+  text-align: right;
+}
+
+#references th::before {
+  content: "[";
+}
+
+#references th::after {
   content: "]";
 }
+/* }}} rst-specific */
+
+/* {{{ md-specific */
+a.footnote-ref sup {
+  vertical-align: baseline;
+  font-size: 100%;
+}
+
+/* pandoc only, not multimarkdown */
+#footnotes ol {
+  margin-top: -3ex;
+}
+
+.footnotes li {
+  margin-top: -0.8ex;
+  margin-left: 1em;
+  list-style-type: md-references;
+}
+
+.footnotes ::marker {
+  font-weight: 600;
+  font-size: 1.125rem;
+}
+
+.footnotes hr {
+  display: none;
+}
+
+.footnote-back::before {
+  content: " ";
+}
+
+@counter-style md-references {
+  system: extends decimal;
+  prefix: "[";
+  suffix: "]     ";
+}
+/* }}} md-specific */
 
 strong, b {
   font-family: 'robotomedium',Arial,Helvetica Neue,Helvetica,sans-serif;
@@ -361,7 +415,6 @@ hr {
   margin: 1.875rem 0;
 }
 
-
 table {
   border-collapse: collapse;
   border: 0 none transparent;
@@ -399,22 +452,6 @@ td:first-child {
   padding-bottom: 0.4rem;
 }
 
-#references table, #references th, #references td {
-  border: 0 none transparent;
-  font-size: 1.125rem;
-}
-
-#references table {
-  margin-bottom: 0;
-}
-
-#references th::before {
-  content: "[";
-}
-#references th::after {
-  content: "]";
-}
-
 @media (max-width: 576px) {
   table:not(.footnote) {
       display: block;