automathpads¶

automathpads is a collection of pads: small web forms, each dedicated to one kind of figure. A pad gathers what the figure needs, writes the matching atmxg string, and has automathd draw it as an SVG, shown live beside the form.

The pads are plain HTML, CSS and JavaScript, with no build step and no framework. Each pad stands on its own; they only share a stylesheet and a few modules (common/).

What a pad needs¶

A pad calls automathd over HTTP, and nothing else:

• GET /render/svg draws the figure;
• GET /render/wrappers (font_mode=embedded) gives the @font-face of the chosen fonts, for the preview to show them and the SVG file to carry them;
• GET /fonts/storage lists the fonts to choose from.

Only fonts from the server's catalogue are offered: their licence allows embedding them in a file. An uploaded font's licence is unknown.

Where automathd answers is found out when the page loads:

1. window.__AUTOMATHD_URL__, when the server injects it (as nginx does for automathon, with sub_filter);
2. otherwise, a pad opened on this machine (localhost, 127.0.0.1) talks to the local daemon, http://127.0.0.1:9998;
3. otherwise, /api on the same origin: the server proxies it to the daemon.

automathd limits the requests of each visitor (rate_limit.render in its configuration). A pad waits until the typing has stopped for 0.4 s before asking for a drawing, and never asks twice for the same one.

The form is kept in the page's address, after the #: reloading the page, or sending its address to someone, gives back the same figure. What belongs to the machine rather than to the figure — the scale factor that makes up for the printer — is kept by the browser (localStorage), and shared by every pad.

Every pad prints its figure to a scale: one cell is 1 cm in a plot, 1 cm stands for so much on the value axis of a bar chart. The figure says how long that is in the SVG's own units — data-cell-size (a plot) or data-unit-size (a bar chart), on the <g> that holds it — and the pad sizes the file in centimetres from it. The size the figure and its text take on paper is shown under the preview.

What all the pads do in the same way — this, the fonts, the preview, the files, the import — lives in common/pad.js; a pad brings its own figure: its form, the string it writes (atmxg.js) and reads back (import.js).

Using them locally¶

With automathd running, serve the pads from where the package keeps them:

cd "$(automath show automathpads_path)"
python -m http.server 8001

then open http://localhost:8001/. The pages are JavaScript modules, which a browser does not load from a file:// address: they have to be served, even locally.

Deploying them¶

automathics_postinstall copies the pads to the directory deploy.path names in automathpads.yaml (in /etc/automathics/ or ~/.config/automathics/):

deploy:
  path: /usr/local/www/automathpads

Empty, the default, they are not deployed. The directory is replaced wholesale on each install: give it a directory of its own, never a shared one.

They are then served as static files. With nginx, next to the /api proxy:

location ^~ /api/ {
    proxy_pass http://127.0.0.1:9998/;
}

location ^~ /pads/ {
    alias /usr/local/www/automathpads/;
}

^~ keeps /pads/ off the regular expression that serves the published apps; pads is reserved, and no app may be published under that name.

Tests¶

The JavaScript that writes and reads the atmxg strings has no dependency on the page, and is tested with Node's own runner, nothing to install:

node --test 'tests/automathpads/*.test.js'     # from the project root

From src/automathon, npm run test:pads runs the same; npm run test:web runs automathon's tests and the pads'; npm run check type-checks and lints automathon, then runs both.