Details about keyboards, screens and bootstrap

.gitignore

@@ -0,0 +1 @@
+*~

.gitlab-ci.yml

@@ -0,0 +1,12 @@
+before_script:
+  - apt-get update -qq
+  - apt-get -y -qq install graphviz ghostscript markdown
+
+pages:
+  stage: deploy
+  script:
+    - make
+    - if test -e public; then mv public public.old; fi && mv artifacts public
+  artifacts:
+    paths:
+      - public/

.travis.yml

@@ -0,0 +1,20 @@
+language: c
+sudo: false
+
+addons:
+  apt:
+    packages:
+      - graphviz
+      - ghostscript
+      - markdown
+
+# TODO: don't overwrite artifacts.
+script:
+ - make
+ - ./travis/auto-push.sh "https://github.com/jsmaniac/os-test-framework.git" \
+                         "git@github.com:jsmaniac/os-deploy-artifacts.git" \
+                         "artifacts-$TRAVIS_BRANCH" \
+                         "deploy-base" \
+                         "82336783091193a09541c42d0f688c6478323952" \
+                         "_build/artifacts" \
+                         "$(if test "$TRAVIS_BRANCH" = "master"; then echo master; else echo dev; fi)"

Makefile

@@ -0,0 +1,42 @@
+all: artifacts/deps.svg artifacts/deps.png artifacts/deps.pdf artifacts/index.html artifacts/references/index.html micro-scheme/test-result
+
+deps.dot: deps.sh
+	mkdir -p $$(dirname $@)
+	sh $< > $@
+
+artifacts/deps.svg: deps.dot Makefile
+	mkdir -p $$(dirname $@)
+	dot -Tsvg $< > $@
+
+artifacts/deps.png: deps.dot Makefile
+	mkdir -p $$(dirname $@)
+	dot -Tpng $< > $@
+
+artifacts/deps.pdf: deps.dot Makefile
+	mkdir -p $$(dirname $@)
+	dot -Tpdf  $< > $@
+
+artifacts/index.html: doc-src/index.html artifacts/style.css artifacts/deps.svg artifacts/deps.png artifacts/deps.pdf artifacts/references/index.html artifacts/open-tasks/index.html Makefile
+	mkdir -p $$(dirname $@)
+	cp doc-src/index.html $@
+
+artifacts/references/index.html: references.md artifacts/references/style.css Makefile
+	mkdir -p $$(dirname $@)
+	doc-src/markdown2html.sh $< "References" > $@
+
+artifacts/style.css: doc-src/style.css Makefile
+	mkdir -p $$(dirname $@)
+	cp $< $@
+
+artifacts/references/style.css: doc-src/style.css Makefile
+	mkdir -p $$(dirname $@)
+	cp $< $@
+
+micro-scheme/test-result: micro-scheme/nano-scheme.sh Makefile
+	mkdir -p $$(dirname $@)
+	sh $< > $@
+
+.PHONY: artifacts/open-tasks/index.html
+artifacts/open-tasks/index.html: Makefile
+	mkdir -p $$(dirname $@)
+	tests/to-do/list-to-dos.sh > $@

build-system/mek.md

@@ -0,0 +1,94 @@
+Problems solved:
+* Forgotten dependencies: build in isolated environment
+* Reactive builds (auto-rebuild): mek watch
+* Access to the build environment: eval $(mek)
+* What changed since last good build(s) without doing git commit all the time: mek source --good (also: cd toto.err.source/)
+* Track downloads of third-party components: build in isolated environment without network access
+* Archive of source and all dependencies, including downloaded stuff
+
+Usage:
+```
+mek build toto         # builds toto or toto.err in case of an error.
+                       # Cached errors are displayed early, but the build is retried in case it was a cosmic ray.
+
+mek clean              # only necessary if a hardware or system failure (e.g. out of memory) made a build appear as SUCCESSFUL when it was not
+                       # (e.g. a poorly-written test that expected an error, caught an OOM but the real execution would not have produced an error)
+
+mek watch              # rebuilds everything incrementally as soon as sources are modified (threads 1 and 3 or 2 and 3, see below).
+mek daemon             # same but with '&' after initialization
+mek watch toto         # rebuilds toto incrementally as soon as one of its transitive dependencies is modified
+
+ls                     # show progress next to (future) targets and a symlink to the backup of their source
+ls _build.err          # stderr of the last build (if non-empty)
+ls _build/err          # stderr of the last build
+ls _build/source/      # source of the last build
+ls _build/good.source/ # source of the last successful build
+ls _build/err.source/  # source of the last failed build
+ls toto.err            # stderr when building toto (if non-empty)
+ls toto.source         # source of the last build of toto
+ls toto.good.source    # source of the last successful build of toto
+ls toto.err.source     # source of the last failed build of toto
+
+mek source             # dumps the source of the last build
+mek source --good      # dumps the source of the last successful build
+mek source --err       # dumps the source of the last failed build
+mek source toto        # dumps the source of the last successful build of toto
+mek source toto.err    # dumps the source of the last failed build of toto
+
+eval $(mek)            # builds and adds the output bin directory to $PATH etc.
+eval "$(mek)"          # same
+$(mek)                 # same
+. mekfile.sh           # same
+mek; copy-paste output # same
+$(mek daemon)          # same but detaches right away and builds incrementally in the background
+
+eval $(mek build toto) # adds an output bin directory containing only toto (can be a collection of outputs) to $PATH etc.
+mek shell toto         # subshell in the directory and with the env of the recipe that builds toto
+mek shell toto.err     # same as above
+eval $(mek shell toto) # cd to build directory for toto and add to $PATH etc.
+
+mek archive toto       # toto.tar now contains the source of toto and of all its dependencies with a build.sh
+```
+
+Example session:
+```
+$ $(mek daemon)
+$ ls
+(toto 60%)  toto.source  toto.c  toto.h
+$ ls
+toto  toto.source  toto.c  toto.h
+$ echo "bad stuff" >> toto.h
+$ ls
+toto (34%)  toto.c  toto.h
+$ ls
+toto  toto.source  toto.err  toto.err.source  toto.c  toto.h
+$ meld $(mek source --good) $(mek source)
+$ echo "fix bug" >> toto.h
+$ ls
+toto  toto.source  toto.c  toto.h
+```
+
+In a `mekfile`:
+```
+toto: toto.h
+# automatic dependency on the gcc executable and on toto.c
+# "," is the unquote from scheme, it escapes from the implicitly-quoted shell command.
+# Maybe gcc (a variable pointing to a third-party tool) should be distinguished from toto.c (a local file)
+> ,gcc ,toto.c -o ,output
+```
+
+* Uses hashes, not timestamps
+* Builds are done in isolated environments (cd, proot, Nix, chroot, container, VM, whatever is available), which only contain the dependencies.
+* Transitions are atomic (mv of a symlink), so that the bin folder in the $PATH contains executables from the same version of the source, not toto from one version and tata from another.
+* Two builds can run in parallel without interfering with each other, yet if work can be shared it will be.
+
+Note about build threads:
+* Invariant when threads 2 and 3 are enabled: if the user constantly modifies a file, e.g. `while sleep 1; do date > somesource; done` which produces an infinite stream of changes, and one of the versions causes the compiler to deadlock / go in an infinite loop, `mek` will still eventually produce an infinite stream of output binaries, where the latest produced binary is not based on a "very old" change (i.e. it is not a queue of jobs that grows indefinitely). It tries to build the latest changes, but it is resistant to the compiler hanging forever on some inputs, and it is resistant to a rapid stream of changes that could cause a naive algorithm to always restart without ever finishing any build.
+* Thread 1 builds, and then checks for new changes. (If the build gets stuck in an infinite loop or deadlocks, the build never finishes and new changes are never taken into account.)
+* Thread 2 builds, but aborts and restarts as soon as there's any change. Upon completion it kills threads 1 and 3 because it got a successful build of a more recent version. (If you're constantly modifying and the build takes a while, it never gets a chance to finish.)
+* Thread 3 works like thread 1 but aborts if there are new changes and the build took longer than a timeout, e.g. twice the time of the last successful build by any thread and increasing geometrically
+
+
+Random requirements:
+* meta-rules: a rule which returns rules. Can be memoized easily, and be part of the normal reactive flow.
+* Easy changes of config: dev / build, -O3, -Odebug etc.

