better documentation

diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc
index ba94b0f3f7abadf97db4013aaba77123e5909f6a..1d9ffdb50d5ef343ce1bab5ecb0a51b7466e71d4 100644 (file)
--- a/adoc/p_literal_string.adoc
+++ b/adoc/p_literal_string.adoc
@@ -1,21 +1,22 @@
-//compile.asm: WORD p_literal_string,'S"',fasm ;; " (fool emacs)
+//compile.asm: WORD p_literal_string,'LIT-STRING',fasm
 
 anchor:p_literal_string[]
 
-=== Word: S"
+=== Word: LIT-STRING
 
 ....
 Data stack: ( -- chars* n )
 ....
 
-"S"" is a function word that pushes the [n:char] pointer for a string
-inlined subsequently to it in the containing definition. This is
-similar to <<p_lit,LIT>> but for a string literal.
+"LIT-STRING" is a function word that pushes the char* and length n of
+a subsequent inline string, then advances execution to continue after
+the string. This is similar to <<p_lit,LIT>> but for a block literal.
+
+Note that the inlined byte count includes the terminating NUL byte.
 
 ====
-.Definition concept for LIT
+.Definition concept for LIT-STRING
 ****
-: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
+: LIT-STRING  R@ DUP @ 8 +  R@ @  2DUP + R> + >R  1 - ;
 ****
 ====
-

diff --git a/adoc/p_literal_string_compile.adoc b/adoc/p_literal_string_compile.adoc
new file mode 100644 (file)
index 0000000..23b3c79
--- /dev/null
+++ b/adoc/p_literal_string_compile.adoc
@@ -0,0 +1,18 @@
+//compile.asm: WORD p_literal_string_compile,'S"',fasm ;; " (fool emacs)
+
+anchor:p_literal_string_compile[]
+
+=== Word: S"
+
+....
+Data stack: ( -- )  Input stream: " chars" 
+....
+
+"S"" is an immediate function word that compiles the subseqent
+characters up to terminating double-quote into the current definition,
+preceded by a <<p_literal_string,LIT-STRING>> cell, and the count of
+bytes scanned. The inline text includes a terminating NUL character
+which also is included in the inlined count.
+
+Note that "S"" uses <<p_double_quote,">> for reading the string.
+

diff --git a/adoc/p_semicolon.adoc b/adoc/p_semicolon.adoc
index c16e147357d5b94484d02ae89a6da10f63305fde..0caf2f53faae77ca8180a3257564679b6e470969 100644 (file)
--- a/adoc/p_semicolon.adoc
+++ b/adoc/p_semicolon.adoc
@@ -9,8 +9,9 @@ anchor:p_semicolon[]
 Data stack: ( -- )
 ....
 
-";" (semi-colon) is a function word that ends a new forth definition
-by means of adding an <<p_exit,EXIT>>
+";" (semi-colon) is an immediate function word that ends a new forth
+definition by means of adding an <<p_exit,EXIT>> cell, then changing
+<<p_state,STATE> to interpreting.
 
 ====
 .Definition concept for ;

diff --git a/adoc/p_str2temp.adoc b/adoc/p_str2temp.adoc
new file mode 100644 (file)
index 0000000..5415d5e
--- /dev/null
+++ b/adoc/p_str2temp.adoc
@@ -0,0 +1,24 @@
+// temp.asm:   WORD p_str2temp,'STR>TEMP'
+
+anchor:p_str2temp[]
+
+=== Word: STR>TEMP
+
+****
+Data stack: ( char* n -- char* n )
+****
+
+"STR>TEMP" is a function word that copies a given string plus a
+terminating NUL character into a <<p_tempspace,TEMPSPACE>> snippet,
+all preceded by a length cell. It returns a pointer for to the text in
+the snippet and its length, excluding the NUL character at end and the
+length cell before tie text.
+
+.copied string
+[caption='Layout for ']
+----
+        length: 8 bytes
+returned char*: n bytes 
+           nul: 1 byte
+----
+

diff --git a/adoc/p_temp.adoc b/adoc/p_temp.adoc
new file mode 100644 (file)
index 0000000..b928dd3
--- /dev/null
+++ b/adoc/p_temp.adoc
@@ -0,0 +1,21 @@
+// temp.asm:   WORD p_temp,'TEMP',fasm
+
+anchor:p_temp[]
+
+=== Word: TEMP
+
+****
+Data stack: ( size -- addr )
+****
+
+"TEMP" is a function word that "allocates" a <<p_tempspace,TEMPSPACE>>
+area of given size and returns its base address. The allocation is
+temporary and only valid until there is a later allocation that
+overruns this area.
+
+Allocations are done in succession until the requested size overruns
+the <<p_tempspace,TEMPSPACE>>. If so, the allocation pointer is reset
+and the space is allocated from start again. This is all intended for
+small and short-lived data areas.
+
+

