Top

How To Read The Mozart Documentation

Denys Duchier

1 Document Trails

The Mozart system comes with extensive on-line documentation. In order to take effective advantage of it, you should understand how to navigate its linked structure of web pages. The design of this structure was inspired by the Emacs info model.

Prev and Next links

All pages at the same level of the hierarchy (sibling pages) are linked together through Prev and Next links. These appear both at the top and at the bottom of the page.

Up links

Further, each page is linked to its parent (if any) through an Up link. This too appears at the top and bottom of each page.

Table of Contents

Each page, for which there exist sub-levels in the documentation hierarchy displayed on other pages, makes available a table of contents. In Emacs info, this is normally a menu. Following a link in a table of contents (by clicking) will take you to the corresponding page.

When you reach the last page at the current level of the hierarchy, you will see that it has only a Prev and an Up link. Clicking on Up takes you back to the parent, where you should then click on Next to visit the parent's next sibling page.

2 Indexes and Cross-References

As much as possible, we have tried to equip each document with an index. This facility was patterned after the LaTeX index mechanism. It is far from perfect, but can give you fast access to relevant points.

Our cross reference facility was also inspired by LaTeX's mechanism. You will notice, however, that it extends cross references across all documents in our documentation. We have used this ability extensively to allow you easy access to other points in our entire documentation set wherever they might be necessary. This makes our on-line documentation very effective. Help us improve it: if a particular cross reference would have been helpful to you, let us know. We respond very quickly.

3 Program Examples

Code Chunks

As you might well expect, our documentation is illustrated will a great many code examples. For didactic reasons, it is often desirable to present code in small chunks, where details are only incrementally revealed. To this end, we often use a coding and presentation technique introced by D.Knuth and known as Literate Programming. It alternates documentation text and code chunks. Each chunk can essentially be regarded as a macro with a long meaningful name.

<Wait For Godot>=
local 
   Godot={Lookup godot}
in 
   {Wait Godot}
end

The first line gives the name of the chunk being defined, and the following lines its content. Each code chunk may refer to other code chunks. Just below is a code chunk that refers to 5 other chunks. The advantages of this presentation technique are readily apparent: the high-level intent of the code can be immediately perceived; it is not obscured by details of implementation. These are only revealed later.

<Frog Daiquiri>=
<Get Frog> 
<Get Blender> 
<Insert frog into blender> 
<Take it for a spin> 
<Serve, shaken not stired>

In our documentation, each reference to a code chunk is hyperlinked to its definition, thus facilitating the reader's explorative reading of a documented implementation. For example, in Appendix A we present the partial implementation of the first chunk in that ever so cool recipe of the Frog Daiquiri.



Denys Duchier
Version 1.4.0 (20080702)