Glitzersachen

Some months ago (ten, to be precise) I started learning Common Lisp, strictly privately, though, since my day job has no use for Lisp.

My motivation to work with Common Lisp is manifold and perhaps a topic for another day. Suffice it to say, that I'm interested in programming languages per se on the one side and in computer history on the other side. Common Lisp is just an important milestone on both roads.

Today, now, I filed my first issue for Slime. Slime does not always follow references from the buffer where it displays documentation strings in the expected way. Which would be to look for symbols, that have not been qualified with the package name, in the package where the symbol comes from.

The problem only manifests when one is already in the documentation buffer and following a reference to a symbol in another package. Then, the new state of the documentation buffer is all wrong.

Background, why I even discovered this, is, that I've come to think about Slime plus documentation strings as a kind of hypertext system that makes it much less urgent to be able to extract documentation from the packages as HTML or PDF, like for example Declt does.

I mostly don't like the documentation tools available for Common Lisp, because they produce voluminous, but ultimately difficult to read reference documentation. Compare that to Sphinx for Python which is geared primarily towards writing a manual with introduction, overview and anything, and inserting extracted documentation fragments into it as necessary.

What I'd ultimately like to see, though, would be to have almost all of the manual available, that is referable, in "slime as hypertext", as a symbol. Which is what "slime as hypertext" treats as references.

This is easy to achieve, for example, by having a macro that attaches documentation to symbols whose only purpose is holding that documentation string:

(defdocumentation *OVERVIEW*
    "Overview"
    "
    Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi
    nec facilisis facilisis, est dui fermentum leo, quis tempor ligula
    erat quis odio.
    Nunc porta vulputate tellus.  Nunc rutrum turpis
    sed pede.  Sed bibendum.")

The documentation can now be referred to in the following fashion:

(defun foo (bar)
  "Introduces a foo into BAR.

   Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum
   leo, quis tempor ligula erat quis odio.

   For context refer to `*OVERVIEW*'.")

But now I got the wish to be able to refer to information that is only collected while loading a system and display that information in a documentation string, for example

(defdocumentation *OVERVIEW*
    "Overview"
    "
    Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi
    nec facilisis facilisis, est dui fermentum leo, quis tempor ligula
    erat quis odio.

    For the tests available see `*TEST-REGISTRY*'.")    

and then the documentation string displayed by Slime for *TEST-REGISTRY* would list all tests loaded at the time:

MY-PACKAGE:*TEST-REGISTRY*
  [symbol]

*FEATURES* names a special variable:
  Value: (CHECK-FOO CHECK-BAR CHECK-BAZ)
  Documentation:

  Tests available in MY-PACKAGE:

  - CHECK-FOO -- Test if FOO provides fooness to standard objects.
  - CHECK-BAR -- Test if the bar works correctly.
  - CHECK-BAZ -- Bazification tests.

Turns out, DOCUMENTATION is a generic function, so can be specialized to provide the string in question dynamically every time it is evoked on exactly this symbol — instead of modifying the documentation string every time a new test is defined:

(defmethod documentation ((object eql '*TEST-REGISTRY*) (doc-type eql 'variable))
  (extract-the-test-list-or-whatever))

Continuing with this theme and a bit more effort, it is possible to store hierarchical documentation (sections and sub-sections) in symbols and add navigation references in the style of the emacs info reader to them: Next, Previous and Up.

This is what I'm currently trying to achieve with in CL-SPECIFICATION, though the package is not complete yet.