add an intro to the new directory structure to the README

there's also additional wording attempting to explain that, yes, the way to learn the language really is to read the language's source. it really is documentation.

from discussions elsewhere, some people found this obvious and some people didn't notice it and thought there was no documentation, so we've done our best to explain the choice.

Force-Push: yes
Change-Id: Ie9e4b81cd48e7ae014032d1983120edf3d823234

1 files changed, 43 insertions, 5 deletions

diff --git a/README.txt b/README.txt
index 8657dc6..e77c57f 100644
--- a/README.txt
+++ b/README.txt
@@ -199,19 +199,57 @@ even a little, it won't be so scary next time. It's heavily commented and
 meant for anyone with a little programming knowledge to be able to read, even
 if you've never done systems programming before.
 
-  If you find something in it confusing, please don't be afraid to ask! It's
-likely other people are confused too, and sharing your questions helps improve
-the documentation and lets others learn by watching.
+  In particular, the authoritative documentation about what basic words exist
+and how to use them is language/static/core.e. If you read nothing else, you
+should read that file. As of this writing, core.e has 665 lines of comments
+and only 538 lines of actual code; Irenes promise this isn't just an excuse to
+not write documentation. After you've read core.e, you'll know a lot of basic
+words that can be used as commands within Evocation.
+
+  Evocation takes the view that putting doucmentation and code next to each
+other is strictly more useful than separating them. First, separate
+documentation would be more prone to getting out of date. Second, seeing the
+implementations alongside the explanations clarifies both. Often there's a
+long explanation of something with a trivial implementation, and seeing both
+together teaches you that, yes, this is magick, but it isn't beyond your
+ability to understand - whereas seeing just the explanation would send the
+opposite message. It's empowering, if you let it be.
+
+  If you find something in the code confusing, please don't be afraid to ask!
+It's likely other people are confused too, and sharing your questions helps
+improve the documentation and lets others learn by watching.
+
+  Thus motivated, we will now explain the overall structure of Evocation's
+source code, and point out what all the major pieces are.
 
   The top-level source file whose job is to compile Evocation itself is
 evoke.e. It's really short, and worth a quick glance right now. It lists all
 the other source files and the order they get loaded in and how they're
 processed.
 
+  The bulk of the actual code is divided among three locations:
+language/static/, language/dynamic/, and compilation/. One way to think about
+the code's overall structure is that first "static" is loaded, then "dynamic",
+then finally "compilation". The code in "dynamic" is built out of the pieces
+provided in "static", and then the code in "compilation" is built out of the
+pieces provided in the other two. If you read the code in this order, every
+piece you encounter, with very few exceptions, will be built out of the pieces
+you've already read.
+
+  In reality the compilation process does this all "in advance", rather than
+it happening at runtime. That's why the code is able to use Evocation's
+syntax, before the words to implement the syntax have been created. That's
+also why the handful of very rare forward references are possible.
+Nonetheless, there is still a lot of conceptual truth to be had by thinking of
+it as a body of code written to run in this one specific order, building on
+itself.
+
+  So much for the linear order; now, how about categorizing the code by
+subject?
+
   The files that do the work to make Evocation run at all are
 compilation/execution.e and language/static/core.e. It's worth reading through
-both of them slowly. After you've read core.e, you'll know a lot of basic
-words that can be used as commands within Evocation.
+both of them slowly.
 
   A lot of Evocation is written in Evocation's version of assembly language.
 The file language/static/amd64.e is the one that implements all the assembly