embed stack comments in various library/ files

FossilOrigin-Name: fa9205cf084acd917af13e72a932f0133285215b2f163299dbd3dc76128ab68d

RELEASE-NOTES

@@ -57,6 +57,7 @@
     i/o extension
     - adds "openbsd:pledge"
     - adds "openbsd:unveil"
+  - remove "describe.retro"
 
 - retro-compiler
 

library/block-editor.retro

@@ -15,8 +15,8 @@ This begins by using these to implement the `block:load` and
 ~~~
 'ilo.blocks block:set-file
 
-:block:load block:read ;
-:block:save block:write ;
+:block:load (:na-) block:read ;
+:block:save (:na-) block:write ;
 ~~~
 
 In Konilo, the memory is constrained to 65,536 cells, with a
@@ -37,14 +37,17 @@ are provided. Alter the `Blocks` count to match your actual
 data store limits.
 
 ~~~
-'Block var
-#128 'Blocks var-n
+'Block var (:-a)
+'Variable;_current_block_number add-description
+
+#128 'Blocks var-n (:-a)
+'Variable;_number_of_blocks_in_block_store add-description
 ~~~
 
 `e:line` displays a line from the block buffer.
 
 ~~~
-:e:line (n-)
+:e:line (:n-)
   #64 n:mul block:buffer n:add
   #64 [ fetch-next c:put ] times drop nl ;
 ~~~
@@ -63,9 +66,9 @@ data store limits.
   :block# 'Editing_# s:put @Block n:put
           '_of_ s:put @Blocks n:dec n:put nl ;
 ---reveal---
-  :list* nl #16 [ I e:line ] indexed-times ;
-  :list# nl lines ;
-  :list  nl sep lines sep block# ;
+  :list* (:-) nl #16 [ I e:line ] indexed-times ;
+  :list# (:-) nl lines ;
+  :list  (:-) nl sep lines sep block# ;
 }}
 ~~~
 
@@ -88,13 +91,13 @@ blocks.
 {{
   :constrain @Block #0 @Blocks n:dec n:limit !Block ;
 ---reveal---
-  :set  &Block store constrain ;
-  :save &Block fetch block:buffer block:save ;
-  :load &Block fetch block:buffer block:load ;
-  :next &Block v:inc constrain load ;
-  :prev &Block v:dec constrain load ;
-  :new  block:buffer #1024 [ #32 swap store-next ] times drop ;
-  :edit set load @e:Display call ;
+  :set  (:n-) &Block store constrain ;
+  :save (:-) &Block fetch block:buffer block:save ;
+  :load (:-) &Block fetch block:buffer block:load ;
+  :next (:-) &Block v:inc constrain load ;
+  :prev (:-) &Block v:dec constrain load ;
+  :new  (:-) block:buffer #1024 [ #32 swap store-next ] times drop ;
+  :edit (:n-) set load @e:Display call ;
 }}
 ~~~
 
@@ -160,7 +163,7 @@ arrays.
     &set-input &count-words bi
     [ parse-word valid? [ a:to-string interpret ] &drop choose ] times ;
 ---reveal---
-  :run &block:buffer n:dec #1024 over store s:evaluate ;
+  :run (:-) &block:buffer n:dec #1024 over store s:evaluate ;
 }}
 ~~~
 
@@ -172,9 +175,9 @@ arrays.
     +-------+-----+--------------------------------------------+
 
 ~~~
-:use (block) set load run ;
+:use (:block) set load run ;
 
-:using (first,last)
+:using (:first,last)
   over n:sub swap set load run [ next run ] times ;
 ~~~
 
@@ -192,7 +195,7 @@ space.
   :save &Block fetch ;
   :restore &Block store load ;
 ---reveal---
-  :titles save setup @Blocks &describe indexed-times restore ;
+  :titles (:-) save setup @Blocks &describe indexed-times restore ;
 }}
 ~~~
 
@@ -219,7 +222,7 @@ but not:
   :actual block:buffer n:dec dup #32 a:index a:left a:to-string ;
   :code?  block:buffer fetch $( eq? ;
 ---reveal---
-  :needs (s-)
+  :needs (:s-)
     @Hash [ @Block swap
       s:hash !Hash
       @Blocks [ I set load reset code?

library/c-get-ext.retro

@@ -1,10 +1,10 @@
 ~~~
-:keys:UP    #-300 ;
-:keys:DOWN  #-301 ;
-:keys:RIGHT #-302 ;
-:keys:LEFT  #-303 ;
+:keys:UP    (:-n) #-300 ;
+:keys:DOWN  (:-n) #-301 ;
+:keys:RIGHT (:-n) #-302 ;
+:keys:LEFT  (:-n) #-303 ;
 
-:c:get/ext (-c)
+:c:get/ext (:-c)
   c:get dup #27 eq?
   [ drop c:get drop c:get #235 + n:negate ] if ;
 ~~~

library/describe.retro

@@ -1,7 +0,0 @@
-This adds a `describe` word which runs retro-describe(1). It's
-a useful tool for looking up glossay data in an interactive
-session.
-
-~~~
-:describe (s-) 'retro-describe_%s s:format unix:system ;
-~~~

library/konilo.retro

@@ -17,12 +17,12 @@ placed in the `n:` namespace. (In Konilo, these are the standard
 names for these).
 
 ~~~
-:n:add    + ;
-:n:sub    - ;
-:n:mul    * ;
-:n:div    / ;
-:n:mod    mod ;
-:n:divmod /mod ;
+:n:add    (:nn-n) + ;
+:n:sub    (:nn-n) - ;
+:n:mul    (:nn-n) * ;
+:n:div    (:nn-nn) / ;
+:n:mod    (:nn-n) mod ;
+:n:divmod (:nn-n) /mod ;
 
-:comma    , ;
+:comma    (:n-) , ;
 ~~~

library/tob.retro

@@ -58,14 +58,14 @@ them for an 80x25 display.
   #13  [ #0 !TX &TY v:inc ] case
   &TOB TOB:W @TY n:mul n:add @TX n:add store &TX v:inc ;
 
-:tob:put (c-) handle advance-cursor ;
+:tob:put (:c-) handle advance-cursor ;
 
 :tob:display
   &TOB TOB:H [ TOB:W [ fetch-next c:put ] times nl ] times drop ;
 
-:tob:with (q-) &tob:put &c:put set-hook call &c:put unhook ;
+:tob:with (:q-) &tob:put &c:put set-hook call &c:put unhook ;
 
-:tob:clear (-)
+:tob:clear (:-)
   TOB:W TOB:H n:mul [ #32 tob:put ] times #0 !TX #0 !TY ;
 
 tob:clear