scribble-math
1 Typesetting math with $ and $$
$
$$
with-html5
$-html-handler
$$-html-handler
$-katex
$$-katex
$-mathjax
$$-mathjax
$-tex2svg
$$-tex2svg
use-katex
use-mathjax
use-tex2svg
current-tex2svg-path
2 Drawing figures with Asymptote
asymptote
7.8

scribble-math

Jens Axel Søgaard <jensaxel@soegaard.net>
and Georges Dupéron <georges.duperon@gmail.com>

 (require scribble-math) package: scribble-math

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

    1 Typesetting math with $ and $$

    2 Drawing figures with Asymptote

1 Typesetting math with $ and $$

 (require scribble-math/dollar) package: scribble-math

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.

procedure

($ str ...)  element?

  str : string?
Renders the given strings as inline mode math. Inline mode math is typeset as part of the surrounding text. Either MathJax or KaTeX is used for the HTML output, depending on the current configuration. For the LaTeX output, the code is simply passed as-is. For example, when using MathJax, ($ "x^2") renders as x^2.

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.

procedure

($$ str ...)  element?

  str : string?
Renders the given strings as display mode math. Display mode math is typeset alone on its line, and is centered. Some symbols like \sum are larger in display mode than in inline mode, which makes the former better for complex equations. Either MathJax or KaTeX is used for the HTML output, depending on the current configuration. For the LaTeX output, the code is simply passed as-is. For example, when using MathJax,

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

renders as:

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

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.

procedure

(with-html5 doc-style)  style?

  doc-style : style?
Alters the given document style, so that the resulting document uses HTML5.

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

parameter

($-html-handler)  ( (listof? string?) element?)

($-html-handler handler)  void?
  handler : ( (listof? string?) element?)
 = $-katex
A parameter whose value is a function called by $, to transform the math code into HTML. The $ function uses this parameter only when rendering the document as HTML.

parameter

($$-html-handler)  ( (listof? string?) element?)

($$-html-handler handler)  void?
  handler : ( (listof? string?) element?)
 = $$-katex
A parameter whose value is a function called by $$, to transform the math code into HTML. The $$ function uses this parameter only when rendering the document as HTML.

procedure

($-katex math)  element?

  math : (listof? string?)
Produces an element? which contains the given math code, so that it is rendered as inline mode math using KaTeX. More precisely, the resulting element uses several scribble properties to add scripts and stylesheets to the document. The resulting element also uses a specific CSS class so that when the page is loaded into a browser, KaTeX can recognise it and render it in inline mode.

procedure

($$-katex math)  element?

  math : (listof? string?)
Produces an element? which contains the given math code, so that it is rendered as display mode math (centered, alone on its line) using KaTeX. More precisely, the resulting element uses several scribble properties to add scripts and stylesheets to the document. The resulting element also uses a specific CSS class so that when the page is loaded into a browser, KaTeX can recognise it and render it in display mode.

procedure

($-mathjax math)  element?

  math : (listof? string?)
Produces an element? which contains the given math code, so that it is rendered as inline mode math using MathJax. More precisely, the resulting element uses several scribble properties to add scripts and stylesheets to the document. The resulting element also uses a specific CSS class so that when the page is loaded into a browser, MathJax can recognise it and render it in inline mode.

procedure

($$-mathjax math)  element?

  math : (listof? string?)
Produces an element? which contains the given math code, so that it is rendered as display mode math (centered, alone on its line) using KaTeX. More precisely, the resulting element uses several scribble properties to add scripts and stylesheets to the document. The resulting element also uses a specific CSS class so that when the page is loaded into a browser, MathJax can recognise it and render it in display mode.

procedure

($-tex2svg math)  element?

  math : (listof? string?)
Produces an element? which contains the given math rendered as an HTML SVG literal. It is rendered in inline mode math using tex2svg. More precisely, the resulting element uses the xexpr-property to render the SVG directly to the HTML document. This means no new scripts or stylesheets are added to the document. It also has no style, so its style cannot be customized.

This procedure requires Racket 6.12 or later.

procedure

($$-tex2svg math)  element?

  math : (listof? string?)
Produces an element? which contains the given math rendered as an HTML SVG literal. It is rendered in display mode math using tex2svg. More precisely, the resulting element uses the xexpr-property to render the SVG directly to the HTML document. This means no new scripts or stylesheets are added to the document. It also has no style, so its style cannot be customized.

This procedure requires Racket 6.12 or later.

procedure

(use-katex)  void?

This shorthand calls ($-html-handler $-katex) and ($$-html-handler $$-katex). The mathematical formulas passed to $ and $$ which appear later in the document will therefore be typeset using KaTeX.

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.

procedure

(use-mathjax)  void?

This shorthand calls ($-html-handler $-mathjax) and ($$-html-handler $$-mathjax). The mathematical formulas passed to $ and $$ which appear later in the document will therefore be typeset using MathJax.

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.

procedure

(use-tex2svg)  void?

This shorthand calls ($-html-handler $-tex2svg) and ($$-html-handler $$-tex2svg). The mathematical forumulas passed to $ and $$ which appear later in the document will therefore be typeset using tex2svg.

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.

parameter

(current-tex2svg-path)  path?

(current-tex2svg-path path)  void?
  path : path?
 = #f
A parameter whose value is the path to the tex2svg binary. This binary is used to transform math code into HTML when using the tex2svg backend.

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

This parameter requires Racket 6.12 or later.

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

 (require scribble-math/asymptote)
  package: scribble-math

procedure

(asymptote [#:cache cache?] str ...+)  image?

  cache? : any/c = #t
  str : string?
Renders the figure described by the given strings using Asymptote. If cache? is #f, then the resulting images are generated into temporary PNG, SVG and PDF files using make-temporary-file. Otherwise, to improve compilation speed, the result is cached in the "asymptote-images" directory, based on a checksum of the strings. It is a good idea to clean up the working directory after experimenting a lot with a figure, as it will be cluttered with stale cached files.

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: