about summary refs log tree commit diff stats
path: root/subx
diff options
context:
space:
mode:
authorKartik Agaram <vc@akkartik.com>2018-10-14 00:13:41 -0700
committerKartik Agaram <vc@akkartik.com>2018-10-14 00:13:41 -0700
commit5d06fe27fb57cb67d73deb5e6aa42b6898896a32 (patch)
tree1b1fdbf3a12ec7a542dbb86897c95831ce61e214 /subx
parent0f851e48aa3e89648dfd39f706c36ba3c6964da8 (diff)
downloadmu-5d06fe27fb57cb67d73deb5e6aa42b6898896a32.tar.gz
4696
Update the syntax documentation.
Diffstat (limited to 'subx')
-rw-r--r--subx/011run.cc28
1 files changed, 14 insertions, 14 deletions
diff --git a/subx/011run.cc b/subx/011run.cc
index 2ebdf3a9..b1ff46dd 100644
--- a/subx/011run.cc
+++ b/subx/011run.cc
@@ -12,26 +12,26 @@ put_new(Help, "syntax",
   "Comments start with the '#' character. It should be at the start of a word\n"
   "(start of line, or following a space).\n"
   "\n"
-  "Each segment starts with a header line: a '==' delimiter followed by the\n"
-  "starting address for the segment.\n"
+  "Each segment starts with a header line: a '==' delimiter followed by the name of\n"
+  "the segment.\n"
   "\n"
-  "The starting address for a segment has some finicky requirements. But just\n"
-  "start with a round number, and `subx` will try to guide you to a valid\n"
-  "configuration.\n"
-  "A good rule of thumb is to try to start the first segment at the default\n"
-  "address of 0x08048000, and to start each subsequent segment at least 0x1000\n"
-  "(most common page size) bytes after the last.\n"
-  "If a segment occupies than 0x1000 bytes you'll need to push subsequent\n"
-  "segments further down.\n"
-  "Currently only the first segment contains executable code (because it gets\n"
-  "annoying to have to change addresses in later segments every time an earlier\n"
-  "one changes length; one of those finicky requirements).\n"
+  "Currently SubX assumes the first segment encountered contains executable code, and\n"
+  "the second contains global variables. By convention we call them 'code' and 'data'\n"
+  "respectively.\n"
+  "The first instruction executed in the resulting binary is always the first\n"
+  "instruction of the first segment.\n"
+  "\n"
+  "Segments with the same name get merged together. This rule helps keep functions and\n"
+  "their data close together in .subx files.\n"
+  "Later segments with the same name get their contents *prepended* to earlier ones.\n"
+  "This rule helps each .subx file to put forth a different entrypoint for the binary,\n"
+  "overriding previously loaded files.\n"
   "\n"
   "Lines consist of a series of words. Words can contain arbitrary metadata\n"
   "after a '/', but they can never contain whitespace. Metadata has no effect\n"
   "at runtime, but can be handy when rewriting macros.\n"
   "\n"
-  "Check out some examples in this directory (ex*.subx)\n"
+  "Check out the examples in the examples/ directory.\n"
   "Programming in machine code can be annoying, but let's see if we can make\n"
   "it nice enough to be able to write a compiler in it.\n"
 );