added a README

at least it's a start :)

Force-Push: yes
Change-Id: I221a916c8d6ae5ac45c1d884232b31da89584ddc

1 files changed, 88 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..88a7147
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,88 @@
+~~~~~~~~~~~~~~
+~~ Welcome! ~~~~~~
+~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
+
+  The documentation is a work in progress. It doesn't say most of the things
+it needs to, yet.
+
+
+ ~~~~~~~~~~~~
+~~ Building ~~
+ ~~~~~~~~~~~~
+
+  To get started, first build the flatassembler version:
+
+  $ fasmg quine.asm quine
+  $ chmod 755 quine
+
+  This is a working Evocation interpreter, but it's incomplete and will become
+more so with time. So, next, build Evocation-in-Evocation:
+
+  $ (cat labels.e elf.e transform.e execution.e; echo 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e ; echo pyrzqxgl; cat evoke.e) | ./quine > evoke
+  $ chmod 755 evoke
+
+  Finally, rebuild Evocation-in-Evocation with itself:
+
+  $ (cat labels.e elf.e transform.e execution.e; echo 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e ; echo pyrzqxgl; cat evoke.e) | ./evoke > evoke2
+  $ chmod 755 evoke2
+
+  Now keep your evoke binary somewhere safe, and use it to build new versions
+as you modify Evocation.
+
+
+ ~~~~~~~~~~~~~
+~~ Exploring ~~
+ ~~~~~~~~~~~~~
+
+  You can now try out Evocation. Type to it interactively:
+
+  $ ./evoke
+  ." Hi, Irenes!"
+  6 7 * . newline
+  bye
+
+  See what it prints!
+
+  Some helpful words to try to get started are list-dictionary and describe.
+
+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~ Reading Evocation's source code ~~
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Even if you're only interested in using Evocation, not in modifying it, we
+encourage you to at least skim through the source. If you've looked at it,
+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.
+
+  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 files that do the work to make Evocation run at all are execution.e and
+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.
+
+  A lot of Evocation is written in Evocation's version of assembly language.
+The file amd64.e is the one that implements all the assembly instructions.
+Writing a real program in assembly also requires resolving labels, which are
+a special syntax that gives names to addresses. The behavior of labels is all
+implemented in labels.e.
+
+  On the assembly language front, there's also linux.e which contains assembly
+words for doing things specific to the Linux operating system, such as reading
+input, and there's elf.e which contains words for outputting the special file
+headers that let the operating system understand that a file is an executable
+program.
+
+  TODO output.e interpret.e dynamic.e flow-control.e execution-support.e
+