major touch-up into presentable form

diff --git a/adoc/data_stack.adoc b/adoc/data_stack.adoc
index 0055cfed3e66d4fadf323e8fcf1717b0550da665..3d536a9f346617ebabca0e2e3403b0aeea046797 100644 (file)
--- a/adoc/data_stack.adoc
+++ b/adoc/data_stack.adoc
@@ -1,9 +1,11 @@
+// rrqforth.asm:       WORD data_stack,'DATA-STACK',dovariable
+

 anchor:data_stack
 
 anchor:data_stack
 

-Word: DATA-STACK
-----------------
+=== Word: DATA-STACK

 
 

-----
-rrqforth.asm:  WORD data_stack,'DATA-STACK',dovariable
-----
+....
+Data stack: ( -- a )
+....

 
 

+"DATA-STACK" is a variable word that harbours the data stack.

diff --git a/adoc/inline_code.adoc b/adoc/inline_code.adoc
index 91bb246ed899fc8bb63c12b5660ffa992a77666c..b1a9c46097bc2b63704d873631aa6e25201a0db0 100644 (file)
--- a/adoc/inline_code.adoc
+++ b/adoc/inline_code.adoc
@@ -1,11 +1,22 @@
+// rrqforth.asm:       WORD inline_code,'[ASM]',fasm
+

 anchor:inline_code[]
 
 anchor:inline_code[]
 

-Word: [ASM]
-----------
+=== Word: [ASM]

 
 

-----
-rrqforth.asm:  WORD inline_code,'[ASM]',fasm
-----
+....
+data stack: ( -- )
+....

 
 

-"[ASM]" is a function word that introduces inlined assembly.
+"[ASM]" is a function word that introduces inline assembly in an
+RRQFORTH definition. Such assembly code may return to subsequence
+RRQFORTH executon by means of the following instruction sequence:

 
 

+====
+----
+       mov rsi,forthcode
+       lodsq
+       jmp qword [rax]
+forthcode:
+----
+====

diff --git a/adoc/p_0branch.adoc b/adoc/p_0branch.adoc
index 16c69c0249c115ab3cddd90a70a5b8f1b1107db7..4f396c3b82e5d3f08b2f3f2a537f45d9827515d2 100644 (file)
--- a/adoc/p_0branch.adoc
+++ b/adoc/p_0branch.adoc
@@ -1,9 +1,16 @@
+// rrqforth.asm:       WORD p_zero_branch,'0BRANCH',fasm
+

 anchor:p_zero_branch[]
 
 anchor:p_zero_branch[]
 

-Word: 0BRANCH
--------------
+=== Word: 0BRANCH
+
+....
+Data stack: ( v -- )
+....

 
 

-----
-rrqforth.asm:  WORD p_zero_branch,'0BRANCH',fasm
-----
+"0BRANCH" is a function word that implements execution conditional by
+means of optionally adding the subsequent branch offset, or not, to
+the point of execution. If the value, is 0 then the branch offset is
+added, and otherwise execution continues with the cell following the
+branch offset in the definition.

 
 

diff --git a/adoc/p_0equal.adoc b/adoc/p_0equal.adoc
index 63980d4b338782703cb3c1ada8eb65346a2870d5..827c0f1e206857c1c65924e8c3e519a5b41a3971 100644 (file)
--- a/adoc/p_0equal.adoc
+++ b/adoc/p_0equal.adoc
@@ -1,9 +1,16 @@
+// logic.asm:  WORD p_0equal, '0=',fasm
+

 anchor:p_0equal[]
 
 anchor:p_0equal[]
 

-Word: 0=
-----------
+=== Word: 0=
+
+....
+Data stack: ( v -- 0/-1 )
+....
+

 
 

-----
-logic.asm:     WORD p_0equal, '0=',fasm
-----
+"0=" is a function word that replaces a value with its logical
+complement; the result is zero if the value non-zero, and the result
+is non-zero if the value is zero.

 
 

+Compare with <<p_not,NOT>>.

diff --git a/adoc/p_0less.adoc b/adoc/p_0less.adoc
index 6ce109cc4c100550f9913ebc94dd0cc4c06f3027..b068b636a74dcc129892d99642ee3f42745da8b2 100644 (file)
--- a/adoc/p_0less.adoc
+++ b/adoc/p_0less.adoc
@@ -1,9 +1,23 @@
+// logic.asm:  WORD p_0less, '0<',fasm
+

 anchor:p_0less[]
 
 anchor:p_0less[]
 

-Word: 0<
-----------
+=== Word: 0<
+
+....
+Data stack: ( v -- 0/-1 )
+....
+
+"0<" is a function word that replaces a value with -1 if the value is
+less than 0, and 0 otherwise.

 
 

+====
+.Word: 0<
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-logic.asm:     WORD p_0less, '0<',fasm
+: 0= 0 SWAP < ;

 ----
 ----

+====

 
 

+See also <<p_swap,SWAP>> and
+<<p_lessthan,<>>.

diff --git a/adoc/p_2drop.adoc b/adoc/p_2drop.adoc
index 4d5942fdfbd6ddb8f54f643c0082e8a64ef577bd..92d1b6f9820ea6a007dd844c953ac43643c1bd78 100644 (file)
--- a/adoc/p_2drop.adoc
+++ b/adoc/p_2drop.adoc
@@ -1,9 +1,12 @@
+// stack.asm:  WORD p_2drop, '2DROP',fasm
+

 anchor:p_2drop[]
 
 anchor:p_2drop[]
 

-Word: 2DROP
-----------
+=== Word: 2DROP

 
 

-----
-stack.asm:     WORD p_2drop, '2DROP',fasm
-----
+....
+Data stack: ( v1 v2 -- )
+....

 
 

+"2DROP" is a function word that plainly discards the top 2 cells from
+the data stack.

diff --git a/adoc/p_2dup.adoc b/adoc/p_2dup.adoc
index 17c000554b060b20fa661e41c7ddb956c491e383..0b39b0853f948ed029a7c3887d3d04dc6fbf0b94 100644 (file)
--- a/adoc/p_2dup.adoc
+++ b/adoc/p_2dup.adoc
@@ -1,9 +1,20 @@
+// stack.asm:  WORD p_2dup, '2DUP',fasm
+

 anchor:p_2dup[]
 
 anchor:p_2dup[]
 

-Word: 2DUP
-----------
+=== Word: 2DUP
+
+....
+Data stack: ( v1 v2 -- v1 v2 v1 v2 )
+....

 
 

+"2DUP" is a function word that duplicates the top 2 cells on the data
+stack.
+
+====
+.Word: 2DUP
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-stack.asm:     WORD p_2dup, '2DUP',fasm
+: 2DUP OVER OVER ;

 ----
 ----

-
+====

diff --git a/adoc/p_2over.adoc b/adoc/p_2over.adoc
index 772d238b86f7ead92b75303b2ed1e688da0b0e37..058bfdd0216af138231f67850522eb8b11b0f1a4 100644 (file)
--- a/adoc/p_2over.adoc
+++ b/adoc/p_2over.adoc
@@ -1,9 +1,22 @@
+// stack.asm:  WORD p_2over, '2OVER',fasm
+

 anchor:p_2over[]
 
 anchor:p_2over[]
 

-Word: 2OVER
-----------
+=== Word: 2OVER
+
+....
+Data stack: ( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 )
+....
+
+"2OVER" is a function word that replicates the second duble-cell pair
+onto the top of the data stack. This is similar to <<p_over,OVER>> but
+working with cell pairs rather than single cells.

 
 

+====
+.Word: 2OVER
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-stack.asm:     WORD p_2over, '2OVER',fasm
+: 2OVER 3 PICK 3 PICK ;

 ----
 ----

+====

 
 

diff --git a/adoc/p_2swap.adoc b/adoc/p_2swap.adoc
index 7b0694caf8cb7f68bb4d67730a0d8632f243e689..6c123cfad61406bd5549c66dae164c4e224c9308 100644 (file)
--- a/adoc/p_2swap.adoc
+++ b/adoc/p_2swap.adoc
@@ -1,9 +1,21 @@
+// stack.asm:  WORD p_2swap, '2SWAP',fasm
+

 anchor:p_2swap[]
 
 anchor:p_2swap[]
 

-Word: 2SWAP
-----------
+=== Word: 2SWAP
+
+....
+Data stack: ( v1 v2 v3 v4 -- v3 v4 v1 v2 )
+....

 
 

+"2SWAP" is a function word the reorgnizes the top 4 cells swappping
+the upper and lower pair. This is similar to <<p_swap,SWAP>> but
+working with cell pairs rather than single cells.
+
+====
+.Word: 2SWAP
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-stack.asm:     WORD p_2swap, '2SWAP',fasm
+: 2SWAP 3 ROLL 3 ROOL ;

 ----
 ----

-
+====

diff --git a/adoc/p_Ccomma.adoc b/adoc/p_Ccomma.adoc
index 0cb190077909cdc9ca30ee902f55d0674bec0029..a0b07cd9771604e11d0f100400162b362d91d35e 100644 (file)
--- a/adoc/p_Ccomma.adoc
+++ b/adoc/p_Ccomma.adoc
@@ -1,20 +1,25 @@
-Word: C,
---------
+// compile.asm:        WORD p_Ccomma,'C,',fasm
+

 anchor:p_Ccomma[]
 anchor:p_Ccomma[]

-----
-compile.asm:   WORD p_Ccomma,'C,',fasm
-----

 
 

+=== Word: C,
+
+
+....

 Data stack: ( v -- )
 Data stack: ( v -- )

+....

 
 

-"C," is a function word that puts a byte on the heap. It stores the
-least significant byte of the value to the current free heap address,
-and increments that.
+"C," (C-comma) is a function word that puts a byte on the
+<<p_here,HERE>> heap. The least significant byte of the value is put
+at the current free head address, which also is incremented.

 
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: C,
-  HERE @ 1 ALLOT C! ( v -- ; Claim 1 byte and put lsb value there )
-;
+.Word: C,
+[caption='Definition concept {counter:exec}: ']
+----
+: C, HERE @ 1 ALLOT C! ;  ( v -- ; Claim 1 byte and put lsb value there )
+----

 ====
 
 ====
 

+See also <<p_colon,:>>, <<p_comma>>. <<p_here,HERE>>, <<p_get,@>>,
+<<p_allot,ALLOT>>, <<p_Cput,C!>> and <<p_semicolon,;>>.

diff --git a/adoc/p_Rget.adoc b/adoc/p_Rget.adoc
index 8eb5f6da8803a3bf9515fa6039b1f9a3516a4c01..236e2ee478053ecdc2cb4b4c33ba6f4bbadd1bfc 100644 (file)
--- a/adoc/p_Rget.adoc
+++ b/adoc/p_Rget.adoc
@@ -1,8 +1,12 @@
+// stack.asm:  WORD p_Rget, 'R@',fasm
+

 anchor:p_Rget[]
 
 anchor:p_Rget[]
 

-Word: R@
---------
+=== Word: R@
+
+....
+Data stack: ( -- v )   Return stack: ( v -- v )
+....

 
 

-----
-stack.asm:     WORD p_Rget, 'R@',fasm
-----
+"R@" is a function word that "copies" the top return stack value onto
+the data stack.

diff --git a/adoc/p_Rgt.adoc b/adoc/p_Rgt.adoc
index 65fef542600f8e8c3923270d33444031fd1c9f2b..c3dcaee1bcdf794389a1e57307d9a2a18ba56cf4 100644 (file)
--- a/adoc/p_Rgt.adoc
+++ b/adoc/p_Rgt.adoc
@@ -1,9 +1,12 @@
+// stack.asm:  WORD p_Rgt, 'R>',fasm
+

 anchor:p_Rgt[]
 
 anchor:p_Rgt[]
 

-Word: R>
-----------
+=== Word: R>

 
 

-----
-stack.asm:     WORD p_Rgt, 'R>',fasm
-----
+....
+Data stack: ( -- v )   Return stack: ( v -- )
+....

 
 

+"R>" is a function word that "moves" the top return stack value onto
+the data stack.

diff --git a/adoc/p_abs.adoc b/adoc/p_abs.adoc
index 51726f2f01cb80af7a822b1cc2e2b97f17729aa6..8a9ed224ade52739c4ecbfaed8cceacd90dcfa4c 100644 (file)
--- a/adoc/p_abs.adoc
+++ b/adoc/p_abs.adoc
@@ -1,9 +1,12 @@
+// math.asm:   WORD p_abs, 'ABS',fasm
+

 anchor:p_abs[]
 
 anchor:p_abs[]
 

-Word: ABS
----------
+=== Word: ABS

 
 

-----
-math.asm:      WORD p_abs, 'ABS',fasm
-----
+....
+Data stack: ( v1 -- v2 )
+....

 
 

+"ABS" is a function word that replaces a value with its absolute
+value. To that end, the values are 64-bit signed integers.

diff --git a/adoc/p_allot.adoc b/adoc/p_allot.adoc
index cf6e3b9e1e27f553b3e021259ce77be2a31e127e..78440106c47e3047635324c63d9256882035d51b 100644 (file)
--- a/adoc/p_allot.adoc
+++ b/adoc/p_allot.adoc
@@ -1,26 +1,31 @@
+// compile.asm:        WORD p_allot,'ALLOT',fasm
+

 anchor:p_allot[]
 
 anchor:p_allot[]
 

-Word: ALLOT
------------
-
-----
-compile.asm:   WORD p_allot,'ALLOT',fasm
-----
+=== Word: ALLOT

 
 

+....

 Data stack: ( n -- )
 Data stack: ( n -- )

