--- gforth/blocks.fs	1999/11/08 22:01:07	1.27
+++ gforth/blocks.fs	2000/08/17 12:46:57	1.30
@@ -45,7 +45,15 @@ Variable last-block
 $20 Value buffers
 
 User block-fid
-User offset   0 offset !  \ store 1 here fore 0.4.0 compatibility
+User block-offset ( -- addr ) \ gforth
+\G User variable containing the number of the first block (default
+\G since 0.5.0: 0).  Block files created with Gforth versions before
+\G 0.5.0 have the offset 1.  If you use these files you can: @code{1
+\G offset !}; or add 1 to every block number used; or prepend 1024
+\G characters to the file.
+0 block-offset !  \ store 1 here fore 0.4.0 compatibility
+
+' block-offset alias offset \ !! eliminate this?
 
 : block-cold ( -- )
     block-fid off  last-block off
@@ -91,7 +99,7 @@ Defer flush-blocks ( -- ) \ gforth
     offset @ - chars/block chars um* get-block-fid reposition-file throw ;
 
 : update ( -- ) \ block
-    \G Mark the current block buffer as dirty.
+    \G Mark the state of the current block buffer as assigned-dirty.
     last-block @ ?dup IF  buffer-dirty on  THEN ;
 
 : save-buffer ( buffer -- ) \ gforth
@@ -109,7 +117,7 @@ Defer flush-blocks ( -- ) \ gforth
 
 : save-buffers  ( -- ) \ block
     \G Transfer the contents of each @code{update}d block buffer to
-    \G mass storage, then mark all block buffers as unassigned.
+    \G mass storage, then mark all block buffers as assigned-clean.
     block-buffers @
     buffers 0 ?DO dup save-buffer next-buffer LOOP drop ;
 
@@ -131,7 +139,7 @@ Defer flush-blocks ( -- ) \ gforth
 : get-buffer ( u -- a-addr ) \ gforth
     0 buffers um/mod drop buffer-struct %size * block-buffers @ + ;
 
-: block ( u -- a-addr ) \ block- block
+: block ( u -- a-addr ) \ gforthman- block
     \G If a block buffer is assigned for block @i{u}, return its
     \G start address, @i{a-addr}. Otherwise, assign a block buffer
     \G for block @i{u} (if the assigned block buffer has been
@@ -168,7 +176,7 @@ Defer flush-blocks ( -- ) \ gforth
     \ reading in the block is unnecessary, but simpler
     block ;
 
-User scr ( -- a-addr ) \ block-ext
+User scr ( -- a-addr ) \ block-ext s-c-r
     \G @code{User} variable -- @i{a-addr} is the address of a cell containing
     \G the block number of the block most recently processed by
     \G @code{list}.
@@ -176,7 +184,8 @@ User scr ( -- a-addr ) \ block-ext
 
 \ nac31Mar1999 moved "scr @" to list to make the stack comment correct
 : updated?  ( n -- f ) \ gforth
-    \G Return true if block @i{n} has been marked as dirty.
+    \G Return true if @code{updated} has been used to mark block @i{n}
+    \G as assigned-dirty.
     buffer
     [ 0 buffer-dirty 0 block-buffer - ] Literal + @ ;
 
@@ -225,7 +234,7 @@ User scr ( -- a-addr ) \ block-ext
     \G current block + @i{n1} thru the current block + @i{n2}.
     1+ swap ?DO  I +load  LOOP ;
 
-: --> ( -- ) \ gforth- gforth chain
+: --> ( -- ) \ gforthman- gforth chain
     \G If this symbol is encountered whilst loading block @i{n},
     \G discard the remainder of the block and load block @i{n+1}. Used
     \G for chaining multiple blocks together as a single loadable