deps.sh

@@ -0,0 +1,289 @@
+#!/bin/sh
+# align on "->" and "[" keyboard macro:
+# (fset 'indent->\[ [C-home ?\C-s ?. ?d ?i ?g ?r ?a ?p ?h ?\C-m home ?\C-  ?\C-s ?. ?\} ?\C-m ?\M-x ?a ?l ?i ?g ?n ?- ?r ?e ?g ?e ?x ?p ?\C-m ?- ?> ?\C-m C-home ?\C-m ?\C-? ?\C-s ?. ?d ?i ?g ?r ?a ?p ?h ?\C-m home ?\C-  ?\C-s ?. ?\} ?\C-m ?\M-x ?a ?l ?i ?g ?n ?- ?r ?e ?g ?e ?x ?p ?\C-m ?\[ ?\[ ?\] ?\C-m ?\C-m ?\C-?])
+
+(sed -e '/^\./!s/^\( *\)\([^ "][^ ]*\)/\1"\2"/' \
+|sed -e '/^\./!s/^\( *\([^-]\|-[^>]\)\+ *-> *\)\([^ "][^ ]*\)/\1"\3"/' \
+|sed -e '/^\./!s/3rdpartybin/shape=box/' \
+|sed -e '/^\./!s/3rdpartyplatform/shape=box/' \
+|sed -e '/^\./!s/bdep/style=dashed/' \
+|sed -e '/^\./!s/rdep/style=solid/' \
+|sed -e '/^\./!s/\([[].*\)mostly-solved/\1fillcolor=yellow,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)unsolved+problem/\1fillcolor=red,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)many-to-do-ok/\1fillcolor=azure,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)many-to-do/\1fillcolor=deepskyblue,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)unsolved/\1fillcolor=orange,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)solved/\1fillcolor=darkolivegreen1,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)implemented/\1fillcolor=green,style=filled/' \
+|sed -e '/^\./!s/\([[].*\)currentwip/\1color=green,penwidth=5/' \
+|sed -e '/^\./!s/\([[].*\)wip/\1color=green,penwidth=5,style="filled,dashed"/' \
+|sed -e 's/^\./ /') <<'EOF'
+.digraph g {
+. compound=true
+. subgraph cluster_legend {
+.   label=legend
+.   subgraph cluster_legend_deps {
+.     label="dependencies"
+      "third-party tool"                                   [3rdpartybin]
+      component              -> build-dep                  [bdep]
+      component              -> run-time-dep               [rdep]
+.   }
+.   subgraph cluster_legend_solved {
+.     label="solved (theoretically)"
+.//     subgraph cluster_legend_solved_ok {
+.//       style=invis label="";
+        implemented                                        [implemented]
+        solved                                             [solved]
+        many-to-do-ok                                      [many-to-do-ok,label="many to implement\nsimpler workaround"]
+.//     }
+.//     subgraph cluster_legend_solved_problem {
+.//       style=invis label="";
+        "mostly solved"                                    [mostly-solved]
+        unsolved                                           [unsolved]
+        many-to-do                                         [many-to-do, label="many to implement\n500-page standards\npoorly explained\npoorly indexed"]
+        "open problem?"                                    [unsolved+problem]
+.//     }
+.   }
+.   subgraph cluster_legend_implem {
+.     label="implementation"
+      wip                                                  [wip,fillcolor=none]
+      "current wip"                                        [currentwip]
+.   }
+. }
+
+. subgraph cluster_host_platform {
+.   label="host platform"
+    host-platform                                          [3rdpartyplatform,label="host = one of …"]
+    sh                                                     [3rdpartyplatform]
+    x86-bootsector                                         [3rdpartyplatform]
+    raspberry-pi                                           [3rdpartyplatform]
+    windows-.exe                                           [3rdpartyplatform]
+    html+js                                                [3rdpartyplatform]
+    host-platform-more                                     [3rdpartyplatform,label="…"]
+. }
+  host-platform              -> sh                         [rdep]
+  host-platform              -> x86-bootsector             [rdep]
+  host-platform              -> raspberry-pi               [rdep]
+  host-platform              -> windows-.exe               [rdep]
+  host-platform              -> html+js                    [rdep]
+  host-platform              -> host-platform-more         [rdep]
+
+. subgraph cluster_build_os {
+.   label="bootstrap build of the OS"
+    nano-scheme                                            [solved,currentwip]
+    micro-scheme                                           [solved]
+    reproducible-environment                               [solved]
+    chameleon                                              [solved,wip]
+    build-system                                           [mostly-solved]
+    bootstrappable                                         [solved]
+    gcc                                                    [3rdpartybin]
+    sgdisk                                                 [3rdpartybin]
+    zip                                                    [3rdpartybin]
+    other-chameleon-tools                                  [3rdpartybin,label="other tools"]
+
+    micro-scheme             -> nano-scheme                [rdep]
+    build-system             -> micro-scheme               [rdep]
+    Guix                     -> "Guix bootstrap"           [bdep]
+    Nix                      -> Guix                       [bdep]
+    build-system             -> bootstrappable             [rdep]
+    build-system             -> reproducible-environment   [rdep]
+    chameleon                -> build-system               [rdep]
+    chameleon                -> gcc                        [rdep]
+    chameleon                -> sgdisk                     [rdep]
+    chameleon                -> zip                        [rdep]
+    chameleon                -> other-chameleon-tools      [rdep]
+    proot                                                  [3rdpartybin]
+    run-in-emulator                                        [solved,wip]
+.   subgraph cluster_tests {
+.     label="tests"
+      tests/portability                                    [label=portability]
+      tests/gui                                            [label=gui]
+      tests/bootstrappable-builds                          [label="build is\nbootstrappable"]
+      subimage-search                                      [implemented]
+      tests/reproducible-builds                            [label="build is\nreproducible"]
+.   }
+    qemu                                                   [3rdpartybin]
+.   subgraph cluster_repro_env {
+.     label="reproducible build environment (software, hardware)"
+      reproducible-environment
+      Nix          
+      proot        
+      "POSIX system"                                       [3rdpartyplatform]
+.   }
+. }
+. subgraph cluster_programming_language {
+.   label="programming language"
+    programming-language
+    typesystem                                             [mostly-solved]
+    syntax                                                 [solved]
+    semantics                                              [mostly-solved]
+    vm                                                     [unsolved]
+    IDE                                                    [solved]
+    refactoring                                            [mostly-solved]
+    hyper-literate                                         [solved]
+    "package management\n(deps & versions)"                [unsolved+problem]
+. }
+. subgraph cluster_portble_platform {
+.   label="portable platform"
+    "portable execution stubs"
+    basic-drivers                                          [solved]
+    "more drivers\n(udi,hypervised linux)"                 [many-to-do-ok]
+. }
+  vm                         -> "portable execution stubs" [rdep]
+  "portable execution stubs" -> chameleon                  [bdep]
+  "portable execution stubs"                               [solved]
+  run-in-emulator
+. subgraph cluster_gui {
+.   label="gui"
+    gui                                                    [mostly-solved]
+    constraint-solver                                      [mostly-solved]
+    graph-layout                                           [unsolved]
+    constraint-solver-contract                             [unsolved+problem]
+    relative-arbitrary-precision                           [mostly-solved]
+    zoomable                                               [mostly-solved]
+. }
+. subgraph cluster_document_model {
+.   label="document model"
+    "general\nprinciples"                                  [solved]
+.   subgraph cluster_viewers {
+.     label="viewers"
+      "rich text lens"                                     [solved]
+      "list lens"                                          [solved, label="column-list lens"]
+      "set lens"                                           [solved]
+      "compound document lens"                             [solved]
+.   }
+.   subgraph cluster_tools {
+.     label="tools"
+      sort                                                 [solved]
+      filter                                               [solved]
+      project                                              [solved]
+      other-tools                                          [mostly-solved,label="…"]
+.   }
+.   subgraph cluster_algorithms {
+.     label="algorithms"
+      other-algorithms                                     [label="…",many-to-do]
+      "abstract datatypes"                                 [solved]
+      union-find                                           [solved]
+      "sat solver"                                         [solved]
+      raytracing                                           [solved]
+      sort-algo                                            [label="sort",solved]
+.   }
+.   subgraph cluster_documents {
+.     label="data / document types"
+      transformation-of                                    [solved]
+      styled-layout-of                                     [solved]
+      printable-layout                                     [unsolved]
+      compound-document                                    [solved]
+.     subgraph cluster_simple_data {
+.       label="simple data"
+        "vectorial image"                                  [unsolved]
+        "bitmap image"                                     [solved]
+        set                                                [solved]
+        list                                               [solved,label="list / database"]
+        "rich text"                                        [solved]
+.     }
+.   }
+.   subgraph cluster_data_sources {
+.     label="data sources"
+.     subgraph cluster_importers {
+.       label="importers"
+        "word"                                             [many-to-do]
+        "excel"                                            [many-to-do]
+        "PDF"                                              [many-to-do]
+        "RTF"                                              [many-to-do]
+        "PSD"                                              [many-to-do]
+        "SVG"                                              [many-to-do]
+.     }
+.     subgraph cluster_network {
+.       label="network and protocols"
+        "websites\n(webkit in sandbox)"                    [many-to-do-ok]
+        more-network-protocols                             [many-to-do, label="…"]
+        "NTP"                                              [solved]
+        "REST APIs"                                        [many-to-do]
+.     }
+.   }
+. }
+  "REST APIs"                -> compound-document          [ltail=cluster_data_sources,lhead=cluster_documents]
+  compound-document          -> styled-layout-of
+  compound-document          -> transformation-of
+  compound-document          -> list                       [lhead=cluster_simple_data]
+  styled-layout-of           -> printable-layout
+  "list lens"                -> compound-document          [ltail=cluster_viewers,lhead=cluster_documents]
+. /*
+  "list lens"                -> list
+  "set lens"                 -> set
+  "compound document lens"   -> "compound document"
+  "rich text lens"           -> "rich text"
+. */
+  "set lens"                -> gui [rdep,ltail=cluster_viewers]
+. /*
+  "set lens"                 -> gui
+  "compound document lens"   -> gui
+  "rich text lens"           -> gui
+. */
+  "compound document lens"   -> constraint-solver
+  "compound document lens"   -> graph-layout
+  sort                       -> sort-algo                  [rdep,ltail=cluster_tools,lhead=cluster_algorithms]
+  other-algorithms           -> "abstract datatypes"       [rdep]
+  union-find                 -> "abstract datatypes"       [rdep]
+  "sat solver"               -> "abstract datatypes"       [rdep]
+  raytracing                 -> "abstract datatypes"       [rdep]
+  sort-algo                  -> "abstract datatypes"       [rdep]
+  sort                       -> compound-document          [rdep,ltail=cluster_tools,lhead=cluster_documents]
+  list                       -> typesystem                 [bdep,ltail=cluster_documents]
+. /*
+  sort                       -> list
+  filter                     -> list
+  project                    -> list
+. */
+  reproducible-environment   -> Nix
+  reproducible-environment   -> proot
+  reproducible-environment   -> run-in-emulator
+  reproducible-environment   -> "POSIX system"
+  tests/portability          -> subimage-search            [rdep]
+  tests/gui                  -> subimage-search            [rdep]
+  tests/portability          -> run-in-emulator            [rdep]
+
+  nano-scheme                -> sh                         [rdep]
+  gui                        -> basic-drivers              [rdep]
+  Guix                                                     [3rdpartybin]
+  "Guix bootstrap"                                         [3rdpartybin]
+  Nix                                                      [3rdpartybin]
+  basic-drivers              -> host-platform              [rdep]
+  gui                        -> programming-language       [bdep]
+  programming-language       -> typesystem                 [rdep]
+  programming-language       -> vm                         [rdep]
+  run-in-emulator            -> qemu                       [rdep]
+  subimage-search
+  tests/reproducible-builds
+  "portable execution stubs" -> "host-platform"            [rdep]
+
+
+  SVG                        -> "REST APIs"                [style=invis]
+  many-to-do-ok              -> "current wip"              [style=invis]
+  printable-layout           -> "zoomable"                 [style=invis]
+  _sh                                                      [style=invis]
+  _sh                        -> "sh"                       [style=invis]
+  "current wip"              -> "general\nprinciples"      [style=invis]
+  "Guix bootstrap"           -> _sh                        [style=invis]
+  styled-layout-of           -> set                        [style=invis]
+  "general\nprinciples"      -> "list lens"                [style=invis]
+.}
+
+EOF
+
+
+#dynalist → c'est une mind map (moche) avec des checkbox, dates et hashtags?
+# mode lecture 1 focus, édition 1 focus, édition+référence: 2 focus, édition+référence+outils: 3 focus, édition+référence+calculs+style+outils: 5 focus
+
+
+# DK encyclo vs. Android encyclopedias
+# DK book on multimedia
+# keyboard
+# hw difficulties:
+# * PCB layout: lots of interferences (see rowhammer…)
+# * GPU is one of the most opaque components. In the Raspberry Pi it means that the boot process is partially opaque.
+# * Stateless : a lot of components have flashable firmware nowadays
+# * Opaque / undocumented HW
+# * casing (high precision otherwise buttons get stuck or jiggle)
+# * If you want to make your own hardware, probably best is to hire someone who did it for a small-scale project (e.g. EvilDragon who did the Pandora and Pyra)

