From 31e4d599f2ec9eb85961b47115da7553e7f83fb7 Mon Sep 17 00:00:00 2001
From: crc <crc@noemail.net>
Date: Fri, 22 Mar 2019 11:20:08 +0000
Subject: [PATCH] book: begin commenting the make-book tool

FossilOrigin-Name: b9b68954573b952ee9500ca68546c69a5af2f64eb45bf95a30d8d11643f06766
---
 RETRO-Book.md                            |  8 ----
 book/Programming-Techniques-Return-Stack |  7 ----
 make-book.retro                          | 52 ++++++++++++++++--------
 3 files changed, 34 insertions(+), 33 deletions(-)
 delete mode 100644 book/Programming-Techniques-Return-Stack

diff --git a/RETRO-Book.md b/RETRO-Book.md
index ee79086..5f1f49d 100644
--- a/RETRO-Book.md
+++ b/RETRO-Book.md
@@ -1873,14 +1873,6 @@ already in the buffers after updating these or you will risk
 data corruption and possible crashes.
 
 
-# The Return Stack
-
-RETRO has two stacks. The primary one is used to pass data
-beween words. The second one primarily holds return addresses.
-
-Each time a word is called, the next address is pushed to
-the return stack.
-
 # Working With Assembly Language
 
 RETRO runs on a virtual machine called Nga. It provides a
diff --git a/book/Programming-Techniques-Return-Stack b/book/Programming-Techniques-Return-Stack
deleted file mode 100644
index f65996e..0000000
--- a/book/Programming-Techniques-Return-Stack
+++ /dev/null
@@ -1,7 +0,0 @@
-# The Return Stack
-
-RETRO has two stacks. The primary one is used to pass data
-beween words. The second one primarily holds return addresses.
-
-Each time a word is called, the next address is pushed to
-the return stack.
diff --git a/make-book.retro b/make-book.retro
index 3a81c3f..f825cc9 100755
--- a/make-book.retro
+++ b/make-book.retro
@@ -1,25 +1,20 @@
 #!/usr/bin/env retro
 
+This is used to assemble the Markdown copy of the RETRO Handbook.
+
+The individual chapters are in the `book/` directory. This is set
+using the `BOOK-BASE` constant.
+
 ~~~
 'book/  'BOOK-BASE s:const
-'Out var
+~~~
 
-:import        here swap BOOK-BASE s:prepend file:slurp ;
-:\n            ASCII:LF @Out file:write ;
-:add-to-book   here [ @Out file:write ] s:for-each \n ;
-:process-files [ import add-to-book ] array:for-each ;
-:open          'RETRO-Book.md file:open<for-writing> !Out ;
-:close         @Out file: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 ;
+The chapters are specified it the `TOC`, a named array. These are
+the file names, they will be included in order. I am structuring
+it using separate file to make the actual editing process easier
+for me.
 
+~~~
 {
   'Overview
   'Obtaining-Retro
@@ -49,7 +44,6 @@
   'Programming-Techniques-Working-With-Pointers
   'Programming-Techniques-Working-With-Strings
   'Programming-Techniques-Writing-Combinators
-  'Programming-Techniques-Return-Stack
   'Programming-Techniques-Working-With-Assembly
   'Internals
   'Internals-Nga
@@ -61,5 +55,27 @@
   'Errors
   'Tech-Notes
   'Historical-Papers
-} process
+} 'TOC const
+~~~
+
+~~~
+'Out var
+
+:import        here swap BOOK-BASE s:prepend file:slurp ;
+:\n            ASCII:LF @Out file:write ;
+:add-to-book   here [ @Out file:write ] s:for-each \n ;
+:process-files [ import add-to-book ] array:for-each ;
+:open          'RETRO-Book.md file:open<for-writing> !Out ;
+:close         @Out file: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 ;
+
+TOC process
 ~~~