From b3f9cdf372c7cf5a3bbc8590d608ce7e849c3c4b Mon Sep 17 00:00:00 2001
From: Glen Whitney <glen@studioinfinity.org>
Date: Fri, 12 Feb 2021 17:08:55 -0800
Subject: [PATCH] docs: Add statics development documentation

  Hopefully the new section will be helpful, given that it can be
  a bit confusing to get started with Statix. With this commit,
  the background is established and the stage is set to
  dive into type checking.
---
 mkdocs.yml        |  1 +
 trans/statics.stx | 48 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 6726b34..e316a98 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,6 +2,7 @@ site_name: fostr language
 nav:
 - README.md
 - tests/basic.md
+- trans/statics.md
 - implementation.md
 
 plugins:
diff --git a/trans/statics.stx b/trans/statics.stx
index 7772698..fa795fe 100644
--- a/trans/statics.stx
+++ b/trans/statics.stx
@@ -2,7 +2,53 @@ module statics
 
 imports signatures/fostr-sig
 
-// see docs/implementation.md for details on how to switch to multi-file analysis
+/** md
+Title: Adding Program Analysis with Statix
+
+## Development of fostr static analysis
+
+This section is more documentation of Spoofax in general and Statix
+in particular than of fostr itself, but is being maintained here in case
+it could be either helpful to someone getting started with Statix or
+helpful in understanding how the static characteristics of fostr were designed.
+
+As mentioned in the [Overview](../README.md), I don't like to program and a
+corollary of that is never to use a facility unless/until there's a need for
+it. So the first few rudimentary passes at fostr simply declared every program
+to be "OK" from the point of view of Statix:
+```statix
+{! "\git docs/statix_start:trans/statics.stx" extract:
+  start: programOk
+  stop: (.*TopLevel.*)
+!}
+```
+
+Then I reached the point at which the grammar was basically just
+```SDF3
+// Start.TopLevel = <Ex>
+// Ex.Sequence    = sq:Ex+ {layout: align-list sq}
+// Ex.Terminated  = <<Ex>;>
+{! "\git docs/statix_start:syntax/fostr.sdf3" extract:
+  start: TermEx.Terminate
+  stop: (.*bracket.*)
+!}
+```
+(The first three clauses are in comments because they approximate fostr's
+grammar; it actually uses a few more sorts for sequences of
+expressions, to acheive fostr's exact layout rules.)
+
+This was the first point at which there were two different types that might
+need to be written to standard output (Int and String), and although of course
+the dynamically-typed Python and Javascript code generated dealt with both fine,
+the Haskell code needed to differ depending on the
+type of the item written (and I hadn't even started OCaml code generation at
+that point since I knew it would be hopeless without statically typing fostr
+programs).
+
+So it was time to bite the bullet and add type checking via Statix to fostr.
+**/
+
+// see docs/implementation.md for detail on how to switch to multi-file analysis
 
 rules // single-file entry point