From 6b4b8ad13b174da2ed172d3eca2f6bd3553f7b71 Mon Sep 17 00:00:00 2001
From: kitty <nepeta@canaglie.net>
Date: Wed, 8 Apr 2026 16:03:51 +1000
Subject: some documentation

maybe reorganise the docs into topics
---
 readme.md    | 30 ++++++++++++++++++++++++++++++
 sanctuary.fs | 11 ++---------
 sanctuary.s  | 11 +++++++----
 3 files changed, 39 insertions(+), 13 deletions(-)

diff --git a/readme.md b/readme.md
index 2c17143..b5eae4b 100644
--- a/readme.md
+++ b/readme.md
@@ -84,6 +84,9 @@ this word does not update latest.
 ### `(hide)   ( ht -- )`
 set the smudge bit on the header ht.
 
+### `(unhide)   ( ht -- )`
+unset the smudge bit on the header ht.
+
 ### `*   ( u1 u2 -- u )`
 multiply u1 and u2.
 
@@ -143,6 +146,9 @@ set the system to compiling mode.
 ### `:   ( "name" -- )`
 start compilation of the word 'name'.
 
+### `:noname   ( -- xt )`
+start compiling a nameless, headerless word and yield its xt.
+
 ### `;   ( -- ) IMMEDIATE`
 end compilation of the currently compiling word.
 
@@ -205,6 +211,9 @@ move a value from the working stack to the return stack.
 ### `>resolve   ( a -- )`
 mark the destination of a forward branch.
 
+### `?allocate   ( u -- a e )`
+allocate a dynamic block of memory, producing an error on failure.
+
 ### `?branch   ( -- )`
 compile into user memory an incomplete conditional branch.
 if the value on the stack is zero the branch is taken.
@@ -219,6 +228,15 @@ if a word was found,
 its link field address is returned along with the true flag.
 if no word was found or the string is of length zero, abort.
 
+### `?notfound   ( -- )`
+produce a word not found error.
+
+### `?overflow   ( -- )`
+produce a stack overflow error.
+
+### `?underflow   ( -- )`
+produce a stack underflow error.
+
 ### `0=   ( n -- ? )`
 return true if n is equal to zero.
 
@@ -256,6 +274,9 @@ call the error handler
 ### `again   ( -- ) IMMEDIATE COMPILE-ONLY`
 complete an infinite loop began by the word `begin`.
 
+### `allocate   ( u -- a e )`
+allocate a dynamic block of memory.
+
 ### `allot   ( u -- )`
 reserve u bytes of user memory.
 
@@ -413,6 +434,9 @@ which is used as the user memory space.
 ### `execute   ( xt -- )`
 call the word xt.
 
+### `exit   ( -- ) IMMEDIATE COMPILE-ONLY`
+compile into the current definition a return instruction.
+
 ### `false   ( -- u )`
 a cell with no bits set.
 
@@ -422,6 +446,9 @@ a zero is returned along with the original given string
 if no word was found. if a word was found,
 its link field address is returned along with the true flag.
 
+### `free   ( a u -- e )`
+free the given block of memory created by `allocate`.
+
 ### `grow   ( u -- )`
 grows, and marks as executable, the user memory space by u bytes.
 
@@ -501,6 +528,9 @@ perform a munmap(2) system call.
 ### `nip   ( u1 u2 -- u2 )`
 drop the second-highest value from the stack.
 
+### `nonaming   ( -- ? )`
+a `value`: true if the currently compiling word is a `:noname` word.
+
 ### `number   ( a u -- n -1 | 0 )`
 convert given string into a number along with a flag.
 if parsing a number fails then 0 (false) is returned
diff --git a/sanctuary.fs b/sanctuary.fs
index e161e6e..b7e5469 100644
--- a/sanctuary.fs
+++ b/sanctuary.fs
@@ -26,7 +26,7 @@
 : repeat  branch swap <resolve >resolve ; immediate compile-only
 
 : ?dup  dup 0<> if dup then ;
-: exit  [ hex ] c3 c, [ decimal ] ; immediate \ todo doc
+: exit  [ hex ] c3 c, [ decimal ] ; immediate compile-only
 
 : allot  dp +! ;
 
@@ -80,11 +80,6 @@ decimal
 : s>z  here -rot cmove, 0 c, ;
 
 \ DEFER {{{
-\ todo doc
-\ : defer  create ['] abort , does> @ execute ;
-\ : create  parse-name (header) latest ! ['] (create) compile, 0 , ;
-\ : does>  latest @ >body 2 + ['] (does>) over ! \ replace call loc
-\ 	( replace destination ) 11 + r> swap ! ;
 \ todo ['] abort → ['] ?defer or something (where ?defer yields an appropriate error)
 : defer  parse-name (header) latest !
 	['] (defer) compile, ['] abort , ( sic ) ;
@@ -101,7 +96,7 @@ decimal
 \ privatisation yoinked from pforth
 
 : (hide)  cell+ dup c@ 1 or swap c! ;
-: (unhide)  cell+ dup c@ 1 invert and swap c! ; \ todo doc
+: (unhide)  cell+ dup c@ 1 invert and swap c! ;
 : hide  parse-name ?find (hide) ;
 
 variable private0  variable private$
@@ -139,7 +134,6 @@ decimal
 : mmap  9 syscall6 ;
 : munmap  11 syscall2 ;
 
-\ todo doc
 : allocate ( u -- a e )  >r 0 -1 ( offset fd , unused here )
 	MAP_PRIVATE MAP_ANONYMOUS or ( flags )
 	PROT_READ PROT_WRITE or ( prot )
@@ -166,7 +160,6 @@ variable hld
 
 \ NONAME {{{
 \ will maybe(?) be modified later in the vocabulary section.
-\ todo doc
 false value nonaming
 
 : :noname  here  true to nonaming  postpone ] ;
diff --git a/sanctuary.s b/sanctuary.s
index 74b9528..041a6fe 100644
--- a/sanctuary.s
+++ b/sanctuary.s
@@ -1126,15 +1126,18 @@ defcode "abort", abort, 0
 	call r11
 	ret
 
-; todo doc? maybe?
-defdefer "!underflow", q_underflow, 0
+; i don't like these names
+defdefer "?underflow", q_underflow, 0
 	call abort
+	ret
 
-defdefer "!overflow", q_overflow, 0
+defdefer "?overflow", q_overflow, 0
 	call abort
+	ret
 
-defdefer "!notfound", q_notfound, 0
+defdefer "?notfound", q_notfound, 0
 	call abort
+	ret
 ; }}}
 
 ; these words are called from `create`d words,
-- 
cgit v1.2.3