+....

 
 

-"ALLOT" is a function word that merely increments the "HERE" variable
-with +n+ so as to claim that amount of the allocation space.
+"ALLOT" is a function word that merely increments the <<p_here,HERE>>
+variable with +n+ so as to claim that amount of the heap.

 
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: ALLOT
-  HERE @ + HERE !
-;
+.Word: ALLOT
+[caption='Defintion concept {counter:exec}: ']
+----
+: ALLOT HERE @ + HERE ! ;
+----

 ====
 
 ====
 

-.Usage example

 ====
 ====

+.Usage example
+****

 HERE @ 16 ALLOT ( -- p ; Claiming 16 bytes )
 HERE @ 16 ALLOT ( -- p ; Claiming 16 bytes )

+****

 ====
 
 ====
 

+See also <<p_colon,:>>, <<p_here,HERE>>, <<p_get,@>>, <<p_plus,+>>,
+<<p_put,!>> and <<p_semicolon,;>>.
+

diff --git a/adoc/p_and.adoc b/adoc/p_and.adoc
index ec2f20e40a7fc738dc258f46eb4af01903f96aef..11a3d1c1b343c47920cd6c9c2149da6625e59785 100644 (file)
--- a/adoc/p_and.adoc
+++ b/adoc/p_and.adoc
@@ -1,9 +1,15 @@
+// logic.asm:  WORD p_and, 'AND',fasm
+

 anchor:p_and[]
 
 anchor:p_and[]
 

-Word: AND
-----------
+=== Word: AND
+
+....
+Data stack: ( v1 v2 -- v3 )
+....
+
+"AND" is a function word that replaces a value pair with their bitwise
+conjunction; each bit is 1 if the corresponding bits of both operands
+are 1 and 0 if not.

 
 

-----
-logic.asm:     WORD p_and, 'AND',fasm
-----

 
 

diff --git a/adoc/p_args.adoc b/adoc/p_args.adoc
index 7575bd1565d669c5d1e5419c2826909da8647f14..a003e7af438f67f2519975b67158213463046936 100644 (file)
--- a/adoc/p_args.adoc
+++ b/adoc/p_args.adoc
@@ -1,9 +1,15 @@
+//rrqforth.asm:        WORD p_args,'ARGS',dostring
+

 anchor:p_args[]
 
 anchor:p_args[]
 

-Word: ARGS
-----------
+=== Word: ARGS
+
+....
+Data stack: ( -- argv** argc )
+....

 
 

-----
-rrqforth.asm:  WORD p_args,'ARGS',dostring
-----
+"ARGS" is a value word that results in pusing the command line
+argument block. Here argc is the length of the block, and argv** is a
+pointer to a data block of that many asciiz pointers, which are the
+command line arguments given to RRQFORTH at start.

 
 

diff --git a/adoc/p_base.adoc b/adoc/p_base.adoc
index 43c2e9e52c21a4e6be374843d72774e56516817c..a8748b71fdb63ef957ba9c5d89418df388477b68 100644 (file)
--- a/adoc/p_base.adoc
+++ b/adoc/p_base.adoc
@@ -1,8 +1,19 @@
-Word: BASE
-----------
+// compile.asm: WORD p_base,'BASE',dovariable

 
 anchor:p_base[]
 
 anchor:p_base[]

-----
-compile.asm:   WORD p_base,'BASE',dovariable
-----

 
 

+=== Word: BASE
+
+....
+Data stack: ( -- a )
+....
+
+"BASE" is a variable word for the numerical base used by input and
+output functions, <<p_number,NUMBER>> and <<p_dot>>, when
+translating numbers between cell value form and text form. The
+numerical base is set to 10 or 16 by <<p_decimal,DECIMAL>> and
+<<p_hex,HEX>> respectively, and those are the only two bases currently
+supported.
+
+See also <<p_digits,DIGITS>>, which holds the mapping table from
+digits to text.

diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc
index b555fd6cc2c1d6b2baf3ae80222d4e6735bd52bf..9e4d0d27c0fe5bc672899cd70b87ae538861f9f8 100644 (file)
--- a/adoc/p_branch.adoc
+++ b/adoc/p_branch.adoc
@@ -1,9 +1,13 @@
+// rrqforth.asm:       WORD p_branch,'BRANCH',fasm
+

 anchor:p_branch[]
 
 anchor:p_branch[]
 

-Word: BRANCH
-----------
+=== Word: BRANCH

 
 

-----
-rrqforth.asm:  WORD p_branch,'BRANCH',fasm
-----
+....
+Data stack: ( -- )
+....

 
 

+"BRANCH" is a function word that implements execution transfer by
+means of adding the subsequent branch offset to the point of
+execution.

diff --git a/adoc/p_clear_stream.adoc b/adoc/p_clear_stream.adoc
index 7672daf7150616850265b0ac17389d7c6470446b..5ecd9fad993e28e1939a5b912887e1b80a347519 100644 (file)
--- a/adoc/p_clear_stream.adoc
+++ b/adoc/p_clear_stream.adoc
@@ -1,9 +1,15 @@
+// stdio.asm:  WORD p_clear_stream,'CLEAR-STREAM',fasm
+

 anchor:p_clear_stream[]
 
 anchor:p_clear_stream[]
 

-Word: CLEAR-STREAM
-------------------
+=== Word: CLEAR-STREAM
+
+....
+Data stack: ( stream -- )
+....

 
 

-----
-stdio.asm:     WORD p_clear_stream,'CLEAR-STREAM',fasm
-----
+"CLEAR-STREAM" is a function word that discards whatever is currently
+remaining in the buffer for the stream, so that a subsequent read will
+pull in more data from its source.

 
 

+See also <<p_read_stream_char,READ-STREAM-CHAR>>.

diff --git a/adoc/p_colon.adoc b/adoc/p_colon.adoc
index 2fb446b8ccb939bf2e9820466b519a55bb872167..3a5acecd2ec6695b980c14b449dd32279b5f4044 100644 (file)
--- a/adoc/p_colon.adoc
+++ b/adoc/p_colon.adoc
@@ -1,8 +1,26 @@
-anchor:p_evaluate_stream[]
+// compile.asm:        WORD p_colon[],':'

 
 

-Word: :
--------
+anchor:p_colon[]

 
 

+=== Word: :
+
+
+....
+Data stack: ( -- )    Input stream: word
+....
+
+":" (colon) is a function word that starts a new forth definition.
+This includes reading the next word for making a new dictionary entry
+and setting evaluation state to compiling mode.
+
+====
+.Word: :
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-compile.asm:   WORD p_colon[],':'
+: : doFORTH READ-WORD CREATE TFA>CFA ! ] ;

 ----
 ----

+====
+
+See also <<p_doforth,doFORTH>>, <<p_read_word,READ-WORD>>,
+<<p_create,CREATE>>, <<p_tfa2cfa,TFA>CFA>>, <<p_put,!>>,
+<<p_left_bracket,]>> and <<p_semicolon,;>>.

diff --git a/adoc/p_comma.adoc b/adoc/p_comma.adoc
index cca9e0b218b9dc076577967266890fcda19b513f..ae000355431e11c80fcf157eb4944029f20d4ac1 100644 (file)
--- a/adoc/p_comma.adoc
+++ b/adoc/p_comma.adoc
@@ -1,19 +1,24 @@
-Word: ,
--------
+// compile.asm:        WORD p_comma,',',fasm
+

 anchor:p_comma[]
 anchor:p_comma[]

-----
-compile.asm:   WORD p_comma,',',fasm
-----

 
 

+=== Word: ,
+
+
+....

 Data stack: ( v -- )
 Data stack: ( v -- )

+....

 
 

-"," is a function word that puts a cell on the heap.
+"," (comma) is a function word that puts a cell value on the
+<<p_here,HERE>> heap.

 
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: ,
-  HERE @ 8 ALLOT ! ( v -- ; Claim 8 bytes and put value there )
-;
+.Word: ,
+[caption='Definition concept{counter:exec}: ']
+----
+: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )
+----

 ====
 
 ====
 

-
+See also <<p_colon,:>>, <<p_Ccomma>>. <<p_here,HERE>>, <<p_get,@>>,
+<<p_allot,ALLOT>>, <<p_put,!>> and <<p_semicolon,;>>.

diff --git a/adoc/p_create.adoc b/adoc/p_create.adoc
index dc6926a9cd441240e65fe13284e89d3611649644..cf8914e7b9afb27f0315a414e8f36a50e693aade 100644 (file)
--- a/adoc/p_create.adoc
+++ b/adoc/p_create.adoc
@@ -1,13 +1,13 @@
+// compile.asm:        WORD p_create,'CREATE',fasm
+

 anchor:p_create[]
 
 anchor:p_create[]
 

-Word: CREATE
-------------
+=== Word: CREATE

 
 

-----
-compile.asm:   WORD p_create,'CREATE',fasm
-----

 
 

+....

 Data stack: ( char* n -- tfa )
 Data stack: ( char* n -- tfa )

