scribble-math

7.7

top ← prev up next →

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

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.

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:

top ← prev up next →

1	Typesetting math with $ and $$
2	Drawing figures with Asymptote