doc-src/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>{{{project-name}}}</title>
+    <link type="text/css" rel="stylesheet" href="style.css" />
+  </head>
+  <body>
+    <h1>{{{project-name}}}</h1>
+    
+    <ul>
+      <li><a href="deps.svg">Dependency graph</a> with work-in-progress indications (<a href="deps.png">PNG</a> and <a href="deps.pdf">PDF</a> versions)</li>
+      <li><a href="references/index.html">References</a></li>
+      <li><a href="open-tasks/index.html">Open tasks</a></li>
+    </ul>
+  </body>
+</html>

doc-src/markdown2html.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+
+if test $# -ne 2; then
+  printf %s\\n 'Usage: path/to/markdown2html.sh file.md "Page title"'
+  exit 1
+fi
+
+cat <<EOF
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>$2</title>
+    <link type="text/css" rel="stylesheet" href="style.css" />
+  </head>
+  <body>
+EOF
+markdown "$1" | sed -e 's/^/    /'
+cat <<'EOF'
+  </body>
+</html>
+EOF

doc-src/style.css

@@ -0,0 +1,94 @@
+html {
+  background: #eee;
+  padding: 0 .5em;
+}
+
+body {
+  background: white;
+  border: thick solid #ddd;
+  border-radius: 2em;
+  padding: 0.5em 2em 1.5em;
+  max-width: 40em;
+  margin: 2em auto;
+  font-family: Helvetica,Arial,sans-serif;
+  font-size: 120%;
+  line-height: 1.3em;
+  color: #333;
+}
+
+h1 {
+  color: #222;
+}
+
+code {
+  color: #04c;
+  background: #eee;
+  padding: 0.1em 0.3em;
+}
+
+input, select {
+  padding: 0.3em !important;
+}
+
+pre em {
+  color: red;
+  font-style: normal;
+}
+
+kbd {
+  color: #444;
+  background-color: aliceblue;
+  border: thin solid gray;
+  border-radius: .5ex;
+  padding-left: .5ex;
+  padding-right: .5ex;
+}
+
+pre kbd {
+  color: #04c;
+  border: none;
+  border-radius: 0;
+  padding-left: initial;
+  padding-right: initial;
+}
+
+pre {
+  overflow: auto;
+  background: #eee;
+  border: thin solid #ccc;
+  padding: .5em;
+  border-radius: .5em;
+}
+
+hr {
+  margin: 1em 25%;
+  height: .35ex;
+  color: #aaa;
+  background-color: #aaa;
+  border: none;
+  border-radius: .175ex;
+}
+
+/* TODO: use a technique like tinytypo's to change the quotes based on the language?
+ * https://github.com/tetue/tinytypo/blob/5f7411746c8c4d634ac8cd14c730b86f4ffd1813/css/typo.css#L397
+ */
+blockquote {
+    border-left: 0.85ex solid #ccc;
+    padding: 0.8ex 1ex;
+    background: #f0f0f0;
+    margin: 1em 2em;
+}
+
+/* An <ul> appearing at the end of a blockquote has too much vertical space following it. */
+ul:last-child {
+  margin-bottom: .25ex
+}
+
+img {
+  max-width: 100%;
+  max-height: 100vh;
+}
+
+li > img, li > a > img {
+  vertical-align: top;
+}