+....

 
 "CREATE" is a function word that allocates a "word header" with the
 indicated [n:char*] print name, and returns the "TFA" (Token Field
 
 "CREATE" is a function word that allocates a "word header" with the
 indicated [n:char*] print name, and returns the "TFA" (Token Field


@@ -41,11 +41,10 @@ its DFA when executed. This is changed to "doforth" for RRQFORTH
 function words initiated by ":" (aka "COLON") or changed to "dovalue"
 for RRQFORTH constants created by "CONSTANT".
 
 function words initiated by ":" (aka "COLON") or changed to "dovalue"
 for RRQFORTH constants created by "CONSTANT".
 

-See "<<p_execute,EXECUTE>>" about range of +doer+ assignments and
-their meanings.
-
-.Execution semantics expressed in RRQFORTH

 ====
 ====

+.Word: CREATE
+[caption='Definition concept {counter:exec}: ']
+----

 HERE @ R> ( save tfa on RS )
   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
   DUP 49 + R@ + ,             ( pCFA )
 HERE @ R> ( save tfa on RS )
   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
   DUP 49 + R@ + ,             ( pCFA )


@@ -53,15 +52,19 @@ HERE @ R> ( save tfa on RS )
   DUP , ( length )
   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
   R@ ,                        ( pTFA )
   DUP , ( length )
   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
   R@ ,                        ( pTFA )

-  0,                          ( OFF )
+  0 ,                         ( OFF )

   doVARIABLE                  ( CFA, default semantics )
   doVARIABLE                  ( CFA, default semantics )

+----

 ====
 
 ====
 

-.Usage example
-====
-\ A possible definition of the word CONSTANT
-: CONSTANT
-  READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! !
-;
-====
+.Usage example: a possible definition of CONSTANT
+****
+: CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
+****

 
 

+See also <<p_put,!>>, <<p_plus,+>>, <<p_comma>>, <<p_get,@>>,
+<<p_Ccomma>>, <<p_current_word,CURRENT-WORD>>, <<p_dup,DUP>>,
+<<p_here,HERE>>, <<p_herememcpy,HERE>>, <<p_Rget,R@>>, <<p_rot,ROT>>,
+and <<p_dovariable,doVARIABLE>>,
+as well as <<p_execute,EXECUTE>>
+about the range of "doer" assignments and their meanings.

diff --git a/adoc/p_current_wordlist.adoc b/adoc/p_current_wordlist.adoc
index 340cabd73fb4cc349ed752469600846af6497407..6f086a6adb539e318e7d7e7dac5d8db798d2a8dd 100644 (file)
--- a/adoc/p_current_wordlist.adoc
+++ b/adoc/p_current_wordlist.adoc
@@ -1,9 +1,25 @@
+// wordlists.asm:      WORD p_wordlist,'CURRENT-WORDLIST',dovariable
+

 anchor:p_wordlist[]
 
 anchor:p_wordlist[]
 

-Word: CURRENT-WORDLIST
-----------------------
+=== Word: CURRENT-WORDLIST
+....
+Data stack: ( -- a )
+....

 
 

+"CURRENT-WORDLIST" is a variable word that points out the DFA of the
+current word list word for <<p_find,FIND>> to use finding words. The
+word list word content is as follows:
+====
+.word list word content
+[caption='Layout {counter:layout}: ']

 ----
 ----

-wordlists.asm: WORD p_wordlist,'CURRENT-WORDLIST',dovariable
+  8 TFA of latest word in the word list
+  8 DFA of the/a subsequent word list to search through

 ----
 ----

+====
+
+Note that word lists are chained by "extension" and in general it ends
+with the <<p_forth,FORTH>> word list. Initially the
+<<p_system,SYSTEM>> word list is the only other word list.

 
 

diff --git a/adoc/p_decimal.adoc b/adoc/p_decimal.adoc
index df737ee72a4bb5417652bd3e43cb1894e28311bc..b06e5f25fc4a6e9b089921594effd88b38dfef86 100644 (file)
--- a/adoc/p_decimal.adoc
+++ b/adoc/p_decimal.adoc
@@ -1,8 +1,20 @@
-Word: DECIMAL
--------------
+// compile.asm:        WORD p_decimal,'DECIMAL',fasm

 
 anchor:p_decimal[]
 
 anchor:p_decimal[]

+
+=== Word: DECIMAL
+
+
+....
+Data stack: ( -- )
+....
+
+"DECIMAL" is a function word that sets <<p_base,BASE>> to 10.
+
+====
+.Word: DECIMAL
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-compile.asm:   WORD p_decimal,'DECIMAL',fasm
+: DECIMAL 10 BASE ! ;

 ----
 ----

-
+====

diff --git a/adoc/p_depth.adoc b/adoc/p_depth.adoc
index 8a92b1308719b3f001fb2bb9a3b2587a92217dee..6b6c0cdeb5a93ce2c327fe4601968d658110cbfe 100644 (file)
--- a/adoc/p_depth.adoc
+++ b/adoc/p_depth.adoc
@@ -1,9 +1,12 @@
+// stack.asm:  WORD p_depth,'DEPTH',fasm
+

 anchor:p_depth[]
 
 anchor:p_depth[]
 

-Word: DEPTH
-----------
+=== Word: DEPTH

 
 

-----
-stack.asm:     WORD p_depth,'DEPTH',fasm
-----
+....
+Data stack: ( -- v )
+....

 
 

+"DEPTH" is a function word that pushes the count of data stack cells
+onto the data stack.

diff --git a/adoc/p_digits.adoc b/adoc/p_digits.adoc
index 3bbfdf455906b92c1dfb544122eec422245614d0..4c3d8a1bbad6a7293faeaa7353647607547aa64b 100644 (file)
--- a/adoc/p_digits.adoc
+++ b/adoc/p_digits.adoc
@@ -1,9 +1,12 @@
+// stdio.asm:  WORD p_digits,'DIGITS',dovariable
+

 anchor:p_digits[]
 
 anchor:p_digits[]
 

-Word: DIGITS
-------------
+=== Word: DIGITS

 
 

-----
-stdio.asm:     WORD p_digits,'DIGITS',dovariable
-----
+....
+Data stack: ( -- a )
+....

 
 

+"DIGITS" is a variable word that holds the character array for mapping
+digit values to characters. It contains the 16 characters 0-9 and a-f.

diff --git a/adoc/p_divmod.adoc b/adoc/p_divmod.adoc
index bae6cbb0ef3fbfcea4324228057e743950004920..5e8f2a9034005d846e7a946556ceede4a1ea0f40 100644 (file)
--- a/adoc/p_divmod.adoc
+++ b/adoc/p_divmod.adoc
@@ -1,9 +1,21 @@
+// math.asm:   WORD p_divmod,'/MOD',fasm
+

 anchor:p_divmod[]
 
 anchor:p_divmod[]
 

-Word: /MOD
-----------
+=== Word: /MOD
+
+....
+Data stack: ( v1 v2 -- q r )
+....
+
+"/MOD" (div-mod) is a function word that replaces a pair of values
+with the results of signed integer division of the first, v1, divided
+by the scond, v2. To that end, the values are 64-bit signed integers.
+The result is the integer quotient, q, and the remainder, r, where q
+and r are the respectively largest and smallest integers to satisfy
+the formula:
+....
+       v1 = q * v2 + r
+....

 
 

-----
-math.asm:      WORD p_divmod,'/MOD',fasm
-----

 
 

diff --git a/adoc/p_dodoes.adoc b/adoc/p_dodoes.adoc
index 19319f53e2d9c655b213c95bb08617b138f159d5..9a1c320141fe814dba501773db06d351b4682cba 100644 (file)
--- a/adoc/p_dodoes.adoc
+++ b/adoc/p_dodoes.adoc
@@ -1,9 +1,14 @@
+// rrqforth.asm:       WORD p_dodoes,'doDOES',dovariable
+

 anchor:p_dodoes[]
 
 anchor:p_dodoes[]
 

-Word: doDOES
-----------
+=== Word: doDOES

 
 

-----
-rrqforth.asm:  WORD p_dodoes,'doDOES',dovariable
-----
+....
+Data stack: ( -- a )
+....

 
 

+"doDOES" is a variable word whose value is the implementation of the
+<<p_does>> execution semantics. This is the same as
+<<p_doforth,doFORTH>> but it starts at an offset into the word
+concerned.

diff --git a/adoc/p_does.adoc b/adoc/p_does.adoc
index 6517157c5b91501c46b67bd937056767d12dc751..a9ac349c73fdf116ce13ae9bbf609a89fe0ebc0c 100644 (file)
--- a/adoc/p_does.adoc
+++ b/adoc/p_does.adoc
@@ -1,26 +1,49 @@
-WORD: DOES>
------------
+// compile.asm:        WORD p_does,'DOES>',fasm,IMMEDIATE
+

 anchor:p_does[]
 anchor:p_does[]

-----
-compile.asm:   WORD p_does,'DOES>',fasm,IMMEDIATE
-----

 
 

+=== WORD: DOES>
+
+....

 Data stack: ( -- )
 Data stack: ( -- )

+....

 
 "DOES>" is a function that in execution mode does nothing but in
 compilation mode it changes the execution semantics assignments for
 
 "DOES>" is a function that in execution mode does nothing but in
 compilation mode it changes the execution semantics assignments for

-the most recent word to use the "dodoes" sematics with adjustment
+the most recent word to use the +dodoes+ sematics with adjustment

 offset to the current heap address. I.e., the word being defined will
 have its execution start at whatever comes after "DOES>".
 
 offset to the current heap address. I.e., the word being defined will
 have its execution start at whatever comes after "DOES>".
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

+.Word: DOES>
+----

 : DOES> IMMEDIATE
 STATE @ != IF ( only for compilation mode )
   CURRENT-WORDLIST @ @ TFA>CFA    ( cfa of current word )
     doDOES OVER !                 ( set up doer )
     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset
 : DOES> IMMEDIATE
 STATE @ != IF ( only for compilation mode )
   CURRENT-WORDLIST @ @ TFA>CFA    ( cfa of current word )
     doDOES OVER !                 ( set up doer )
     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset

-THEN
+  THEN

 ;
 ;

+----

 ====
 
 ====
 

+See also
+<<p_put,!>>,
+<<p_unequal,!=>>,
+<<p_plus,+>>,
+<<p_minus,->>,
+<<p_semicolon,;>>,
+<<p_get,@>>,
+<<p_current_wordlist,CURRENT-WORDLIST>>,
+<<p_here,HERE>>,
+<<p_if,IF>>,
+<<p_immediate,IMMEDIATE>>,
+<<p_over,OVER>>,
+<<p_state,STATE>>,
+<<p_swap,SWAP>>,
+<<p_tfa2cfa,TFA>CFA>>,
+<<p_then,THEN>>,
+<<p_dodoes,doDOES>>,
+as well as  <<p_execute,EXECUTE>>
+about the range of "doer" assignments and their meanings.
+

diff --git a/adoc/p_dofasm.adoc b/adoc/p_dofasm.adoc
index 920a16c8f864eaeabfb07f390cfda0ccf1cb843c..31ec84eb52a8cdae9be52c6504854e8f92256728 100644 (file)
--- a/adoc/p_dofasm.adoc
+++ b/adoc/p_dofasm.adoc
@@ -1,9 +1,11 @@
-anchor:p_dofasm[]
+// rrqforth.asm:       WORD p_dofasm,'doFASM',dovariable

 
 

-Word: doFASM
-------------
+anchor:p_dofasm[]

 
 

-----
-rrqforth.asm:  WORD p_dofasm,'doFASM',dovariable
-----
+=== Word: doFASM
+....
+Data stack: ( -- a )
+....

 
 

+"doFASM" is a variable word whose value is the implementation of the
+execution semantics for assembly code content.

diff --git a/adoc/p_doforth.adoc b/adoc/p_doforth.adoc
index 8fa70ef88e56586f4ba99ff14c02f73d88f2ca01..0fd4d2f169ec512e58abc7e57150f550c1bef6c0 100644 (file)
--- a/adoc/p_doforth.adoc
+++ b/adoc/p_doforth.adoc
@@ -1,9 +1,13 @@
+// rrqforth.asm:       WORD p_doforth,'doFORTH',dovariable ;
+

 anchor:p_doforth[]
 
 anchor:p_doforth[]
 

-Word: doFORTH
--------------
+=== Word: doFORTH
+
+....
+Data stack: ( -- a )
+....

 
 

-----
-rrqforth.asm:  WORD p_doforth,'doFORTH',dovariable ;
-----
+"doFORTH" is a variable word whose value is the implementation of the
+RRQFORTH execution semantics.

 
 

diff --git a/adoc/p_dostring.adoc b/adoc/p_dostring.adoc
index 54725c166ed9a3a6f898c57008b25ba9fdf97dcd..3645b06921f0df1bd613f84a33a5830dfa2f0fc4 100644 (file)
--- a/adoc/p_dostring.adoc
+++ b/adoc/p_dostring.adoc
@@ -1,9 +1,26 @@
+// rrqforth.asm:       WORD p_dostring,'doSTRING',dovariable
+

 anchor:p_dostring[]
 
 anchor:p_dostring[]
 

-Word: doSTRING
---------------
+=== Word: doSTRING
+
+....
+Data stack: ( -- a )
+....
+
+"doFASM" is a variable word whose value is the implementation of the
+execution semantics for assembly code implemented words. In those
+cases the execution leads to the word content.
+
+The register context at entry to an assembly code implemented word is
+as follows:

 
 ----
 
 ----

-rrqforth.asm:  WORD p_dostring,'doSTRING',dovariable
+    rax = cfa* of word to execute
+    rsi = cell* in the calling definition, after calling cell
+    rsp = data stack pointer
+    rbp = return stack pointer

 ----
 
 ----
 

+The assembly code must ensure that +rsi+ is preserved and that +rsp+
+and +rbp+ are used according to their roles.

diff --git a/adoc/p_dot.adoc b/adoc/p_dot.adoc
index 621bee267d9b41e5952e98343d9dba46c061c2ba..1a884ed227f84544a6bad9500aabac4cadde4b68 100644 (file)
--- a/adoc/p_dot.adoc
+++ b/adoc/p_dot.adoc
@@ -1,14 +1,13 @@
-anchor:p_dot[]
+// stdio.asm:  WORD p_dot,'.',fasm

 
 

-Word: .
--------
+anchor:p_dot[]

 
 

-----
-stdio.asm:     WORD p_dot,'.',fasm
-----
+=== Word: .

 
 

+....

 Data stack: ( v -- )
 Data stack: ( v -- )

+....

 
 

-"." is a function word that prints the top stack value to stdout usonb
-<<p_base,BASE>> (either <<p_decimal,DECIMAL>> or <<p_hex,HEX>>).
-
+"." is a function word that prints the top stack value to stdout using
+the current <<p_base,BASE>> (either <<p_decimal,DECIMAL>> or
+<<p_hex,HEX>>).

diff --git a/adoc/p_double_quote.adoc b/adoc/p_double_quote.adoc
index 1c8e09ffa5df738e8ec855568448e6d9b18717ca..8568180c7f8f275e6ef47cdcb603f31a73733c44 100644 (file)
--- a/adoc/p_double_quote.adoc
+++ b/adoc/p_double_quote.adoc
@@ -1,9 +1,15 @@
+// stdio.asm:  WORD p_double_quote,'"',fasm ;; " (fool emacs)
+

 anchor:p_double_quote[]
 
 anchor:p_double_quote[]
 

-Word: "
--------
+=== Word: "
+....
+data stack: ( -- char n )    Input stream: ...."
+....
+
+""" (double quote) is a function word that copies the input stream
+text up to next double quote to <<p_pad,PAD>>, and returns the
+[n:char*] cell pair for that string.
+

 
 

-----
-stdio.asm:     WORD p_double_quote,'"',fasm ;; " (fool emacs)
-----

 
 

diff --git a/adoc/p_dovalue.adoc b/adoc/p_dovalue.adoc
index 1670131735ba68bfc8fcb513d4e181f0d1b804f9..696e9e5df7d73c9032de06761fcf37030308664f 100644 (file)
--- a/adoc/p_dovalue.adoc
+++ b/adoc/p_dovalue.adoc
@@ -1,9 +1,20 @@
+// rrqforth.asm:       WORD p_dovalue,'doVALUE',dovariable
+

 anchor:p_dovalue[]
 
 anchor:p_dovalue[]
 

-Word: doVALUE
--------------
+=== Word: doVALUE
+
+....
+Data stack: ( -- a )
+....
+
+"doVALUE" is a variable word whose value is the implementation of the
+execution semantics for cell values, which are variables with a single
+64-bit cell holding the value.
+
+The execution of this result in pushing the value:
+....
+Resulting data stack: ( -- v )
+....

 
 

-----
-rrqforth.asm:  WORD p_dovalue,'doVALUE',dovariable
-----

 
 

diff --git a/adoc/p_dovariable.adoc b/adoc/p_dovariable.adoc
index dd27a6ef363be9af2b1e520fb0faa516da6a095e..38c2c5e47e465f1fe248ae6194cd5a533d474b6c 100644 (file)
--- a/adoc/p_dovariable.adoc
+++ b/adoc/p_dovariable.adoc
@@ -1,9 +1,20 @@
+// rrqforth.asm:       WORD p_dovariable,'doVARIABLE',dovariable
+

 anchor:p_dovariable[]
 
 anchor:p_dovariable[]
 

-Word: doVARIABLE
-----------------
+=== Word: doVARIABLE
+
+....
+Data stack: ( -- a )
+....
+
+"doVARIABLE" is a variable word whose value is the implementation of
+the execution semantics for "variables", which basically are markers
+into the heap for some number block of memory.
+
+The execution of a variable results in pushing its content address:
+....
+Resulting data stack: ( -- a )
+....

 
 

-----
-rrqforth.asm:  WORD p_dovariable,'doVARIABLE',dovariable
-----

 
 

diff --git a/adoc/p_drop.adoc b/adoc/p_drop.adoc
index 123afdb50296af1a6a160ee33548dc2f1b96f605..fe0ec113449dd28a88aea06cb9a837b6d99fa860 100644 (file)
--- a/adoc/p_drop.adoc
+++ b/adoc/p_drop.adoc
@@ -1,9 +1,12 @@
+// stack.asm:  WORD p_drop, 'DROP',fasm
+

 anchor:p_drop[]
 
 anchor:p_drop[]
 

-Word: DROP
-----------
+=== Word: DROP
+
+....
+Data stack: ( v -- )
+....

 
 

-----
-stack.asm:     WORD p_drop, 'DROP',fasm
-----
+"DROP" is a function word that discards the top stack cell.

 
 

diff --git a/adoc/p_dup.adoc b/adoc/p_dup.adoc
index 8f2a8c4d29597daaffe7dbaf6b172b8e074fcf40..f8ac7f181cad76d8c4417bddc8e292c838940b80 100644 (file)
--- a/adoc/p_dup.adoc
+++ b/adoc/p_dup.adoc
@@ -1,9 +1,12 @@
+// stack.asm:  WORD p_dup, 'DUP',fasm
+

 anchor:p_dup[]
 
 anchor:p_dup[]
 

-Word: DUP
-----------
+=== Word: DUP
+
+....
+Data stack: ( v -- v v )
+....

 
 

-----
-stack.asm:     WORD p_dup, 'DUP',fasm
-----
+"DUP" is a function word that duplicates the top stack cell.

 
 

diff --git a/adoc/p_emit.adoc b/adoc/p_emit.adoc
index 26651f29e8aa723f40fa449315bf55a4202a6146..b20ecfc326e64fdedbb0dade919d433978f8d650 100644 (file)
--- a/adoc/p_emit.adoc
+++ b/adoc/p_emit.adoc
@@ -1,9 +1,14 @@
+// stdio.asm:  WORD p_emit,'EMIT',fasm
+

 anchor:p_emit[]
 
 anchor:p_emit[]
 

-Word: EMIT
-----------
+=== Word: EMIT
+
+....
+Data stack: ( c -- )
+....

 
 

-----
-stdio.asm:     WORD p_emit,'EMIT',fasm
-----
+"EMIT" is a function word that puts the given character code to
+standard output (file descriptor 1). The character is the least
+significant byte of the top cell.

 
 

diff --git a/adoc/p_equal.adoc b/adoc/p_equal.adoc
index d15a8e7a6953b94625c9b586bc98ee47a0b0e5d7..20829812cb192d1c8c138e5667bf49d3e83359e9 100644 (file)
--- a/adoc/p_equal.adoc
+++ b/adoc/p_equal.adoc
@@ -1,9 +1,12 @@
+// logic.asm:  WORD p_equal, '=',fasm
+

 anchor:p_equal[]
 
 anchor:p_equal[]
 

-Word: =
--------
+=== Word: =

 
 

-----
-logic.asm:     WORD p_equal, '=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+"=" is a function word that replaces a pair of values with -1 of the
+values are equal, and 0 otherwise.

diff --git a/adoc/p_evaluate_stream.adoc b/adoc/p_evaluate_stream.adoc
index aae56c437ef46057b96120a13b0d5b9c48120767..2a051af4b1f155e562fb1277d3aafdd212f67a28 100644 (file)
--- a/adoc/p_evaluate_stream.adoc
+++ b/adoc/p_evaluate_stream.adoc
@@ -1,11 +1,53 @@
-anchor:p_evaluate_stream[]
+// compile.asm:        WORD p_evaluate_stream,'EVALUATE-STREAM'

 
 

-Word: EVALUATE-STREAM
----------------------
+anchor::p_evaluate_stream[]

 
 

+=== Word: EVALUATE-STREAM
+
+....
+Data stack: ( stream -- ??? 0/1 )     Input stream: ......
+....
+
+"EVALUATE-STREAM" is a function word that reads words separated by
+whitespace from the stream until it discovers an unknown word, or the
+stream is exhausted. Depending on <<p_state,STATE>>, the words are
+either executed or compiled, and all ther stack and heap effects are
+preserved. "EVALUATE-STREAM" returns with an additional 0 or 1 on the
+stack to respectively indicate that the last word was unkown, i.e. not
+found (<<p_find,FIND>>) in the current word list
+(<<p_current_wordlist,CURRENT-WORDLIST>>) and not a
+<<p_number,NUMBER>> of the current <<p_base,BASE>>.
+
+Note that numbers in the current <<p_base,BASE>> are treated as known
+words that are parsed into cell values. If interpreting, then the
+value is left on the stack. If compiling, then the value is added to
+the heap subsequent to first adding <<p_literal,LIT>>, which is done
+so as to make that value be push to the data stack upon a later
+execution.
+
+In the <<p_decimal,DECIMAL>> base, the number word may begin with a
+minus sign.
+
+The words are read and executed one by one, accounting for whether its
+a number word or not, whether it is an <<p_immediate,IMMEDIATE>> word
+or not, and whether the state at the time of execution indicates
+"compiling" of "interpreting". Immediate words are executed in both
+interpreting and compiling state, while other words have their CFA get
+added to the heap so as to gain their execution effect upon a later
+execution.
+
+Note that "EVALUATE-STREAM" keeps the stream (pointer) on the return
+stack while reading, parsing and executing.
+
+If "EVALUATE-STREAM" ends with 0, then <<p_this_word,THIS-WORD>> holds
+the [n:chars] reference of the offending word in the stream buffer.
+
+====
+.Word: EVALUATE-STREAM
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-compile.asm:   WORD p_evaluate_stream,'EVALUATE-STREAM'
+( too complex to include here )

 ----
 ----

-
+====

 
 
 
 

diff --git a/adoc/p_execute.adoc b/adoc/p_execute.adoc
index 8197f0c3202fa499f0a432143d756d5e10f0d128..7b73566f0309e0dc7a928cb52d05f6eb9aaaa1b9 100644 (file)
--- a/adoc/p_execute.adoc
+++ b/adoc/p_execute.adoc
@@ -1,9 +1,38 @@
+// rrqforth.asm:       WORD p_execute,'EXECUTE',fasm
+

 anchor:p_execute[]
 
 anchor:p_execute[]
 

-Word: EXECUTE
--------------
+=== Word: EXECUTE
+
+....
+Data stack: ( cfa -- )
+....
+
+"EXECUTE" is a function word that transfers the execution to the
+indicated "Code Field Address", which typically is the CFA of an
+RRQFORTH word with the CFA cell containing a jump address for the code
+that implements the execution semnatics of the word.
+
+The following execution semantics are predefined:
+
+ * assembler implemented words constitute their own execution
+   semantics;
+   
+ * <<p_doforth>> implements the FORTH machine. This treats the word
+   content as a succession of cells that hold the cfa pointers for the
+   words that make of the definition. As is customary in FORTH
+   machines, the advance through that succession is provided by each
+   word code ending making an explicit jump to its successor. The
+   <<p_return_stack,RETURN-STACK>> serves as a call stack for tracking
+   the nesting of FORTH executions by saving the "addresses" of the
+   successor cells.
+
+ * <<p_dodoes>> implements the variation of starting the FORTH
+   execution somewhere within a definition rather than at the
+   beginning.

 
 

-----
-rrqforth.asm:  WORD p_execute,'EXECUTE',fasm
-----
+ * <<p_dostring>>, <<p_dovalue>> and <<p_dovariable>> implement
+   different common ways of using word content other the as FORTH
+   definitions.

 
 

+   

diff --git a/adoc/p_exit.adoc b/adoc/p_exit.adoc
index c1f4a909c55db5c4fadbbefa444a534c6f638ccc..1d9d78ad8a77156fc73012dc3ea92f7c7f192c16 100644 (file)
--- a/adoc/p_exit.adoc
+++ b/adoc/p_exit.adoc
@@ -1,9 +1,14 @@
+// rrqforth.asm:       WORD p_exit, 'EXIT',fasm
+

 anchor:p_exit[]
 
 anchor:p_exit[]
 

-Word: EXIT
-----------
+=== Word: EXIT
+
+....
+Data stack: ( -- )
+....

 
 

-----
-rrqforth.asm:  WORD p_exit, 'EXIT',fasm
-----
+"EXIT" is a function word that implements the ending of a FORTH
+definition and its threading to the subsequent step of the calling
+definition.

 
 

diff --git a/adoc/p_false.adoc b/adoc/p_false.adoc
index 467e45879ef5a594cf77a66dcdf3f2c29042026c..489082d621870a9d8573731287d5e324c1041b73 100644 (file)
--- a/adoc/p_false.adoc
+++ b/adoc/p_false.adoc
@@ -1,9 +1,11 @@
+// logic.asm:  WORD p_false, 'FALSE',dovalue
+

 anchor:p_false[]
 
 anchor:p_false[]
 

-Word: FALSE
-----------
+=== Word: FALSE

 
 

-----
-logic.asm:     WORD p_false, 'FALSE',fasm
-----
+....
+Data stack: ( -- 0 )
+....

 
 

+"FALSE" is a value word representing logical false.

diff --git a/adoc/p_find.adoc b/adoc/p_find.adoc
index c8f355c2d1c8528e689a396be8c448ed2e407063..01c4579148af95865c8ddb054c56188defadefa7 100644 (file)
--- a/adoc/p_find.adoc
+++ b/adoc/p_find.adoc
@@ -1,9 +1,22 @@
+// wordlists.asm:      WORD p_find,'FIND',fasm
+

 anchor:p_find[]
 
 anchor:p_find[]
 

-Word: FIND
-----------
+=== Word: FIND
+....
+Data stack: ( char* n -- [ char* n 0 ]/[ tfa ] )
+....
+
+"FIND" is a function word that searches the current word list search
+path for the given [n:char*] word, and returns the TFA of the matching
+word if any. Otherwise FIND preserves the initial data stack but adds
+0 to it.

 
 

-----
-wordlists.asm: WORD p_find,'FIND',fasm
-----
+The word is sought starting with the
+<<p_current_wordlist,CURRENT-WORDLIST>> word list, for the first
+occurence of a match. If not found, the search continues with the
+subsequent word list, and so on.

 
 

+When a word is found, then the data stack is changed by discarding the
+[n:char*] double cell string pointer and pushing (only) the TFA of the
+matching word instead.

diff --git a/adoc/p_forth.adoc b/adoc/p_forth.adoc
index 15c269566ce5c8dc39b3bb924775b58fbdfc8630..e76b2fbe4be99cdda5ee14444a1e4e286d55019a 100644 (file)
--- a/adoc/p_forth.adoc
+++ b/adoc/p_forth.adoc
@@ -1,9 +1,12 @@
+// wordlists.asm:      WORD p_forth,'FORTH',dovariable
+

 anchor:p_forth[]
 
 anchor:p_forth[]
 

-Word: FORTH
------------
+=== Word: FORTH
+....
+data stack: ( -- a )
+....

 
 

-----
-wordlists.asm: WORD p_forth,'FORTH',dovariable
-----
+"FORTH" is a variable word for the FORTH word list, which does not
+have any subsequent word list.

 
 

diff --git a/adoc/p_greaterequal.adoc b/adoc/p_greaterequal.adoc
index 8a11ab84838d3c546dc4bd970e8fec574699b691..e89cb8c278c6d1d47f5351ec72e3f5210071619b 100644 (file)
--- a/adoc/p_greaterequal.adoc
+++ b/adoc/p_greaterequal.adoc
@@ -1,9 +1,13 @@
+// logic.asm:  WORD p_greaterequal, '>=',fasm
+

 anchor:p_greaterequal[]
 
 anchor:p_greaterequal[]
 

-Word: >=
-----------
+=== Word: >=

 
 

-----
-logic.asm:     WORD p_greaterequal, '>=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+">=" is a function word that replaces a pair of values with -1 if the
+first, v1, is greater than or equal to the second, v1, otherwise 0. To
+that end, the values are 64-bit signed integers.

diff --git a/adoc/p_greaterthan.adoc b/adoc/p_greaterthan.adoc
index b35585936e6f439009cb778950f3ab7fedf16669..2975d00ffc2dc6a7245e1651a090931dd662ecc2 100644 (file)
--- a/adoc/p_greaterthan.adoc
+++ b/adoc/p_greaterthan.adoc
@@ -1,9 +1,13 @@
+// logic.asm:  WORD p_greaterthan, '>',fasm
+

 anchor:p_greaterthan[]
 
 anchor:p_greaterthan[]
 

-Word: >
--------
+=== Word: >

 
 

-----
-logic.asm:     WORD p_greaterthan, '>',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+">" is a function word that replaces a pair of values with -1 if the
+first, v1, is greater than the second, v1, otherwise 0. To that end,
+the values are 64-bit signed integers.

diff --git a/adoc/p_gtR.adoc b/adoc/p_gtR.adoc
new file mode 100644 (file)
index 0000000..c185ffb
--- /dev/null
+++ b/adoc/p_gtR.adoc
@@ -0,0 +1,12 @@
+// stack.asm:  WORD p_gtR, '>R',fasm
+
+anchor:p_gtR[]
+
+=== Word: >R
+
+....
+Data stack: ( v -- )   Return stack: ( -- v )
+....
+
+">R" is a function word that "moves" the top data stack value onto the
+return stack.

diff --git a/adoc/p_here.adoc b/adoc/p_here.adoc
index 116c817c34ba5281303a20b91e30d39f77cc4fb9..5a6c41609ffd4bdf8dbbe08622f609a0f8df809d 100644 (file)
--- a/adoc/p_here.adoc
+++ b/adoc/p_here.adoc
@@ -1,12 +1,20 @@
+// compile.asm:        WORD p_here,'HERE',dovariable
+

 anchor:p_here[]
 
 anchor:p_here[]
 

-Word: HERE
-----------
-----
-compile.asm:   WORD p_here,'HERE',dovariable
-----
+=== Word: HERE
+
+....
+Data stack: ( -- a )
+....

 
 "HERE" is a variable word that keeps the lowest address of the free
 
 "HERE" is a variable word that keeps the lowest address of the free

-allocation space. It get updated by all words that allocate space.
+allocation space. It get updated by all words that allocate memory.
+

 
 

+.Usage example
+****
+1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )
+****

 
 

+See also <<p_allot,ALLOT>>.

diff --git a/adoc/p_hex.adoc b/adoc/p_hex.adoc
index 4ea5b7b3de9bd0f0b0fb55e50128683883034cc1..35ef0ff4130a6fccf13ecbfe1096d526933f2e63 100644 (file)
--- a/adoc/p_hex.adoc
+++ b/adoc/p_hex.adoc
@@ -1,7 +1,21 @@
-Word: HEX
-----------
+// compile.asm:        WORD p_hex,'HEX',fasm
+

 anchor:p_hex[]
 anchor:p_hex[]

+
+=== Word: HEX
+
+....
+Data stack: ( -- )
+....
+
+"HEX" is a function word that sets <<p_base,BASE>> to 16, which uses
+letters a-f as additional digits. (Uppercase letter are also accepted
+on input).
+
+====
+.Word: HEX
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-compile.asm:   WORD p_hex,'HEX',fasm
+: HEX 16 BASE ! ;

 ----
 ----

-
+====

diff --git a/adoc/p_immediate.adoc b/adoc/p_immediate.adoc
new file mode 100644 (file)
index 0000000..4c4b613
--- /dev/null
+++ b/adoc/p_immediate.adoc
@@ -0,0 +1,25 @@
+// compile.asm:        WORD p_immediate,'IMMEDIATE',fasm,IMMEDIATE
+
+anchor::p_immediate[]
+
+=== Word: IMMEDIATE
+
+....
+Data stack: ( -- )
+....
+
+"IMMEDIATE" is an immediate function word that sets the flags field of
+the most recent word to 1, thereby making that word an immediate word.
+
+====
+.Word: IMMEDIATE
+[caption='Definition concept {counter:exec}:']
+----
+: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;
+----
+====
+
+See also <<p_colon,:>>, <<p_current_wordlist,CURRENT-WORDLIST>>,
+<<p_get,@>>, <<p_plus,+>>, <<p_put,!>>, and <<p_semicolon;>>.
+
+

diff --git a/adoc/p_left_bracket.adoc b/adoc/p_left_bracket.adoc
index 4907988231cc3f559fbde46a2553487bfaf1dae7..ead7d3bbe25cd90913b2eb3b55e2a92bb0abff8b 100644 (file)
--- a/adoc/p_left_bracket.adoc
+++ b/adoc/p_left_bracket.adoc
@@ -1,18 +1,22 @@
+// compile.asm:        WORD p_left_bracket,'[',fasm,IMMEDIATE
+

 anchor:p_left_bracket[]
 
 anchor:p_left_bracket[]
 

-Word: [
--------
+=== Word: [

 
 

-----
-compile.asm:   WORD p_left_bracket,'[',fasm,IMMEDIATE
-----
+....
+Data stack: ( -- )
+....

 
 

-"[" (left bracket) is function word that sets the stream evaluation
+"[" (left bracket) is a function word that sets the stream evaluation

 mode to be intepreting. In this mode, words are executed immediately
 after parsing, by invoking their "doer".
 
 mode to be intepreting. In this mode, words are executed immediately
 after parsing, by invoking their "doer".
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: [ IMMEDIATE 1 STATE ! ;
+.Word: [
+[caption='Definition concept {counter:exec}: ']
+----
+: [ IMMEDIATE 0 STATE ! ;
+----

 ====
 
 ====
 

diff --git a/adoc/p_lessequal.adoc b/adoc/p_lessequal.adoc
index 781c29c2ce7babb63bed224392138b04b8cdcd09..9bf7f3627280ad0ad86d34f074061a97fe9ec2af 100644 (file)
--- a/adoc/p_lessequal.adoc
+++ b/adoc/p_lessequal.adoc
@@ -1,9 +1,13 @@
+// logic.asm:  WORD p_lessequal, '<=',fasm
+

 anchor:p_lessequal[]
 
 anchor:p_lessequal[]
 

-Word: <=
-----------
+=== Word: \<=

 
 

-----
-logic.asm:     WORD p_lessequal, '<=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+"\<=" is a function word that replaces a pair of values with -1 if the
+first, v1, is less than or equal to the second, v1, otherwise 0. To
+that end, the values are 64-bit signed integers.

diff --git a/adoc/p_lessthan.adoc b/adoc/p_lessthan.adoc
index ce86406b0c355f2e50e4b5b67b559b5cc5b33115..99a0dff879351e8c9262669de39fd49f207d87d5 100644 (file)
--- a/adoc/p_lessthan.adoc
+++ b/adoc/p_lessthan.adoc
@@ -1,9 +1,13 @@
+// logic.asm:  WORD p_lessthan, '<',fasm
+

 anchor:p_lessthan[]
 
 anchor:p_lessthan[]
 

-Word: <
--------
+=== Word: <

 
 

-----
-logic.asm:     WORD p_lessthan, '<',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+"<" is a function word that replaces a pair of values with -1 if the
+first, v1, is less than the second, v1, otherwise 0. To that end, the
+values are 64-bit signed integers.

diff --git a/adoc/p_literal.adoc b/adoc/p_literal.adoc
index b469880fdeac41b629c6d6052e0b0a99cfdb020c..35d98da0d2fc69c244fe51752a29d9c868514763 100644 (file)
--- a/adoc/p_literal.adoc
+++ b/adoc/p_literal.adoc
@@ -1,30 +1,27 @@
-Word: LIT
----------
+// compile.asm:        WORD p_literal,'LIT',fasm

 
 anchor:p_literal[]
 
 anchor:p_literal[]

-----
-compile.asm:   WORD p_literal,'LIT',fasm
-----

 
 

-Data stack: compiling ( v -- ) interpreting ( -- v )
+=== Word: LIT

 
 

-"LIT" is a function word for, in compiling mode, creating a literal
-value the gets pushed in interpreting mode. In compiling mode, it a
-lays out its own CFA pointer, then grabs the current stack value onto
-the heap. In interpreting mode it recreates the value onto the stack.
+....
+Data stack: ( -- v )
+....

 
 

-Note that the value is layed out as if a subsequent CFA poitnter in
-the containing definition, but the LIT execution will make the
-execution skip past that and instead contine with the CFA pointer
-folling the value.
+"LIT" is a function word that pushes the cell subsequent and moves
+excution past that. The literal value is thus layed out as if a
+subsequent CFA pointer in the containing definition, and the LIT
+execution will make the execution skip past that and instead contine
+with the CFA pointer following the value.

 
 It's not a good idea to use "LIT" interactively.
 
 
 It's not a good idea to use "LIT" interactively.
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: LIT IMMEDIATE
-  STATE @ IF p_literal , ELSE R> DUP 8 + >R @ THEN
-;
+.Word: LIT
+[caption='Definition concept {counter:exec}: ']
+----
+: LIT R> DUP 8 + >R @ ;
+----

 ====
 
 
 ====
 
 

diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc
index 5eaaec5345809a36b6df3c5c9aa0ee0b64e3e57c..218f443e7bab945ce1bedf8550502cb890129a04 100644 (file)
--- a/adoc/p_literal_string.adoc
+++ b/adoc/p_literal_string.adoc
@@ -1,15 +1,23 @@
-Word: S"
-----------
+//compile.asm: WORD p_literal_string,'S"',fasm ;; " (fool emacs)

 
 anchor:p_literal_string[]
 
 anchor:p_literal_string[]

-----
-compile.asm:   WORD p_literal_string,'S"',fasm ;; " (fool emacs)
-----

 
 

-"S"" is a function word for, in compaling mode, creating a string
-literal whose pname ( char* n ) gets pushed in interpreting mode.
+=== Word: S"
+
+....
+Data stack: ( -- chars* n )
+....

 
 

-Similar to "LIT", "S"" will insert the string into the containing
-definition, and use it from there.
+"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.
+
+====
+.Word: LIT
+[caption='Definition concept {counter:exec}: ']
+----
+: LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
+----
+====

 
 
 
 

diff --git a/adoc/p_lparen.adoc b/adoc/p_lparen.adoc
new file mode 100644 (file)
index 0000000..027d3d4
--- /dev/null
+++ b/adoc/p_lparen.adoc
@@ -0,0 +1,12 @@
+// stdio.asm:  WORD p_lparen,'(',fasm,IMMEDIATE
+
+anchor:p_tell[]
+
+=== Word: (
+....
+Data stack: ( -- )
+....
+
+"(" (left parenthesis) is a function word that scans and ignores words
+until the next right parenthesis, or the end of the stream. This is
+used for comments in RRQFORTH code.

diff --git a/adoc/p_ltR.adoc b/adoc/p_ltR.adoc
deleted file mode 100644 (file)
index f3c1b56..0000000
--- a/adoc/p_ltR.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-anchor:p_ltR[]
-
-Word: >R
-----------
-
-----
-stack.asm:     WORD p_ltR, '>R',fasm
-----
-

diff --git a/adoc/p_malloc.adoc b/adoc/p_malloc.adoc
index f1dd8016b2bfb1a649025e612cc0bdd68496181f..4a86f0ba37b228aae0dd7c7ebdd7b51ae71bae52 100644 (file)
--- a/adoc/p_malloc.adoc
+++ b/adoc/p_malloc.adoc
@@ -1,9 +1,21 @@
+// stdio.asm:  WORD p_malloc,'MALLOC',fasm
+

 anchor:p_malloc[]
 
 anchor:p_malloc[]
 

-Word: MALLOC
-------------
+=== Word: MALLOC
+
+....
+Data stack: ( n -- a )
+....
+
+"MALLOC" is a word that allocates memory using mmap of at least n
+bytes and returns the lowest address of the allocated block.
+
+Note that this makes new page allocations for the process from the
+kernel, and the granularity is in pages, i.e. a multiple of 4 kb.

 
 

-----
-stdio.asm:     WORD p_malloc,'MALLOC',fasm
-----
+The memory is allocated with READ and WRITE access but not EXEC
+access, and flagged as PRIVATE, ANONYMOUS and LOCKED. See the "man
+page" of mmap for details.

 
 

+See also <<p_stream,STREAM>>

diff --git a/adoc/p_minus.adoc b/adoc/p_minus.adoc
index 629c926c671505df75bb5d0b332d6d7076789b8a..fddf23ab9bf4225acd38815443971a8fb45fc050 100644 (file)
--- a/adoc/p_minus.adoc
+++ b/adoc/p_minus.adoc
@@ -1,9 +1,13 @@
+// math.asm:   WORD p_minus, '-',fasm
+

 anchor:p_minus[]
 
 anchor:p_minus[]
 

-Word: -
--------
+=== Word: -

 
 

-----
-math.asm:      WORD p_minus, '-',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....

 
 

+"-" (minus) is a function word that replaces a pair of values with the
+result of reducing the first, v1, with the second, v2. To that end,
+the values are 64-bit signed integers.

diff --git a/adoc/p_mult.adoc b/adoc/p_mult.adoc
index 5689d8a85e0d49d9af43cf3d04317f06a322f9ca..083321f765a441eb0725cb68d31bc85346f3f167 100644 (file)
--- a/adoc/p_mult.adoc
+++ b/adoc/p_mult.adoc
@@ -1,9 +1,13 @@
+// math.asm:   WORD p_mult, '*',fasm
+

 anchor:p_mult[]
 
 anchor:p_mult[]
 

-Word: *
--------
+=== Word: *

 
 

-----
-math.asm:      WORD p_mult, '*',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....

 
 

+"*" is a function word that replaces a pair of values with the result
+of multiplying them. To that end, the values are 64-bit signed
+integers, and clipping the result to the least signifcant 64 bits.

diff --git a/adoc/p_negate.adoc b/adoc/p_negate.adoc
index b47e603c314df13d81c425f99d6f645a28715fe1..6c65a15b17ea7e9619f58f831014ddc747efa886 100644 (file)
--- a/adoc/p_negate.adoc
+++ b/adoc/p_negate.adoc
@@ -1,9 +1,13 @@
+// math.asm:   WORD p_negate, 'NEGATE',fasm
+

 anchor:p_negate[]
 
 anchor:p_negate[]
 

-Word: NEGATE
-----------
+=== Word: NEGATE

 
 

-----
-math.asm:      WORD p_negate, 'NEGATE',fasm
-----
+....
+Data stack: ( v1 -- v2 )
+....

 
 

+"NEGATE" is a function word that replaces a value with its
+2's-complement negation. To that end, the values are 64-bit signed
+integers.

diff --git a/adoc/p_nip.adoc b/adoc/p_nip.adoc
index cc74eb73585ca2ab82e61db927ba2740b985ed96..8e1494666fca9efed6ee8b21ae0eced2bea94c05 100644 (file)
--- a/adoc/p_nip.adoc
+++ b/adoc/p_nip.adoc
@@ -1,9 +1,20 @@
+// stack.asm:  WORD p_nip, 'NIP',fasm
+

 anchor:p_nip[]
 
 anchor:p_nip[]
 

-Word: NIP
-----------
+=== Word: NIP
+
+....
+Data stack: ( v1 v2 -- v2 )
+....

 
 

+"NIP" is a function word that discards the second of the top two cells
+on the data stack.
+
+====
+.Word: NIP
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-stack.asm:     WORD p_nip, 'NIP',fasm
+: NIP SWAP DROP ;

 ----
 ----

-
+====

diff --git a/adoc/p_nl.adoc b/adoc/p_nl.adoc
index 15b1a9978a40d10d19c319addc2bc28d2dc059a8..58bcae961f611c732c12fe5db7dbb0d682254a25 100644 (file)
--- a/adoc/p_nl.adoc
+++ b/adoc/p_nl.adoc
@@ -1,9 +1,11 @@
+// stdio.asm:  WORD p_nl,'NL',dovalue
+

 anchor:p_nl[]
 
 anchor:p_nl[]
 

-Word: NL
---------
+=== Word: NL

 
 

-----
-stdio.asm:     WORD p_nl,'NL',dovalue
-----
+....
+Data stack: ( -- v )
+....

 
 

+"NL" is a value word pushing a newline character onto the data stack.

diff --git a/adoc/p_not.adoc b/adoc/p_not.adoc
index 1a7003549c4e5069c240068179dd87f57c5aa56f..1582cf5eaffaf6a018dc6fe2583d8a4c9b8a8d68 100644 (file)
--- a/adoc/p_not.adoc
+++ b/adoc/p_not.adoc
@@ -1,9 +1,14 @@
+// logic.asm:  WORD p_not, 'NOT',fasm
+

 anchor:p_not[]
 
 anchor:p_not[]
 

-Word: NOT
-----------
+=== Word: NOT
+
+....
+Data stack: ( v1 -- v2 )
+....

 
 

-----
-logic.asm:     WORD p_not, 'NOT',fasm
-----
+"NOT" is a function word that replaces a value with its bitwise 
+complement; each bit is zero if non-zero, and non-zero if zero.

 
 

+Compare with <<p_0equal,0=>>.

diff --git a/adoc/p_number.adoc b/adoc/p_number.adoc
index 94d5a3ca7dbe1163ef7b80f7033b9c7090b5c3e1..d3bcce5890e329c5335d61371ebbc300e4e82d2e 100644 (file)
--- a/adoc/p_number.adoc
+++ b/adoc/p_number.adoc
@@ -1,8 +1,27 @@
-Word: NUMBER
-----------
+// compile.asm:        WORD p_number,'NUMBER',fasm

 
 anchor:p_number[]
 
 anchor:p_number[]

+
+=== Word: NUMBER
+
+....
+Data stack: ( char n -- [ 0 ]/[ v 1 ] )
+....
+
+"NUMBER" is a function word that parses a text number using
+<<p_base,BASE>> as numerical base, then returns the result number and
+a 1 on top, or just a 0 if the word didn't parse.
+
+A number consists of, first an optional minus sign, if in
+<<p_decimal,DECIMAL>> base, then digits 0-9 and, if in <<p_hex,HEX>>
+base, letters a-f or A-F for values 10-15. I.e. the normal positive or
+negative decimal integers or normal (positive only) hexadecimal
+integers.
+
+====
+.Word: NUMBER
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-compile.asm:   WORD p_number,'NUMBER',fasm
+( too complex to include here )

 ----
 ----

-
+====

diff --git a/adoc/p_or.adoc b/adoc/p_or.adoc
index ab5cbe7bc1a034cf94bdc5ddb567c64a7801adf1..7d8401f41bde51d4c15300e55cb1bea1374a4546 100644 (file)
--- a/adoc/p_or.adoc
+++ b/adoc/p_or.adoc
@@ -1,9 +1,15 @@
+// logic.asm:  WORD p_or, 'OR',fasm
+

 anchor:p_or[]
 
 anchor:p_or[]
 

-Word: OR
-----------
+=== Word: OR
+
+....
+Data stack: ( v1 v2 -- v3 )
+....
+
+"OR" is a function word that replaces a value pair with their bitwise
+disjunction; each bit is 1 if the corresponding bits of any operand
+is 1 and 0 if not.

 
 

-----
-logic.asm:     WORD p_or, 'OR',fasm
-----

 
 

diff --git a/adoc/p_over.adoc b/adoc/p_over.adoc
index 78be2430bc9f0288e0ca744f6b3b20c81fcdd0fa..5746eb6f0aac9cd144cc23bf7158f874acf0ec05 100644 (file)
--- a/adoc/p_over.adoc
+++ b/adoc/p_over.adoc
@@ -1,9 +1,14 @@
+// stack.asm:  WORD p_over, 'OVER',fasm
+

 anchor:p_over[]
 
 anchor:p_over[]
 

-Word: OVER
-----------
+=== Word: OVER
+
+....
+Data stack: ( v1 v2 -- v1 v2 v1 )
+....
+
+"OVER" is a function word that duplicates the second top stack cell on
+the data stack.

 
 

-----
-stack.asm:     WORD p_over, 'OVER',fasm
-----

 
 

diff --git a/adoc/p_pad.adoc b/adoc/p_pad.adoc
index 3903cd02049628f27fe18bb72a94c49e998ba98a..1bd1638ff89e06c6abee68234fab9140b25c2033 100644 (file)
--- a/adoc/p_pad.adoc
+++ b/adoc/p_pad.adoc
@@ -1,9 +1,12 @@
+// stdio.asm:  WORD p_pad,'PAD',dovariable
+

 anchor:p_pad[]
 
 anchor:p_pad[]
 

-Word: PAD
----------
+=== Word: PAD

 
 

-----
-stdio.asm:     WORD p_pad,'PAD',dovariable
-----
+....
+Data stack: ( -- a )
+....

 
 

+"PAD" is a variable word for a 1 kb data space that is used by
+<<p_double_quote>> (only), and otherwise free for temporary use.

diff --git a/adoc/p_pick.adoc b/adoc/p_pick.adoc
index 8f0376f4fd5d94661c70bc893318dad34ee11e74..32f76b24428f0645d201989d9703c8c72b37eb46 100644 (file)
--- a/adoc/p_pick.adoc
+++ b/adoc/p_pick.adoc
@@ -1,9 +1,16 @@
+// stack.asm:  WORD p_pick, 'PICK',fasm
+

 anchor:p_pick[]
 
 anchor:p_pick[]
 

-Word: PICK
-----------
+=== Word: PICK
+
+....
+Data stack: ( vu...v1 v0 u -- vu...v1 v0 vu )
+....
+
+"PICK" is a function word that pushes the u:th data stack cell down
+from top onto the data stack. 0 indicates the top cell making it the
+same as <<p_dup,DUP>>, and 1 indicates the second top cell making it
+the same as <<p_over,OVER>>.

 
 

-----
-stack.asm:     WORD p_pick, 'PICK',fasm
-----

 
 

diff --git a/adoc/p_plus.adoc b/adoc/p_plus.adoc
index 9bf9cd7210241f344b1428c916f42c878a3a13df..ffabee268562fa539b11f06c491afdb5c61866f5 100644 (file)
--- a/adoc/p_plus.adoc
+++ b/adoc/p_plus.adoc
@@ -1,10 +1,15 @@
+// math.asm:   WORD p_plus, '+',fasm

 
 anchor:p_plus[]
 
 
 anchor:p_plus[]
 

-Word: +
--------
+// note that asciidoc takes offence to a plain + in the title an
+// therefore we here rely an a convenince macro
+=== Word: {plus} 

 
 

-----
-math.asm:      WORD p_plus, '+',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....

 
 

+"+" (plus) is a function word that replaces a pair of values with the
+result of adding them. To that end, the values are 64-bit signed
+integers.

diff --git a/adoc/p_program_version.adoc b/adoc/p_program_version.adoc
index 80d00a41718e4bd23ee0513f5e78bab56b6015ed..debc57de7855db3c56551f652896081783a5c079 100644 (file)
--- a/adoc/p_program_version.adoc
+++ b/adoc/p_program_version.adoc
@@ -1,9 +1,11 @@
+// rrqforth.asm:       WORD p_program_version,'PROGRAM_VERSION',dostring
+

 anchor:p_program_version[]
 
 anchor:p_program_version[]
 

-Word: PROGRAM_VERSION
----------------------
+=== Word: PROGRAM_VERSION

 
 

-----
-rrqforth.asm:  WORD p_program_version,'PROGRAM_VERSION',dostring
-----
+....
+Data stack: ( -- char* length )
+....

 
 

+"PROGRAM_VERSION" is a string variable hilding the version string.

diff --git a/adoc/p_quit.adoc b/adoc/p_quit.adoc
index 737421bc82aaf015babff06228c1b16f3a4d5bef..ff847d9b8f2c7c7cdca3a1505a96a27684f11fd9 100644 (file)
--- a/adoc/p_quit.adoc
+++ b/adoc/p_quit.adoc
@@ -1,9 +1,14 @@
+// rrqforth.asm:       WORD p_quit,'QUIT',fasm
+

 anchor:p_quit[]
 
 anchor:p_quit[]
 

-Word: QUIT
-----------
+=== Word: QUIT

 
 

-----
-rrqforth.asm:  WORD p_quit,'QUIT',fasm
-----
+....
+Data stack: ??
+....

 
 

+"QUIT" is a function word that implements the root execution loop of
+RRQFORTH. First it resets the stacks to their original settings, and
+thereafter it enters loop of reading words from <<p_stdin,STDIN>> and
+executing them.

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[]
 
 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>>.

diff --git a/adoc/p_read_word.adoc b/adoc/p_read_word.adoc
index f917434f55980efb848c8183f30beaa3adaa75be..76bb0e60789c9c8c826559616d6e28bfb42ba587 100644 (file)
--- a/adoc/p_read_word.adoc
+++ b/adoc/p_read_word.adoc
@@ -1,9 +1,15 @@
+// stdio.asm:  WORD p_read_word,'READ-WORD',fasm
+

 anchor:p_read_word[]
 
 anchor:p_read_word[]
 

-Word: READ-WORD
----------------
+=== Word: READ-WORD
+....
+Data stack: ( stream -- char* n )
+....

 
 

-----
-stdio.asm:     WORD p_read_word,'READ-WORD',fasm
-----
+"READ-WORD" is a function word that "reads" the next whitespace
+separated word from the given stream and returns the [n:char*] duoble
+cell pointer for it. The characters of the word are copied to
+<<p_pad,PAD>>, and there is a limit of 1024 characters.

 
 

+At the end of the stream READ-WORD returns 0 length.

diff --git a/adoc/p_right_bracket.adoc b/adoc/p_right_bracket.adoc
index 4f8589d620fbcb9fd0a58c76eccf75b1bc328387..218873a0272c87180ae0a2f308938b9ae1b62d18 100644 (file)
--- a/adoc/p_right_bracket.adoc
+++ b/adoc/p_right_bracket.adoc
@@ -1,21 +1,27 @@
+compile.asm:   WORD p_right_bracket,']',fasm
+

 anchor:p_right_bracket[]
 
 anchor:p_right_bracket[]
 

-Word: ]
--------
+=== Word: ]

 
 

-----
-compile.asm:   WORD p_right_bracket,']',fasm
-----
+....
+Data stack: ( -- )
+....

 
 

-"]" (right bracket) is function word that sets the stream evaluation
-mode to be compiling. In this mode, words are not executed immediately
-after parsing but rather having their CFA placed on the heap. However,
-words marked as IMMEDIATE (flags&1 != 0) are executed as if
-interpreting mode. Likewise for numbers.
+"]" (right bracket) is a function word that sets the stream evaluation
+mode to be compiling. In this mode words parsed into CFA pointers
+which are placed on the heap in the given order, unless the word is
+flagged as <<p_immediate,IMMEDIATE>> or a <<p_number,NUMBER>>. An
+immediate word is executed immediately, and a number is parsed and
+left on the stack.
+
+Note that a word is parsed as a number only if it is not found in the
+wordlist; i.e., the word list may contain definitions for numbers.

 
 

-.Execution semantics expressed in RRQFORTH

 ====
 ====

-: [ IMMEDIATE 1 STATE ! ;
+.Word: ]
+[caption='Definition concept {counter:exec}: ']
+----
+: ] 1 STATE ! ;
+----

 ====
 ====

-
-

diff --git a/adoc/p_roll.adoc b/adoc/p_roll.adoc
index 79083f26a9dda91f03e3538ee406ba3d56aa81ab..a4d4419967d281e02f25acdda91aa04f68bc6388 100644 (file)
--- a/adoc/p_roll.adoc
+++ b/adoc/p_roll.adoc
@@ -1,9 +1,19 @@
+// stack.asm:  WORD p_roll, 'ROLL',fasm
+

 anchor:p_roll[]
 
 anchor:p_roll[]
 

-Word: ROLL
-----------
+=== Word: ROLL
+
+....
+Data stack: ( vu...v1 v0 u -- ...v1 v0 vu )
+....
+
+"ROLL" is a function word that "moves" the u:th data stack cell down
+from top onto the data stack while discarding it. 0 indicates the top
+cell; 1 indicates the second top cell making it the same as
+<<p_swap,SWAP>>; 2 indicates the third top cell making it the same as
+<<p_rot,ROT>>.
+
+

 
 

-----
-stack.asm:     WORD p_roll, 'ROLL',fasm
-----

 
 

diff --git a/adoc/p_rot.adoc b/adoc/p_rot.adoc
index 5764e0e4c001125cd7059a8b075f22e685f2f00e..649a4067c981855b291fcccfe4af65d3da01f90d 100644 (file)
--- a/adoc/p_rot.adoc
+++ b/adoc/p_rot.adoc
@@ -1,9 +1,15 @@
+// stack.asm:  WORD p_rot, 'ROT',fasm
+

 anchor:p_rot[]
 
 anchor:p_rot[]
 

-Word: ROT
-----------
+=== Word: ROT
+
+....
+Data stack: ( v1 v2 v3 -- v2 v3 v1 )
+....

 
 

-----
-stack.asm:     WORD p_rot, 'ROT',fasm
-----
+"ROT" is a function word that "rotates" the top three data stack cells
+such that the third becomes the first while the second becomes third
+and the first becomes the second.

 
 

+See also <<p_roll,ROLL>>.

diff --git a/adoc/p_sp.adoc b/adoc/p_sp.adoc
index 01e770afb033738d601099cce26b03945372d934..8f0ce9bfd5c9a66d79d391e72508691dfc3b1f39 100644 (file)
--- a/adoc/p_sp.adoc
+++ b/adoc/p_sp.adoc
@@ -1,9 +1,10 @@
-anchor:p_sp[]
+// stdio.asm:  WORD p_sp,'SP',dovalue

 
 

-Word: SP
---------
+anchor:p_sp[]

 
 

-----
-stdio.asm:     WORD p_sp,'SP',dovalue
-----
+=== Word: SP
+....
+Data stack: ( -- v )
+....

 
 

+"SP" is a value word pushing a space character onto the data stack.

diff --git a/adoc/p_state.adoc b/adoc/p_state.adoc
index 460f7f96e7689c3fe2ec1d4f3671299bc670225a..62ed9c79a8ffc1b2f999a1ed5b47823e675e5c8b 100644 (file)
--- a/adoc/p_state.adoc
+++ b/adoc/p_state.adoc
@@ -1,10 +1,12 @@
-Word: STATE
-----------
+// compile.asm:        WORD p_state,'STATE',dovariable

 
 anchor:p_state[]
 
 anchor:p_state[]

-----
-compile.asm:   WORD p_state,'STATE',dovariable
-----
+
+=== Word: STATE
+
+....
+Data stack: ( -- a )
+....

 
 "STATE" is a variable word marking whether the stream evaluator is in
 compiling mode (1) or intepreting (0) mode.
 
 "STATE" is a variable word marking whether the stream evaluator is in
 compiling mode (1) or intepreting (0) mode.

diff --git a/adoc/p_stdin.adoc b/adoc/p_stdin.adoc
index 5bb09b0508861760a11c25ca77ddf74fca9a1716..a01321066ca0b5475803cc1fd8839ebb60c975ec 100644 (file)
--- a/adoc/p_stdin.adoc
+++ b/adoc/p_stdin.adoc
@@ -1,9 +1,12 @@
+// rrqforth.asm:       WORD p_stdin,'STDIN',dovalue
+

 anchor:p_stdin[]
 
 anchor:p_stdin[]
 

-Word: STDIN
------------
+=== Word: STDIN

 
 

-----
-rrqforth.asm:  WORD p_stdin,'STDIN',dovalue
-----
+....
+Data stack: ( -- stream )
+....

 
 

+"STDIN" is a value word referring to the stream buffer for the
+standard input file descriptor.

diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc
index 37ffb5ae7aa07c8df2b4aa9b03c34c24a39ffc9d..cec3e9a1227bb3917d2e5e3e005c3e582c0f557b 100644 (file)
--- a/adoc/p_stream.adoc
+++ b/adoc/p_stream.adoc
@@ -1,9 +1,45 @@
+// stdio.asm:  WORD p_stream,'STREAM',fasm
+

 anchor:p_stream[]
 
 anchor:p_stream[]
 

-Word: STREAM
-------------
+=== Word: STREAM
+....
+Data stack: ( fd size -- addr ) or ( block -1 -- addr )
+....
+
+"STREAM" is a function word that sets up a buffer for an input file
+descriptor or for a memory block (of size+data).
+
+==== File descriptor backed STREAM
+
+A file descriptor backed STREAM gains a buffer of the given size
+prefixed by a 32 byte STREAM header of the following layout:
+
+====
+.file descriptor
+[caption='Stream layout {counter:layout}, for ']
+----
+  8 bytes = size of buffer (excluding the 32 byte header)
+  8 bytes source file descriptor
+  8 bytes current fill
+  8 current read position
+----
+====
+
+==== Memory block backed STREAM
+
+A memory block stream is only the header (though allocated via
+<<p_malloc,MALLOC>> which reserves a full kernel page) with the
+following layout:

 
 

+====
+.memory block
+[caption='Stream layout {counter:layout}, for ']

 ----
 ----

-stdio.asm:     WORD p_stream,'STREAM',fasm
+  8 bytes = block address
+  8 -1 (indicates memory block)
+  8 size of block (taken from the block's first 8 bytes)
+  8 current read position

 ----
 ----

+====

 
 

diff --git a/adoc/p_stream_nchars.adoc b/adoc/p_stream_nchars.adoc
index c56b88a6886d6533b188b5c4aecf77fea939e6a2..0a9e85ae307458f79d23d6eeb40d848fe0dbac40 100644 (file)
--- a/adoc/p_stream_nchars.adoc
+++ b/adoc/p_stream_nchars.adoc
@@ -1,9 +1,14 @@
+// stdio.asm:  WORD p_stream_nchars,'STREAM-NCHARS',fasm
+

 anchor:p_stream_nchars[]
 
 anchor:p_stream_nchars[]
 

-Word: STREAM-NCHARS
--------------------
+=== Word: STREAM-NCHARS
+....
+Data stack: ( stream -- n )
+....

 
 

-----
-stdio.asm:     WORD p_stream_nchars,'STREAM-NCHARS',fasm
-----
+"STREAM-NCHARS" is a function word that scans ahead in the stream
+buffer for the next non-whitespace character, and returns its position
+relative to the end of the buffer. This is done without changing the
+stream (or filling it by reading the backing file).

 
 

diff --git a/adoc/p_strncmp.adoc b/adoc/p_strncmp.adoc
index 19f2e69e30427d234b948b5d374a7843765fbcfc..54642bd6b9d4e7b05120875d93a831ee33f665d2 100644 (file)
--- a/adoc/p_strncmp.adoc
+++ b/adoc/p_strncmp.adoc
@@ -1,9 +1,18 @@
+// wordlists.asm:      WORD p_strncmp,'STRNCMP',fasm
+

 anchor:p_strncmp[]
 
 anchor:p_strncmp[]
 

-Word: STRNCMP
--------------
+=== Word: STRNCMP
+....
+Data stack: ( s1 s2 n -- v )
+....

 
 

-----
-wordlists.asm: WORD p_strncmp,'STRNCMP',fasm
-----
+"STRNCMP" is a function words that compares up to n characters of
+character sequences s1 and s2, and returns the difference of the first
+differing characters, as in +s2[i] - s1[i]+, or 0 if all n characters
+are the same.

 
 

+I.e., the value v is less than 0 if string [n:s1] is alpha-numerically
+less than [n:s2],
+v is greater than 0 if [n:s1] is greater than [n:s2],
+and v is 0 if [n:s1] and [n:s2] are equal.

diff --git a/adoc/p_swap.adoc b/adoc/p_swap.adoc
index 981bde753e76591665b31a75f3be5c3c66047c31..f2e27c758088205bfb959b3de341ad7035306f85 100644 (file)
--- a/adoc/p_swap.adoc
+++ b/adoc/p_swap.adoc
@@ -1,9 +1,11 @@
+// stack.asm:  WORD p_swap, 'SWAP',fasm
+

 anchor:p_swap[]
 
 anchor:p_swap[]
 

-Word: SWAP
-----------
+=== Word: SWAP

 
 

-----
-stack.asm:     WORD p_swap, 'SWAP',fasm
-----
+....
+Data stack: ( v1 v2 -- v2 v1 )
+....

 
 

+"SWAP" is a function word the swaps the top two data stack cells.

diff --git a/adoc/p_system.adoc b/adoc/p_system.adoc
index 11224d6a5c1f7c6734f9dd7b9167cd8a9623c747..11cc731be136a55fc1bb9b1f6c3d496e5670d25c 100644 (file)
--- a/adoc/p_system.adoc
+++ b/adoc/p_system.adoc
@@ -1,9 +1,14 @@
+// rrqforth.asm:       WORD p_system,'SYSTEM',dovariable
+

 anchor:p_system[]
 
 anchor:p_system[]
 

-Word: SYSTEM
-----------
+=== Word: SYSTEM
+
+....
+Data value: ( -- a )
+....

 
 

-----
-rrqforth.asm:  WORD p_system,'SYSTEM',dovariable
-----
+"SYSTEM" is a variable that holds the word list data for the system
+calls. This is set up as separate word list from <<p_forth,FORTH>>
+merely as a matter of segregation.

 
 

diff --git a/adoc/p_tell.adoc b/adoc/p_tell.adoc
index 4a607d7a7be40236e3d2099f3ec45af43cc622c0..a84fb1a84698b36fe94510745c6ca0ad4426126d 100644 (file)
--- a/adoc/p_tell.adoc
+++ b/adoc/p_tell.adoc
@@ -1,9 +1,11 @@
-anchor:p_tell[]
+// stdio.asm:  WORD p_tell,'TELL',fasm

 
 

-Word: TELL
-----------
+anchor:p_tell[]

 
 

-----
-stdio.asm:     WORD p_tell,'TELL',fasm
-----
+=== Word: TELL
+....
+Data stack: ( char* n -- )
+....

 
 

+"TELL" is a function word that prints a string to stdout (file
+descriptor 1).

diff --git a/adoc/p_terminate0.adoc b/adoc/p_terminate0.adoc
index 4f39e851002ff3910c85ef144c20e8ed0c062ec7..e9644fe98b8081e3dc5b89dd0cdda3b69cd5e9c2 100644 (file)
--- a/adoc/p_terminate0.adoc
+++ b/adoc/p_terminate0.adoc
@@ -1,9 +1,12 @@
+// rrqforth.asm:       WORD p_terminate0, 'TERMINATE0',fasm
+

 anchor:p_terminate0[]
 
 anchor:p_terminate0[]
 

-Word: TERMINATE0
-----------------
+=== Word: TERMINATE0

 
 

-----
-rrqforth.asm:  WORD p_terminate0, 'TERMINATE0',fasm
-----
+....
+Data stack: ( -- )
+....

 
 

+"TERMINATE0" is a function word that terminates the program with exit
+code 0.

diff --git a/adoc/p_this_word.adoc b/adoc/p_this_word.adoc
index 338009342a083f9f26b0c1518918b3abc30757bd..7372603fce0bdab691d9d56d8d0015960a49ce1e 100644 (file)
--- a/adoc/p_this_word.adoc
+++ b/adoc/p_this_word.adoc
@@ -1,11 +1,12 @@
+// compile.asm:        WORD p_this_word,'THIS-WORD',dovariable
+

 anchor:p_this_word[]
 
 anchor:p_this_word[]
 

-Word: THIS-WORD
----------------
+=== Word: THIS-WORD

 
 

-----
-compile.asm:   WORD p_this_word,'THIS-WORD',dovariable
-----
+....
+Data stack: ( -- a )
+....

 
 "THIS-WORD" is a variable word used in
 <<p_evaluate_stream:EVALUATE-STREAM>> as cache for the [n:char*]
 
 "THIS-WORD" is a variable word used in
 <<p_evaluate_stream:EVALUATE-STREAM>> as cache for the [n:char*]

diff --git a/adoc/p_true.adoc b/adoc/p_true.adoc
index 30e1fcc16b4a57fbcc5ed3a614aa5fbbcf1bdc65..8392542a7a62f55db09908c7fd544dd2ec171193 100644 (file)
--- a/adoc/p_true.adoc
+++ b/adoc/p_true.adoc
@@ -1,9 +1,11 @@
+// logic.asm:  WORD p_true, 'TRUE',fasm
+

 anchor:p_true[]
 
 anchor:p_true[]
 

-Word: TRUE
-----------
+=== Word: TRUE

 
 

-----
-logic.asm:     WORD p_true, 'TRUE',fasm
-----
+....
+Data stack: ( -- -1 )
+....

 
 

+"TRUE" is a value word representing logical true.

diff --git a/adoc/p_tuck.adoc b/adoc/p_tuck.adoc
index d06a6780a17d16f102add255b3f13aa7489fccca..965f0d3c73d993849cadd6972c7a45c6a92533ca 100644 (file)
--- a/adoc/p_tuck.adoc
+++ b/adoc/p_tuck.adoc
@@ -1,9 +1,20 @@
+// stack.asm:  WORD p_tuck, 'TUCK',fasm
+

 anchor:p_tuck[]
 
 anchor:p_tuck[]
 

-Word: TUCK
-----------
+=== Word: TUCK
+
+....
+Data stack ( v1 v2 -- v2 v1 v2 )
+....

 
 

+"TUCK" is a function word that "inserts" the top cell below the second
+cell on the data stack.
+
+====
+.Word: TUCK
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-stack.asm:     WORD p_tuck, 'TUCK',fasm
+: TUCK SWAP OVER ;

 ----
 ----

-
+====

diff --git a/adoc/p_unequal.adoc b/adoc/p_unequal.adoc
index 2a1791dbaecbb1b344226e81bb14941e189c03ec..640c2a6f1c5cbf70b2d3a48596a4c9d1b4385992 100644 (file)
--- a/adoc/p_unequal.adoc
+++ b/adoc/p_unequal.adoc
@@ -1,9 +1,12 @@
+// logic.asm:  WORD p_unequal, '!=',fasm
+

 anchor:p_unequal[]
 
 anchor:p_unequal[]
 

-Word: !=
-----------
+=== Word: !=

 
 

-----
-logic.asm:     WORD p_unequal, '!=',fasm
-----
+....
+Data stack: ( v1 v2 -- 0/-1 )
+....

 
 

+"!=" is a function word that replaces a pair of values with -1 of the
+values are unequal, and 0 otherwise.

diff --git a/adoc/p_within.adoc b/adoc/p_within.adoc
index 3d7ea491c79b35ac3ba44c77d167c3cf42a512f3..911325f0fff828e8d985e038dafb722869b78b1b 100644 (file)
--- a/adoc/p_within.adoc
+++ b/adoc/p_within.adoc
@@ -1,9 +1,21 @@
+// logic.asm:  WORD p_within, 'WITHIN',fasm
+

 anchor:p_within[]
 
 anchor:p_within[]
 

-Word: WITHIN
-----------
+=== Word: WITHIN
+
+....
+Data stack: ( v lo hi -- 0/-1
+....

 
 

+"WITHIN" is a function word that replaces a triple of values with -1
+of the the first, v, is within the value range spanned by the second,
+lo, inclusive and third, hi, exclusive.
+
+====
+.Word: WITHIN
+[caption='Definition concept {counter:exec}: ']

 ----
 ----

-logic.asm:     WORD p_within, 'WITHIN',fasm
+: WITHIN 2 PICK > ROT ROT <= AND ;

 ----
 ----

-
+====

diff --git a/adoc/p_words.adoc b/adoc/p_words.adoc
index b2cae3d66f3f65603cfb741dd0ec71f55ffe1b41..d51c9d8ee886a845f38b19bc7d0b8925345c0dea 100644 (file)
--- a/adoc/p_words.adoc
+++ b/adoc/p_words.adoc
@@ -1,9 +1,11 @@
-anchor:p_words[]
+// wordlists.asm:      WORD p_words,'WORDS',fasm

 
 

-Word: WORDS
------------
+anchor:p_words[]

 
 

-----
-wordlists.asm: WORD p_words,'WORDS',fasm
-----
+=== Word: WORDS
+....
+Data stack: ( wl -- )
+....

 
 

+"WORDS" is a function word that prints all words of teh given word
+list to stdout (file descriptor 1).

diff --git a/adoc/p_xor.adoc b/adoc/p_xor.adoc
index 04f763ae708055901d7b913ba4381e1c0239ce48..5c8b6378f2e1385916c7bfb71b47ead6b36f1b00 100644 (file)
--- a/adoc/p_xor.adoc
+++ b/adoc/p_xor.adoc
@@ -1,9 +1,13 @@
+// logic.asm:  WORD p_xor, 'XOR',fasm
+

 anchor:p_xor[]
 
 anchor:p_xor[]
 

-Word: XOR
-----------
+=== Word: XOR

 
 

-----
-logic.asm:     WORD p_xor, 'XOR',fasm
-----
+....
+Data stack: ( v1 v2 -- v3 )
+....

 
 

+"XOR" is a function word that replaces a value pair with their bitwise
+exclusion; each bit is 1 if the corresponding bits of the two operands
+differ and 0 if not.

diff --git a/adoc/return_stack.adoc b/adoc/return_stack.adoc
index 649902cbfb8a81d578c6b793e137702dce0bcd48..900d316f5d2a89e1d0b735ea746b530678d858d6 100644 (file)
--- a/adoc/return_stack.adoc
+++ b/adoc/return_stack.adoc
@@ -1,8 +1,11 @@
+// rrqforth.asm:       WORD return_stack,'RETURN-STACK',dovariable
+

 anchor:return_stack[]
 
 anchor:return_stack[]
 

-Word: RETURN-STACK
-------------------
+=== Word: RETURN-STACK
+
+....
+Data stack: ( -- a )
+....

 
 

-----
-rrqforth.asm:  WORD return_stack,'RETURN-STACK',dovariable
-----
+"RETURN-STACK" is a variable word harbouring the return stack.

diff --git a/reference.adoc b/reference.adoc
index 0d71f8fd0194146821ceec8aeff4bddb06ea33b6..d44db8850766be690d664f62f7f0c800c4abc255 100644 (file)
--- a/reference.adoc
+++ b/reference.adoc
@@ -1,7 +1,9 @@
-RRQFORTH Reference Documentation
-================================
-// :toc:
+= RRQFORTH Reference Documentation
+:author: Ralph Ronnquist <ralph.ronnquist@gmail.com>
+:plus: +

 
 

+
+== Compilation words

 // include::compile.adoc[]
 include::adoc/p_allot.adoc[]
 include::adoc/p_base.adoc[]
 // include::compile.adoc[]
 include::adoc/p_allot.adoc[]
 include::adoc/p_base.adoc[]


@@ -14,6 +16,7 @@ include::adoc/p_does.adoc[]
 include::adoc/p_evaluate_stream.adoc[]
 include::adoc/p_here.adoc[]
 include::adoc/p_hex.adoc[]
 include::adoc/p_evaluate_stream.adoc[]
 include::adoc/p_here.adoc[]
 include::adoc/p_hex.adoc[]

+include::adoc/p_immediate.adoc[]

 include::adoc/p_left_bracket.adoc[]
 include::adoc/p_literal.adoc[]
 include::adoc/p_literal_string.adoc[]
 include::adoc/p_left_bracket.adoc[]
 include::adoc/p_literal.adoc[]
 include::adoc/p_literal_string.adoc[]


@@ -22,6 +25,7 @@ include::adoc/p_right_bracket.adoc[]
 include::adoc/p_state.adoc[]
 include::adoc/p_this_word.adoc[]
 
 include::adoc/p_state.adoc[]
 include::adoc/p_this_word.adoc[]
 

+== Logic operation words

 //include::logic.adoc[]
 include::adoc/p_0equal.adoc[]
 include::adoc/p_0less.adoc[]
 //include::logic.adoc[]
 include::adoc/p_0equal.adoc[]
 include::adoc/p_0less.adoc[]


@@ -39,6 +43,7 @@ include::adoc/p_unequal.adoc[]
 include::adoc/p_within.adoc[]
 include::adoc/p_xor.adoc[]
 
 include::adoc/p_within.adoc[]
 include::adoc/p_xor.adoc[]
 

+== Math operation words

 // include::math.adoc[]
 include::adoc/p_abs.adoc[]
 include::adoc/p_divmod.adoc[]
 // include::math.adoc[]
 include::adoc/p_abs.adoc[]
 include::adoc/p_divmod.adoc[]


@@ -47,6 +52,7 @@ include::adoc/p_mult.adoc[]
 include::adoc/p_negate.adoc[]
 include::adoc/p_plus.adoc[]
 
 include::adoc/p_negate.adoc[]
 include::adoc/p_plus.adoc[]
 

+== RRQFORTH main words

 //include::rrqforth.adoc[]
 include::adoc/data_stack.adoc[]
 include::adoc/inline_code.adoc[]
 //include::rrqforth.adoc[]
 include::adoc/data_stack.adoc[]
 include::adoc/inline_code.adoc[]


@@ -61,6 +67,7 @@ include::adoc/p_dovalue.adoc[]
 include::adoc/p_dovariable.adoc[]
 include::adoc/p_execute.adoc[]
 include::adoc/p_exit.adoc[]
 include::adoc/p_dovariable.adoc[]
 include::adoc/p_execute.adoc[]
 include::adoc/p_exit.adoc[]

+include::adoc/p_lparen.adoc[]

 include::adoc/p_program_version.adoc[]
 include::adoc/p_quit.adoc[]
 include::adoc/p_stdin.adoc[]
 include::adoc/p_program_version.adoc[]
 include::adoc/p_quit.adoc[]
 include::adoc/p_stdin.adoc[]


@@ -68,6 +75,7 @@ include::adoc/p_system.adoc[]
 include::adoc/p_terminate0.adoc[]
 include::adoc/return_stack.adoc[]
 
 include::adoc/p_terminate0.adoc[]
 include::adoc/return_stack.adoc[]
 

+== Stack operation words

 //include::stack.adoc[]
 include::adoc/p_2drop.adoc[]
 include::adoc/p_2dup.adoc[]
 //include::stack.adoc[]
 include::adoc/p_2drop.adoc[]
 include::adoc/p_2dup.adoc[]


@@ -76,7 +84,7 @@ include::adoc/p_2swap.adoc[]
 include::adoc/p_depth.adoc[]
 include::adoc/p_drop.adoc[]
 include::adoc/p_dup.adoc[]
 include::adoc/p_depth.adoc[]
 include::adoc/p_drop.adoc[]
 include::adoc/p_dup.adoc[]

-include::adoc/p_ltR.adoc[]
+include::adoc/p_gtR.adoc[]

 include::adoc/p_nip.adoc[]
 include::adoc/p_over.adoc[]
 include::adoc/p_pick.adoc[]
 include::adoc/p_nip.adoc[]
 include::adoc/p_over.adoc[]
 include::adoc/p_pick.adoc[]


@@ -87,6 +95,7 @@ include::adoc/p_rot.adoc[]
 include::adoc/p_swap.adoc[]
 include::adoc/p_tuck.adoc[]
 
 include::adoc/p_swap.adoc[]
 include::adoc/p_tuck.adoc[]
 

+== Input/output words

 //include::stdio.adoc[]
 include::adoc/p_clear_stream.adoc[]
 include::adoc/p_digits.adoc[]
 //include::stdio.adoc[]
 include::adoc/p_clear_stream.adoc[]
 include::adoc/p_digits.adoc[]


@@ -103,6 +112,7 @@ include::adoc/p_stream.adoc[]
 include::adoc/p_stream_nchars.adoc[]
 include::adoc/p_tell.adoc[]
 
 include::adoc/p_stream_nchars.adoc[]
 include::adoc/p_tell.adoc[]
 

+== Wordlist words

 //include::wordlists.adoc[]
 include::adoc/p_current_wordlist.adoc[]
 include::adoc/p_find.adoc[]
 //include::wordlists.adoc[]
 include::adoc/p_current_wordlist.adoc[]
 include::adoc/p_find.adoc[]


@@ -110,4 +120,15 @@ include::adoc/p_forth.adoc[]
 include::adoc/p_strncmp.adoc[]
 include::adoc/p_words.adoc[]
 
 include::adoc/p_strncmp.adoc[]
 include::adoc/p_words.adoc[]
 

+== System calls

 //include::syscalls.adoc[]
 //include::syscalls.adoc[]

+
+RRQFORTH includes function wrapping for all "Linux syscalls", which
+generally are described in their "man pages. This wrapping takes the
+arguments fro the data stack in reverse order, i.e. the first argument
+is deepest.
+
+Use +SYSTEM WORDS+ to get a list of all (321) available syscalls.
+
+
+include::wordindex.adoc[]

diff --git a/wordindex.adoc b/wordindex.adoc
new file mode 100644 (file)
index 0000000..c6bcd71
--- /dev/null
+++ b/wordindex.adoc
@@ -0,0 +1,121 @@
+
+== Index of word links
+
+<<data_stack>>
+<<inline_code>>
+<<return_stack>>
+
+<<p_0branch>>
+<<p_0equal>>
+<<p_0less>>
+
+<<p_2drop>>
+<<p_2dup>>
+<<p_2over>>
+<<p_2swap>>
+
+<<p_abs>>
+<<p_allot>>
+<<p_and>>
+<<p_args>>
+
+<<p_base>>
+<<p_branch>>
+
+<<p_Ccomma>>
+<<p_clear_stream>>
+<<p_colon>>
+<<p_comma>>
+<<p_create>>
+<<p_current_wordlist>>
+
+<<p_decimal>>
+<<p_depth>>
+<<p_digits>>
+<<p_divmod>>
+<<p_dodoes>>
+<<p_does>>
+<<p_dofasm>>
+<<p_doforth>>
+<<p_dostring>>
+<<p_dot>>
+<<p_double_quote>>
+<<p_dovalue>>
+<<p_dovariable>>
+<<p_drop>>
+<<p_dup>>
+
+<<p_emit>>
+<<p_equal>>
+<<p_evaluate_stream>>
+<<p_execute>>
+<<p_exit>>
+
+<<p_false>>
+<<p_find>>
+<<p_forth>>
+
+<<p_greaterequal>>
+<<p_greaterthan>>
+<<p_gtR>>
+
+<<p_here>>
+<<p_hex>>
+
+<<p_immediate>>
+
+<<p_left_bracket>>
+<<p_lessequal>>
+<<p_lessthan>>
+<<p_literal>>
+<<p_literal_string>>
+
+<<p_malloc>>
+<<p_minus>>
+<<p_mult>>
+
+<<p_negate>>
+<<p_nip>>
+<<p_nl>>
+<<p_not>>
+<<p_number>>
+
+<<p_or>>
+<<p_over>>
+<<p_pad>>
+
+<<p_pick>>
+<<p_plus>>
+<<p_program_version>>
+
+<<p_quit>>
+
+<<p_read_stream_char>>
+<<p_read_word>>
+<<p_Rget>>
+<<p_Rgt>>
+<<p_right_bracket>>
+<<p_roll>>
+<<p_rot>>
+
+<<p_sp>>
+<<p_state>>
+<<p_stdin>>
+<<p_stream>>
+<<p_stream_nchars>>
+<<p_strncmp>>
+<<p_swap>>
+<<p_system>>
+
+<<p_tell>>
+<<p_terminate0>>
+<<p_this_word>>
+<<p_true>>
+<<p_tuck>>
+
+<<p_unequal>>
+
+<<p_within>>
+<<p_words>>
+
+<<p_xor>>