major touch-up into presentable form

[rrq/rrqforth.git] / adoc / p_read_stream_char.adoc

diff --git a/adoc/p_read_stream_char.adoc b/adoc/p_read_stream_char.adoc
index ba1579e2229182e8dfbf12d4d5281e5543b61486..1472c27aafae60c7e99affa001658fad3911cada 100644 (file)
--- a/adoc/p_read_stream_char.adoc
+++ b/adoc/p_read_stream_char.adoc
@@ -1,9 +1,18 @@
+// stdio.asm:  WORD p_read_stream_char,'READ-STREAM-CHAR',fasm
+
 anchor:p_read_stream_char[]
 
-Word: READ-STREAM-CHAR
-----------------------
+=== Word: READ-STREAM-CHAR
+
+....
+Data stack: ( stream -- c )
+....
 
-----
-stdio.asm:     WORD p_read_stream_char,'READ-STREAM-CHAR',fasm
-----
+"READ-STREAM-CHAR" is a function word that gets the next character
+from the given stream buffer, possibly refilling the buffer if it is
+backed by a file descriptor. The refill is done by a SYS_READ call
+when more characters are needed. The next character is pushed on the
+stack, unless the stream is exhausted in which case the -1 is pushed
+instead.
 
+See also <<p_stream,STREAM>>.