fork.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+if test $# -ne 1 || test "$1" = '-h' || test "$1" = '--help'; then
+  echo 'Usage: ./fork.sh name'
+  echo 'Renames the project'
+  exit 1
+fi
+
+if printf %s "$1" | grep -q -v '[-0-9a-zA-Z_ ]'; then
+  echo 'The name should not contain characters outside of [-0-9a-zA-Z_ ]'
+  echo 'TODO: escape problematic characters in the regexp and allow them'
+  exit 1
+fi
+
+if git grep -q -e "$1"; then
+  echo "The proposed name already appears in the source code."
+  echo "If you proceed, the new name will prevent easy renaming of this code base."
+  exit 1
+fi
+
+git ls-tree -r HEAD | awk '{ print $4 }' | xargs sed -i -e 's/{{{project-name}}}/'"$1"/g

micro-scheme/nano-scheme.sh

@@ -38,9 +38,9 @@
 # N null           "_"
 # F free cell      ptr
 # I integer        int
-# Y symbol         hex
+# Y symbol         octal
 #
-# Note: hex strings must not contain any spaces.
+# Note: octal strings must not contain any spaces.
 
 h=0
 s=0
@@ -97,7 +97,7 @@ debug_print() {
   elif test $a = Y; then
     if $2; then printf %s '.'; fi
     heap_get_val $1
-    printf %s $a | xxd -ps -r
+    printf \\$a
     if $2; then printf %s ')'; fi
   else
     if $2; then printf %s '.'; fi
@@ -110,21 +110,86 @@ debug_print() {
   fi
 }
 
+eval_scheme() {
+  local callee ptr result
+  heap_get_type $1
+  if test $a = P; then
+      heap_get_val $1
+      # TDODO: use a stack
+      echo h=$h
+      heap_sbrk; heap_set_pair $h P $a $h;
+      echo h=$h
+      callee=$a
+      echo -n callee=
+      debug_print $callee false
+      echo
+      # compute the arguments
+      a=P
+      heap_get_cdr $1
+      ptr=$a
+      heap_get_type $ptr
+      echo cdr1=$ptr type=$a
+      while test "$a" != N; do
+        heap_get_val $ptr
+        echo val=$a
+        eval_scheme $a
+        # TODO: push on a stack
+        echo h=$h
+        heap_sbrk; heap_set_pair $h P $a $h;
+        echo h=$h
+        result=$a
+        echo result=$result
+        heap_get_cdr $ptr
+        ptr=$a
+        heap_get_type $ptr
+        echo cdr=$ptr type=$a
+        a=N
+      done
+      # TODO: this assumes that the callee is a symbol.
+      heap_get_val $callee
+      echo callee====$callee
+      echo callee----$a
+      case $a in
+        # octal for "r"
+        162) echo READ
+             # fake read (always returns "h", soon to be "hello"!)
+             a=150;; # TODO: should be some-input | od -v -A n -t x1 | read -n 1 a
+        # octal for "w"
+        167) echo WRITE: $result
+             printf \\$result >> output;; # TODO: should use octal, \x is not portable.
+        *)   echo TODO_OR_ERROR
+             a=42;;
+      esac
+  else
+    echo TODO_OR_ERROR
+    a=42
+  fi
+}
+
 main() {
-  printf '(w((lxx)r))' \
+  # printf '(w((lxx)r))' \
-    | od -v -A n -t x1 \
+  # printf '(r)' \
+  printf '(w(r))' \
+    | od -v -A n -t o1 \
     | sed -e 's/^ //' \
     | tr ' ' \\n \
     | (while read c; do
 	 echo lex:$c
 	 case "$c" in
-	   28)                              s=$(($s+1)); eval s$s=M  ;;
+           # octal for "("
-	   29) stack_debug; rlist; stack_debug ;;
+	   050)                              s=$(($s+1)); eval s$s=M  ;;
+           # octal for ")"
+	   051) stack_debug; rlist; stack_debug ;;
 	   *)  heap_sbrk; heap_set $h Y $c; s=$(($s+1)); eval s$s=$h ;;
 	 esac
        done
        heap_debug
