From: Bryan English <bryan@rethought.computer>
Date: Sat, 11 Apr 2026 02:54:10 +0000 (-0400)
Subject: doc updates
X-Git-Url: https://rethought.computer/gitweb//gitweb//git?a=commitdiff_plain;h=d82beed15c82fe51e7fdd8ad74c3f4ad0307ff73;p=sorel-lang.git

doc updates
---

diff --git a/README.md b/README.md
index 40b5544..28c2454 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,26 @@
 # sorel
 
-The name means "Stack-Oriented Rethought Language".
+_The name means "Stack-Oriented Rethought Language"._
 
+**Sorel** a compiled-only Forth variant with the following goals:
 
-## TODO
+* It should be useful and usable as a systems programming language.
+    * This includes being able to make kernels and compilers.
+* The language and compiler should be simple enough for novice programmers to understand.
+* Neither C nor the C standard library should be relied upon for any functionality.
+    * Sorel should be _independently_ useful.
+* Self-hosting (_not implemented yet!_)
 
-* [x] Imports
-* [x] Syscalls
-* [x] Loops
-* [ ] Structs
-* [ ] many, many more things
+In order to reduce complexity, Sorel only targets one CPU architecture (64-bit RISC-V), and one OS kernel (Linux, for now).
 
-## Helpful External Resources
+For an overview of the language itself in its current state, see `docs/language_overview.md`.
 
-* https://gpages.juszkiewicz.com.pl/syscalls-table/syscalls.html
-* https://godbolt.org/
-* https://projectf.io/posts/riscv-cheat-sheet/
-* https://github.com/dvoytik/riscv-cheats
+To build the compiler, or to get set up to develop Sorel, see `docs/hacking.md`.
+
+## Contributing
+
+See CONTRIBUTING.md
+
+## License
+
+Apache 2.0. See LICENSE.
diff --git a/docs/hacking.md b/docs/hacking.md
index afd8f77..dc05693 100644
--- a/docs/hacking.md
+++ b/docs/hacking.md
@@ -32,9 +32,9 @@ cargo build
 ```
 
 This puts the compiler binary at `target/debug/sorelc`.
-Release builds can also be created in the usual Rust/`cargo` fasion.
+Release builds can also be created in the usual Rust/`cargo` fashion.
 
-Note that if you change any stdlib files, you'll need to rebuild.
+Note that if you change any stdlib files, you'll need to rebuild the compiler.
 
 ## Compiling a Sorel Program
 
@@ -70,3 +70,10 @@ target remote :4567
 
 Then you can use normal gdb commands!
 The `tui layout asm` is highly recommended.
+
+## Helpful External Resources
+
+* https://gpages.juszkiewicz.com.pl/syscalls-table/syscalls.html
+* https://godbolt.org/
+* https://projectf.io/posts/riscv-cheat-sheet/
+* https://github.com/dvoytik/riscv-cheats
diff --git a/docs/language_overview.md b/docs/language_overview.md
index b4780f4..0a993a6 100644
--- a/docs/language_overview.md
+++ b/docs/language_overview.md
@@ -66,7 +66,6 @@ To pass arguments, simply put them on the stack in the order that they appear in
 Be careful with types.
 The return value is added to the stack once the function returns.
 
-For the moment, dynamic libraries cannot be loaded.
 Exposing Sorel functions to C is also not currently supported, and Sorel _must_ control the entrypoint/`main()`/`_start`.
 
 ## Built-in Words