Edrxbox: a simpler way to write `dim-*' functions in Maxima

1. What is this?

In Maxima we can define operations that are displayed and LaTeXed in special ways. Making `underbrace(a,b)' be LaTeXed as `\underbrace{a}_{b}', as in the first screenshot below, is very easy; making it be displayed as in the second screenshot, as something that looks vaguely like a fraction but in which the baseline is the baseline of the top object, is VERY hard.

Look at this bug report, for example - it took me ages to understand dim-antideriv.lisp, and more ages to find a one-line fix that fixed its behavior in most cases. We need something better, like another way to write display functions... and I think that this is a step in the right direction.

2. Try it!

If you have eev installed and activated - and Maxima, of course - you can try edrxbox by downloading its two files, edrxbox.lisp and edrxbox-examples.lisp, with something like these commands...

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
cd /tmp/
wget -N https://anggtwu.net/MAXIMA/edrxbox.lisp
wget -N https://anggtwu.net/MAXIMA/edrxbox-examples.lisp

# (find-fline "/tmp/edrxbox.lisp")
# (find-fline "/tmp/edrxbox-examples.lisp")

...and then run the tests and examples in its test blocks. The next sections explain what its tests and examples do.

3. The core: edrxbox.lisp

The file edrxbox.lisp has lots of explanations, and it has only a handful of (boring) test blocks that demonstrate low-level things... these ones, starting on the second screenshot:

It also has lots of links to displm.lisp and displa.lisp. To make them work in Emacs you need a `code-c-d' like this one:

(code-c-d "maximagit" "~/bigsrc/maxima/")

In Emacs they will point to specific lines in the Maxima source, like in this screenshot:

but in the htmlized version of edrxbox.lisp their pos-spec-lists don't work, and the links point to the top of the files in the git repository.

4. The examples: edrxbox-examples.lisp

The file edrxbox-examples.lisp is much more interesting... it has these examples:

4.1. Verbatimbox

Verbatimbox is used by lisptree:

Note what was needed to center the drawing around the baseline - just a call to `edrxbox-vcenter', that added a "move" command to the drawing instructions.

4.2. Antideriv

The first two screenshots below show `antideriv' and `hdw'. `hdw' creates a box with a certain height, depth, and width; I use it mostly to debug `dim-*' functions. The third screenshot below shows a comparison between the `antideriv' written with edrxbox and its antecessor, dim-antideriv.lisp:

4.3. Underbrace

The next screenshot shows `underbrace' - note how the horizontal centering was done by just calling `edrxbox-hcenter' - and a demo that uses my substitution operator, `_s_', and these variants of it.

The second screenshot shows how these underbraces are LaTeXed - see the introduction.

4.4. Displaying edrxboxes

Remember that in a previous section we saw a debugging function, `edrxbox-from-form', that displays the drawing instructions for a given Maxima object. Here is its screenshot again:

The next example is another debugging function, `edrxbox-display', that receives an edrxbox, converts its drawing instructions into a Maxima object - whose associated `dim-*' function is `dim-edrxbox' -, and makes Maxima display it. The conversion is explained in the first two screenshots below,

...and the third screenshot shows what can happen when we don't run `edrxboxvars-push-x-y-end' to move the current (x,y) position to the "right" ending place.

This is related one of my motivations for writing edrxbox.lisp, by the way... see this bug report, that describes a similar bug that took us months to fix, and the explanations in the beginning of edrxbox.lisp, that have this paragraph:

It is very difficult to write new `dim-*' functions in the style used in "displa.lisp" because the user/programmer has to write the drawing instructions in a cryptic DSL in which many parts of the code look reversed, and has to keep several variables, like the box boundaries, in sync and with sane values, "by hand".