Clean up tutorial. (#30)

tutorial.html

@@ -384,7 +384,7 @@ <h2 id="sec-1"><span class="section-number-2">1</span> Relational Data</h2>
 </pre>
 
 <p>
-No shared attributes.
+No shared attributes:
 </p>
 <div class="org-src-container">
 
@@ -397,7 +397,7 @@ <h2 id="sec-1"><span class="section-number-2">1</span> Relational Data</h2>
 </pre>
 
 <p>
-No match.
+No match:
 </p>
 <div class="org-src-container">
 
@@ -410,7 +410,7 @@ <h2 id="sec-1"><span class="section-number-2">1</span> Relational Data</h2>
 </pre>
 
 <p>
-Cartesian product.
+Cartesian product:
 </p>
 <div class="org-src-container">
 
@@ -481,7 +481,8 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 
 <p>
 Before we perform any calculation, we need to define the relationship between variables. In this case, we will define
-<code>adults</code> as the sum of <code>men</code> and <code>women</code>; and <code>population</code> as the sum of <code>adults</code> and <code>children</code>.
+<code>ADULTS</code> as the sum of <code>MEN</code> and <code>WOMEN</code>; and <code>POPULATION</code> as the sum of <code>ADULTS</code> and <code>CHILDREN</code>. <code>PETS</code> is the product
+of <code>CHILDREN</code> and <code>PETS-PER-CHILD</code>.
 </p>
 <div class="org-src-container">
 
@@ -536,43 +537,15 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 <p>
 The resulting system contains transformations for deriving parameters from each other, when possible.
 </p>
-<pre class="example">
-#&lt;SYSTEM (:COMPONENTS
-          ((COMPONENT ((TRANSFORMATION (SIG #{
-                                              MEN
-                                              WOMEN } -&gt; #{
-                                                           ADULTS }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              MEN
-                                              ADULTS } -&gt; #{
-                                                            WOMEN }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              WOMEN
-                                              ADULTS } -&gt; #{
-                                                            MEN }) === "FN()")))
-           (COMPONENT ((TRANSFORMATION (SIG #{
-                                              ADULTS
-                                              CHILDREN } -&gt; #{
-                                                              POPULATION }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              ADULTS
-                                              POPULATION } -&gt; #{
-                                                                CHILDREN }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              CHILDREN
-                                              POPULATION } -&gt; #{
-                                                                ADULTS }) === "FN()"))))
-          :SUBSYSTEMS NIL :SCHEMA NIL :DATA NIL)&gt;
-</pre>
 
 <p>
-Now that we have defined the relationship between parameters, we can use the convenience function, <code>ask</code> to ask
-questions. <code>ask</code> takes a system, a list of target attributes, and input data. If Orient can find a solution it will be
+Now that we have defined the relationship between parameters, we can use the convenience function, <code>ASK</code> to ask
+questions. <code>ASK</code> takes a system, a list of target attributes, and input data. If Orient can find a solution it will be
 returned.
 </p>
 
 <p>
-Let's calculate <code>population</code> and <code>adults</code>.
+Let's calculate <code>POPULATION</code> and <code>ADULTS</code>.
 </p>
 <div class="org-src-container">
 
@@ -615,7 +588,7 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 </pre>
 
 <p>
-And remember, Orient is relational, so our input can be a relation and so can the output. Here we join a relation
+Remember, Orient is relational, so our input can be a relation and so can the output. Here we join a relation
 containing a number of different populations with a tuple containing the (constant) numbers of women and adults. And in
 order to make our results more legible, we ask for the population too.
 </p>
@@ -641,12 +614,12 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 </pre>
 
 <p>
-If we want more information about the solution, we can use <code>solve-for</code>. <code>solve-for</code> returns the whole solution and
-doesn't project just the requested attributes like <code>ask</code> does.
+If we want more information about the solution, we can use <code>SOLVE-FOR</code>. <code>SOLVE-FOR</code> returns the whole solution and
+doesn't project just the requested attributes like <code>ASK</code> does.
 </p>
 
 <p>
