lots of improvements and fixes of the homepage/handbook [fix]

_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-midnight

basis-escher.html

@@ -20,64 +20,64 @@ <h1>Escher faculty</h1>
 <h2>Index reflex</h2>
 
 <p>Every running Escher circuit program has been <a href="program.html">materialized relative to an index</a>.
-The index reflex, <code>escher.Index</code>, is a noun reflex that emits the index relative to which
+The index reflex, <code>e.Index</code>, is a noun reflex that emits the index relative to which
 the current circuit has been materialized.
 
 <p>The following program, for instance, will print out the index used to materialize the invoking circuit program:
 
-<pre>
+<pre class="escher">
 {
-	*Show = *escher.Index
+	*e.Show = *e.Index
 }
 </pre>
 
 <h2>Materialize reflex</h2>
 
-<p>The materialize reflex, named <code>escher.Materialize</code>,
+<p>The materialize reflex, named <code>e.Materialize</code>,
 materializes a program circuit relative to an index of faculties.
 
 <p>The reflex requires that two valves, <code>:View</code> and <code>:Residue</code>, be connected.
 Values sent to <code>:View</code> must be circuits containing gates named <code>Index</code> and <code>Program</code>.
-The value of the <code>Program</code> gate must be a circuit program (or any 
+The value of the <code>Program</code> gate must be a circuit program (or any
 <a href="program.html">gate value allowed within a circuit program</a>). Whereas the value of the
 <code>Index</code> gate should hold the index, relative to which the program will be materialized.
 
-<p>When a value is received at <code>:View</code>, the materialize reflex will materialize the 
+<p>When a value is received at <code>:View</code>, the materialize reflex will materialize the
 program relative to the given index and will return the residue to the valve <code>:Residue</code>.
 
 <p>Consider the following example program:
 
-<pre>
+<pre class="escher">
 {
-	m *escher.Materialize
-	f *Fork
+	m *e.Materialize
+	f *e.Fork
 
 	m:View = f:
 	f:Program = {
-		*Show = "Hello from the child circuit program."
+		*e.Show = "Hello from the child circuit program."
 	}
-	f:Index = *escher.Index
-	m:Residue = *Show
+	f:Index = *e.Index
+	m:Residue = *e.Show
 }
 </pre>
 
 <p>This program will materialize the child program
 
-<pre>
+<pre class="escher">
 {
-	*Show = "Hello from the child circuit program."
+	*e.Show = "Hello from the child circuit program."
 }
 </pre>
 
 <p>using the same index that was used to materialize the parent program, as acquired from
-the <code>*escher.Index</code> reflex in the parent program.
+the <code>*e.Index</code> reflex in the parent program.
 
 
 	</div>
 
 	<div class="footer">
 	The <a href="http://escher.io">Escher</a> and <a href="http://gocircuit.org">Circuit</a> projects are
-	partially supported by the 
+	partially supported by the
 	<a href="http://www.darpa.mil/Our_Work/I2O/Programs/XDATA.aspx">DARPA XData Initiative</a>.<br>
 	Sponsors and partners are welcome and appreciated. Contact <a href="mailto:[email protected]">Petar Maymounkov</a> for details.
 	</div>

basis-flow.html

@@ -23,69 +23,76 @@ <h1>Information flow reflexes</h1>
 
 <h3>Star reflex</h3>
 
-<p>The star is the simplest flow reflex. It accepts any number of 
+<p>(The implementation can be found in
+<a href="https://github.com/gocircuit/escher/blob/master/faculty/basic/star.go">faculty/basic/star.go</a>.)
+
+<p>The star is the simplest flow reflex. It accepts any number of
 connected valves and ignores their specific names.
 
 <p>When a value is received on any one of its connected valves,
 the star reflex forwards that value to all other connected valves.
 
-<p>Every forwarded value is emitted (i.e. sent) to its respective 
-valve on a dedicated goroutine. Therefore the star reflex never
-blocks. 
+<p>Every forwarded value is emitted (i.e. sent) to its respective
+valve on a dedicated Go routine. Therefore, the star reflex never
+blocks.
 
 <p>An example usage:
 
-<pre>
+<pre class="escher">
 {
-	star *Star
+	star *e.Star
 	one 1
 
 	star:X = one:
-	star:Y = *Show
-	star:Z = *Show
-	star:W = *Show
+	star:Y = *e.Show
+	star:Z = *e.Show
+	star:W = *e.Show
 }
 </pre>
 
 <p>When this circuit is materialized, the constant <code>1</code> will be emitted from gate <code>one</code>
 to valve <code>X</code> of gate <code>star</code>. The <code>star</code> gate will then forward the value
 to each of the valves <code>Y</code>, <code>Z</code> and <code>W</code> in parallel. Consequently
-it will be printed on the standard output three times by the receiving <code>*Show</code> reflexes.
+it will be printed on the standard output three times by the receiving <code>*e.Show</code> reflexes.
 
 <h3>Fork reflex</h3>
 
+<p>(The implementation can be found in
+<a href="https://github.com/gocircuit/escher/blob/master/be/union.go">be/union.go</a>.)
+
 <p>In our experience, the fork is the most commonly used synchronization primitive in Escher.
-It requires that the distinguished empty-string valve be connected, as well as one or more 
+It requires that the distinguished empty-string valve be connected, as well as one or more
 freely-named (string or integer) other valves.
 
-<p>Fork can be described as two entirely independent reflexes, let us call 
-them <em>merge</em> and <em>split</em>, embodied in one.
+<p>Fork can be described as two entirely independent reflexes.
+Let us call them <em>merge</em> and <em>split</em>, embodied in one.
 
 <h4>Split direction</h4>
 
-<p>Whenever a value W is received on the empty string valve of a fork,
-the reflex will process it using the split logic. The received value must be of type
-circuit. For every valve whose name N is not the empty string, fork will
-send the value of the gate named N from circuit W to that valve.
+<p>Whenever a value <em>W</em> (must be of type <code>Circuit</code>)
+is received on the empty string valve of a fork,
+the reflex will process it using the split logic.
+For every valve whose name <em>N</em> is not the empty string,
+fork will send the value of the gate named <em>N</em> from circuit <em>W</em> to that valve.
 
 <p>Take for instance this program:
 
-<pre>
+<pre class="escher">
 {
-	f *Fork
+	f *e.Fork
 	f: = {
 		x "Hello"
 		y "World"
 		z "Foo"
 	}
-	f:x = *Show
-	f:y = *Show
+	f:x = *e.Show
+	f:y = *e.Show
 }
 </pre>
 
-<p>The values <code>"Hello"</code> and <code>"World"</code> will be sent 
-to and printed by the connected <code>*Show</code> reflexes. Whereas the value <code>"Foo"</code>
-will be ignored.
+<p>The values <code>"Hello"</code> and <code>"World"</code> will be sent
+to and printed by the connected <code>*e.Show</code> reflexes.
+Whereas the value <code>"Foo"</code> will be ignored.
 
 <h4>Merge direction</h4>
 
@@ -94,16 +101,16 @@ <h4>Merge direction</h4>
 gate names follow respective valve names, and will send this circuit out to its empty string valve.
 
 <p>Note that in the merge direction fork reflexes act as powerful synchronization primitives.
-They effectively wait, blocking any other receptions on the non-empty-string valves, until 
-one value is available on each such valve. Subsequently these values are packed into a 
-single circuit and sent out.
+They effectively wait, blocking any other receptions on the non-empty-string valves, until
+one value is available on each such valve.
+Subsequently, these values are packed into a single circuit and sent out.
 
 <p>Consider the following program, for instance:
 
-<pre>
+<pre class="escher">
 {
-	f *Fork
-	f: = *Show
+	f *e.Fork
+	f: = *e.Show
 	f:x = "New"
 	f:y = "York"
 }
@@ -112,21 +119,21 @@ <h4>Merge direction</h4>
 <p>Fork will wait until <code>"New"</code> and <code>"York"</code> are received
 on valves <code>x</code> and <code>y</code>, respectively. Then the value
 
-<pre>
+<pre class="escher">
 {
 	x "New"
 	y "York"
 }
 </pre>
 
-<p>will be sent to and printed by the <code>*Show</code> reflex.
+<p>will be sent to and printed by the <code>*e.Show</code> reflex.
 
 
 	</div>
 
 	<div class="footer">
 	The <a href="http://escher.io">Escher</a> and <a href="http://gocircuit.org">Circuit</a> projects are
-	partially supported by the 
+	partially supported by the
 	<a href="http://www.darpa.mil/Our_Work/I2O/Programs/XDATA.aspx">DARPA XData Initiative</a>.<br>
 	Sponsors and partners are welcome and appreciated. Contact <a href="mailto:[email protected]">Petar Maymounkov</a> for details.
 	</div>

basis-os.html

@@ -18,7 +18,7 @@ <h1>POSIX faculty</h1>
 <p>The <code>os</code> faculty contains various reflexes for interacting with the POSIX
 environment within which an Escher program executes. It contains a few simple reflexes
 for accessing things like command-line arguments, environment variables, standard file
-descriptors, process execution and the like. 
+descriptors, process execution and the like.
 
 <p>Most reflexes in <code>os</code> are implemented in less than 10 lines of code
 and in that sense their implementation is their best documentation. Here we detail
@@ -36,7 +36,7 @@ <h2>Process execution reflex</h2>
 
 <p>An example of the command circuit value is as follows:
 
-<pre>
+<pre class="escher">
 {
 	Env {
 		"PATH=/abc:/bin"
@@ -50,7 +50,7 @@ <h2>Process execution reflex</h2>
 
 <p>The returned IO circuit value is of the following form:
 
-<pre>
+<pre class="escher">
 {
 	Stdin (io.WriteCloser)
 	Stdout (io.ReadCloser)
@@ -63,7 +63,7 @@ <h2>Process execution reflex</h2>
 
 <p>The exit circuit is of the form
 
-<pre>
+<pre class="escher">
 {
 	Exit (int)
 }
@@ -72,32 +72,32 @@ <h2>Process execution reflex</h2>
 <p>The following example demonstrates invoking the <code>/bin/ls</code> command
 and forwarding its standard output and error to those of the Escher program itself.
 
-<pre>
+<pre class="escher">
 {
 	proc *os.Process
 	proc:Command = {
 		Path "/bin/ls"
 		Args { "/" }
 	}
 
-	yio *Fork
+	yio *e.Fork
 	proc:IO = yio:
 
-	yio:Stdin = *Ignore
+	yio:Stdin = *e.Ignore
 	yio:Stdout = *os.Stdout
 	yio:Stderr = *os.Stderr
 
-	yexit *Fork
-	proc:Exit = yexit:
-	
+	yExit *e.Fork
+	proc:Exit = yExit:
+
 	exit *os.Exit
-	yexit:Exit = exit:
+	yExit:Exit = exit:
 }
 </pre>
 
 <p>The standard file descriptors of the child process must always be handled.
 In this example, standard output and error are forwarded while standard input is
-“ignored”. The reflex <code>*Ignore</code> is a “smart” reflex which
+“ignored”. The reflex <code>*e.Ignore</code> is a “smart” reflex which
 ignores primitive values (integers, floats, etc.), whereas it closes <code>io.Closer</code>
 objects and it drains <code>io.Reader</code> objects.
 
@@ -106,7 +106,7 @@ <h2>Process execution reflex</h2>
 
 	<div class="footer">
 	The <a href="http://escher.io">Escher</a> and <a href="http://gocircuit.org">Circuit</a> projects are
-	partially supported by the 
+	partially supported by the
 	<a href="http://www.darpa.mil/Our_Work/I2O/Programs/XDATA.aspx">DARPA XData Initiative</a>.<br>
 	Sponsors and partners are welcome and appreciated. Contact <a href="mailto:[email protected]">Petar Maymounkov</a> for details.
 	</div>

basis.html

@@ -15,15 +15,22 @@
 
 <h1>Reflex basis and faculties</h1>
 
-<p>There are two kinds of reflexes in Escher: 
+<p>A faculty is a set of reflexes, similar to a package in Java, or a namespace in C++.
+
+<p>There are two kinds of reflexes in Escher:
 <ul>
-<li>Those that are implemented in the underlying technology, the Go language, and linked into the runtime, which we call
-<em>basis</em> reflexes.
-<li>And those that are compositions of other reflexes, described by program circuits, which we call 
-<em>derivative reflexes</em>.
+<li><em>Basis reflexes</em>
+	are implemented in the underlying technology —
+	the Go language — and linked into the runtime
+<li><em>Derivative reflexes</em>
+	are compositions of other reflexes,
+	described by program circuits
 </ul>
 
-<p>Basis reflexes determine the basic arithmetic and data manipulation 
+<p>We will now have a look at the equivalent of <code>std</code> in C++,
+the Escher basis faculty.
+
+<p>Basis reflexes determine the basic arithmetic and data manipulation
 operations that Escher programs can ultimately perform, as well as
 external technologies that Escher programs might have access to.
 
@@ -37,29 +44,33 @@ <h3>Arithmetic</h3>
 <h3>Information flow</h3>
 
 <p>We find that most Escher programs benefit from
-a few basic reflexes that control information flow. 
-We have included a few in the default runtime and they are described in the following
-sections. These gates can be viewed as Escher's “synchronization” facilities.
+a few basic reflexes that control information flow.
+We have included a few in the default runtime,
+and they are described in <a href="basis-flow.html">a separate page</a>.
+These gates can be viewed as Escher's “synchronization” facilities.
 
 <h3>External technologies</h3>
 
-<p>Basis reflexes are also Escher's way of interacting with external technologies,
+<p>Basis reflexes are also Escher's way of interacting with external technologies
 such as input/output devices. The POSIX systems is a canonical example of an
-external technology and Escher has a dedicated <code>os</code> faculty for it.
+external technology, and Escher has a dedicated
+<a href="https://github.com/gocircuit/escher/tree/master/faculty/os"><code>os</code></a>
+faculty for it.
 
 <h3>Escher within Escher</h3>
 
-<p>The most powerful feature of Escher is its recursive nature: Circuit programs
-can create program circuits and materialize them into other circuit programs.
-This programming pattern is enabled by the <code>escher</code> faculty,
-which among other things offers reflexes that materialize program circuits.
+<p>The most powerful feature of Escher is its recursive nature:
+Circuit programs can create program circuits and materialize them into other circuit programs.
+This programming pattern is enabled by the
+<a href="https://github.com/gocircuit/escher/tree/master/faculty/escher"><code>escher</code></a>
+faculty, which among other things offers reflexes that materialize program circuits.
 
 
 	</div>
 
 	<div class="footer">
 	The <a href="http://escher.io">Escher</a> and <a href="http://gocircuit.org">Circuit</a> projects are
-	partially supported by the 
+	partially supported by the
 	<a href="http://www.darpa.mil/Our_Work/I2O/Programs/XDATA.aspx">DARPA XData Initiative</a>.<br>
 	Sponsors and partners are welcome and appreciated. Contact <a href="mailto:[email protected]">Petar Maymounkov</a> for details.
 	</div>