-       debug_print $h false)
+       echo
+       to_eval=$h
+       heap_sbrk; heap_set $h N _
+       eval_scheme $to_eval
+       echo
+       debug_print $to_eval false)
 }
 
 if true; then main; exit $?; fi

references.md

@@ -1,21 +1,119 @@
-* [9780751305418](https://isbnsearch.com/isbn/9780751305418) Dorling Kindersley Multimedia The Complete User-Friendly Guide to the Internet, World Wide Web, DVDs, Virtual Reality, CD-ROMs and 3D Games
+# Multimedia software
+
+* [Dorling Kindersley Multimedia The Complete User-Friendly Guide to the Internet, World Wide Web, DVDs, Virtual Reality, CD-ROMs and 3D Games](https://isbnsearch.com/isbn/9780751305418).
+  ISBN-13: 978-0751305418, ISBN-10: 0751305413
   
   This is an overview of the professions and techniques involved in the creation of interactive multimedia software. It fits well as a welcome guide for new employes, to let them know what the other professions are doing in the company, or as a pamhplet for students interested in joining a school training them for these professions.
+
+# User interface
+
 * The Humane interface Jeff Raskin
+* [DocumentDefinitions](https://wiki.c2.com/?DocumentDefinitions), some definitions related to document-based interfaces, on the [C2 WikiWikiWeb](https://wiki.c2.com)
+* [ZoomableUserInterface](https://wiki.c2.com/?ZoomableUserInterface), on the [C2 WikiWikiWeb](https://wiki.c2.com)
+
+# Software engineering best practices
+
+* [Software Engineer's Reference Book](https://isbnsearch.com/isbn/9780750608138),
+  John McDermid, 1992. ISBN-13: 978-0750608138, ISBN-10: 0750608137
+
+  This is a compilation of surveys written by people in the fields of
+  testing, systems design, and so on. Each survey describes the
+  practices and techniques used in that field, and include a rich
+  bibliography
+
+# Programming practices (human-human interactions)
+
 * The psychology of computer programming silver anniversary edition
 
 # Hardware
 
+## CPU and integrated circuits
+
+* Wikipedia's illustration of a [NAND gate's physical layout](https://en.wikipedia.org/wiki/CMOS#Example:_NAND_gate_in_physical_layout) clearly shows how NMOS and PMOS transistors are created on a silicon substrate, as well as a schematic representation of the resulting layers. Page visited on 2019-03-12.
+* Some people have built small integrated circuits (e.g. inverters) at home, using simple equipment: [Jeri Ellsworth](https://hackaday.com/2010/03/10/jeri-makes-integrated-circuits/), [HomeCMOS](https://hackaday.com/2012/07/09/make-your-own-integrated-circuits-at-home/).
+* [visual6502.org](http://visual6502.org/), a sumulation of the 6502 CPU based on photos of the silicon die. It features an online zoomable view of the CPU with different colors for the logic states, in which wires and transistors blink as the CPU executes instructions.
+
 ## Keyboard
 
-* N-shot injection keycaps:
+* N-shot injection keycaps
   * [![double-shot injection keycaps cut in half to expose the two plastic parts](https://i.imgur.com/kVQNa.jpg)](https://imgur.com/a/OhRd4)
   * [The best mechanical keycaps](https://blog.wooting.nl/what-are-the-best-mechanical-keyboard-keycaps), a presentation of various properties of keycaps
-  * [![Quadruple-shot injection keycap with two colors for the label and transparent plastic for caps lock or scroll lock indicator](https://deskauthority.net/download/file.php?id=5573)](https://deskauthority.net/viewtopic.php?p=80654#p80654)
+  * [![Quadruple-shot injection keycap with two colors for the label and transparent plastic for caps lock or scroll lock indicator](https://deskthority.net/download/file.php?id=5573)](https://deskthority.net/viewtopic.php?p=80654#p80654)
-* Planck [![Example layout of a planck keyboard](https://i.imgur.com/cNipMSc.png)](https://i.imgur.com/cNipMSc.png)
+* Planck keyboards have only four rows. The first row is usually activated with the thumbs, and all other keys are at most 1 key away from the home row. [![Example layout of a planck keyboard](https://i.imgur.com/cNipMSc.png)](https://i.imgur.com/cNipMSc.png)
 * [WASD Keyboards](https://www.wasdkeyboards.com/) does full-color print on keycaps. Examples:
   [![illustrations (planets and space decor) on keys](https://i.imgur.com/F3lgqHJ.jpg)](https://i.imgur.com/F3lgqHJ.jpg)
   [![Video editing software shortcuts](https://66.media.tumblr.com/9e8cbe7747b696822570ce0329f92fa1/tumblr_noo0x0SAcK1u475ako1_1280.jpg)](https://wasdkeyboards.tumblr.com/image/120541521288)
   [![On-key characters for greek, mathematical symbols and other languages accessible via XCompose](https://i.imgur.com/21OoXw0.jpg)](https://imgur.com/a/DpQHW)
 * Manufacturers and sellers:
   * [Massdrop](https://www.massdrop.com/) gathers enthusiasts to buy medium-sized batches of random items (including keybords) to reduce the costs of small series that would not be commercialy viaable otherwise.
+* [Relegendable keycaps](https://pimpmykeyboard.zendesk.com/hc/en-us/articles/204416135-What-are-Relegendable-Keycaps-), a paper label can be placed below a transparent snap-on top. [Other source](https://www.fentek-ind.com/keys.htm#relegend).
+  [![Relegendable keys can have part of the legend on the front, and can be flat keys or thick keys.](https://pimpmykeyboard.zendesk.com/hc/en-us/article_attachments/201690109/Relegendables.jpg)](https://pimpmykeyboard.zendesk.com/hc/en-us/articles/204416135-What-are-Relegendable-Keycaps-)
+* [Apple Touch Bar](https://support.apple.com/en-us/HT207055)
+* [Optimus Maximus](https://www.artlebedev.com/optimus/maximus/) keyboard has OLED screens below the keys, which are transparent, so that the symbols or icons under the keys can be changed.
+
+## Screen
+
+* [OLPC display](http://wiki.laptop.org/go/Display#Understanding_the_display_system)
+
+  The OLPC (One Laptop Per Child project) integrates a Pixel Qi
+  screen. This screen uses subpixels (red, green, blue) with a square
+  aspect ratio using a non-traditional layout of the subpixels. It
+  features a reflective higher-resolution black and white display,
+  which works in bright sunlight. Behind that black and white layer,
+  there is a backlit screen with colored pixels. This means that
+  depending on the lighting of the environment and backlight
+  brightness, the color may fade away, but a crisp black and white
+  picture will always be visible. This also allows for reduced power
+  consumption if the backlight is disabled or its brightness reduced.
+
+# File format standards
+
+## Used to generate or write files in this project
+
+* [Polyglot Markup](https://dev.w3.org/html5/html-polyglot/html-polyglot.html), an intersection of valid HTML5 and XHTML (except for the doctype)
+* [Sending XHTML as text/html Considered Harmful](hixie.ch/advocacy/xhtml) on the subtle differences between XHTML and HTML.
+* POSIX a.k.a. IEEE Std 1003.1 a.k.a. Open Group Base Specifications Issue 7:
+  * [latest edition](https://pubs.opengroup.org/onlinepubs/9699919799/),
+  * [2017-2018 edition](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/),
+  *      [2016 edition](https://pubs.opengroup.org/onlinepubs/9699919799.2016edition/),
+  *      [2013 edition](https://pubs.opengroup.org/onlinepubs/9699919799.2013edition/),
+  *      [2008 edition](https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/).
+  * The oldest version of POSIX [(IEEE Std 1003.2-1992)](https://ieeexplore.ieee.org/document/6880751) that we could find is behind a paywall.
+  * The oldest version of the Single Unix® Specification [(Version 1 Document Set UNIX 95)](https://publications.opengroup.org/c43x) that we could find is behind a login wall, but seems free to download.
+* [GraphViz Reference](https://www.graphviz.org/doc/info/)
+
+## Used to read files
+
+# Bootstrap
+
+Bootstrapping is an important facet of technology. By having a clear
+path to bootstrap a given branch of science or technology we can
+explain it in a more synthetic way, implement things in a clean way
+while getting rid of historical blunders and baseless
+traditions.
+
+Having some hindsight on the shortest path to success can give some
+foresight on the future directions to explore. If the failed paths are
+also made clear, this foresight might extend to knowing which future
+directions should likely be avoided.
+
+The references in this section are not limited to computer-related
+technologies.
+
+* [RepStrap](https://www.reprap.org/wiki/Category:RepStrap)
+
+  RepRap is a 3D printer that is capable of replicating most of its
+  parts which are not off-the-shelf.
+
+  RepStrap projects are about creating an initial RepRap without an
+  existing RepRap and without advanced tooling.
+* [Global Village Construction Set](https://www.opensourcetechnology.org/gvcs/)
+
+  The GVCS aims to design construction kits for 50 industrial machines
+  which would be necessary for a self-sufficient village. Among these
+  are the compressed earth brick press (used to make bricks for
+  buildings), a tractor, a wind turbine, or the Fabrication
+  Construction Set which can be used to build the other machines.
+* [The Knowledge](https://isbnsearch.com/isbn/9780143127048) How to
+  rebuild our world from scratch, Lewis Dartnell, ISBN-10: 0143127047,
+  ISBN-13: 978-0143127048

tests/to-do/README.md

@@ -0,0 +1,5 @@
+Check how many tasks have been left aside.
+
+These tasks are marked with the four consecutive letters T, O, D, O in the source code.
+
+This tool also looks for instances of F, I, X, M, E and of X, X, X

tests/to-do/list-to-dos.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+
+escapehtml() {
+  sed -e 's/&/\&/g' \
+      | sed -e 's/</\&lt;/g' \
+      | sed -e 's/>/\&gt;/g' \
+      | sed -e 's/"/\&quot;/g'
+}
+
+cat <<'EOF'
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>{{{project-name}}}</title>
+    <style>
+      body > ul { display: table; }
+      ul   > li { display: table-row; }
+      li   > a, li > span { display: table-cell; }
+      li   > * + span { padding-left: 1em; }
+      li   > a + span { text-align: right; }
+    </style>
+  </head>
+  <body>
+    <h1>Open tasks</h1>
+    <ul>
+EOF
+  
+commit="$(git rev-parse HEAD | escapehtml)"
+(
+  cd "$(git rev-parse --show-cdup)";
+  git grep -i -n \\\(todo\\\|fixme\\\|xxx\\\)
+) \
+    | escapehtml \
+    | sed -e 's~^\([^:]*\):\([^:]*\):\(.*\)$~      <li><a href="https://gitlab.com/project-name/project-name/blob/'"$commit"'/\1">\1</a> <span>\2</span> <span>\3</span></li>~'
+
+cat <<'EOF'
+    </ul>
+  </body>
+</html>
+EOF

tests/website/README.md

@@ -0,0 +1,5 @@
+Tests for the web pages.
+
+* Checks that the pages are valid Polyglot Markup (an HTML5 / XHTML chameleon, TODO link to references)
+  * Uses the W3C validator to check that the pages are valid HTML 5, XHTML 1.0, XHTML 1.1, as well as valid HTML 3.2, HTML 4.0 with the exception of the obvious incompatibilities (doctype and self-closing tags)
+* Checks that there are no broken links between the pages, and no broken links to external pages.

travis/auto-push.sh

@@ -0,0 +1,83 @@
+#!/bin/sh
+set -e
+set +x # do not display any command, as they could contain the Travis openssl key and IV.
+
+usage() {
+  echo "Usage: $0 official_repo deploy_repo deploy_branch deploy_base_commit key_iv_id deploy_directory"
+  echo "official_repo:       https://github.com/user/repo.git"
+  echo "deploy_repo:         git@github.com:user/repo.git"
+  echo "deploy_branch:       gh-pages"
+  echo "deploy_base_commit:  branch name or tag"
+  echo "key_iv_id:           123456789abc, part of encrypted_123456789abc_key and encrypted_123456789abc_iv"
+  echo "deploy_directory:    directory to copy on top of deploy_base_commit"
+  echo "from_branch:         master # allow push only when building the given branch"
+}
+
+if test "$#" -eq 1 && test "$1" = "-h" -o "$1" = "--help"; then
+  usage
+  exit 0
+elif test "$#" -ne 7; then
+  usage
+  exit 1
+fi
+
+official_repo="$1"      # https://github.com/user/repo.git
+deploy_repo="$2"        # git@github.com:user/repo.git
+deploy_branch="$3"      # gh-pages
+deploy_base_commit="$4" # branch name or tag
+key_iv_id="$5"          # 123456789abc, part of encrypted_123456789abc_key and encrypted_123456789abc_iv
+deploy_directory="$6"   # directory to copy on top of deploy_base_commit
+from_branch="$7"        # master # allow push only when building the given branch
+key_env_var_name="encrypted_${key_iv_id}_key"
+iv_env_var_name="encrypted_${key_iv_id}_iv"
+key="$(sh -c 'echo "${'"$key_env_var_name"'}"')"
+iv="$(sh -c 'echo "${'"$iv_env_var_name"'}"')"
+
+if test "$(git config remote.origin.url)" != "$official_repo"; then
+  echo "Not on official repo, will not deploy to ${deploy_repo}:${deploy_branch}."
+elif test "$TRAVIS_PULL_REQUEST" != "false"; then
+  echo "This is a Pull Request, will not deploy to ${deploy_repo}:${deploy_branch}."
+elif test "$TRAVIS_BRANCH" != "$from_branch"; then
+  echo "Not on $from_branch branch (TRAVIS_BRANCH = $TRAVIS_BRANCH), will not deploy to ${deploy_repo}:${deploy_branch}."
+elif test -z "${key:-}" -o -z "${iv:-}"; then
+  echo "Travis CI secure environment variables are unavailable, will not deploy to ${deploy_repo}:${deploy_branch}."
+elif test ! -e travis-deploy-key-id_rsa.enc; then
+  echo "travis-deploy-key-id_rsa.enc not present, will not deploy to ${deploy_repo}:${deploy_branch}."
+else
+  echo "Automatic push to ${deploy_repo}:${deploy_branch}"
+
+  # Git configuration:
+  git config --global user.name "$(git log --format="%aN" HEAD -1) (Travis CI automatic commit)"
+  git config --global user.email "$(git log --format="%aE" HEAD -1)"
+
+  # SSH configuration
+  mkdir -p ~/.ssh
+  chmod 700 ~/.ssh
+  if openssl aes-256-cbc -K "$key" -iv "$iv" -in travis-deploy-key-id_rsa.enc -out travis-deploy-key-id_rsa -d >/dev/null 2>&1; then
+    echo "Decrypted key successfully."
+  else
+    echo "Error while decrypting key."
+    exit 1
+  fi
+  # TODO: all the config should be in a separate folder, instead of using ~/.ssh for the id_rsa.
+  mv travis-deploy-key-id_rsa ~/.ssh/travis-deploy-key-id_rsa
+  chmod 600 ~/.ssh/travis-deploy-key-id_rsa
+  eval `ssh-agent -s`
+  ssh-add ~/.ssh/travis-deploy-key-id_rsa
+
+  travis_known_hosts="$("$(dirname "$0")/absolute-path.sh" "$(dirname "$0")/travis_known_hosts")"
+  chmod 600 "$travis_known_hosts"
+  echo "$travis_known_hosts"
+  cat "$travis_known_hosts"
+  ssh -o UserKnownHostsFile=$travis_known_hosts git@github.com || true
+
+  TRAVIS_AUTO_PUSH_REPO_DIR="$HOME/travis-temp-auto-push-$(date +%s)"
+  if test -e "$TRAVIS_AUTO_PUSH_REPO_DIR"; then rm -rf "$TRAVIS_AUTO_PUSH_REPO_DIR"; fi
+  GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=$travis_known_hosts" git clone -b "$deploy_base_commit" --depth 1 --shallow-submodules "$deploy_repo" "$TRAVIS_AUTO_PUSH_REPO_DIR"
+  (cd "$TRAVIS_AUTO_PUSH_REPO_DIR" && git checkout -b "$deploy_branch")
+  rsync -a "${deploy_directory}/" "${TRAVIS_AUTO_PUSH_REPO_DIR}/"
+  (cd "$TRAVIS_AUTO_PUSH_REPO_DIR" && git add -A . && git commit --allow-empty -m "Auto-publish to $deploy_branch") > commit.log || (cat commit.log && exit 1)
+  (cd "$TRAVIS_AUTO_PUSH_REPO_DIR" && git log --oneline --decorate --graph -10)
+  echo '(cd '"$TRAVIS_AUTO_PUSH_REPO_DIR"' && git push --force --quiet "'"$deploy_repo"'" "'"$deploy_branch"'")'
+  (cd "$TRAVIS_AUTO_PUSH_REPO_DIR" && GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=$travis_known_hosts" git push --force --quiet "$deploy_repo" "$deploy_branch" >/dev/null 2>&1) >/dev/null 2>&1 # redirect to /dev/null to avoid showing credentials.
+fi