--- gforth/prim	2006/03/11 23:05:09	1.191
+++ gforth/prim	2006/04/09 08:24:47	1.193
@@ -1646,31 +1646,43 @@ n=1;
 
 \g hostos
 
-key-file	( wfileid -- n )		gforth	paren_key_file
+key-file	( wfileid -- c )		gforth	paren_key_file
+""Read one character @i{c} from @i{wfileid}.  This word disables
+buffering for @i{wfileid}.  If you want to read characters from a
+terminal in non-canonical (raw) mode, you have to put the terminal in
+non-canonical mode yourself (using the C interface); the exception is
+@code{stdin}: Gforth automatically puts it into non-canonical mode.""
 #ifdef HAS_FILE
 fflush(stdout);
-n = key((FILE*)wfileid);
+c = key((FILE*)wfileid);
 #else
-n = key(stdin);
+c = key(stdin);
 #endif
 
-key?-file	( wfileid -- n )	        gforth	key_q_file
+key?-file	( wfileid -- f )	        gforth	key_q_file
+""@i{f} is true if at least one character can be read from @i{wfileid}
+without blocking.  If you also want to use @code{read-file} or
+@code{read-line} on the file, you have to call @code{key?-file} or
+@code{key-file} first (these two words disable buffering).""
 #ifdef HAS_FILE
 fflush(stdout);
-n = key_query((FILE*)wfileid);
+f = key_query((FILE*)wfileid);
 #else
-n = key_query(stdin);
+f = key_query(stdin);
 #endif
 
 \+os
 
 stdin	( -- wfileid )	gforth
+""The standard input file of the Gforth process.""
 wfileid = (Cell)stdin;
 
 stdout	( -- wfileid )	gforth
+""The standard output file of the Gforth process.""
 wfileid = (Cell)stdout;
 
 stderr	( -- wfileid )	gforth
+""The standard error output file of the Gforth process.""
 wfileid = (Cell)stderr;
 
 form	( -- urows ucols )	gforth