scribble-math🔗ℹ

This library allows typesetting math and Asymptote figures in Scribble documents.

1 Typesetting math with $ and $$🔗ℹ

The following functions help with typesetting mathematical equations. The main functions are $ for inline mode math and $$ for display mode math, respectively. The functions use-katex and use-mathjax change the rendering engine used, the default being katex. To use katex, it is necessary to use @title[#:style (with-html5 manual-doc-style)]{…} or a similar configuration; for more details see the documentation of with-html5.

The syntax accepted by $ is a subset of the commands supported by LaTeX, and depends on the backend used (MathJax should support more commands than KaTeX). For details, see their respective documentation.

($$ "\\sum_{i=0}^n x_i^3")

renders as:

The syntax accepted by $$ is a subset of the commands supported by LaTeX, and depends on the backend used (MathJax should support more commands than KaTeX). For details, see their respective documentation.

This function should be called to alter the #:style argument for title when KaTeX is used, as KaTeX is incompatible with the default scribble DOCTYPE (the HTML 4.01 Transitional loose DTD). The scribble document should therefore contain code similar to the following:

@title[#:style (with-html5 manual-doc-style)]{...}

This function works by changing the existing html-defaults property or adding a new one, so that it uses an HTML5 prefix file (the prefix file contains the DOCTYPE line).

($-katex "x^2") renders as x^2.

($$-katex "\\sum_{i=0}^n x_i^3")

renders as:

\sum_{i=0}^n x_i^3

($-mathjax "x^2") renders as x^2.

($$-mathjax "\\sum_{i=0}^n x_i^3")

renders as:

This procedure requires that tex2svg be installed via npm install mathjax-node-cli.

This procedure requires Racket 6.12 or later.

This procedure requires that tex2svg be installed via npm install mathjax-node-cli.

This procedure requires Racket 6.12 or later.

The KaTeX library will be added to the HTML document only if it uses the result of one of $, $$, $-katex or $$-katex. It is therefore safe to call this function in libraries to change the default handler, without the risk of adding extra resources to the page if the user changes the default before typesetting any math.

The MathJax library will be added to the HTML document only if i uses the result of one of $, $$, $-katex or $$-katex. It is therefore safe to call this function in libraries to change the default handler, without the risk of adding extra resources to the page if the user changes the default before typesetting any math.

No new CSS or JavaScript libraries will be added to the document. Instead, the generated HTML document have the math embedded directly an svg.

This requires that tex2svg is installed on the system. You can install it globally via sudo npm install –global mathjax-node-cli or locally with npm install mathjax-node-cli. The backend will attempt to find the tex2svg, preferring local sources. You can set the path manually with the parameter current-tex2svg-path.

tex2svg will only be used when rendering an HTML document, and only if it uses $ or $$ to render math. It is therefore safe to call this function in libraries to change the default handler.

This procedure requires Racket 6.12 or later.

The functions $-tex2svg and $$-tex2svg use this parameter only when rendering the document as HTML.

This parameter requires Racket 6.12 or later.

For example, if the HTML document is accessed via file:///home/user/docs/document1/index.html, and (use-external-mathjax "../common/MathJax/MathJax.js?config=default") was used, then MathJax will be loaded from file:///home/user/docs/common/MathJax/MathJax.js?config=default.

An URL to a CDN is also valid, but may be a poor choice regarding the privacy of your users.

This feature is in beta and might not work, please report any issue.

For example, if the HTML document is accessed via file:///home/user/docs/document1/index.html, and (use-external-katex (list "../common/KaTeX/katex.min.js" "../common/KaTeX/katex.min.css")) was used, then the KaTeX script will be loaded from file:///home/user/docs/common/KaTeX/katex.min.js and the KaTeX stylesheet from file:///home/user/docs/common/KaTeX/katex.min.css.

An URL to a CDN is also valid, but may be a poor choice regarding the privacy of your users.

Please note that using a .js and a .css file which are not in the same directory is unsupported (it has not been tested and may or may not work).

This feature is in beta and might not work, please report any issue.

When using MathJax, $ and $$ wrap their content with "$…$" and "\\[…\\]" respectively, and insert it in an element with the class "tex2jax_process". MathJax is configured to only process elements with this class, so it is safe to use $ signs in the source document. For example, the text $\sum x^3$ is typeset as-is, like the rest of the text.

When using tex2svg, no additional JavaScript processing is done on the page, so it is safe to use $ signs in the source document. For example, the text $\sum x^3$ is typeset as-is, like the rest of the text.

2 Drawing figures with Asymptote🔗ℹ

If the Asymptote code is dynamically generated, make sure that the result is always the same, or use #:cache #f. Otherwise, each compilation would cause a new file to be generated.

The asy executable must be installed on the machine that renders the figures. If the results are already cached, then the scribble document can be compiled without installing Asymptote.

As an example, the code

@asymptote{

import drawtree;

size(4cm, 0);

TreeNode root = makeNode("let");

TreeNode bindings = makeNode(root, "bindings");

TreeNode binding = makeNode(bindings, "binding");

TreeNode bid = makeNode(binding, "id");

TreeNode bexpr = makeNode(binding, "expr");

TreeNode bindingddd = makeNode(bindings, "\vphantom{x}\dots");

TreeNode body = makeNode(root, "body");

TreeNode bodyddd = makeNode(root, "\vphantom{x}\dots");

draw(root, (0,0));

shipout(scale(2)*currentpicture.fit());

}

renders as: