Transcripts

Tags: lisp, Date: 2014-10-20

I've just committed a major feature to MGL-PAX: the ability to include code examples in docstrings. Printed output and return values are marked up with ".." and "=>", respectively.

(values (princ :hello) (list 1 2))
.. HELLO
=> :HELLO
=> (1 2)

The extras are:

• parsing back and updating a transcript,

• auto-checking of up-to-dateness at documentation generation time,

• readable return values can be commented, hand-indented without breaking consistency checks and updates will not destroy those changes,

• Emacs integration: transcribing the last expression and updating a transcript in a region.

• TRANSCRIBE works without the rest of MGL-PAX so it can be used to format bug reports or as a poor man's expect script.

The documentation provides a tutorialish treatment. I hope you'll find it useful.