Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. #953

daira · 2024-11-08T14:31:48Z

Make the style of reference links and references (almost) consistent between Markdown and reStructuredText.
The $...$ syntax can now be —and is— used in rST, except in tables and headings. fixes Make $...$ work in reStructuredText ZIPs #952

The reason why $...$ doesn't work in general for tables and headings is that replacing it with :math:`...` throws off the column-sensitive markup. Things like that are why column-sensitive markup is a bad idea.
In most cases when using $...$ followed by a punctuation mark, there is no need to manually correct spacing (in either rST or Markdown). The render.sh script does it automatically if required. This does not apply to :math:`...`.
Math is rendered using KaTeX instead of MathJax. fixes Switch from MathJax to KaTeX for ZIP rendering #432, fixes The size of rendered math in ZIPs is inconsistent between reloads #375
The rendering of math from Markdown is greatly improved. Previously it could only handle simple expressions that could be rendered at low quality as text; now it supports everything that KaTeX supports, and the quality of rendering is consistent (if not quite up to pdflatex standards).
This PR is also preparation for switching to MultiMarkdown. MultiMarkdown fixes the duplicate reference bug (References are duplicated in the rendering of Markdown ZIPs #893) and also has some nice features like colspan in tables (use $n$ | characters on the right-hand-side of a table entry to make it span $n$ columns).

daira · 2024-11-08T14:32:38Z

This should be merged after #951 [edit: which is now merged].

daira · 2024-11-08T23:16:47Z

When reviewing this, please also check how reference links and the References section look after the CSS changes. That might vary between browsers; I only tested desktop Firefox (115.1.0esr) and Chromium (124.0.6367.118) on Debian. It's difficult to test mobile without having GitHub Pages rendering of PRs.

daira · 2024-11-10T16:18:17Z

render.sh

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


Yes I had to add --mathjax (relative to the pandoc command that was previously in the Makefile) as part of switching from MathJax to KaTeX. That's because KaTeX is compatible with MathJax's representation of math spans as:

<span class="math">$latex code$</span>

(class="math inline" also works.) Previously the $ $ delimiters were not being added by pandoc; that's what the --mathjax option does. multimarkdown adds them without an explicit option.

daira · 2024-11-10T19:03:04Z

This PR is also preparation for switching to MultiMarkdown. MultiMarkdown fixes the duplicate reference bug (References are duplicated in the rendering of Markdown ZIPs #893) and also has some nice features like colspan in tables (use $n$ | characters on the right-hand-side of a table entry to make it span $n$ columns).

The reason why I didn't just immediately switch to MultiMarkdown in this PR, is that it is not packaged for Linux distributions. It has to be built from source (requiring CMake, for the current version). The build is pretty straightforward though, so I'll switch the default once I've added it to the docker image and added some documentation.

…tent between Markdown and reStructuredText. (This also anticipates a possible switch from Pandoc to Multimarkdown; the changes are designed to work with both.) Signed-off-by: Daira-Emma Hopwood <[email protected]>

Signed-off-by: Daira-Emma Hopwood <[email protected]>

(zip-guide *incorrectly* said that we were already using KaTeX. This has been wrong since zcash#645.) Signed-off-by: Daira-Emma Hopwood <[email protected]>

Signed-off-by: Daira-Emma Hopwood <[email protected]>

This supports MultiMarkdown as well as Pandoc, using `make MARKDOWN_OPTION=--mmd` Signed-off-by: Daira-Emma Hopwood <[email protected]>

Signed-off-by: Daira-Emma Hopwood <[email protected]>

nuttycom

utACK with minor questions

nuttycom · 2024-11-09T21:24:59Z

preprocessrst.sh

+# which is much easier than trying to handle escapes within a capture;
+# I don't even know if the latter is possible.
+
+sed 's|[\][$]|💲|g' "$1" | sed 's|[$]\([^$]\+\)[$]|:math:`\1`|g' | sed 's|💲|$|g'


Clever approach!

nuttycom · 2024-11-16T00:11:24Z

zips/zip-0203.rst

+If the expiry is at block height $N\!$, then the transaction must be included in block
 $N$ or earlier. Block $N+1$ will be too late, and the transaction will be
 removed from the mempool.

 The new consensus rule will enforce that the transaction will not be considered valid if
-included in block of height greater than $N$, and blocks that include expired
+included in block of height greater than $N\!$, and blocks that include expired


Why the additions of \! here? Elsewhere in this commit I've seen a bunch of removals, and I'm not sure what the change means.

nuttycom · 2024-11-16T00:13:16Z

zips/zip-0225.rst

@@ -145,15 +145,15 @@ Transaction Format
 |``1``                        |``flagsOrchard``          |``byte``                                |An 8-bit value representing a set of flags. Ordered from LSB to MSB: |
 |                             |                          |                                        | * ``enableSpendsOrchard``                                           |
 |                             |                          |                                        | * ``enableOutputsOrchard``                                          |
-|                             |                          |                                        | * The remaining bits are set to ``0``.                              |
+|                             |                          |                                        | * The remaining bits are set to :math:`0\!`.                        |


Why are these still using :math: instead of $...$ ?

nuttycom · 2024-11-16T00:13:32Z

zips/zip-0225.rst

 +-----------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------+
 |``8``                        |``valueBalanceOrchard``   |``int64``                               |The net value of Orchard spends minus outputs.                       |
 +-----------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------+
 |``32``                       |``anchorOrchard``         |``byte[32]``                            |A root of the Orchard note commitment tree at some block             |
 |                             |                          |                                        |height in the past.                                                  |
 +-----------------------------+--------------------------+----------------------------------------+---------------------------------------------------------------------+
 |``varies``                   |``sizeProofsOrchard``     |``compactSize``                         |Length in bytes of ``proofsOrchard``. Value is                       |
-|                             |                          |                                        |:math:`2720 + 2272 \cdot \mathtt{nActionsOrchard}`.                  |
+|                             |                          |                                        |:math:`2720 + 2272 \cdot \mathtt{nActionsOrchard}\!`.                |


Same question.

nuttycom · 2024-11-16T00:42:50Z

zips/zip-0227.rst

 From the Asset Digest, we derive a specific Asset Base within each shielded protocol using the applicable hash-to-curve algorithm. This Asset Base is included in shielded notes.

 Let

 - $\mathsf{asset\_desc}$ be the asset description, which includes any information pertaining to the issuance, and is a byte sequence of up to 512 bytes which SHOULD be a well-formed UTF-8 code unit sequence according to Unicode 15.0.0 or later.
 - $\mathsf{ik}$ be the issuance validating key of the issuer, a public key used to verify the signature on the issuance transaction's SIGHASH.

-Define $\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{"ZSA-Asset-Digest"},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))\!$,
+Define $\mathsf{AssetDigest_{AssetId}} := \textsf{BLAKE2b-512}(\texttt{“ZSA-Asset-Digest”},\; \mathsf{EncodeAssetId}(\mathsf{AssetId}))$,


Unicode quotes like this are a little annoying; unless you have the correct editor they're a challenge to work with.

daira marked this pull request as draft November 8, 2024 14:32

daira force-pushed the easier-math-in-rst branch from 76e676a to 7d04605 Compare November 8, 2024 20:11

daira marked this pull request as ready for review November 8, 2024 20:12

daira requested a review from str4d November 8, 2024 20:15

daira force-pushed the easier-math-in-rst branch from 7d04605 to 4e905e4 Compare November 8, 2024 23:00

daira requested a review from nuttycom November 8, 2024 23:10

daira force-pushed the easier-math-in-rst branch from 4e905e4 to cb9a900 Compare November 9, 2024 12:29

daira changed the title ~~Easier math in reStructuredText~~ Easier math in reStructuredText; make references consistent between Markdown and rST Nov 9, 2024

daira changed the title ~~Easier math in reStructuredText; make references consistent between Markdown and rST~~ Make references consistent between Markdown and rST, and allow $...$ for inline math in rST Nov 9, 2024

daira force-pushed the easier-math-in-rst branch from cb9a900 to 976d268 Compare November 9, 2024 21:02

daira added S-scratching-an-itch Status: Something we haven't planned for a sprint but are doing anyway ZIP rendering labels Nov 9, 2024

daira changed the title ~~Make references consistent between Markdown and rST, and allow $...$ for inline math in rST~~ Various improvements in the rendering of math and references. rSt now supports $...$ for inline math. Nov 9, 2024

daira mentioned this pull request Nov 9, 2024

References are duplicated in the rendering of Markdown ZIPs #893

Open

daira force-pushed the easier-math-in-rst branch 2 times, most recently from f472b90 to a9fc3ae Compare November 9, 2024 22:36

daira mentioned this pull request Nov 9, 2024

The size of rendered math in ZIPs is inconsistent between reloads #375

Open

daira force-pushed the easier-math-in-rst branch 3 times, most recently from 7e35f12 to 7c2bd6c Compare November 10, 2024 04:56

daira changed the title ~~Various improvements in the rendering of math and references. rSt now supports $...$ for inline math.~~ Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. Nov 10, 2024

daira force-pushed the easier-math-in-rst branch from 7c2bd6c to 00e90e7 Compare November 10, 2024 12:34

daira commented Nov 10, 2024

View reviewed changes

daira added 4 commits November 12, 2024 19:47

ZIP 225: use math in some tables.

d5d9643

Signed-off-by: Daira-Emma Hopwood <[email protected]>

ZIPs 231, 234, 235: Minor formatting and reference fixes.

70ed5c5

Signed-off-by: Daira-Emma Hopwood <[email protected]>

Support $...$ for inline math in reStructuredText.

49f2555

Signed-off-by: Daira-Emma Hopwood <[email protected]>

daira added 5 commits November 12, 2024 19:49

Use $...$ for inline math in existing reStructuredText ZIPs.

ba09951

Signed-off-by: Daira-Emma Hopwood <[email protected]>

Switch from MathJax to KaTeX. fixes zcash#432

936223b

(zip-guide *incorrectly* said that we were already using KaTeX. This has been wrong since zcash#645.) Signed-off-by: Daira-Emma Hopwood <[email protected]>

Various formatting tweaks.

e1ddb75

Signed-off-by: Daira-Emma Hopwood <[email protected]>

Rewrite the rendering in a more functional style.

673cbc7

This supports MultiMarkdown as well as Pandoc, using `make MARKDOWN_OPTION=--mmd` Signed-off-by: Daira-Emma Hopwood <[email protected]>

Re-render.

96dafb2

Signed-off-by: Daira-Emma Hopwood <[email protected]>

daira force-pushed the easier-math-in-rst branch from 00e90e7 to 96dafb2 Compare November 12, 2024 19:50

daira mentioned this pull request Nov 14, 2024

Switch to MultiMarkdown #961

Open

nuttycom approved these changes Nov 16, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. #953

Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. #953

daira commented Nov 8, 2024 •

edited

Loading

daira commented Nov 8, 2024 •

edited

Loading

daira commented Nov 8, 2024 •

edited

Loading

daira Nov 10, 2024 •

edited

Loading

daira commented Nov 10, 2024 •

edited

Loading

nuttycom left a comment

nuttycom Nov 9, 2024

nuttycom Nov 16, 2024

nuttycom Nov 16, 2024

nuttycom Nov 16, 2024

nuttycom Nov 16, 2024

Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. #953

Are you sure you want to change the base?

Various improvements in the rendering of math and references. rST ZIPs now support $...$ for inline math. #953

Conversation

daira commented Nov 8, 2024 • edited Loading

daira commented Nov 8, 2024 • edited Loading

daira commented Nov 8, 2024 • edited Loading

daira Nov 10, 2024 • edited Loading

Choose a reason for hiding this comment

daira commented Nov 10, 2024 • edited Loading

nuttycom left a comment

Choose a reason for hiding this comment

nuttycom Nov 9, 2024

Choose a reason for hiding this comment

nuttycom Nov 16, 2024

Choose a reason for hiding this comment

nuttycom Nov 16, 2024

Choose a reason for hiding this comment

nuttycom Nov 16, 2024

Choose a reason for hiding this comment

nuttycom Nov 16, 2024

Choose a reason for hiding this comment

daira commented Nov 8, 2024 •

edited

Loading

daira commented Nov 8, 2024 •

edited

Loading

daira commented Nov 8, 2024 •

edited

Loading

daira Nov 10, 2024 •

edited

Loading

daira commented Nov 10, 2024 •

edited

Loading