--- gforth/blocks.fs	1999/02/03 00:10:19	1.21
+++ gforth/blocks.fs	1999/03/29 22:52:27	1.23
@@ -58,7 +58,7 @@ block-cold
 Defer flush-blocks
 
 : open-blocks ( addr u -- ) \ gforth
-    \g use the file, whose name is given by @var{addr u}, as blocks file 
+    \g Use the file, whose name is given by @var{addr u}, as the blocks file.
     2dup open-fpath-file 0<>
     if
 	r/w bin create-file throw
@@ -70,7 +70,7 @@ Defer flush-blocks
     block-fid ! ;
 
 : use ( "file" -- ) \ gforth
-    \g use @var{file} as blocks file
+    \g Use @var{file} as the blocks file.
     name open-blocks ;
 
 \ the file is opened as binary file, since it either will contain text
@@ -83,7 +83,7 @@ Defer flush-blocks
     block-fid @ ;
 
 : block-position ( u -- ) \ block
-    \G Position the block file to the start of block u.
+    \G Position the block file to the start of block @var{u}.
     1- chars/block chars um* get-block-fid reposition-file throw ;
 
 : update ( -- ) \ block
@@ -120,9 +120,9 @@ Defer flush-blocks
     buffers mod buffer-struct %size * block-buffers @ + ;
 
 : block ( u -- a-addr ) \ block- block
-  \G u identifies a block number. Assign a block buffer to u,
+  \G @var{u} identifies a block number. Assign a block buffer to @var{u},
   \G make it the current block buffer and return its start
-  \G address, a-addr.
+  \G address, @var{a-addr}.
     dup 0= -35 and throw
     dup get-buffer >r
     dup r@ buffer-block @ <>
@@ -145,7 +145,7 @@ Defer flush-blocks
     block ;
 
 User scr ( -- a-addr ) \ block-ext
-    \G USER VARIABLE a-addr is the address of a cell containing
+    \G USER VARIABLE @var{a-addr} is the address of a cell containing
     \G the block number of the block most recently processed by
     \G @code{LIST}.
     0 scr !
@@ -165,13 +165,15 @@ User scr ( -- a-addr ) \ block-ext
 	i 2 .r space scr @ block i 64 * chars + 64 type cr
     loop ;
 
-: (source)  ( -- addr len )
+: (source)  ( -- c-addr u )
   blk @ ?dup
   IF    block chars/block
   ELSE  tib #tib @
   THEN ;
 
-' (source) IS source
+' (source) IS source ( -- c-addr u ) \ core
+\G @var{c-addr} is the address of the input buffer and @var{u} is the
+\G number of characters in it.
 
 : load ( i*x n -- j*x ) \ block
   push-file