embed stack comments in various library/ files

FossilOrigin-Name: b4679cff7215b99fa283ced0915a0411dddc6c8bbaa808d54a02c141c2ff59fb

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/termina.retro

@@ -2,19 +2,19 @@
 #74 'ti:width  var-n
 #21 'ti:height var-n
 
-:vt:esc (-) #27 c:put ;
-:vt:csi (-) vt:esc $[ c:put ;
+:vt:esc (:-) #27 c:put ;
+:vt:csi (:-) vt:esc $[ c:put ;
 
-:vt:home  (-) vt:csi $H c:put ;
-:vt:row,col (nn-) vt:csi swap n:put $; c:put n:put $H c:put ;
-:vt:up    (-) vt:csi n:put $A c:put ;
-:vt:down  (-) vt:csi n:put $B c:put ;
-:vt:right (-) vt:csi n:put $C c:put ;
-:vt:left  (-) vt:csi n:put $D c:put ;
-:vt:clear (-) vt:csi '2J s:put ;
+:vt:home  (:-) vt:csi $H c:put ;
+:vt:row,col (:nn-) vt:csi swap n:put $; c:put n:put $H c:put ;
+:vt:up    (:-) vt:csi n:put $A c:put ;
+:vt:down  (:-) vt:csi n:put $B c:put ;
+:vt:right (:-) vt:csi n:put $C c:put ;
+:vt:left  (:-) vt:csi n:put $D c:put ;
+:vt:clear (:-) vt:csi '2J s:put ;
 :vt:reset vt:csi '0m s:put ;
 
-:vt:set/color (n-) vt:csi '1;34; s:put n:put $m c:put ;
+:vt:set/color (:n-) vt:csi '1;34; s:put n:put $m c:put ;
 
 :fg:black   #30 vt:set/color ;  :bg:black   #40 vt:set/color ;
 :fg:red     #31 vt:set/color ;  :bg:red     #41 vt:set/color ;
@@ -27,17 +27,17 @@
 
 'ti:Actions d:create #128 comma #128 allot
 
-:ti:set-action (qc-) &ti:Actions swap a:store ;
+:ti:set-action (:qc-) &ti:Actions swap a:store ;
 
-:ti:reset-actions (-)
+:ti:reset-actions (:-)
   #128 [ #0 I ti:set-action ] indexed-times ;
 
-:ti:get-action (c-q) &ti:Actions swap a:fetch ;
+:ti:get-action (:c-q) &ti:Actions swap a:fetch ;
 
-:ti:perform-action (c-)
+:ti:perform-action (:c-)
   ti:get-action dup n:-zero? &call &drop choose ;
 
-:ti:input (-) c:get ti:perform-action ;
+:ti:input (:-) c:get ti:perform-action ;
 
 {{
  'ti:Hints d:create #130 allot :empty  (-s)  '____________ ;
@@ -49,9 +49,9 @@
                   dup n:put sp start s:put sp ;
  :clean     (-)   '_ s:temp constrain pad I start #13 copy ;
 ---reveal---
- :ti:add-hint (sn-)
+ :ti:add-hint (:sn-)
    #13 n:mul &ti:Hints n:add [ constrain pad ] dip #13 copy ;
- :ti:reset-hints (-) #10 &clean indexed-times ;
+ :ti:reset-hints (:-) #10 &clean indexed-times ;
  :ti:hints  #10 [ display I #4 eq? &nl if ] indexed-times ;
 }}
 
@@ -59,22 +59,22 @@
 
 &ti:display/none 'ti:Display var-n
 
-:ti:set-display (a-) !ti:Display ;
+:ti:set-display (:a-) !ti:Display ;
 
-:ti:reset-display (-) &ti:display/none ti:set-display ;
+:ti:reset-display (:-) &ti:display/none ti:set-display ;
 
-:ti:display (-)
+:ti:display (:-)
   vt:home @ti:Display call
   @ti:height #3 n:sub #0 vt:row,col @ti:width [ $- c:put ] times
   nl ti:hints nl ;
 
 'ti:ptrs d:create #0 comma #5 allot
-:ti:add-program (a-) &ti:ptrs v:inc &ti:ptrs @ti:ptrs a:store ;
-:ti:current (-a) &ti:ptrs @ti:ptrs a:fetch ;
-:ti:more? (-f) @ti:ptrs n:-zero? ;
+:ti:add-program (:a-) &ti:ptrs v:inc &ti:ptrs @ti:ptrs a:store ;
+:ti:current (:-a) &ti:ptrs @ti:ptrs a:fetch ;
+:ti:more? (:-f) @ti:ptrs n:-zero? ;
 :ti:remove &ti:ptrs v:dec ;
 
-:ti:load (-)
+:ti:load (:-)
   ti:current call
   !ti:Display ti:reset-hints call ti:reset-actions call ;
 
@@ -82,10 +82,10 @@
 :ti:done #-1 !ti:Done vt:reset nl ;
 :ti:done? @ti:Done ;
 
-:ti:application/run (-)
+:ti:application/run (:-)
   [ #0 !ti:Done ti:display ti:input ti:done? ] until
   ti:remove ti:more? [ ti:load #0 !ti:Done ] if ;
 
-:ti:application (q-)
+:ti:application (:q-)
   ti:add-program ti:load ti:application/run ;
 ~~~

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

library/x11.retro

@@ -1,29 +1,29 @@
 ~~~
-:pixel (xyc-)     #33 io:scan-for io:invoke ;
-:get-pixel (xy-c) #34 io:scan-for io:invoke ;
-:mouse (-xyb)     #35 io:scan-for io:invoke ;
+:pixel (:xyc-)     #33 io:scan-for io:invoke ;
+:get-pixel (:xy-c) #34 io:scan-for io:invoke ;
+:mouse (:-xyb)     #35 io:scan-for io:invoke ;
 
-:hline (xyw-)
+:hline (:xyw-)
   [ dup-pair #1 pixel &n:inc dip ] times drop-pair ;
 
-:vline (xyh-)
+:vline (:xyh-)
   [ dup-pair #1 pixel n:inc ] times drop-pair ;
 
-:dline\ (xyl-)
+:dline\ (:xyl-)
   [ dup-pair #1 pixel &n:inc bi@ ] times drop-pair ;
 
-:dline/ (xyl-)
+:dline/ (:xyl-)
   [ dup-pair #1 pixel &n:dec &n:inc bi* ] times drop-pair ;
 
 'X var 'Y var 'H var 'W var
 
-:rect (xyhw-) !W !H !Y !X
+:rect (:xyhw-) !W !H !Y !X
   @X @Y @W hline   @X @Y @H n:add @W hline
   @X @Y @H vline   @X @W n:add @Y @H vline ;
 
 'XC var 'YC var 'X var 'Y var
 
-:octant (xc,yc,x,y)
+:octant (:xc,yc,x,y)
   !Y !X !YC !XC
   @XC @X n:add @YC @Y n:add #1 pixel
   @XC @X n:sub @YC @Y n:add #1 pixel
@@ -36,7 +36,7 @@
 
 'XC var 'YC var 'X var 'Y var 'D var 'R var
 
-:circle (xyr-)
+:circle (:xyr-)
   !R !YC !XC  #0 !X  @R [ !Y ] [ !D ] bi
   @XC @YC @X @Y octant
   [ &X v:inc
@@ -55,8 +55,8 @@
 :t:right [ &X v:inc ] !D ;
 :t:up [ &Y v:dec ] !D ;
 :t:down [ &Y v:inc ] !D ;
-:t:at (xy-) !Y !X ;
-:t:forward (n-) [ @X @Y @C pixel @D call ] times ;
+:t:at (:xy-) !Y !X ;
+:t:forward (:n-) [ @X @Y @C pixel @D call ] times ;
 
 #320 #240 t:at t:lower t:right