From 13aa08e59cdd2e2307eef4dedad77826f7fe5178 Mon Sep 17 00:00:00 2001
From: Stefan Verhoeven <stefan.verhoeven@gmail.com>
Date: Thu, 4 Jun 2020 16:29:17 +0200
Subject: [PATCH 1/5] Make `entangled tangle` generate OK code.

---
 CONTRIBUTING.md | 8 +++++---
 INSTALL.md      | 2 +-
 README.md       | 4 ++--
 entangled.dhall | 8 ++++++++
 4 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4451466..6f66d53 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -113,10 +113,12 @@ Before you submit a pull request, check that it meets these guidelines:
 
 ## Generating code from Markdown
 
-The [Entangled - Pandoc filters](https://github.com/entangled/filters) Docker image can be used to generate source code files from the Markdown files.
+The [Entangled](https://github.com/entangled/entangled) Docker image can be used to generate source code files from the Markdown files.
 
-```{.awk #pandoc-tangle}
-docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md
+```{.awk #entangled-tangle}
+rm -r .entangled
+docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled insert -s *.md
+docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled tangle -a
 ```
 
 ## Generate code from Markdown and vice versa
diff --git a/INSTALL.md b/INSTALL.md
index 8daf4a4..78a8910 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -25,7 +25,7 @@ ENTANGLED := $(shell perl -ne 'print $$1,"\n" if /^```\{.*file=(.*)\}/' *.md | g
 COMPILED := bin/newtonraphson.exe src/py/newtonraphsonpy.*.so apache2/cgi-bin/newtonraphson src/js/newtonraphsonwasm.js  src/js/newtonraphsonwasm.wasm
 
 entangle: *.md
-	<<pandoc-tangle>>
+	<<entangled-tangle>>
 
 $(ENTANGLED): entangle
 
diff --git a/README.md b/README.md
index 2dd52f1..a70efd5 100644
--- a/README.md
+++ b/README.md
@@ -977,7 +977,7 @@ The code supplied here should not be used in production as converting JSX in the
 The web application in our example should have a form with a `epsilon` and `guess` input field and a submit button.
 The form in JSX can be written in the following way:
 
-```{.jsx #react-form}
+```{.jsxinline #react-form}
 { /* this JavaScript snippet is later referred to as <<react-form>> */ }
 <form onSubmit={handleSubmit}>
   <label>
@@ -1221,7 +1221,7 @@ function handleChange(event) {
 
 The form can be rendered with
 
-```{.jsx #jsonschema-form}
+```{.jsxinline #jsonschema-form}
 { /* this JavaScript snippet is later referred to as <<jsonschema-form>>  */}
 <Form
   uiSchema={uiSchema}
diff --git a/entangled.dhall b/entangled.dhall
index ea5bcba..4735a0a 100644
--- a/entangled.dhall
+++ b/entangled.dhall
@@ -1,7 +1,15 @@
 let entangled = https://raw.githubusercontent.com/entangled/entangled/v1.0.1/data/config-schema.dhall
                 sha256:9fd18824499379eee53b974ca7570b3bc064fda546348d9b31841afab3b053a7
 
+let jsxinlineComment = entangled.Comment.Block { start = "{ /*", end = "*/ }" }
+
+let languages = entangled.languages #
+    [ { name = "jsx", identifiers = ["jsx"], comment = entangled.comments.cppStyle }
+     ,{ name = "jsxinline", identifiers = ["jsxinline"], comment = jsxinlineComment }
+    ]
+
 in { entangled = entangled.Config :: { database = Some ".entangled/db.sqlite"
                                      , watchList = ["README.md", "INSTALL.md", "CONTRIBUTING.md", "TESTING.md"] : List Text
+                                     , languages = languages
                                      }
    }

From 43b36467f2ca7a03a1c3c3ffa3ea610021fccdd3 Mon Sep 17 00:00:00 2001
From: Stefan Verhoeven <stefan.verhoeven@gmail.com>
Date: Thu, 4 Jun 2020 16:34:03 +0200
Subject: [PATCH 2/5] Replace .awk with .shell

.awk was chosen as pandoc filter could not define new languages
---
 CONTRIBUTING.md |  8 ++++----
 README.md       | 38 +++++++++++++++++++-------------------
 entangled.dhall |  1 +
 3 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f66d53..5a71341 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -115,7 +115,7 @@ Before you submit a pull request, check that it meets these guidelines:
 
 The [Entangled](https://github.com/entangled/entangled) Docker image can be used to generate source code files from the Markdown files.
 
-```{.awk #entangled-tangle}
+```{.shell #entangled-tangle}
 rm -r .entangled
 docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled insert -s *.md
 docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled tangle -a
@@ -146,7 +146,7 @@ The rest of this section describes how the git hook works.
 
 The pre-commit hook script runs entangle using Docker and adds newly written files to the current git commit.
 
-```{.awk file=.githooks/pre-commit}
+```{.shell file=.githooks/pre-commit}
 #!/bin/sh
 # this shell script is stored as .githooks/pre-commit
 
@@ -167,13 +167,13 @@ echo $FILES | xargs git add
 
 The hook must be made executable with
 
-```{.awk #hook-permission}
+```{.shell #hook-permission}
 chmod +x .githooks/pre-commit
 ```
 
 The git hook can be enabled with
 
-```{.awk #init-git-hook}
+```{.shell #init-git-hook}
 git config --local core.hooksPath .githooks
 ```
 
diff --git a/README.md b/README.md
index a70efd5..5627697 100644
--- a/README.md
+++ b/README.md
@@ -119,13 +119,13 @@ int main()
 
 Compile with
 
-```{.awk #build-cli}
+```{.shell #build-cli}
 g++ src/cli-newtonraphson.cpp -o bin/newtonraphson.exe
 ```
 
 Run with
 
-```{.awk #test-cli}
+```{.shell #test-cli}
 ./bin/newtonraphson.exe
 ```
 
@@ -227,13 +227,13 @@ Where `nlohmann/json.hpp` is a JSON serialization/unserialization C++ header onl
 
 This can be compiled with
 
-```{.awk #build-cgi}
+```{.shell #build-cgi}
 g++ -Ideps src/cgi-newtonraphson.cpp -o apache2/cgi-bin/newtonraphson
 ```
 
 The CGI script can be tested directly with
 
-```{.awk #test-cgi}
+```{.shell #test-cgi}
 echo '{"guess":-20, "epsilon":0.001}' | apache2/cgi-bin/newtonraphson
 ```
 
@@ -308,7 +308,7 @@ Python can call functions in a C++ library if its functions use [Python.h dataty
 
 To use pybind11, it must installed with pip
 
-```{.awk #pip-pybind11}
+```{.shell #pip-pybind11}
 pip install pybind11
 ```
 
@@ -339,7 +339,7 @@ PYBIND11_MODULE(newtonraphsonpy, m) {
 
 Compile with
 
-```{.awk #build-py}
+```{.shell #build-py}
 g++ -O3 -Wall -shared -std=c++14 -fPIC `python3 -m pybind11 --includes` \
 src/py-newtonraphson.cpp -o src/py/newtonraphsonpy`python3-config --extension-suffix`
 ```
@@ -357,7 +357,7 @@ print(root)
 
 The Python example can be run with
 
-```{.awk #test-py}
+```{.shell #test-py}
 python src/py/example.py
 ```
 
@@ -374,7 +374,7 @@ To assist in making a web application a web framework needs to be picked. The [F
 
 The Flask Python library can be installed with
 
-```{.awk #pip-flask}
+```{.shell #pip-flask}
 pip install flask
 ```
 
@@ -439,7 +439,7 @@ app.run(port=5001)
 
 And running it with
 
-```{.awk #run-webapp}
+```{.shell #run-webapp}
 python src/py/webapp.py
 ```
 
@@ -452,13 +452,13 @@ When performing a long calculation (more than 30 seconds), the end-user requires
 Celery needs a broker for a queue and result storage.
 We'll use [redis](https://redis.io/) in a Docker container as Celery broker, because it's simple to setup. Redis can be started with the following command
 
-```{.awk #start-redis}
+```{.shell #start-redis}
 docker run --rm -d -p 6379:6379 --name some-redis redis
 ```
 
 To use Celery we must install the redis flavored version with
 
-```{.awk #pip-celery}
+```{.shell #pip-celery}
 pip install celery[redis]==4.4.3
 ```
 
@@ -549,13 +549,13 @@ if __name__ == '__main__':
 
 Start the web application like before with
 
-```{.awk #run-celery-webapp}
+```{.shell #run-celery-webapp}
 python src/py/webapp-celery.py
 ```
 
 Tasks will be run by the Celery worker. The worker can be started with
 
-```{.awk #run-celery-worker}
+```{.shell #run-celery-worker}
 PYTHONPATH=src/py celery worker -A tasks
 ```
 
@@ -569,7 +569,7 @@ To test the web service
 
 The redis server can be shut down with
 
-```{.awk #stop-redis}
+```{.shell #stop-redis}
 docker stop some-redis
 ```
 
@@ -659,7 +659,7 @@ def calculate(body):
 
 To provide the `calculate` method as a web service we must install Connexion Python library (with the Swagger UI for later testing)
 
-```{.awk #pip-connexion}
+```{.shell #pip-connexion}
 pip install connexion[swagger-ui]
 ```
 
@@ -676,14 +676,14 @@ app.run(port=8080)
 
 The web service can be started with
 
-```{.awk #run-webservice}
+```{.shell #run-webservice}
 python src/py/webservice.py
 ```
 
 We can try out the web service using the Swagger UI at [http://localhost:8080/ui/](http://localhost:8080/ui/).
 Or by running a ``curl`` command like
 
-```{.awk #test-webservice}
+```{.shell #test-webservice}
 curl -X POST "http://localhost:8080/api/newtonraphson" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"epsilon\":0.001,\"guess\":-20}"
 ```
 
@@ -721,7 +721,7 @@ EMSCRIPTEN_BINDINGS(newtonraphsonwasm) {
 The algorithm and binding can be compiled into a WebAssembly module with the Emscripten compiler called `emcc`.
 To make live easier we configure the compile command to generate a `src/js/newtonraphsonwasm.js` file which exports the `createModule` function.
 
-```{.awk #build-wasm}
+```{.shell #build-wasm}
 emcc --bind -o src/js/newtonraphsonwasm.js -s MODULARIZE=1 -s EXPORT_NAME=createModule src/wasm-newtonraphson.cpp
 ```
 
@@ -775,7 +775,7 @@ To be able to use the `createModule` function, we will import the `newtonraphson
 The web browser can only load the `newtonraphsonwasm.js` file when hosted by a web server.
 Python ships with a built-in web server, we will use it to host the all files of the repository on port 8000.
 
-```{.awk #host-files}
+```{.shell #host-files}
 python3 -m http.server 8000
 ```
 
diff --git a/entangled.dhall b/entangled.dhall
index 4735a0a..c1a38ec 100644
--- a/entangled.dhall
+++ b/entangled.dhall
@@ -6,6 +6,7 @@ let jsxinlineComment = entangled.Comment.Block { start = "{ /*", end = "*/ }" }
 let languages = entangled.languages #
     [ { name = "jsx", identifiers = ["jsx"], comment = entangled.comments.cppStyle }
      ,{ name = "jsxinline", identifiers = ["jsxinline"], comment = jsxinlineComment }
+     ,{ name = "Bash", identifiers = ["bash", "sh", "shell"], comment = entangled.comments.hash }
     ]
 
 in { entangled = entangled.Config :: { database = Some ".entangled/db.sqlite"

From 2a6342481e7dc4c6287be6dfac0a6f5cee1caf90 Mon Sep 17 00:00:00 2001
From: Stefan Verhoeven <stefan.verhoeven@gmail.com>
Date: Thu, 4 Jun 2020 17:49:33 +0200
Subject: [PATCH 3/5] Switch to entangled some more

---
 CONTRIBUTING.md | 7 +++----
 INSTALL.md      | 5 ++++-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5a71341..fcf8605 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -116,7 +116,6 @@ Before you submit a pull request, check that it meets these guidelines:
 The [Entangled](https://github.com/entangled/entangled) Docker image can be used to generate source code files from the Markdown files.
 
 ```{.shell #entangled-tangle}
-rm -r .entangled
 docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled insert -s *.md
 docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled tangle -a
 ```
@@ -155,9 +154,9 @@ UID=$(id -u)
 echo 'Check entangled files are up to date'
 
 # Entangle Markdown to source code and store the output
-LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md 2>&1 > /dev/null)
-# Parse which filenames have been written from output
-FILES=$(echo $LOG | perl -ne 'print $1,"\n" if /^Writing \`(.*)\`./')
+LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled -m tangle -a 2>&1 > /dev/null)
+# Parse which filenames have been created or modified from output, ignoring deleted files (start with `- `)
+FILES=$(echo $LOG | grep -v '^-' | cut -c 3-)
 [ -z "$FILES" ] && exit 0
 echo $FILES
 
diff --git a/INSTALL.md b/INSTALL.md
index 78a8910..e7d50e4 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -21,7 +21,7 @@ All the commands in the [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTIN
 
 UID := $(shell id -u)
 # Prevent suicide by excluding Makefile
-ENTANGLED := $(shell perl -ne 'print $$1,"\n" if /^```\{.*file=(.*)\}/' *.md | grep -v Makefile | sort -u)
+ENTANGLED := $(shell docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled list)
 COMPILED := bin/newtonraphson.exe src/py/newtonraphsonpy.*.so apache2/cgi-bin/newtonraphson src/js/newtonraphsonwasm.js  src/js/newtonraphsonwasm.wasm
 
 entangle: *.md
@@ -116,6 +116,9 @@ init-git-hook:
 
 check: entangle
 	git diff-index --quiet HEAD --
+# TODO entangled always OK due to entangle target being run before. `make check` should not have entangle target called.
+#check:
+#	docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled -c tangle -a
 ```
 
 For example the Python dependencies can be installed with

From 1990180d2ac5321890dc6f5cf0906d521ca7fb5e Mon Sep 17 00:00:00 2001
From: Stefan Verhoeven <stefan.verhoeven@gmail.com>
Date: Thu, 4 Jun 2020 17:49:58 +0200
Subject: [PATCH 4/5] Generated files with `entangled tangle`

---
 .githooks/pre-commit                          | 11 ++--
 Makefile                                      | 59 ++++++++++++++++++-
 apache2/apache2.conf                          |  5 +-
 cypress/integration/example-app_spec.js       |  5 +-
 .../example-jsonschema-form_spec.js           |  5 +-
 .../integration/example-web-worker_spec.js    |  5 +-
 cypress/integration/example_spec.js           |  5 +-
 src/cgi-newtonraphson.cpp                     |  7 ++-
 src/cli-newtonraphson.cpp                     |  7 ++-
 src/js/app.js                                 | 29 ++++++++-
 src/js/example-app.html                       | 13 +++-
 src/js/example-jsonschema-form.html           | 13 +++-
 src/js/example-web-worker.html                | 13 +++-
 src/js/example.html                           | 13 +++-
 src/js/jsonschema-app.js                      | 23 +++++++-
 src/js/worker.js                              | 13 +++-
 src/newtonraphson.hpp                         |  5 +-
 src/py-newtonraphson.cpp                      |  7 ++-
 src/py/api.py                                 |  5 +-
 src/py/example.py                             |  5 +-
 src/py/openapi.yaml                           |  5 +-
 src/py/tasks.py                               |  7 ++-
 src/py/webapp-celery.py                       | 11 +++-
 src/py/webapp.py                              | 11 +++-
 src/py/webservice.py                          |  5 +-
 src/wasm-newtonraphson.cpp                    |  7 ++-
 26 files changed, 262 insertions(+), 32 deletions(-)

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 00d6070..1007142 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,3 +1,5 @@
+# ~\~ language=Bash filename=.githooks/pre-commit
+# ~\~ begin <<CONTRIBUTING.md|.githooks/pre-commit>>[0]
 #!/bin/sh
 # this shell script is stored as .githooks/pre-commit
 
@@ -6,11 +8,12 @@ UID=$(id -u)
 echo 'Check entangled files are up to date'
 
 # Entangle Markdown to source code and store the output
-LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md 2>&1 > /dev/null)
-# Parse which filenames have been written from output
-FILES=$(echo $LOG | perl -ne 'print $1,"\n" if /^Writing \`(.*)\`./')
+LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled -m tangle -a 2>&1 > /dev/null)
+# Parse which filenames have been created or modified from output, ignoring deleted files (start with `- `)
+FILES=$(echo $LOG | grep -v '^-' | cut -c 3-)
 [ -z "$FILES" ] && exit 0
 echo $FILES
 
 echo 'Adding written files to commit'
-echo $FILES | xargs git add
\ No newline at end of file
+echo $FILES | xargs git add
+# ~\~ end
diff --git a/Makefile b/Makefile
index a69c1d5..7a132d7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,13 +1,18 @@
+# ~\~ language=Make filename=Makefile
+# ~\~ begin <<INSTALL.md|Makefile>>[0]
 # this Makefile snippet is stored as Makefile
 .PHONY: clean clean-compiled clean-entangled test all check entangle entangle-list py-deps start-redis stop-redis run-webservice run-celery-webapp run-webapp build-wasm host-files test-wasm
 
 UID := $(shell id -u)
 # Prevent suicide by excluding Makefile
-ENTANGLED := $(shell perl -ne 'print $$1,"\n" if /^```\{.*file=(.*)\}/' *.md | grep -v Makefile | sort -u)
+ENTANGLED := $(shell docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled list)
 COMPILED := bin/newtonraphson.exe src/py/newtonraphsonpy.*.so apache2/cgi-bin/newtonraphson src/js/newtonraphsonwasm.js  src/js/newtonraphsonwasm.wasm
 
 entangle: *.md
-	docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md
+	# ~\~ begin <<CONTRIBUTING.md|entangled-tangle>>[0]
+	docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled insert -s *.md
+	docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled tangle -a
+	# ~\~ end
 
 $(ENTANGLED): entangle
 
@@ -17,35 +22,55 @@ entangled-list:
 py-deps: pip-pybind11 pip-flask pip-celery pip-connexion
 
 pip-pybind11:
+	# ~\~ begin <<README.md|pip-pybind11>>[0]
 	pip install pybind11
+	# ~\~ end
 
 pip-flask:
+	# ~\~ begin <<README.md|pip-flask>>[0]
 	pip install flask
+	# ~\~ end
 
 pip-celery:
+	# ~\~ begin <<README.md|pip-celery>>[0]
 	pip install celery[redis]==4.4.3
+	# ~\~ end
 
 pip-connexion:
+	# ~\~ begin <<README.md|pip-connexion>>[0]
 	pip install connexion[swagger-ui]
+	# ~\~ end
 
 bin/newtonraphson.exe: src/cli-newtonraphson.cpp
+	# ~\~ begin <<README.md|build-cli>>[0]
 	g++ src/cli-newtonraphson.cpp -o bin/newtonraphson.exe
+	# ~\~ end
 
 test-cli: bin/newtonraphson.exe
+	# ~\~ begin <<README.md|test-cli>>[0]
 	./bin/newtonraphson.exe
+	# ~\~ end
 
 apache2/cgi-bin/newtonraphson: src/cgi-newtonraphson.cpp
+	# ~\~ begin <<README.md|build-cgi>>[0]
 	g++ -Ideps src/cgi-newtonraphson.cpp -o apache2/cgi-bin/newtonraphson
+	# ~\~ end
 
 test-cgi: apache2/cgi-bin/newtonraphson
+	# ~\~ begin <<README.md|test-cgi>>[0]
 	echo '{"guess":-20, "epsilon":0.001}' | apache2/cgi-bin/newtonraphson
+	# ~\~ end
 
 src/py/newtonraphsonpy.*.so: src/py-newtonraphson.cpp
+	# ~\~ begin <<README.md|build-py>>[0]
 	g++ -O3 -Wall -shared -std=c++14 -fPIC `python3 -m pybind11 --includes` \
 	src/py-newtonraphson.cpp -o src/py/newtonraphsonpy`python3-config --extension-suffix`
+	# ~\~ end
 
 test-py: src/py/example.py src/py/newtonraphsonpy.*.so
+	# ~\~ begin <<README.md|test-py>>[0]
 	python src/py/example.py
+	# ~\~ end
 
 test: test-cli test-cgi test-py test-webservice
 
@@ -62,40 +87,68 @@ clean-entangled:
 	$(RM) $(ENTANGLED)
 
 start-redis:
+	# ~\~ begin <<README.md|start-redis>>[0]
 	docker run --rm -d -p 6379:6379 --name some-redis redis
+	# ~\~ end
 
 stop-redis:
+	# ~\~ begin <<README.md|stop-redis>>[0]
 	docker stop some-redis
+	# ~\~ end
 
 run-webapp: src/py/newtonraphsonpy.*.so
+	# ~\~ begin <<README.md|run-webapp>>[0]
 	python src/py/webapp.py
+	# ~\~ end
 
 run-webservice: src/py/newtonraphsonpy.*.so
+	# ~\~ begin <<README.md|run-webservice>>[0]
 	python src/py/webservice.py
+	# ~\~ end
 
 test-webservice:
+	# ~\~ begin <<README.md|test-webservice>>[0]
 	curl -X POST "http://localhost:8080/api/newtonraphson" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"epsilon\":0.001,\"guess\":-20}"
+	# ~\~ end
 
 run-celery-worker: src/py/newtonraphsonpy.*.so
+	# ~\~ begin <<README.md|run-celery-worker>>[0]
 	PYTHONPATH=src/py celery worker -A tasks
+	# ~\~ end
 
 run-celery-webapp: src/py/newtonraphsonpy.*.so
+	# ~\~ begin <<README.md|run-celery-webapp>>[0]
 	python src/py/webapp-celery.py
+	# ~\~ end
 
 build-wasm: src/js/newtonraphsonwasm.js src/js/newtonraphsonwasm.wasm
 
 src/js/newtonraphsonwasm.js src/js/newtonraphsonwasm.wasm: src/wasm-newtonraphson.cpp
+	# ~\~ begin <<README.md|build-wasm>>[0]
 	emcc --bind -o src/js/newtonraphsonwasm.js -s MODULARIZE=1 -s EXPORT_NAME=createModule src/wasm-newtonraphson.cpp
+	# ~\~ end
 
 host-files: build-wasm
+	# ~\~ begin <<README.md|host-files>>[0]
 	python3 -m http.server 8000
+	# ~\~ end
 
 test-wasm:
+	# ~\~ begin <<TESTING.md|test-wasm>>[0]
 	npx cypress run --config-file false
+	# ~\~ end
 
 init-git-hook:
+	# ~\~ begin <<CONTRIBUTING.md|hook-permission>>[0]
 	chmod +x .githooks/pre-commit
+	# ~\~ end
+	# ~\~ begin <<CONTRIBUTING.md|init-git-hook>>[0]
 	git config --local core.hooksPath .githooks
+	# ~\~ end
 
 check: entangle
-	git diff-index --quiet HEAD --
\ No newline at end of file
+	git diff-index --quiet HEAD --
+# TODO entangled always OK due to entangle target being run before. `make check` should not have entangle target called.
+#check:
+#	docker run --rm --user ${UID} -v ${PWD}:/data nlesc/entangled -c tangle -a
+# ~\~ end
diff --git a/apache2/apache2.conf b/apache2/apache2.conf
index 6961d67..6572c1b 100644
--- a/apache2/apache2.conf
+++ b/apache2/apache2.conf
@@ -1,3 +1,5 @@
+# ~\~ language=Python filename=apache2/apache2.conf
+# ~\~ begin <<README.md|apache2/apache2.conf>>[0]
 # this Apache2 configuration snippet is stored as apache2/apache2.conf
 ServerName 127.0.0.1
 Listen 8080
@@ -8,4 +10,5 @@ LoadModule cgi_module /usr/lib/apache2/modules/mod_cgi.so
 ErrorLog httpd_error_log
 PidFile httpd.pid
 
-ScriptAlias "/cgi-bin/" "cgi-bin/"
\ No newline at end of file
+ScriptAlias "/cgi-bin/" "cgi-bin/"
+# ~\~ end
diff --git a/cypress/integration/example-app_spec.js b/cypress/integration/example-app_spec.js
index 65ea69e..d16f5f8 100644
--- a/cypress/integration/example-app_spec.js
+++ b/cypress/integration/example-app_spec.js
@@ -1,3 +1,5 @@
+/* ~\~ language=JavaScript filename=cypress/integration/example-app_spec.js */
+/* ~\~ begin <<TESTING.md|cypress/integration/example-app_spec.js>>[0] */
 describe('src/js/example-app.html', () => {
   it('should render -1.00', () => {
     cy.visit('http://localhost:8000/src/js/example-app.html');
@@ -6,4 +8,5 @@ describe('src/js/example-app.html', () => {
     cy.contains('Submit').click();
     cy.get('#answer').contains('-1.00');
   });
-});
\ No newline at end of file
+});
+/* ~\~ end */
diff --git a/cypress/integration/example-jsonschema-form_spec.js b/cypress/integration/example-jsonschema-form_spec.js
index ead379d..308e627 100644
--- a/cypress/integration/example-jsonschema-form_spec.js
+++ b/cypress/integration/example-jsonschema-form_spec.js
@@ -1,3 +1,5 @@
+/* ~\~ language=JavaScript filename=cypress/integration/example-jsonschema-form_spec.js */
+/* ~\~ begin <<TESTING.md|cypress/integration/example-jsonschema-form_spec.js>>[0] */
 describe('src/js/example-jsonschema-form.html', () => {
   it('should render -1.00', () => {
     cy.visit('http://localhost:8000/src/js/example-jsonschema-form.html');
@@ -6,4 +8,5 @@ describe('src/js/example-jsonschema-form.html', () => {
     cy.contains('Submit').click();
     cy.get('#answer').contains('-1.00');
   });
-});
\ No newline at end of file
+});
+/* ~\~ end */
diff --git a/cypress/integration/example-web-worker_spec.js b/cypress/integration/example-web-worker_spec.js
index fcc8b24..d40b31b 100644
--- a/cypress/integration/example-web-worker_spec.js
+++ b/cypress/integration/example-web-worker_spec.js
@@ -1,7 +1,10 @@
+/* ~\~ language=JavaScript filename=cypress/integration/example-web-worker_spec.js */
+/* ~\~ begin <<TESTING.md|cypress/integration/example-web-worker_spec.js>>[0] */
 // this JavaScript snippet is run by cypress and is stored as cypress/integration/example-web-worker_spec.js
 describe('src/js/example-web-worker.html', () => {
   it('should render -1.00', () => {
     cy.visit('http://localhost:8000/src/js/example-web-worker.html');
     cy.get('#answer').contains('-1.00');
   });
-});
\ No newline at end of file
+});
+/* ~\~ end */
diff --git a/cypress/integration/example_spec.js b/cypress/integration/example_spec.js
index 023a8fd..fd39280 100644
--- a/cypress/integration/example_spec.js
+++ b/cypress/integration/example_spec.js
@@ -1,7 +1,10 @@
+/* ~\~ language=JavaScript filename=cypress/integration/example_spec.js */
+/* ~\~ begin <<TESTING.md|cypress/integration/example_spec.js>>[0] */
 // this JavaScript snippet is run by cypress and is stored as cypress/integration/example_spec.js
 describe('src/js/example.html', () => {
   it('should render -1.00', () => {
     cy.visit('http://localhost:8000/src/js/example.html');
     cy.get('#answer').contains('-1.00');
   });
-});
\ No newline at end of file
+});
+/* ~\~ end */
diff --git a/src/cgi-newtonraphson.cpp b/src/cgi-newtonraphson.cpp
index bb6a1ca..da7c82d 100644
--- a/src/cgi-newtonraphson.cpp
+++ b/src/cgi-newtonraphson.cpp
@@ -1,8 +1,11 @@
+// ~\~ language=C++ filename=src/cgi-newtonraphson.cpp
+// ~\~ begin <<README.md|src/cgi-newtonraphson.cpp>>[0]
 // this C++ snippet is stored as src/cgi-newtonraphson.hpp
 #include <string>
 #include <iostream>
 #include <nlohmann/json.hpp>
 
+// ~\~ begin <<README.md|algorithm>>[0]
 // this C++ code snippet is later referred to as <<algorithm>>
 #include "newtonraphson.hpp"
 
@@ -40,6 +43,7 @@ double NewtonRaphson::find(double xin)
 
 
 } // namespace rootfinding
+// ~\~ end
 
 int main(int argc, char *argv[])
 {
@@ -60,4 +64,5 @@ int main(int argc, char *argv[])
   response["root"] = root;
   std::cout << response.dump(2) << std::endl;
   return 0;
-}
\ No newline at end of file
+}
+// ~\~ end
diff --git a/src/cli-newtonraphson.cpp b/src/cli-newtonraphson.cpp
index 9e97d93..5eaef0b 100644
--- a/src/cli-newtonraphson.cpp
+++ b/src/cli-newtonraphson.cpp
@@ -1,6 +1,9 @@
+// ~\~ language=C++ filename=src/cli-newtonraphson.cpp
+// ~\~ begin <<README.md|src/cli-newtonraphson.cpp>>[0]
 // this C++ snippet is stored as src/newtonraphson.cpp
 #include<bits/stdc++.h>
 
+// ~\~ begin <<README.md|algorithm>>[0]
 // this C++ code snippet is later referred to as <<algorithm>>
 #include "newtonraphson.hpp"
 
@@ -38,6 +41,7 @@ double NewtonRaphson::find(double xin)
 
 
 } // namespace rootfinding
+// ~\~ end
 
 // Driver program to test above
 int main()
@@ -49,4 +53,5 @@ int main()
 
   std::cout << "The value of the root is : " << x1 << std::endl;
   return 0;
-}
\ No newline at end of file
+}
+// ~\~ end
diff --git a/src/js/app.js b/src/js/app.js
index 239d078..bf9d8b6 100644
--- a/src/js/app.js
+++ b/src/js/app.js
@@ -1,8 +1,13 @@
+// ~\~ language=jsx filename=src/js/app.js
+// ~\~ begin <<README.md|src/js/app.js>>[0]
+// ~\~ begin <<README.md|heading-component>>[0]
 // this JavaScript snippet is later referred to as <<heading-component>>
 function Heading() {
   const title = 'Root finding web application';
   return <h1>{title}</h1>
 }
+// ~\~ end
+// ~\~ begin <<README.md|result-component>>[0]
 // this JavaScript snippet is later referred to as <<result-component>>
 function Result(props) {
   const root = props.root;
@@ -12,34 +17,50 @@ function Result(props) {
   }
   return <div id="answer">{message}</div>;
 }
+// ~\~ end
 
 // this JavaScript snippet appenended to src/js/app.js
 function App() {
+  /* ~\~ begin <<README.md|react-state>>[0] */
   // this JavaScript snippet is later referred to as <<react-state>>
   const [epsilon, setEpsilon] = React.useState(0.001);
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|react-state>>[1] */
   // this JavaScript snippet is appended to <<react-state>>
   function onEpsilonChange(event) {
     setEpsilon(Number(event.target.value));
   }
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|react-state>>[2] */
   // this JavaScript snippet is appended to <<react-state>>
   const [guess, setGuess] = React.useState(-20);
 
   function onGuessChange(event) {
     setGuess(Number(event.target.value));
   }
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|react-state>>[3] */
   // this JavaScript snippet is appended to <<react-state>>
   const [root, setRoot] = React.useState(undefined);
+  /* ~\~ end */
 
   function handleSubmit(event) {
+    // ~\~ begin <<README.md|handle-submit>>[0]
     // this JavaScript snippet is later referred to as <<handle-submit>>
     event.preventDefault();
+    // ~\~ end
+    // ~\~ begin <<README.md|handle-submit>>[1]
     // this JavaScript snippet is appended to <<handle-submit>>
     const worker = new Worker('worker.js');
+    // ~\~ end
+    // ~\~ begin <<README.md|handle-submit>>[2]
     // this JavaScript snippet is appended to <<handle-submit>>
     worker.postMessage({
       type: 'CALCULATE',
       payload: { epsilon: epsilon, guess: guess }
     });
+    // ~\~ end
+    // ~\~ begin <<README.md|handle-submit>>[3]
     // this JavaScript snippet is appended to <<handle-submit>>
     worker.onmessage = function(message) {
         if (message.data.type === 'RESULT') {
@@ -48,11 +69,13 @@ function App() {
           worker.terminate();
       }
     };
+    // ~\~ end
   }
 
   return (
     <div>
       <Heading/>
+      { /* ~\~ begin <<README.md|react-form>>[0] */ }
       { /* this JavaScript snippet is later referred to as <<react-form>> */ }
       <form onSubmit={handleSubmit}>
         <label>
@@ -65,12 +88,16 @@ function App() {
         </label>
         <input type="submit" value="Submit" />
       </form>
+      { /* ~\~ end */ }
       <Result root={root}/>
     </div>
   );
 }
+// ~\~ end
+// ~\~ begin <<README.md|src/js/app.js>>[1]
 // this JavaScript snippet appenended to src/js/app.js
 ReactDOM.render(
   <App/>,
   document.getElementById('container')
-);
\ No newline at end of file
+);
+// ~\~ end
diff --git a/src/js/example-app.html b/src/js/example-app.html
index fab26d9..910ceb2 100644
--- a/src/js/example-app.html
+++ b/src/js/example-app.html
@@ -1,16 +1,27 @@
+<!-- ~\~ language=HTML filename=src/js/example-app.html -->
+<!-- ~\~ begin <<README.md|src/js/example-app.html>>[0] -->
 <!doctype html>
 <!-- this HTML page is stored as src/js/example-app.html -->
 <html>
+  <!-- ~\~ begin <<README.md|imports>>[0] -->
   <!-- this HTML snippet is before and later referred to as <<imports>> -->
   <script src="https://unpkg.com/react@16/umd/react.development.js" crossorigin></script>
   <script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js" crossorigin></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[1] -->
   <!-- this HTML snippet is appended to <<imports>> -->
   <script src="https://unpkg.com/babel-standalone@6/babel.min.js"></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[2] -->
   <!-- this HTML snippet is appended to <<imports>>  -->
   <script src="https://unpkg.com/@rjsf/core/dist/react-jsonschema-form.js"></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[3] -->
   <!-- this HTML snippet is appended to <<imports>>  -->
   <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha384-HSMxcRTRxnN+Bdg0JdbxYKrThecOKuH5zCYotlSAcp1+c8xmyTe9GYg1l9a69psu" crossorigin="anonymous">
+  <!-- ~\~ end -->
   <div id="container"></div>
 
   <script type="text/babel" src="app.js"></script>
-</html>
\ No newline at end of file
+</html>
+<!-- ~\~ end -->
diff --git a/src/js/example-jsonschema-form.html b/src/js/example-jsonschema-form.html
index d3fc452..74a5942 100644
--- a/src/js/example-jsonschema-form.html
+++ b/src/js/example-jsonschema-form.html
@@ -1,16 +1,27 @@
+<!-- ~\~ language=HTML filename=src/js/example-jsonschema-form.html -->
+<!-- ~\~ begin <<README.md|src/js/example-jsonschema-form.html>>[0] -->
 <!doctype html>
 <!-- this HTML page is stored as src/jsexample-jsonschema-form.html -->
 <html>
+  <!-- ~\~ begin <<README.md|imports>>[0] -->
   <!-- this HTML snippet is before and later referred to as <<imports>> -->
   <script src="https://unpkg.com/react@16/umd/react.development.js" crossorigin></script>
   <script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js" crossorigin></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[1] -->
   <!-- this HTML snippet is appended to <<imports>> -->
   <script src="https://unpkg.com/babel-standalone@6/babel.min.js"></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[2] -->
   <!-- this HTML snippet is appended to <<imports>>  -->
   <script src="https://unpkg.com/@rjsf/core/dist/react-jsonschema-form.js"></script>
+  <!-- ~\~ end -->
+  <!-- ~\~ begin <<README.md|imports>>[3] -->
   <!-- this HTML snippet is appended to <<imports>>  -->
   <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha384-HSMxcRTRxnN+Bdg0JdbxYKrThecOKuH5zCYotlSAcp1+c8xmyTe9GYg1l9a69psu" crossorigin="anonymous">
+  <!-- ~\~ end -->
   <div id="container"></div>
 
   <script type="text/babel" src="jsonschema-app.js"></script>
-</html>
\ No newline at end of file
+</html>
+<!-- ~\~ end -->
diff --git a/src/js/example-web-worker.html b/src/js/example-web-worker.html
index 170077a..5cba268 100644
--- a/src/js/example-web-worker.html
+++ b/src/js/example-web-worker.html
@@ -1,23 +1,34 @@
+<!-- ~\~ language=HTML filename=src/js/example-web-worker.html -->
+<!-- ~\~ begin <<README.md|src/js/example-web-worker.html>>[0] -->
 <!doctype html>
 <!-- this HTML page is stored as src/js/example-web-worker.html -->
 <html>
   <script>
+    /* ~\~ begin <<README.md|worker-consumer>>[0] */
     // this JavaScript snippet is later referred to as <<worker-consumer>>
     const worker = new Worker('worker.js');
+    /* ~\~ end */
+    /* ~\~ begin <<README.md|worker-consumer>>[1] */
     // this JavaScript snippet is appended to <<worker-consumer>>
     worker.postMessage({
       type: 'CALCULATE',
       payload: { epsilon: 0.001, guess: -20 }
     });
+    /* ~\~ end */
+    /* ~\~ begin <<README.md|worker-consumer>>[2] */
     // this JavaScript snippet is appended to <<worker-consumer>>
     worker.onmessage = function(message) {
       if (message.data.type === 'RESULT') {
         const root = message.data.payload.root;
+        /* ~\~ begin <<README.md|render-answer>>[0] */
         const answer = document.createElement('span');
         answer.id = 'answer';
         answer.append(root);
         document.body.append(answer);
+        /* ~\~ end */
       }
     }
+    /* ~\~ end */
   </script>
-</html>
\ No newline at end of file
+</html>
+<!-- ~\~ end -->
diff --git a/src/js/example.html b/src/js/example.html
index 3ec769c..cf1b113 100644
--- a/src/js/example.html
+++ b/src/js/example.html
@@ -1,19 +1,28 @@
-<!doctype html>
+<!-- ~\~ language=HTML filename=src/js/example.html -->
+<!-- ~\~ begin <<README.md|src/js/example.html>>[0] -->
 <!-- this HTML page is stored as src/js/example.html -->
+<!doctype html>
 <html>
   <script type="text/javascript" src="newtonraphsonwasm.js"></script>
   <script>
+    /* ~\~ begin <<README.md|wasm-promise>>[0] */
     // this JavaScript snippet is later referred to as <<wasm-promise>>
     createModule().then((module) => {
+      /* ~\~ begin <<README.md|wasm-calculate>>[0] */
       // this JavaScript snippet is later referred to as <<wasm-calculate>>
       const epsilon = 0.001;
       const finder = new module.NewtonRaphson(epsilon);
       const guess = -20;
       const root = finder.find(guess);
+      /* ~\~ end */
+      /* ~\~ begin <<README.md|render-answer>>[0] */
       const answer = document.createElement('span');
       answer.id = 'answer';
       answer.append(root);
       document.body.append(answer);
+      /* ~\~ end */
     });
+    /* ~\~ end */
   </script>
-</html>
\ No newline at end of file
+</html>
+<!-- ~\~ end -->
diff --git a/src/js/jsonschema-app.js b/src/js/jsonschema-app.js
index 0237341..8243cdd 100644
--- a/src/js/jsonschema-app.js
+++ b/src/js/jsonschema-app.js
@@ -1,5 +1,8 @@
+// ~\~ language=jsx filename=src/js/jsonschema-app.js
+// ~\~ begin <<README.md|src/js/jsonschema-app.js>>[0]
 // this JavaScript snippet stored as src/js/jsonschema-app.js
 function App() {
+  /* ~\~ begin <<README.md|jsonschema-app>>[0] */
   // this JavaScript snippet is later referred to as <<jsonschema-app>>
   const schema = {
     "$schema": "http://json-schema.org/draft-07/schema#",
@@ -21,13 +24,19 @@ function App() {
     "required": ["epsilon", "guess"],
     "additionalProperties": false
   }
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|jsonschema-app>>[1] */
   // this JavaScript snippet is appended to <<jsonschema-app>>
   const Form = JSONSchemaForm.default;
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|jsonschema-app>>[2] */
   const uiSchema = {
     "guess": {
       "ui:widget": "range"
     }
   }
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|jsonschema-app>>[3] */
   // this JavaScript snippet is appended to <<jsonschema-app>>
   const [formData, setFormData] = React.useState({
     epsilon: 0.001,
@@ -37,6 +46,8 @@ function App() {
   function handleChange(event) {
     setFormData(event.formData);
   }
+  /* ~\~ end */
+  /* ~\~ begin <<README.md|jsonschema-app>>[4] */
   // this JavaScript snippet is appended to <<jsonschema-app>>
   const [root, setRoot] = React.useState(undefined);
 
@@ -55,10 +66,12 @@ function App() {
       }
     };
   }
+  /* ~\~ end */
 
   return (
     <div>
       <Heading/>
+      { /* ~\~ begin <<README.md|jsonschema-form>>[0] */ }
       { /* this JavaScript snippet is later referred to as <<jsonschema-form>>  */}
       <Form
         uiSchema={uiSchema}
@@ -67,6 +80,7 @@ function App() {
         onChange={handleChange}
         onSubmit={handleSubmit}
       />
+      { /* ~\~ end */ }
       <Result root={root}/>
     </div>
   );
@@ -76,12 +90,17 @@ ReactDOM.render(
   <App/>,
   document.getElementById('container')
 );
+// ~\~ end
+// ~\~ begin <<README.md|src/js/jsonschema-app.js>>[1]
 // this JavaScript snippet appended to src/js/jsonschema-app.js
+// ~\~ begin <<README.md|heading-component>>[0]
 // this JavaScript snippet is later referred to as <<heading-component>>
 function Heading() {
   const title = 'Root finding web application';
   return <h1>{title}</h1>
 }
+// ~\~ end
+// ~\~ begin <<README.md|result-component>>[0]
 // this JavaScript snippet is later referred to as <<result-component>>
 function Result(props) {
   const root = props.root;
@@ -90,4 +109,6 @@ function Result(props) {
     message = 'Root = ' + root;
   }
   return <div id="answer">{message}</div>;
-}
\ No newline at end of file
+}
+// ~\~ end
+// ~\~ end
diff --git a/src/js/worker.js b/src/js/worker.js
index 53f7855..3c69c1a 100644
--- a/src/js/worker.js
+++ b/src/js/worker.js
@@ -1,16 +1,23 @@
+/* ~\~ language=JavaScript filename=src/js/worker.js */
+/* ~\~ begin <<README.md|src/js/worker.js>>[0] */
 // this JavaScript snippet is stored as src/js/worker.js
 importScripts('newtonraphsonwasm.js');
 
+/* ~\~ begin <<README.md|worker-provider-onmessage>>[0] */
 // this JavaScript snippet is later referred to as <<worker-provider-onmessage>>
 onmessage = function(message) {
+  /* ~\~ begin <<README.md|handle-message>>[0] */
   // this JavaScript snippet is before referred to as <<handle-message>>
   if (message.data.type === 'CALCULATE') {
     createModule().then((module) => {
+      /* ~\~ begin <<README.md|perform-calc-in-worker>>[0] */
       // this JavaScript snippet is before referred to as <<perform-calc-in-worker>>
       const epsilon = message.data.payload.epsilon;
       const finder = new module.NewtonRaphson(epsilon);
       const guess = message.data.payload.guess;
       const root = finder.find(guess);
+      /* ~\~ end */
+      /* ~\~ begin <<README.md|post-result>>[0] */
       // this JavaScript snippet is before referred to as <<post-result>>
       postMessage({
         type: 'RESULT',
@@ -18,6 +25,10 @@ onmessage = function(message) {
           root: root
         }
       });
+      /* ~\~ end */
     });
   }
-};
\ No newline at end of file
+  /* ~\~ end */
+};
+/* ~\~ end */
+/* ~\~ end */
diff --git a/src/newtonraphson.hpp b/src/newtonraphson.hpp
index 7cc6647..049ae5e 100644
--- a/src/newtonraphson.hpp
+++ b/src/newtonraphson.hpp
@@ -1,3 +1,5 @@
+// ~\~ language=C++ filename=src/newtonraphson.hpp
+// ~\~ begin <<README.md|src/newtonraphson.hpp>>[0]
 // this C++ snippet is stored as src/newtonraphson.hpp
 #ifndef H_NEWTONRAPHSON_H
 #define H_NEWTONRAPHSON_H
@@ -14,4 +16,5 @@ namespace rootfinding {
   };
 }
 
-#endif
\ No newline at end of file
+#endif
+// ~\~ end
diff --git a/src/py-newtonraphson.cpp b/src/py-newtonraphson.cpp
index a184829..bf2aa2e 100644
--- a/src/py-newtonraphson.cpp
+++ b/src/py-newtonraphson.cpp
@@ -1,7 +1,10 @@
+// ~\~ language=C++ filename=src/py-newtonraphson.cpp
+// ~\~ begin <<README.md|src/py-newtonraphson.cpp>>[0]
 // this C++ snippet is stored as src/py-newtonraphson.cpp
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
+// ~\~ begin <<README.md|algorithm>>[0]
 // this C++ code snippet is later referred to as <<algorithm>>
 #include "newtonraphson.hpp"
 
@@ -39,6 +42,7 @@ double NewtonRaphson::find(double xin)
 
 
 } // namespace rootfinding
+// ~\~ end
 
 namespace py = pybind11;
 
@@ -51,4 +55,5 @@ PYBIND11_MODULE(newtonraphsonpy, m) {
              "Find root starting from initial guess"
         )
     ;
-}
\ No newline at end of file
+}
+// ~\~ end
diff --git a/src/py/api.py b/src/py/api.py
index 1760858..f442c31 100644
--- a/src/py/api.py
+++ b/src/py/api.py
@@ -1,3 +1,5 @@
+# ~\~ language=Python filename=src/py/api.py
+# ~\~ begin <<README.md|src/py/api.py>>[0]
 # this Python snippet is stored as src/py/api.py
 def calculate(body):
   epsilon = body['epsilon']
@@ -5,4 +7,5 @@ def calculate(body):
   from newtonraphsonpy import NewtonRaphson
   finder = NewtonRaphson(epsilon)
   root = finder.find(guess)
-  return {'root': root}
\ No newline at end of file
+  return {'root': root}
+# ~\~ end
diff --git a/src/py/example.py b/src/py/example.py
index 3894153..870a510 100644
--- a/src/py/example.py
+++ b/src/py/example.py
@@ -1,6 +1,9 @@
+# ~\~ language=Python filename=src/py/example.py
+# ~\~ begin <<README.md|src/py/example.py>>[0]
 # this Python snippet is stored as src/py/example.py
 from newtonraphsonpy import NewtonRaphson
 
 finder = NewtonRaphson(epsilon=0.001)
 root = finder.find(guess=-20)
-print(root)
\ No newline at end of file
+print(root)
+# ~\~ end
diff --git a/src/py/openapi.yaml b/src/py/openapi.yaml
index 3ff1f97..4206dab 100644
--- a/src/py/openapi.yaml
+++ b/src/py/openapi.yaml
@@ -1,3 +1,5 @@
+# ~\~ language=YAML filename=src/py/openapi.yaml
+# ~\~ begin <<README.md|src/py/openapi.yaml>>[0]
 # this yaml snippet is stored as src/py/openapi.yaml
 openapi: 3.0.0
 info:
@@ -47,4 +49,5 @@ components:
           type: number
       required:
         - root
-      additionalProperties: false
\ No newline at end of file
+      additionalProperties: false
+# ~\~ end
diff --git a/src/py/tasks.py b/src/py/tasks.py
index 9554c0a..d1f5880 100644
--- a/src/py/tasks.py
+++ b/src/py/tasks.py
@@ -1,9 +1,13 @@
+# ~\~ language=Python filename=src/py/tasks.py
+# ~\~ begin <<README.md|src/py/tasks.py>>[0]
 # this Python snippet is stored as src/py/tasks.py
 import time
 
+# ~\~ begin <<README.md|celery-config>>[0]
 # this Python code snippet is later referred to as <<celery-config>>
 from celery import Celery
 capp = Celery('tasks', broker='redis://localhost:6379', backend='redis://localhost:6379')
+# ~\~ end
 
 @capp.task(bind=True)
 def calculate(self, epsilon, guess):
@@ -16,4 +20,5 @@ def calculate(self, epsilon, guess):
     self.update_state(state='FINDING')
   time.sleep(5)
   root = finder.find(guess)
-  return {'root': root, 'guess': guess, 'epsilon':epsilon}
\ No newline at end of file
+  return {'root': root, 'guess': guess, 'epsilon':epsilon}
+# ~\~ end
diff --git a/src/py/webapp-celery.py b/src/py/webapp-celery.py
index 874002d..fac66a0 100644
--- a/src/py/webapp-celery.py
+++ b/src/py/webapp-celery.py
@@ -1,8 +1,11 @@
+# ~\~ language=Python filename=src/py/webapp-celery.py
+# ~\~ begin <<README.md|src/py/webapp-celery.py>>[0]
 # this Python snippet is stored as src/py/webapp-celery.py
 from flask import Flask, render_template, request, redirect, url_for
 
 app = Flask(__name__)
 
+# ~\~ begin <<README.md|py-form>>[0]
 # this Python code snippet is later referred to as <<py-form>>
 @app.route('/', methods=['GET'])
 def form():
@@ -14,7 +17,9 @@ def form():
       <input type="number" name="guess" value="-20">
       <button type="submit">Submit</button>
     </form>'''
+# ~\~ end
 
+# ~\~ begin <<README.md|py-submit>>[0]
 # this Python code snippet is later referred to as <<py-submit>>
 @app.route('/', methods=['POST'])
 def submit():
@@ -23,7 +28,9 @@ def submit():
   from tasks import calculate
   job = calculate.delay(epsilon, guess)
   return redirect(url_for('result', jobid=job.id))
+# ~\~ end
 
+# ~\~ begin <<README.md|py-result>>[0]
 # this Python code snippet is later referred to as <<py-result>>
 @app.route('/result/<jobid>')
 def result(jobid):
@@ -40,6 +47,8 @@ def result(jobid):
   else:
     return f'''<!doctype html>
       <p>{job.status}<p>'''
+# ~\~ end
 
 if __name__ == '__main__':
-  app.run(port=5000)
\ No newline at end of file
+  app.run(port=5000)
+# ~\~ end
diff --git a/src/py/webapp.py b/src/py/webapp.py
index a6eff3b..625bf87 100644
--- a/src/py/webapp.py
+++ b/src/py/webapp.py
@@ -1,7 +1,10 @@
+# ~\~ language=Python filename=src/py/webapp.py
+# ~\~ begin <<README.md|src/py/webapp.py>>[0]
 # this Python snippet is stored as src/py/webapp.py
 from flask import Flask, request
 app = Flask(__name__)
 
+# ~\~ begin <<README.md|py-form>>[0]
 # this Python code snippet is later referred to as <<py-form>>
 @app.route('/', methods=['GET'])
 def form():
@@ -13,7 +16,9 @@ def form():
       <input type="number" name="guess" value="-20">
       <button type="submit">Submit</button>
     </form>'''
+# ~\~ end
 
+# ~\~ begin <<README.md|py-calculate>>[0]
 # this Python code snippet is later referred to as <<py-calculate>>
 @app.route('/', methods=['POST'])
 def calculate():
@@ -26,6 +31,10 @@ def calculate():
 
   return f'''<!doctype html>
     <p>With epsilon of {epsilon} and a guess of {guess} the found root is {root}.</p>'''
+# ~\~ end
+# ~\~ begin <<README.md|py-calculate>>[1]
   # this Python code snippet is appended to <<py-calculate>>
+# ~\~ end
 
-app.run(port=5001)
\ No newline at end of file
+app.run(port=5001)
+# ~\~ end
diff --git a/src/py/webservice.py b/src/py/webservice.py
index bfaabcf..3430b15 100644
--- a/src/py/webservice.py
+++ b/src/py/webservice.py
@@ -1,6 +1,9 @@
+# ~\~ language=Python filename=src/py/webservice.py
+# ~\~ begin <<README.md|src/py/webservice.py>>[0]
 # this Python snippet is stored as src/py/webservice.py
 import connexion
 
 app = connexion.App(__name__)
 app.add_api('openapi.yaml', validate_responses=True)
-app.run(port=8080)
\ No newline at end of file
+app.run(port=8080)
+# ~\~ end
diff --git a/src/wasm-newtonraphson.cpp b/src/wasm-newtonraphson.cpp
index 1d403a1..cf284de 100644
--- a/src/wasm-newtonraphson.cpp
+++ b/src/wasm-newtonraphson.cpp
@@ -1,6 +1,9 @@
+// ~\~ language=C++ filename=src/wasm-newtonraphson.cpp
+// ~\~ begin <<README.md|src/wasm-newtonraphson.cpp>>[0]
 // this C++ snippet is stored as src/wasm-newtonraphson.cpp
 #include <emscripten/bind.h>
 
+// ~\~ begin <<README.md|algorithm>>[0]
 // this C++ code snippet is later referred to as <<algorithm>>
 #include "newtonraphson.hpp"
 
@@ -38,6 +41,7 @@ double NewtonRaphson::find(double xin)
 
 
 } // namespace rootfinding
+// ~\~ end
 
 using namespace emscripten;
 
@@ -46,4 +50,5 @@ EMSCRIPTEN_BINDINGS(newtonraphsonwasm) {
     .constructor<double>()
     .function("find", &rootfinding::NewtonRaphson::find)
     ;
-}
\ No newline at end of file
+}
+// ~\~ end

From 4320abd32525e1358e190c105cca0c3236356b5b Mon Sep 17 00:00:00 2001
From: Stefan Verhoeven <stefan.verhoeven@gmail.com>
Date: Tue, 11 Aug 2020 09:15:18 +0200
Subject: [PATCH 5/5] Updated example.html

---
 src/js/example.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/js/example.html b/src/js/example.html
index cf1b113..6e3a5d4 100644
--- a/src/js/example.html
+++ b/src/js/example.html
@@ -1,7 +1,7 @@
 <!-- ~\~ language=HTML filename=src/js/example.html -->
 <!-- ~\~ begin <<README.md|src/js/example.html>>[0] -->
-<!-- this HTML page is stored as src/js/example.html -->
 <!doctype html>
+<!-- this HTML page is stored as src/js/example.html -->
 <html>
   <script type="text/javascript" src="newtonraphsonwasm.js"></script>
   <script>