<!DOCTYPE book SYSTEM "ozdoc.dtd" [

<!-- Extension to the DTD -->
<!ENTITY % proglang.values.local "|sh|fundamental">

<!ENTITY % author.class "author|author.extern|comic">
<!ENTITY % picture.element "picture|picture.extern|picture.choice">
<!ELEMENT comic - O (%picture.element;)>

<!-- Include Files -->

<!-- Abbreviations -->
<!ENTITY lt "<">
<!ENTITY gt ">">
<!ENTITY dot "." -- to distinguish it from periods -->
<!ENTITY Oz "Oz">
<!ENTITY LaTeX "LaTeX">

<!-- Processing Instructions -->
<!ENTITY emdash PI "emdash">
<!ENTITY endash PI "endash">
<!ENTITY nbsp PI "nbsp">
<!ENTITY ellipsis PI "ellipsis">
<!ENTITY slash PI "slash">
<!ENTITY ie PI "ie">
<!ENTITY wrt PI "wrt">
<!ENTITY eg PI "eg">

]>

<Book proglang=oz>
  <Front>
    <meta name="proglang.mode" arg1="oz" arg2="oz-mode">
    <meta name="proglang.mode" arg1="sh" arg2="sh-mode">
    <meta name="proglang.mode" arg1="fundamental" arg2="fundamental-mode">
    <!-- Splitting the document into different HTML nodes -->
    <meta name="html.split" value="appendix.a">
    <Meta name=ozversion value="3.0">
    <Meta name=status value=revised>
    <Title/How To Read The Mozart Documentation/
    <Author.Extern to="author.db" key="Denys.Duchier">
  <Body>
<chapter><title/Document Trails/
<p>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 <em/Emacs info/ model.
<list>
	  <entry><code/Prev/ and <code/Next/ links
	  <item>All pages at the same level of the hierarchy (sibling
pages) are linked together through <code/Prev/ and <code/Next/ links.
These appear both at the top and at the bottom of the page.

	  <entry><code/Up/ links
	  <item>Further, each page is linked to its parent (if any)
through an <code/Up/ link.  This too appears at the top and bottom of
each page.

	  <entry>Table of Contents
	  <item>Each page, for which there exist sub-levels in the
documentation hierarchy displayed on other pages, makes available a
<em/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.
</list>
When you reach the last page at the current level of the hierarchy,
you will see that it has only a <code/Prev/ and an <code/Up/ link.
Clicking on <code/Up/ takes you back to the parent, where you should
then click on <code/Next/ to visit the parent's next sibling page.
</p>

<chapter><title/Indexes and Cross-References/
      <p>
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.</p>

      <p>
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 <em/very/ quickly.</p>

<chapter><title/Program Examples/
      <para><title/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 <em/Literate Programming/.
It alternates documentation text and <em/code chunks/.  Each chunk can
essentially be regarded as a macro with a long meaningful name.
<chunk proglang=oz><title/Wait For Godot/
local
   Godot={Lookup godot}
in
   {Wait Godot}
end
</chunk>
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.
<chunk><title/Frog Daiquiri/
<chunk.ref/Get Frog/
<chunk.ref/Get Blender/
<chunk.ref/Insert frog into blender/
<chunk.ref/Take it for a spin/
<chunk.ref/Serve, shaken not stired/
</chunk>
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 <ptr to=appendix.a> we
present the partial implementation of the first chunk in that ever
so cool recipe of the Frog Daiquiri.
<!--
<chunk class=anonymous/<title/Get Blender//
<chunk class=anonymous/<title/Gently Ease Frog Into Blender//
<chunk class=anonymous/<title/Press Button for 30 seconds//
<chunk class=anonymous/<title/Serve, shaken not stired//
-->
</para>
    </chapter>
<appendix id=appendix.a><front//
<p>
<chunk><title/Get Frog/
{InvadeParis}
{GrabAnyOne}
</chunk>
</appendix>
  <Back>
</Book>
<!--
Local Variables:
mode: sgml
mode: auto-fill
sgml-default-dtd-file: "../book.ced"
sgml-auto-activate-dtd: t
adaptive-fill-mode: nil
End:
-->
