May 24, 2003

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?

    (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:

[symbolic composer documentation screenshot

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?

[mcl docstring]

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

On the Symbolics Lisp Machine the authoring system for documentation was called Concordia[1].
In earlier times LispWorks had an documentation editor in its development environment.
In both systems 'real' documentation is maintained seperately.

There are quite a few tools to create formatted documentation out of Lisp source. For example XREF in the Kantrowitz collection of tools (IIRC). Or what Heiko Kirschke uses for Plob! [2].


Posted by: Rainer Joswig on May 24, 2003 02:09 PM

Isn't this just Mathematica implemented in lisp?

Posted by: on May 24, 2003 04:03 PM

Emacs Lisp supports semantic markup in documentation strings. For details, see

Posted by: Luke Gorrie on May 26, 2003 11:59 PM
Post a comment

Email Address:


Unless you answer this question, your comment will be classified as spam and will not be posted.
(I'll give you a hint: the answer is “lisp”.)


Remember info?