duskos

commit 13d00d6cf9edc71cfc12b360928b809eb06a19bf
parent 11e31bfb54f95c9fadffffc575bc560d75e97a85
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Sun, 23 Oct 2022 21:09:36 -0400

doc: improve file documentation

Diffstat:
M
fs/doc/file.txt
 | 
14
++++++++++++++
M
fs/doc/usage.txt
 | 
10
++++++++++

2 files changed, 24 insertions(+), 0 deletions(-)
diff --git a/fs/doc/file.txt b/fs/doc/file.txt
@@ -201,3 +201,17 @@ capabilities to a memory buffer. It extends File with those words:
 
 :ptr ( hdl -- a )
   Address corresponding to current position.
+
+## File loading shortcuts
+
+Feeding the Forth intepreter with the contents of a file is something you'll
+want to do fairly often, which might not sit well with the verbosity of Path's
+API. A shortcut to finding a Path and then loading it is "f<<". This word,
+followed by a path to load in the input stream, with call :fload on that path.
+
+It happens frequently that some piece of code depends on some other so we want
+to load these files first. However, some units are depended upon by more than
+one units and we don't want to load these pieces of code twice. To this end,
+whenever a file is loaded, we record its ID in a linked list to remember we
+loaded it. If you use the "?f<<" word instead of "f<<", the specified file will
+be loaded only if it wasn't already loaded.
diff --git a/fs/doc/usage.txt b/fs/doc/usage.txt
@@ -1,5 +1,8 @@
 # Dusk OS usage
 
+Warning: this OS is not usable yet. It lacks many convenience words would make
+it usable. But still, it can do many nice tricks...
+
 Dusk OS is a Forth that generally follow conventions described in "Starting
 Forth" by Leo Brodie, except that words are lowercase. If you don't know Forth,
 it's recommended that you start there.
@@ -403,3 +406,10 @@ redirectable output" word.
 The basic Dusk console, the sys/rdln subsystem, inserts itself between "key" and
 "stdin". It feeds itself from key and provides line editing capabilities. When
 a whole line is ready to be interpreted, it is fed to stdin.
+
+## Loading files
+
+Dusk's interpreter can be fed with the contents of files through various words
+such as :fload, f<< and ?f<<. Refer to doc/file.
+
+If you want to compile C source files, you'll want to look at doc/cc.