➹ Lib-grenada 1.0.0-rc.4  –  API documentation

Extension to guten-tag.core/deftag.

Defines the same functions as deftag. Additionally defines functions as
described in the doc strings doc strings of t+?-form and map->t-form.

Creates doc strings for forms generated by form generators.

When you write a macro that generates code you want to provide documentation
both to the user of the macro and to the user of the generated code. Neither
of those should be forced to look into source code. All documentation should
be able to documentation page generators. The macro author, Elvira the Lazy,
doesn't want to write very similar documentation in two places, though. This
procedure helps her solve that problem.

When Elvira writes code-generating macros she doesn't want to have all the
generating code in the body of one macro definition. Instead, she writes a
separate function G for each defn or def form F to be generated. This is a 1:1
correspondence. G is of interest to the user of the macro and F is of interest
to the user of the generated code.

As said before, Elvira doesn't want to write the same documentation for G and
F. So she attaches a doc string only to G. The doc string contains some simple
markup as described below. She then generates the doc string for F by
executing make-doc on the var holding G _inside_ G.

Less epic description:

Reads the doc string of FORM-GENERATOR-VAR. Removes all occurences of '||| …
|||' and the leading and trailing whitespace that might result. Substitutes
placeholders according to SUBST-FOR.

Placholders work like this: if SUBST-FOR contains an entry [:KW 'subst'], all
occurrences of $KW in the doc string are replaced with 'subst' (excluding
quotes).