diff --git a/adoc/p_tempspace.adoc b/adoc/p_tempspace.adoc
new file mode 100644 (file)
index 0000000..2afa2b4
--- /dev/null
+++ b/adoc/p_tempspace.adoc
@@ -0,0 +1,23 @@
+// temp.asm:   WORD p_tempspace,'TEMPSPACE',dovariable
+
+
+anchor:p_tempspace[]
+
+=== Word: TEMPSPACE
+
+....
+Data stack: ( -- a )
+....
+
+"TEMPSPACE" is a variable word that holds three cells the for managing
+"temporary memory":
+
+ * the size of the temporary memory space (default 104857600 bytes)
+ * the base address for whole temporary memory area
+ * the amount currently used
+ 
+This memory is intended to be used by requesting snippets of memory in
+a cyclic fashion via <<p_temp,TEMP>> without concern about it possibly
+overlapping a prior request.
+
+

diff --git a/reference.adoc b/reference.adoc
index e9e369f6ed7fe1a8207f94904b9efa9c1b72e165..7f1100eeb6a75bbe8f30ff95a22da0f8a1e8ab86 100644 (file)
--- a/reference.adoc
+++ b/reference.adoc
@@ -177,6 +177,8 @@ include::adoc/p_literal.adoc[]
 include::separator.adoc[]
 include::adoc/p_literal_string.adoc[]
 include::separator.adoc[]
+include::adoc/p_literal_string_compile.adoc[]
+include::separator.adoc[]
 include::adoc/p_load_buffer_size.adoc[]
 include::separator.adoc[]
 include::adoc/p_load_file.adoc[]
@@ -259,6 +261,8 @@ include::adoc/p_stream.adoc[]
 include::separator.adoc[]
 include::adoc/p_stream_nchars.adoc[]
 include::separator.adoc[]
+include::adoc/p_str2temp.adoc[]
+include::separator.adoc[]
 include::adoc/p_strlen.adoc[]
 include::separator.adoc[]
 include::adoc/p_strncmp.adoc[]
@@ -271,6 +275,10 @@ include::adoc/p_system.adoc[]
 include::separator.adoc[]
 include::adoc/p_tell.adoc[]
 include::separator.adoc[]
+include::adoc/p_temp.adoc[]
+include::separator.adoc[]
+include::adoc/p_tempspace.adoc[]
+include::separator.adoc[]
 include::adoc/p_terminate0.adoc[]
 include::separator.adoc[]
 include::adoc/p_tfa2cfa.adoc[]

diff --git a/wordindex.adoc b/wordindex.adoc
index 66d0ae8ab58ef8ee0c4bb65b3a93fc3e0dc7f68f..f849eb790574e8664d18fe0f49e2da68c69b7140 100644 (file)
--- a/wordindex.adoc
+++ b/wordindex.adoc
@@ -39,7 +39,7 @@ xref:p_put_plus[!{plus}] {nbsp}
 xref:p_get_n_increment[@n{plus}{plus}] {nbsp}
 xref:p_get_n_decrement[@n--] {nbsp}
 xref:p_Ccomma[C,] {nbsp}
-xref:p_literal_string[S"] {nbsp}
+xref:p_literal_string_compile[S"] {nbsp}
 xref:p_gtR[>R] {nbsp}
 xref:p_Rget[R@] {nbsp}
 xref:p_Rgt[R>] {nbsp}
@@ -113,6 +113,7 @@ xref:p_immediate[IMMEDIATE] {nbsp}
 xref:p_input[INPUT] {nbsp}
 
 xref:p_literal[LIT] {nbsp}
+xref:p_literal_string[LIT-STRING] {nbsp}
 xref:p_load_buffer_size[LOAD-BUFFER-SIZE] {nbsp}
 xref:p_load_file[LOAD-FILE] {nbsp}
 
@@ -148,6 +149,7 @@ xref:p_state[STATE] {nbsp}
 xref:p_stdin[STDIN] {nbsp}
 xref:p_stream[STREAM] {nbsp}
 xref:p_stream_nchars[STREAM-NCHARS] {nbsp}
+xref:p_str2temp[STR>TEMP] {nbsp}
 xref:p_strlen[STRLEN] {nbsp}
 xref:p_strncmp[STRNCMP] {nbsp}
 xref:p_strncpy[STRNCPY] {nbsp}
@@ -156,6 +158,8 @@ xref:p_system[SYSTEM] {nbsp}
 
 xref:p_tell[TELL] {nbsp}
 xref:p_dot_temp[.TEMP] {nbsp}
+xref:p_temp.adoc[TEMP] {nbsp}
+xref:p_tempspace[TEMPSPACE] {nbsp}
 xref:p_terminate0[TERMINATE0] {nbsp}
 xref:p_tfa2cfa[TFA>CFA] {nbsp}
 xref:p_tfa2dfa[TFA>DFA] {nbsp}