Update READMEs

README.md

@@ -27,33 +27,25 @@ github issue][forth-issue].
 
 Documentation is lacking, it's not ready yet, this is a WIP branch.
 
-## See it in action
+## Getting started
 
-Michael Schierl has put together [a set of emulators running in the browser that
-run Collapse OS in different contexts][jsemul].
-
-Using those while following along with the [User Guide](doc/) is your quickest
-path to giving Collapse OS a try.
-
-## Documentation
-
-Usage documentation is in-system. Run `0 LIST` for an introduction. You can
-also open `blk/000` in a modern text editor.
+Usage documentation is in-system, so access to documentation requires you to
+run Collapse OS. Fortunately, doing so in an emulator is easy.
 
 See `/emul/README.md` for getting an emulated system running.
 
+Then, run `0 LIST` for an introduction, follow instructions from there.
+
 ## Organisation of this repository
 
-* `forth`: Forth is slowly taking over this project (see issue #4). It comes
-           from this folder.
-* `recipes`: collection of recipes that assemble parts together on a specific
+* `blk`: Collapse OS filesystem's content. That's actually where Collapse OS'
+         source code is located. Everything else is peripheral.
+* `recipes`: collection of recipes that assemble Collapse OS on a specific
              machine.
-* `blk`: Collapse OS filesystem's content. See `000` for intro.
-* `doc`: User guide for when you've successfully installed Collapse OS.
 * `tools`: Tools for working with Collapse OS from "modern" environments. For
            example, tools for facilitating data upload to a Collapse OS machine
            through a serial port.
-* `emul`: Emulated applications.
+* `emul`: Tools for running Collapse OS in an emulated environment.
 * `tests`: Automated test suite for the whole project.
 
 ## Status
@@ -63,13 +55,13 @@ for more information.
 
 ## Discussion
 
-For a general discussion of Collapse OS and the ecosystem of technologies and ideas that may develop around it refer to [r/collapseos][discussion]
+For a general discussion of Collapse OS and the ecosystem of technologies and
+ideas that may develop around it refer to [r/collapseos][discussion]
 
-A more traditional [mailing list][listserv] and IRC (#collapseos on freenode) channels are also maintained.
+A more traditional [mailing list][listserv] and IRC (#collapseos on freenode)
+channels are also maintained.
 
-[libz80]: https://github.com/ggambetta/libz80
 [web]: https://collapseos.org
-[jsemul]: https://schierlm.github.io/CollapseOS-Web-Emulator/
 [discussion]: https://www.reddit.com/r/collapseos
 [listserv]: http://lists.sonic.net/mailman/listinfo/collapseos
 [forth-issue]: https://github.com/hsoft/collapseos/issues/4  

emul/README.md

@@ -6,7 +6,7 @@ emulator.
 ## Not real hardware
 
 In the few emulated apps described below, we don't try to emulate real hardware
-because the goal here is to facilitate userspace development.
+because the goal here is to facilitate "high level" development.
 
 These apps run on imaginary hardware and use many cheats to simplify I/Os.
 
@@ -18,44 +18,17 @@ folder.
 First, make sure that the `libz80` git submodule is checked out. If not, run
 `git submodule init && git submodule update`.
 
-After that, you can run `make` and it builds all applications.
+After that, you can run `make` and it builds the `forth` interpreter.
 
-## forth
-
-Collapse OS' Forth interpreter, which is in the process of replacing the
-zasm-based project.
-
-The Forth interpreter is entirely self-hosting, that is, it assembles its
-binary with itself.
-
-There are 3 build stages.
-
-**Stage 0**: At this stage, all we have are our bootstrap binaries, `boot.bin`
-and `z80c.bin`. We concatenate them into `forth0.bin` ans then wrap the
-emulator around it which is named `stage1` (because it builds the stage 1) to
-have a barebone forth interpreter.
-
-**Stage 1**: The `stage1` binary allows us to augment `forth0.bin` with
-the compiled dictionary of a full Forth interpreter. We feed it with
-`$(FORTHSRCS)` and then dump the resulting compiled dict. 
-
-From there, we can create `forth1.bin`, which is wrapped by both the `forth`
-and `stage2` executables. `forth` is the interpreter you'll use.
-
-**Stage 2**: `stage2` is used to resolve the chicken-and-egg problem and use
-the power of a full Forth intepreter, including an assembler, to assemble
-`z80c.bin`. This is a manual step executed through `make updatebootstrap`.
-
-Normally, running this step should yield the exact same `boot.bin` and
-`z80c.bin` as before, unless of course you've changed the source.
+Run `./forth` to get the COllapse OS prompt. Type `0 LIST` for help.
 
 ## Problems?
 
 If the libz80-wrapped zasm executable works badly (hangs, spew garbage, etc.),
 it's probably because you've broken your bootstrap binaries. They're easy to
 mistakenly break. To verify if you've done that, look at your git status. If
-`boot.bin` or `z80c.bin` are modified, try resetting them and then run
-`make clean all`. Things should go better afterwards.
+`forth.bin` is modified, try resetting it and then run `make clean all`. Things
+should go better afterwards.
 
 If that doesn't work, there's also the nuclear option of `git reset --hard`
 and `git clean -fxd`.
@@ -63,3 +36,5 @@ and `git clean -fxd`.
 If that still doesn't work, it might be because the current commit you're on
 is broken, but that is rather rare: the repo on Github is plugged on Travis
 and it checks that everything is smooth.
+
+[libz80]: https://github.com/ggambetta/libz80