From 60d098434997cc00b313b22789a262318a5d5b25 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Sun, 5 Dec 2021 09:50:09 -0500 Subject: add mathyd and posts/2021-12-05-mathyd-easy-tex-to-svg --- content/posts/2021-12-05-mathyd-easy-tex-to-svg.md | 138 +++++++++++++++++++++ content/projects/mathyd.md | 8 ++ 2 files changed, 146 insertions(+) create mode 100644 content/posts/2021-12-05-mathyd-easy-tex-to-svg.md create mode 100644 content/projects/mathyd.md (limited to 'content') diff --git a/content/posts/2021-12-05-mathyd-easy-tex-to-svg.md b/content/posts/2021-12-05-mathyd-easy-tex-to-svg.md new file mode 100644 index 0000000..5961a43 --- /dev/null +++ b/content/posts/2021-12-05-mathyd-easy-tex-to-svg.md @@ -0,0 +1,138 @@ +--- +slug: mathyd-easy-tex-to-svg +title: "Mathyd: Easy TeX to SVG" +date: "2021-12-05T07:02:29-04:00" +draft: true +--- +A few weeks ago I released [Mathyd][], a [Docker][] image containing an +[HTTP][] daemon which converts [TeX][] to [SVG][]. + +[Mathyd][] includes a minimal command-line client which reads [TeX][] +from standard input and prints the generated [SVG][] to standard output, +like so: + +```bash +# set URL and HMAC secret key +# (note: replace value of MATHYD_HMAC_KEY with your own randomly +# generated one) +export MATHYD_URL="http://whatever.example.com:3000/" +export MATHYD_HMAC_KEY="2dhXA3HTmfEMq2d5" + +# render output +bin/mathy < cubic.tex > cubic.svg +``` +  + +Given [this input file][cubic-tex], the command above produces the +following result: + +{{< figure + src="/files/posts/mathyd-easy-tex-to-svg/cubic.svg" + class=image + caption="The Cubic Formula, rendered by Mathyd." +>}} + +### Installation + +You can install and run the [Mathyd Docker image][mathyd-docker] with a +single command: + +```bash +# run mathyd as a daemon on port 3000 +# (note: replace value of MATHYD_HMAC_KEY with your own randomly +# generated one) +docker run --rm -d -e MATHYD_HMAC_KEY="2dhXA3HTmfEMq2d5" -p 3000:3000 pablotron/mathyd:latest +``` +  + +**Notes:** +* Be sure to generate your own [HMAC][] secret key rather than + reusing the key from the examples above. +* Don't expose [Mathyd][] via a publicly-accessible [URL][]; it does + not support [TLS][] and [MathJax][] may use a lot of memory for large + input files. + +### Technical Details + +Under the hood, [Mathyd][] is just: +1. a [container][] running an [Express][] [HTTP][] daemon that exposes a + single endpoint that accepts a `PUT` request containing: + + * A [JSON][]-encoded body of input parameters + * A hex-encoded, [SHA-256 HMAC][hmac] of the body and the [HMAC][] + secret key in the `x-mathyd-hmac-sha256` header. + + The endpoint does the following: + + 1. Verifies the body [HMAC][] + 2. Converts the input [TeX][] to [SVG][] (via [MathJax][]) + 3. Returns a [JSON][] response containing the generated [SVG][] + +2. A command-line client, written in [Ruby][], which: + 1. Reads [TeX][] from standard input and serializes it as [JSON][]. + 2. Sends a `PUT` request to the [Mathyd][] daemon and parses the + response. + 3. Extracts the generated [SVG][] from the response and writes it to + standard output. + +### Rationale + +I wanted an easy way to generate static math [SVGs][svg] for +web pages from the command-line without installing a blizzard of +dependencies and without requiring [MathJax][] on the destination page. + +I prefer [TeX][] over other formats because it's still the least-worst +format for complex math formulas. + +I prefer [SVGs][svg] over bitmap images whenever possible because: + +* [SVGs][svg] scale to any screen size and resolution. This is + particularly useful for [responsive design][]. +* [SVGs][svg] are supported by all modern browsers, including mobile + browsers. (Fun fact: even the [animated logo for this page][logo] is + an [SVG][]). + +### Links + +* [Mathyd GitHub Repository][mathyd] +* [Mathyd on Docker Hub][mathyd-docker] + +**Note:** If you want a web interface to noodle around with [TeX][], +check out [Mathy][] instead. + +[mathyd]: https://github.com/pablotron/mathyd + "Dockerized TeX to SVG HTTP daemon." +[docker]: https://en.wikipedia.org/wiki/Docker_(software) + "Docker" +[http]: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol + "HyperText Transfer Protocol" +[tex]: https://en.wikipedia.org/wiki/TeX + "The TeX typesetting system." +[svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics + "Scalable Vector Graphics" +[mathjax]: https://mathjax.org/ + "Math rendering library." +[cubic-tex]: /files/posts/mathyd-easy-tex-to-svg/cubic.tex.txt + "Example Mathyd input TeX file containing the cubic formula." +[mathy]: https://mathy.pmdn.org/ + "Web-based LaTeX Math renderer, based on MathJax." +[express]: https://expressjs.com/ + "Minimal web framework for Node JS." +[hmac]: https://en.wikipedia.org/wiki/HMAC + "Hashed Message Authentication Code" +[json]: https://json.org/ + "JavaScript Object Notation." +[mathyd-docker]: https://hub.docker.com/repository/docker/pablotron/mathyd + "Mathyd on Docker Hub." +[container]: https://en.wikipedia.org/wiki/OS-level_virtualization + "Operating System-level virtualization." +[Ruby]: https://ruby-lang.org/ + "Ruby programming language." +[url]: https://en.wikipedia.org/wiki/URL + "Uniform Resource Locator" +[logo]: /files/posts/mathyd-easy-tex-to-svg/logo.svg + "current pablotron.org site logo" +[responsive design]: https://en.wikipedia.org/wiki/Responsive_web_design + "Responsive web design." +[tls]: https://en.wikipedia.org/wiki/Transport_Layer_Security + "Transport Layer Security" diff --git a/content/projects/mathyd.md b/content/projects/mathyd.md new file mode 100644 index 0000000..18e265b --- /dev/null +++ b/content/projects/mathyd.md @@ -0,0 +1,8 @@ +--- +title: "Mathyd" +slug: "mathyd" +active: true +repo: "https://git.pablotron.org/mathyd" +text: "Easy TeX to SVG daemon." +--- +Easy TeX to SVG daemon. \ No newline at end of file -- cgit v1.2.3