book: add a section on how retro deals with errors

FossilOrigin-Name: 8747e39ff623322c99590c39ded91059e76b3aaeee72a6022e451d78156e6e6c

RELEASE_NOTES.md

@@ -100,6 +100,7 @@ June 2019.
   image file
 - add `image:save`
 - add `sys:name`
+- will now display an error and exit on stack over/underflow
 
 ### retro-compiler
 

RETRO-Book.md

@@ -2111,3 +2111,37 @@ This only supports hosts using ELF executables.
 
 The output file name is fixed to `a.out`.
 
+# Errors
+
+RETRO does only minimal error checking.
+
+## Non-Fatal
+
+A non-fatal error will be reported on *word not found* during
+interactive or compile time. Note that this only applies to
+calls: if you try to get a pointer to an undefined word, the
+returned pointer will be zero.
+
+## Fatal
+
+A number of conditions are known to cause fatal errors. The
+main ones are stack overflow, stack underflow, and division
+by zero.
+
+On these, RETRO will generally exit. For stack depth issues,
+the VM will attempt to display an error prior to exiting.
+
+In some cases, the VM may get stuck in an endless loop. If this
+occurs, try using CTRL+C to kill the process, or kill it using
+whatever means your host system provides.
+
+## Rationale
+
+Error checks are useful, but slow - especially on a minimal
+system like RETRO. The overhead of doing depth checks adds
+up quickly.
+
+As an example, adding a depth check to `drop` increases the
+time to use it 250,000 times in a loop from 0.16 seconds to
+1.69 seconds.
+

book/Errors

@@ -0,0 +1,34 @@
+# Errors
+
+RETRO does only minimal error checking.
+
+## Non-Fatal
+
+A non-fatal error will be reported on *word not found* during
+interactive or compile time. Note that this only applies to
+calls: if you try to get a pointer to an undefined word, the
+returned pointer will be zero.
+
+## Fatal
+
+A number of conditions are known to cause fatal errors. The
+main ones are stack overflow, stack underflow, and division
+by zero.
+
+On these, RETRO will generally exit. For stack depth issues,
+the VM will attempt to display an error prior to exiting.
+
+In some cases, the VM may get stuck in an endless loop. If this
+occurs, try using CTRL+C to kill the process, or kill it using
+whatever means your host system provides.
+
+## Rationale
+
+Error checks are useful, but slow - especially on a minimal
+system like RETRO. The overhead of doing depth or other checks
+adds up quickly.
+
+As an example, adding a depth check to `drop` increases the
+time to use it 250,000 times in a loop from 0.16 seconds to
+1.69 seconds.
+

make-book.retro

@@ -10,7 +10,15 @@
 :process-files [ import add-to-book ] array:for-each ;
 :open          'RETRO-Book.md file:open<for-writing> !Out ;
 :close         @Out file:close ;
-:process       open process-files close ;
+:assemble      open process-files close ;
+
+:open          'gophermap file:open<for-writing> !Out ;
+:close         @Out file:close ;
+:ENTRY         '0%s\t/book/%s\tforth.works\t70\n ;
+:process-files [ dup ENTRY s:format [ @Out file:write ] s:for-each ] array:for-each ;
+:gophermap     open process-files close ;
+
+:process       dup assemble gophermap ;
 
 {
  'Overview
@@ -53,6 +61,6 @@
  'Additional-Tools
  'Advanced-Builds
  'Retro-Compiler
+ 'Errors
 } process
 ~~~
-