1 files changed, 41 insertions, 0 deletions
diff --git a/development/JAForth/README b/development/JAForth/README
new file mode 100644
index 0000000000..420130a39e
--- /dev/null
+++ b/development/JAForth/README
@@ -0,0 +1,41 @@
+A set of programs written Pedro Gimeno, and offered under the Expat
+license (one of the many MIT licenses).
+
+This package contains three command-line programs:
+
+- JAForth: An interpreter for the Jupiter ACE Forth, written in
+Python, that can also compile to a Jupiter-format or Spectrum-format
+.TAP tape file.
+- jforth: A headless Jupiter ACE emulator which runs the Jupiter ACE
+Forth, reading the input from a file and writing the output to
+standard output.
+- JADecompile: A Jupiter ACE Forth .TAP decompiler.
+
+The first two do more or less the same. While the second was written
+with the sole purpose of validating the first, it turned out to cover
+almost the same functionality as the Python version.
+
+Which one do you need? Well, the Python version is autonomous - you
+only need a Python interpreter in your machine (2.7 or 3); you don't
+even need the ACE ROM. Python interpreters come bundled by default
+in most systems nowadays, including Linux, Windows, OSX, BSD and
+whatnot; if yours is one of these rare cases where there isn't one,
+you can grab a pre-built binary or even compile it from source.
+
+On the other hand, the headless emulator (jforth) requires a ROM
+(named ace.rom and present in the current directory), a C compiler,
+and GNU make to build. The accuracy is of course guaranteed, but
+since it was used to test the accuracy of the Python interpreter,
+I'd say the Python version is on par in accuracy.
+
+JAForth.py can't run Z80 code because it's not an emulator, while
+jforth can. Not that there's much need for that in a tool that is
+aimed at compiling, anyway.
+
+JADecompile.py is a simple Forth decompiler. It's not very accurate
+but it more or less does the job. Unlike the LIST command, it can
+list (to an extent) words defined with VARIABLE, CONSTANT, CREATE
+and VOCABULARY, and it can handle multiple vocabularies. It can
+detect words created with DEFINER but it doesn't know how to write
+them properly (e.g. if they invoke WORD), so it just lists their
+parameter field if there's one.