Update README.md

README.md

@@ -4,7 +4,7 @@ Issie (Interactive Schematic Simulator with Integrated Editor) is an application
 
 The application is was initially developed by Marco Selvatici, as a Final Year Project.
 
-The intercative Wave Simulator was developed by Edoardo Santi over a Summer UROP.
+The interactive waveform simulator was developed by Edoardo Santi over a Summer UROP.
 
 It is currently being maintained and developed by Tom Clarke (owner). 
 
@@ -18,15 +18,15 @@ For the Issie website go [here](https://tomcl.github.io/issie/).
 
 The application is mostly written in F#, which gets transpiled to JavaScript via the [Fable](https://fable.io/) compiler. [Electron](https://www.electronjs.org/) is then used to convert the developed web-app to a cross-platform application. [Electron](electronjs.org) provides access to platform-level APIs (such as access to the file system) which would not be available to vanilla browser web-apps.
 
-[Webpack 4](https://webpack.js.org/) is the module bundler responsible for the JavaScript concatenation and automated building process: the eelctron-webpack build 
+[Webpack 4](https://webpack.js.org/) is the module bundler responsible for the JavaScript concatenation and automated building process: the electron-webpack build 
 is automated with the all-in-one electron-webpack package.
 
 The drawing capabilities are provided by the [draw2d](http://www.draw2d.org/draw2d/) JavaScript library, which has been extended to support digital electronics components.
 
 The choice of F# as main programming language for the app has been dictated by a few factors:
 
-* the success of the [VisUAL2](https://github.com/ImperialCollegeLondon/Visual2), which uses a similar technology stack;
-* strongly typed functional code tends to be easy to maintain and test, as the type-checker massively helps you;
+* The success of the [VisUAL2](https://github.com/ImperialCollegeLondon/Visual2), which uses a similar technology stack;
+* Strongly typed functional code tends to be easy to maintain and test, as the type-checker massively helps you;
 * Imperial College EEE/EIE students learn such language in the 3rd year High-Level-Programming course, hence can maintain the app in the future;
 * F# can be used with the powerful [Elmish](https://elmish.github.io/elmish/) framework to develop User Interfaces in a [Functional Reactive Programming](https://en.wikipedia.org/wiki/Functional_reactive_programming) fashion.
 
@@ -41,27 +41,32 @@ Additionally, the section `"scripts"`:
 ```
  "scripts": {
     "compile": "dotnet fable src/main && dotnet fable src/renderer",
-    "dev": "dotnet fable src/main && dotnet fable watch src/renderer --run electron-webpack dev",
-    "watchmain": "dotnet fable watch src/main",
-    "webpack": "electron-webpack dev",
-    "dist": "npm run compile && electron-builder",
-    "distwin": "npm run compile && electron-builder -w",
-    "distmac": "npm  compile && electron-builder -m"
+    "dev": "cd src/main && dotnet fable watch . --run npm run devrenderer",
+    "devmain": "cd src/main && dotnet fable watch . --run npm run webpackdev",
+    "devrenderer": "cd src/renderer && dotnet fable watch . --run npm run webpackdev",
+    "webpackdev": "electron-webpack dev",
+    "webpack": "electron-webpack",
+    "dist": "npm run compile && npm run webpack &&  electron-builder",
   }
 ```
-Defines the in-project shortcut commands, therefore when we use `npm run <stript_key>` is equivalent to calling `<script_value>`. 
+Defines the in-project shortcut commands as a set of `<key> : <value` lines, so that when we use `npm run <stript_key>` it is equivalent to calling `<script_value>`. 
 For example, in the root of the project, running in the terminal `npm run dev` is equivalent to the command line:
 
 ```
-dotnet fable src/main && dotnet fable watch src/renderer --run electron-webpack dev
+cd src/main && dotnet fable watch . --run npm run devrenderer
 ```
 
-This runs fable 3 to compile the main process, then again to compile and watch the renderer process. After the renderer compilation is finished 
-`electron-webpack dev` will be run. This invokes `electron-webpack` to pack and lauch the code under electron. Fable 3 will watch the rendere F# files
-and convert to javascript on the fly. Electron-webpack will watch the chnges in javascript files and hot load these into the running application.
+This runs fable 3 to transpile the main process, then (`--run` is an option of fable to run another command) runs script `devrenderer` to transpile to javascript and watch the F# files in the renderer process. After the renderer transpilation is finished 
+`electron-webpack dev` will be run. This invokes `webpack` to pack and lauch the javascript code, under electron, and also watches for changes in the javascript code, and *hot loads* these on the running application
 
-The build system depends on a `Fake` file `build.fsx`. This has targets representing build tasks, and normally these are used, 
-accessed via `build.cmd` or `build.sh`, instead of using `dotnet fake` directly.
+As result of this, at any time saving an edited F# renderer project file causes (nearly) immediate:
+
+* fable transpile to from F# to javascript file (dependent F# files may also be transpiled)
+* webpack hot load of any changed javascript files to the running electron application
+
+The build system depends on a `Fake` file `build.fsx`. Fake is a DSL written in F# that is specialised to automate build tasks. Build.fsx has targets representing build tasks, and normally these are run via `build.cmd` or `build.sh`, instead of using `dotnet fake` directly:
+
+* `build <target>` ==> `dotnet fake build -t <target>`
 
 ## Code Structure
 
@@ -76,14 +81,14 @@ Both processes run Javascript under Node.
 
 The `src/Main/Main.fs` source configures electron start-up and is boilerplate. It is transpiled to the root project directory so it can be automatically picked up by Electron.
 
-The remaining app code is arranged in five different sections, each being a separate F# project. This separation allows all the non-web-based code (which can equally be run and tested under .Net) to be run and tested under F# directly in addition to being transpiled and run under Electron.
+The remaining app code is arranged in fourferent sections, each being a separate F# project. This separation allows all the non-web-based code (which can equally be run and tested under .Net) to be run and tested under F# directly in addition to being transpiled and run under Electron.
 
-The project relies on the draw2d JavaScript library, which is extended to support digital electronics components. The extensions are in the `app/public/lib/draw2d_extensions` folder and are loaded by the `index.html` file. The `index.html` file is otherwise empty as the UI elements are dynamically generated with [React](https://reactjs.org/), thanks to the F# Elmish library.
+The project relies on the draw2d JavaScript (node) library, which is extended to support digital electronics components. The extensions are in the `draw2d` sub-folder of teh renderer project source files. 
 
-The code that turns the F# project source into `renderer.js` is the FABLE compiler followed by the Node Webpack bundler that combines multiple Javascript files into a single `renderer.js`. Note that the FABLE compiler is distributed as a node package so gets set up automatically with other Node components.
+The code that turns the F# project source into `renderer.js` is the FABLE compiler followed by the Node Webpack bundler that combines multiple Javascript files into a single `renderer.js`.
 
 The compile process is controlled by the `.fsproj` files (defining the F# source) and `webpack.additions.main.js`, `webpack.additions.renderer.js`
-which defines how Webpack combines F# outputs for both electron main and electron app processes and where the executable code is put. 
+which define how Webpack combines F# outputs for both electron main and electron app processes and where the executable code is put. 
 This is boilerplate which you do not need to change; normally the F# project files are all that needs to be modified.
 
 ## File Structure
@@ -106,21 +111,29 @@ Contains numerous tests for the WidthInferer and Simulator. Based on F# Expecto
 
 Contains static files used in the application.
 
-### `Docsrc` folder
+### `Docs` folder
 
 Contains source information copied (or compiled) into the `docs` directory that controls the project 
 [Github Pages](https://pages.github.com/) website, with url [https://tomcl.github.io/issie/](https://tomcl.github.io/issie/).
 
-## Concept of Project and File in Issie
+## Project versus File in the Issie application
 
-ISSIE allows the users to create projects and files within those projects. A ISSIE project is simply a folder named `<project_name>.dprj` (dprj stands for diagram project). A project contains a collection of designs, each named `<component_name>.dgm` (dgm stands for diagram).
+ISSIE allows the users to create projects and files within those projects. A ISSIE project is simply a folder named `<project-name>` that contains an empty file named `<project_name>.dprj` (dprj stands for diagram project). The project folder any non-zero number of design files, each named `<component_name>.dgm` (dgm stands for diagram). each deisgn file represents one design sheet of a hierarchical hardware design, sheets can contain, as components, other sheets.
 
-When opening a project, ISSIE will search the given repository for `.dgm` files, parse their content, and allow the user to open them in ISSIE or use them as components in other designs.
+When opening a project, ISSIE will initially search the given repository for `.dgm` files, parse and load their content, and allow the user to open them in ISSIE or use them as components in other designs.
 
 ## Build Magic
 
-This project uses modern F# / dotnet cross-platform build. The build tools all install cross-platform under dotnet, downloaded automatically by paket. The Fake 
-tool (F# make) automates the rest of the build and also downloads Node.
+This project uses modern F# / dotnet cross-platform build. The build process runs as follows:
+
+* Before anything can be built dotnet must be installed: there is no other external dependence because everything else will be automatically installed. Dotnet includes the paket tool which will manage other dependencies.
+* Initially (the first time `build.cmd` is run) the tools categorised in `dotnet-tools.json` are installed by `dotnet tool restore`.
+   * fake (with the F# compiler) 
+   * fable
+* Next all the project dotnet dependencies (`paket.dependencies` for the whole project, selected from by the `paket.references` in each project directory, are loaded by the `paket` packet manager.
+* Finally fake runs `build.fsx` (this is platform-independent) to install all the node (Javascript) dependencies listed in `package.json`. That includes tools like webpack and electron, which run under node, as well as the node libraries that will be used by needed by the running electron app, including electron itself. These are all loaded by the `npm` packet manager. To run `npm` Node must be installed, this is also done through a dotnet package. (TODO: is it? Or must it be installed maniually?).
+
+The initial setup does not normally need changing. It is complicated by the fact that dependencies are both dotnet (dotnet build tools and dotnet F#projects) and Node (all the javascript libraries). These are configured and loaded by separate tools: paket for dotnet, and 
 
 
 ## Getting Started