A simple meta demonstration of the Scheme Elucidator

Kurt NÝrmark ©   normark@cs.auc.dk   Department of Computer Science, Aalborg University, Denmark  

Abstract. This elucidative program demonstrates the facilities of the Scheme Elucidator. The program fragments are just simple and well known functions without any coherence or real value.
 
1     A section
This is section one. Here we can give overview of the subsequent subsections, which we happen to call entries.
1.1     An introductory entry
1.2     The next entry
1.3     The next steps
1.4     Discussing details
1.5     The End

1.1     An introductory entry
Here in the first subsection we can introduce the matters. Typically we do not make very many references to program pieces from the first section. A documentation bundle is the set of Scheme files, the textual documentation file, and the LAML setup file.

We have made the documentation bundle by means of the emacs command M-x make-elucidator. This command creates the documentation file, the first program file, and the setup file. It also creates the necessary and underlying file and directory structures. When we execute this editor command we are asked to process the LAML file, and to activate another emacs command setup-elucidator. We just do that.


1.2     The next entry
I made this entry via the Emacs command M-x insert-documentation-entry.

In this entry we can start discussing the Scheme program. Just to have something on the program side, we have made the well-known fak function in meta-demo. So we make a reference to it. If we have lost the editor context we can always say C-e C-r (or M-x elucidator-reset-elucidator) to establish the characteristic split view editor panes with documentation in the top window and program in the bottom window.

Now let us discuss fak. The reference just inserted is conveniently made by selecting the fak header in the Scheme file and entering C-e C-p (elucidator-program-ref). It turns out that this makes a full qualified reference (file and name). The reason is that the editor - at this point in time - does not known any thing about fak. If the documentation bundle had been processed (abstracted) we would have this knowledge. We may change this policy in the future.

We now process the documentation bundle by C-e C-o (or M-x elucidator-elucidate).


1.3     The next steps
We now program additional functions in both meta-demo and in other-source. This - by the way - illustrates links to whole program files.

The functions in meta-demo are list-prefix and its helping function list-prefix-1. Notice first the strong reference (red) and the weak reference (blue). We may also just make typographic emphasis, like list-prefix-1 (C-e C-w).

The functions in other-source are pair-up and its helping function pair-up-1.

At the bottom of other-source we see a definitions of key-list and val-list. Following these definitions we see aref-assignment, which in a rather informal way denotes a section of the program via use of a so-called sectional comment in other-source.


1.4     Discussing details
Let us demonstrate the use of source markers in fak. At we test if the parameter is zero. If it is we return the base value 1 (). If not we return n times (fak (- n 1)) (); This illustrates the recursion in fak.

1.5     The End
This ends our simple demonstration of the Scheme elucidator.