HyperFRED

On the info-mcl mailing list, Pekka Tolonen demonstrates his system for viewing richly formatted documentation (with embedded procedurally generated bits) in MCL.

Hi, perhaps you get some ideas of how I solved Symbolic Composer documentation problem. The problem was that I was having thousand documents having text and lisp code, and my aim is to make them look good with the minimum amount of manual formating.

[...]

While parsing, inline directive executes Lisp as progn, and allows to draw simple graphs and show jpegs based on Alexander Repenning's jpeg code. It also shows the Lisp parse trees. Also basic buttons and interface items are supported by the inline directive.

Pekka's system takes documentation that looks like this:

gen-sin frequency amplitude samples &optional phase modulation

Returns a vector, whose length is determined by samples of a sine
wave having given frequency and amplitude and optional phase and
modulation. If omitted a zero phase is used. The modulation is a
vector pattern returned by another generator. The phase values
range from 0 to 360.

(vector-round 0 127 (gen-sin 1 0.5 64))
--> #(64 70 76 82 88 93 99 104 108 113 116 120 122 124 126 127
     127 127 126 124 122 120 116 113 108 104 99 93 88 82 76 70 64
     57 51 45 39 34 28 23 19 14 11 7 5 3 1 0 0 0 1 3 5 7 11 14 19
     23 28 34 39 45 51 57)

;;How does it look like?

(inline
  (progn
    (make-graph 'draw-vector-x
      (do-quietly (vector-round 0 127 (gen-sin 1 0.5 64))))))

and renders it as something that looks like this:

This reminds me a bit of Knuth's literate programming stuff and of the occasional thread on comp.lang.lisp about documentation string formatting.

Kent Pitman (in 1999):

As a rule, I consider it stylistically a modularity violation to ask for documentation of someone else's doc string and expect to use it for anything other than to dump it raw to the console as archaeology-style debugging clues. It perhaps shouldn't have gone this way, but years of divergent experience make little else feasible.

MCL does support a limited amount of markup in documentation strings (as pictured below); are there any other lisp implementations that do this?

Posted by jjwiseman at May 24, 2003 12:27 PM