doc: introduction

README.md

@@ -124,7 +124,7 @@ To execute the `HelloWorld` HipHop program from within a JavaScript module,
 we create a machine and we proceed to *reactions* (here 4 reactions are
 triggered).
 
-```
+```javascript
 const m = new ReactiveMachine(HelloWorld, "ABRO");
 m.addEventListener("O", e => console.log("got: ", e));
 m.react({ A: 1 });
@@ -133,6 +133,6 @@ m.react({ R: true });
 m.react({ A: 3, B: 4 });
 ```
 
-> [!CAUTION]
+> [!IMPORTANT]
 > HipHop requires the program to use ECMAScript modules. They cannot 
 > be used with CommonJS modules.

doc/README.md

@@ -3,9 +3,9 @@
 
 
 
-  1. [Introduction](./_index.md)
-  2. [License](./license.md)
-  3. [Download](./download.md)
+  1. [Introduction](./_index.md), general introduction to HipHop
+  2. [License](./license.md), the license of this release
+  3. [Download](./download.md), how to get HipHop
   4. [Language](./_lang.md)
   5. [API](./api.md)
   6. [Dev](./dev.md)

doc/_index.md

@@ -1,45 +1,74 @@
-${ var doc = require("hopdoc") }
+<!-- ${ var doc = require("hopdoc") } -->
 
 HipHop.js: Synchronous Multitier JavaScript Reactive Programming
-----------------------------------------------------------------
+================================================================
 
-__HipHop.js__ is an [Hop.js](http://hop.inria.fr) DLS for
-orchestrating web applications. HipHop.js helps programming 
-and maintaining Web applications where the orchestration of
-asynchronous tasks is complex. 
+__HipHop.js__ is a JavaScript DLS for orchestrating asynchronous
+applications. It helps programming applications that require complex
+orchestration tasks. Its main application domains are web applications
+and IoT application. HipHop.js helps programming and maintaining Web
+applications where the
 
 HipHop.js adds synchronous concurrency and preemption to
 JavaScript. Inspired from Esterel, it simplifies the programming of
 non-trivial temporal behaviors as found in complex web interfaces or
 IoT controllers and the cooperation between synchronous and
 asynchronous activities. HipHop.js is compiled into plain sequential
-JavaScript and executes on unmodified runtime environments.
+JavaScript and executes on unmodified JavaScript runtime environments.
 
-${<span class="label label-success">Important:</span>} Since version 1.1.0
-HipHop programs can be executed in [Hop.js](http://hop.inria.fr), all
-web browsers, and [Node.js](https://nodejs.org/en/).
-
-### Example 1
+Example
+-------
 
 Here is a seminal example of synchronous programming languages. This
 program simulates a machine that has three input buttons. It waits for
 buttons `A` and `B` to be clicked before emitting the signal `O`. The
 machine is reset when button `R` is pressed, whatever its current
 state.
 
-```hiphop
-${ doc.include( "abro-gui.hh.js" ) }
+```javascript
+// hello.hh.js
+import { ReactiveMachine } from "@hop/hiphop";
+
+const abro = hiphop module() {
+   in A, in B, in R;
+   out O;
+   do {
+      fork {
+         await (A.now);
+      } par {
+         await (B.now);
+      }
+      emit O();
+   } every (R.now)
+}
+
+const m = new ReactiveMachine(abro);
+m.addEventListener("O", e => console.log("got: ", e));
+m.react({ A: 1 });
+m.react({ B: 2 });
+m.react({ R: true });
+m.react({ A: 3, B: 4 });
 ```
 
-### Example 2, Android
+The statement `do`/`every` implements a loop that executes its body
+each time the condition of the `every` is statisfied. The statement
+`fork`/`par` spawns new computation threads. The statement `await`
+blocs the execution of the current thread until the condition is
+satisfied. For instance, the statement `await (A.now)` blocs the
+first thread of the `fork` statement until the signal `A` is emitted.
 
-HipHop.js can be used on fullfledged computers such as desktops and
-laptops. It can also be used on Android devices. The second example
-binds on-device events inside a HipHop.js reactive machine to
-automatically answer SMS messages still answered after a user defined
-delay has expired.
+To be executed, a HipHop program has to be loaded into a _reactive machine_.
+This is done with the expression `new ReactiveMachine(abro)`, which creates
+a new reactive machine and loads the `abro` into it.
 
-```hiphop
-${ doc.include( "../examples/hhdroid/hhdroid.js" ) }
-```
+Event listeners can be added to a reactive machine so that JavaScript
+can be notified of HipHop executions. In our example, a listener
+is attached to the HipHip signal `O` so that at the end of each
+reactive step, also called a _reaction_, the JavaScript listener will
+be invoked if during the reaction the HipHop signal `O` as been emitted.
 
+At the first reaction, we HipHop program `abro` is executed with
+the signal `A` emitted with the associated value 1. For the second
+reaction, the program is sent the signal `B` with value 2. At
+the third reaction the signal `R` is emitted, and finally, at
+the forth reaction, both signals `A` and `B` are emitted.

doc/license.md

@@ -4,13 +4,14 @@ ${ var xml = require( config.docDir + "/xml.js" ) }
 ${ var cfg = require( "./doc.json" ) }
 ${ var pkg = require( "../package.json" ) } -->
 
-    HipHop.js, Synchronous Multitier JavaScript Reactive Programming
+HipHop.js, Synchronous Multitier JavaScript Reactive Programming
 
-    Copyright (c) 2024 INRIA
-                                                                      
-    Bug descriptions, user reports, comments, suggestions and
-    pull requests are welcome. Submit them them to
-
-       https://github.com/manuel-serrano/hiphop.git
+© 2024 INRIA
+
+This software is released under the [Apache 2.0 license](https://apache.org/licenses/LICENSE-2.0).
+
+Bug descriptions, user reports, comments, suggestions and
+pull requests are welcome. Submit them them to
+
+https://github.com/manuel-serrano/hiphop.git
 
-    This software is released under the [Apache 2.0 license](https://apache.org/licenses/LICENSE-2.0).