-It also returns some other values: the <code>plan</code>, an optional <code>report</code> (which we didn't request here), and the
+It also returns some other values: the <code>PLAN</code>, an optional <code>REPORT</code> (which we didn't request here), and the
 <code>initial-data</code> (which might have been assembled in a more complex way than in this example).
 </p>
 <div class="org-src-container">
@@ -676,27 +649,19 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 Finally, we see the input tuple itself.
 </p>
 
-<pre class="example">
-#{| (MEN 14) (WOMEN 11) (ADULTS 25) (CHILDREN 25) (POPULATION 50) |}
-((TRANSFORMATION (SIG #{ WOMEN ADULTS } -&gt; #{ MEN }) === "FN()")
- (TRANSFORMATION (SIG #{ ADULTS POPULATION } -&gt; #{ CHILDREN }) === "FN()"))
-""
-#{| (WOMEN 11) (ADULTS 25) (POPULATION 50) |}
-</pre>
-
-
 <p>
 The output is a bit hard to read, since multiple values are jammed up together, so let's look at another example which
-binds each value to a variable and stores the results. We will also use the most general function, <code>solve</code> instead of
-the often-more-conveneitn <code>solve-for</code>.
+binds each value to a variable and stores the results. We will also use the most general function, <code>SOLVE</code> instead of
+the often-more-conveneitn <code>SOLVE-FOR</code>.
 </p>
 
 <p>
-This introduces the new concept of a <i>signature</i>, created below with <code>sig</code>. We solve <i>problems</i> over <i>systems</i>. (<i>Problems</i>
+This introduces the new concept of a <i>signature</i>, created below with <code>SIG</code>. We solve <i>problems</i> over <i>systems</i>. (<i>Problems</i>
 have the same shape as simple <i>signatures</i>, so we use <i>signatures</i> here for now. This will change in the future, since the
 overloading of <i>signature</i> can be confusing. We mention it here to hopefully reduce that confusion but realize the
-opposite effect may have been accomplished.
+opposite effect may have been accomplished.)
 </p>
+
 <div class="org-src-container">
 
 <pre class="src src-lisp">(multiple-value-bind (result plan report initial-values)
@@ -716,15 +681,9 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 </pre>
 
 <p>
-The results:
+The results.
 </p>
-<pre class="example">
-#{| (MEN 10) (WOMEN 11) (ADULTS 21) (CHILDREN 5) (POPULATION 26) |}
-</pre>
 
-<p>
-The plan:
-</p>
 <div class="org-src-container">
 
 <pre class="src src-lisp">plan1
@@ -736,10 +695,13 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
  (TRANSFORMATION (SIG #{ ADULTS CHILDREN } -&gt; #{ POPULATION }) === "FN()"))
 </pre>
 
+<p>
+The plan.
+</p>
 
 <p>
-And here is another way to create a signature, without the convenience macro, <code>sig</code>. We compare the two results using
-<code>same</code> which is generally aware of Orient's domain object equality and is useful when writing tests.
+And here is another way to create a signature, without the convenience macro, <code>SIG</code>. We compare the two results using
+<code>SAME</code> which is generally aware of Orient's domain object equality and is useful when writing tests.
 </p>
 <div class="org-src-container">
 
@@ -767,8 +729,9 @@ <h2 id="sec-2"><span class="section-number-2">2</span> Orient Basics</h2>
 </pre>
 
 <p>
-We can still calculate in different directions.
+We can still calculate in different directions, too.
 </p>
+
 <div class="org-src-container">
 
 <pre class="src src-lisp">(ask (find-system 'woozle-population)

tutorial.org

@@ -157,23 +157,23 @@ Joining a tuple with a relation lets you select a subset of its tuples.
 #+RESULTS:
 : #<RELATION #[ A B ] #{ #{| (A 3) (B 8) |} #{| (A 7) (B 8) |} }>
 
-No shared attributes.
+No shared attributes:
 #+BEGIN_SRC lisp :package scratch :exports both
 (join (tuple (a 1)) (tuple (b 2)))
 #+END_SRC
 
 #+RESULTS:
 : #{| (A 1) (B 2) |}
 
-No match.
+No match:
 #+BEGIN_SRC lisp :package scratch :exports both
 (join (tuple (a 1)) (tuple (a 2)))
 #+END_SRC
 
 #+RESULTS:
 : NIL
 
-Cartesian product.
+Cartesian product:
 #+BEGIN_SRC lisp :package scratch :exports both
   (join (relation (a) (1) (2) (3)) (relation (b) (1) (2) (3)))
 #+END_SRC
@@ -221,7 +221,8 @@ Orient uses schemas to define parameters. For now, these only associate descript
 : #<SCHEMA {1006C75D53}>
 
 Before we perform any calculation, we need to define the relationship between variables. In this case, we will define
-=adults= as the sum of =men= and =women=; and =population= as the sum of =adults= and =children=.
+=ADULTS= as the sum of =MEN= and =WOMEN=; and =POPULATION= as the sum of =ADULTS= and =CHILDREN=. =PETS= is the product
+of =CHILDREN= and =PETS-PER-CHILD=.
 #+BEGIN_SRC lisp :package scratch :exports both
     (defconstraint-system woozle-population
         ((adults (+ men women))
@@ -272,41 +273,12 @@ Before we perform any calculation, we need to define the relationship between va
 #+end_example
 
 The resulting system contains transformations for deriving parameters from each other, when possible.
-#+RESULTS:
-#+begin_example
-#<SYSTEM (:COMPONENTS
-          ((COMPONENT ((TRANSFORMATION (SIG #{
-                                              MEN
-                                              WOMEN } -> #{
-                                                           ADULTS }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              MEN
-                                              ADULTS } -> #{
-                                                            WOMEN }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              WOMEN
-                                              ADULTS } -> #{
-                                                            MEN }) === "FN()")))
-           (COMPONENT ((TRANSFORMATION (SIG #{
-                                              ADULTS
-                                              CHILDREN } -> #{
-                                                              POPULATION }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              ADULTS
-                                              POPULATION } -> #{
-                                                                CHILDREN }) === "FN()")
-                       (TRANSFORMATION (SIG #{
-                                              CHILDREN
-                                              POPULATION } -> #{
-                                                                ADULTS }) === "FN()"))))
-          :SUBSYSTEMS NIL :SCHEMA NIL :DATA NIL)>
-#+end_example
 
-Now that we have defined the relationship between parameters, we can use the convenience function, =ask= to ask
-questions. =ask= takes a system, a list of target attributes, and input data. If Orient can find a solution it will be
+Now that we have defined the relationship between parameters, we can use the convenience function, =ASK= to ask
+questions. =ASK= takes a system, a list of target attributes, and input data. If Orient can find a solution it will be
 returned.
 
-Let's calculate =population= and =adults=.
+Let's calculate =POPULATION= and =ADULTS=.
 #+BEGIN_SRC lisp :package scratch :exports both
    (ask (find-system 'woozle-population)
         '(population adults)
@@ -336,7 +308,7 @@ What if we know the population and number of adults but not how many men and chi
 #+RESULTS:
 : #{| (MEN 14) (CHILDREN 75) |}
 
-And remember, Orient is relational, so our input can be a relation and so can the output. Here we join a relation
+Remember, Orient is relational, so our input can be a relation and so can the output. Here we join a relation
 containing a number of different populations with a tuple containing the (constant) numbers of women and adults. And in
 order to make our results more legible, we ask for the population too.
 #+BEGIN_SRC lisp :package scratch :exports both
@@ -357,10 +329,10 @@ order to make our results more legible, we ask for the population too.
 :                                       #{| (CHILDREN 75) (POPULATION 100) |}
 :                                       #{| (CHILDREN 175) (POPULATION 200) |} }>
 
-If we want more information about the solution, we can use =solve-for=. =solve-for= returns the whole solution and
-doesn't project just the requested attributes like =ask= does.
+If we want more information about the solution, we can use =SOLVE-FOR=. =SOLVE-FOR= returns the whole solution and
+doesn't project just the requested attributes like =ASK= does.
 
-It also returns some other values: the =plan=, an optional =report= (which we didn't request here), and the
+It also returns some other values: the =PLAN=, an optional =REPORT= (which we didn't request here), and the
 =initial-data= (which might have been assembled in a more complex way than in this example).
 #+BEGIN_SRC lisp :package scratch :exports both
   (solve-for (find-system 'woozle-population) '(population children) (join (tuple (population 50)) (tuple (women 11) (adults 25))))
@@ -380,22 +352,15 @@ The list of transformations below is the plan. In this example, see that Orient
 
 Finally, we see the input tuple itself.
 
-#+RESULTS:
-: #{| (MEN 14) (WOMEN 11) (ADULTS 25) (CHILDREN 25) (POPULATION 50) |}
-: ((TRANSFORMATION (SIG #{ WOMEN ADULTS } -> #{ MEN }) === "FN()")
-:  (TRANSFORMATION (SIG #{ ADULTS POPULATION } -> #{ CHILDREN }) === "FN()"))
-: ""
-: #{| (WOMEN 11) (ADULTS 25) (POPULATION 50) |}
-
-
 The output is a bit hard to read, since multiple values are jammed up together, so let's look at another example which
-binds each value to a variable and stores the results. We will also use the most general function, =solve= instead of
-the often-more-conveneitn =solve-for=.
+binds each value to a variable and stores the results. We will also use the most general function, =SOLVE= instead of
+the often-more-conveneitn =SOLVE-FOR=.
 
-This introduces the new concept of a /signature/, created below with =sig=. We solve /problems/ over /systems/. (/Problems/
+This introduces the new concept of a /signature/, created below with =SIG=. We solve /problems/ over /systems/. (/Problems/
 have the same shape as simple /signatures/, so we use /signatures/ here for now. This will change in the future, since the
 overloading of /signature/ can be confusing. We mention it here to hopefully reduce that confusion but realize the
-opposite effect may have been accomplished.
+opposite effect may have been accomplished.)
+
 #+BEGIN_SRC lisp :package scratch :exports both
   (multiple-value-bind (result plan report initial-values)
       (solve (find-system 'woozle-population) 
@@ -411,11 +376,8 @@ opposite effect may have been accomplished.
 #+RESULTS:
 : #{| (MEN 10) (WOMEN 11) (ADULTS 21) (CHILDREN 5) (POPULATION 26) |}
 
-The results:
-#+RESULTS:
-: #{| (MEN 10) (WOMEN 11) (ADULTS 21) (CHILDREN 5) (POPULATION 26) |}
+The results.
 
-The plan:
 #+BEGIN_SRC lisp :package scratch :exports both
 plan1
 #+END_SRC
@@ -424,9 +386,10 @@ plan1
 : ((TRANSFORMATION (SIG #{ MEN WOMEN } -> #{ ADULTS }) === "FN()")
 :  (TRANSFORMATION (SIG #{ ADULTS CHILDREN } -> #{ POPULATION }) === "FN()"))
 
+The plan.
 
-And here is another way to create a signature, without the convenience macro, =sig=. We compare the two results using
-=same= which is generally aware of Orient's domain object equality and is useful when writing tests.
+And here is another way to create a signature, without the convenience macro, =SIG=. We compare the two results using
+=SAME= which is generally aware of Orient's domain object equality and is useful when writing tests.
 #+BEGIN_SRC lisp :package scratch :exports both
   (same (make-signature '(men women children) '(adults))
         (sig (men women children) -> (adults)))
@@ -444,7 +407,8 @@ And, just to show a slightly more complex example, let's not forget the pets!
 #+RESULTS:
 : #{| (MEN 14) (PETS 225) (CHILDREN 75) |}
 
-We can still calculate in different directions.
+We can still calculate in different directions, too.
+
 #+BEGIN_SRC lisp :package scratch :exports both
   (ask (find-system 'woozle-population)
        '(children pets-per-child)