4374 - starting to use the online help system

3 files changed, 19 insertions, 2 deletions

diff --git a/subx/001help.cc b/subx/001help.cc
index 3b60f60f..c2b0390e 100644
--- a/subx/001help.cc
+++ b/subx/001help.cc
@@ -54,7 +54,9 @@ void init_help() {
     "Comments start with the '#' character. It should be at the start of a word (start of line, or following a space).\n"
     "Each segment starts with a header line: a '--' delimiter followed by the starting address for the segment.\n"
     "The starting address for a segment has some finicky requirements. But just start with a round number, and `subx` will try to guide you to the right answer.\n"
-    "Currently only the first segment contains executable code (because it gets annoying to have to change addresses in later segments every time an earlier one changes length).\n"
+    "A good default is to try to start the first segment at the default address of 0x08048000, and to start subsequent segments at least 0x1000 (most common page size) bytes after.\n"
+    "If a segment occupies than 0x1000 bytes you'll need to push subsequent segments further down.\n"
+    "Currently only the first segment contains executable code (because it gets annoying to have to change addresses in later segments every time an earlier one changes length; one of those finicky requirements).\n"
     "Programming in machine code can be annoying, but let's see if we can make it nice enough to be able to write a compiler in it.\n"
   );
   // End Help Texts
diff --git a/subx/010vm.cc b/subx/010vm.cc
index 50074114..67c407a8 100644
--- a/subx/010vm.cc
+++ b/subx/010vm.cc
@@ -27,6 +27,19 @@ uint32_t EIP = 1;  // preserve null pointer
 bzero(Reg, sizeof(Reg));
 EIP = 1;  // preserve null pointer
 
+:(before "End Help Contents")
+cerr << "  registers\n";
+:(before "End Help Texts")
+put(Help, "registers",
+  "SubX currently supports 8 integer registers, numbered from 0 to 7.\n"
+  "There's also a register for the address of the currently executing instruction. It is modified by jumps.\n"
+  "Various instructions modify one or more of 3 flags, as a side-effect:\n"
+  "- the sign flag: usually set if an arithmetic result is negative, or reset if not.\n"
+  "- the zero flag: usually set if a result is zero, or reset if not.\n"
+  "- the overflow flag: usually set if an arithmetic result overflows.\n"
+  "We don't support non-integer (floating-point) registers yet.\n"
+);
+
 :(before "End Globals")
 // the subset of x86 flag registers we care about
 bool SF = false;  // sign flag
diff --git a/subx/Readme.md b/subx/Readme.md
index 77f338ad..854a3876 100644
--- a/subx/Readme.md
+++ b/subx/Readme.md
@@ -13,7 +13,9 @@ and libc.)
    check my program for errors rather than to hide low-level details. Force
    myself to think about security by living with raw machine code for a while.
    Reintroduce high level languages (HLLs) only after confidence is regained
-   in the foundations. Delegate only when I can verify with confidence.
+   in the foundations (and when the foundations are ergonomic enough to
+   support developing a compiler in them). Delegate only when I can verify
+   with confidence.
 
 2. The software in our computers has grown incomprehensible. Nobody
    understands it all, not even experts. Even simple programs written by a