standardized call-out blocks

diff --git a/adoc/inline_code.adoc b/adoc/inline_code.adoc
index b1a9c46097bc2b63704d873631aa6e25201a0db0..d85166c1bce422449758b875519825abb9cc138a 100644 (file)
--- a/adoc/inline_code.adoc
+++ b/adoc/inline_code.adoc
@@ -20,3 +20,6 @@ RRQFORTH executon by means of the following instruction sequence:
 forthcode:
 ----
 ====
+
+Note that the FORTH compiler does not invoke an assembler so any
+inline assembly code must be provided in its binary form.

diff --git a/adoc/p_0branch.adoc b/adoc/p_0branch.adoc
index a11ec49756110c3864c4818121f8690c0c10dffe..6488d62ab6c305c4c421abd782609db3eaeab75a 100644 (file)
--- a/adoc/p_0branch.adoc
+++ b/adoc/p_0branch.adoc
@@ -14,3 +14,13 @@ the point of execution. If the value, v, is 0 then the branch offset
 is added, and otherwise execution continues with the cell following
 the branch offset in the definition.
 
+Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first non-zero
+value.
+
+See also <<p_1branch,1BRANCH>>, <<p_branch,BRANCH>>, <<p_if,IF>>,
+<<p_else,ELSE>>, <<p_ifbreak,IFBREAK>> and <<p_ifagain,IFAGAIN>>.

diff --git a/adoc/p_0equal.adoc b/adoc/p_0equal.adoc
index 827c0f1e206857c1c65924e8c3e519a5b41a3971..8e5379c507ca117fbd301d3502bab0731a3d7444 100644 (file)
--- a/adoc/p_0equal.adoc
+++ b/adoc/p_0equal.adoc
@@ -13,4 +13,4 @@ Data stack: ( v -- 0/-1 )
 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>>.
+This is the same function as <<p_not,NOT>>.

diff --git a/adoc/p_0less.adoc b/adoc/p_0less.adoc
index b068b636a74dcc129892d99642ee3f42745da8b2..b5c1f5e9d09722c1a91f86c81ea41d9eaeb7a700 100644 (file)
--- a/adoc/p_0less.adoc
+++ b/adoc/p_0less.adoc
@@ -12,12 +12,10 @@ Data stack: ( v -- 0/-1 )
 less than 0, and 0 otherwise.
 
 ====
-.Word: 0<
-[caption='Definition concept {counter:exec}: ']
-----
-: 0= 0 SWAP < ;
-----
+.Definition concept for 0<
+****
+( v -- 0/1 ) : 0= 0 SWAP < ;
+****
 ====
 
-See also <<p_swap,SWAP>> and
-<<p_lessthan,<>>.
+See also <<p_swap,SWAP>> and <<p_lessthan,<>>.

diff --git a/adoc/p_1branch.adoc b/adoc/p_1branch.adoc
index 0483d007675b34f32953b604d7119df78480f13f..8d1b7ca9b690e0dfc5a3183514466d7df563906a 100644 (file)
--- a/adoc/p_1branch.adoc
+++ b/adoc/p_1branch.adoc
@@ -14,3 +14,12 @@ the point of execution. If the value, v, is non-zero then the branch
 offset is added, and otherwise execution continues with the cell
 following the branch offset in the definition.
 
+Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first zero value.
+
+See also <<p_0branch,0BRANCH>>, <<p_branch,BRANCH>>, <<p_if,IF>>,
+<<p_else,ELSE>>, <<p_ifbreak,IFBREAK>> and <<p_ifagain,IFAGAIN>>.

diff --git a/adoc/p_2dup.adoc b/adoc/p_2dup.adoc
index 0b39b0853f948ed029a7c3887d3d04dc6fbf0b94..d42513172067365f795a946008e561e039f641a0 100644 (file)
--- a/adoc/p_2dup.adoc
+++ b/adoc/p_2dup.adoc
@@ -12,9 +12,8 @@ Data stack: ( v1 v2 -- v1 v2 v1 v2 )
 stack.
 
 ====
-.Word: 2DUP
-[caption='Definition concept {counter:exec}: ']
-----
-: 2DUP OVER OVER ;
-----
+.Definition concept for 2DUP
+****
+( v1 v2 -- v1 v2 v1 v2 ) : 2DUP OVER OVER ;
+****
 ====

diff --git a/adoc/p_2over.adoc b/adoc/p_2over.adoc
index 058bfdd0216af138231f67850522eb8b11b0f1a4..fcfc184e7d29dc82abfb53d6c2188873075978d7 100644 (file)
--- a/adoc/p_2over.adoc
+++ b/adoc/p_2over.adoc
@@ -13,10 +13,8 @@ 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}: ']
-----
-: 2OVER 3 PICK 3 PICK ;
-----
+.Definition concept for 2OVER
+****
+( v1 v2 v3 v4 -- v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;
+****
 ====
-

diff --git a/adoc/p_2swap.adoc b/adoc/p_2swap.adoc
index 6c123cfad61406bd5549c66dae164c4e224c9308..2c03e4968161ed5654e9af6263bc926c5e03e504 100644 (file)
--- a/adoc/p_2swap.adoc
+++ b/adoc/p_2swap.adoc
@@ -13,9 +13,8 @@ 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}: ']
-----
-: 2SWAP 3 ROLL 3 ROOL ;
-----
+.Definition concept for 2SWAP
+****
+( v1 v2 v3 v4 -- v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;
+****
 ====

diff --git a/adoc/p_Ccomma.adoc b/adoc/p_Ccomma.adoc
index a0b07cd9771604e11d0f100400162b362d91d35e..75992a8f0633d302e3d70f608c966cb90c26ba4f 100644 (file)
--- a/adoc/p_Ccomma.adoc
+++ b/adoc/p_Ccomma.adoc
@@ -14,11 +14,10 @@ Data stack: ( v -- )
 at the current free head address, which also is incremented.
 
 ====
-.Word: C,
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for C,
+****
 : 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,@>>,

diff --git a/adoc/p_base.adoc b/adoc/p_base.adoc
index fe6d66f4a10545663a558c3d01edbc586a034318..a8748b71fdb63ef957ba9c5d89418df388477b68 100644 (file)
--- a/adoc/p_base.adoc
+++ b/adoc/p_base.adoc
@@ -17,9 +17,3 @@ supported.
 
 See also <<p_digits,DIGITS>>, which holds the mapping table from
 digits to text.
-
-====
-.Usage example {counter:example}: claim 16 bytes for variable FOO
-[caption='Usage example {counter:example}: ']
-CREATE FOO BASE
-====

diff --git a/adoc/p_begin.adoc b/adoc/p_begin.adoc
index ca4f1af8160b00d8905cd34584995661b33dff97..da124abb1076d85352994226fabab83e52f9a2b8 100644 (file)
--- a/adoc/p_begin.adoc
+++ b/adoc/p_begin.adoc
@@ -14,3 +14,21 @@ implement structured execution control. BEGIN simply places the
 address for resolving branches back to this point during execution,
 and then a 0 as a marker so as to allow for an unknown number of block
 exit points.
+
+====
+.Usage example {counter:example}: 
+----
+: WTELL ( tfa -- ; Print word pname )
+  24 + DUP 8 + SWAP @ TELL SP EMIT
+;
+
+: WORDS ( wordlist -- ; Print all words of word list )
+  BEGIN
+    @ DUP 0= IFBREAK
+    DUP WTELL
+  END
+  DROP
+  NL EMIT
+;
+----
+====

diff --git a/adoc/p_bracketed_quote.adoc b/adoc/p_bracketed_quote.adoc
index 74e15a35154fc37ad214d2d58ae6ac05591c29c3..b7a231c5a6d7d0d9e8da4a03850a63386230cee9 100644 (file)
--- a/adoc/p_bracketed_quote.adoc
+++ b/adoc/p_bracketed_quote.adoc
@@ -11,3 +11,10 @@ Data stack: ( -- cfa )   Input stream: word
 "[']" is an immediate function word that reads the next word on the
 input stream and pushes its cfa.
 
+====
+.Definition concept for [']
+****
+: ['] IMMEDIATE ' ;
+****
+====
+

diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc
index 089e23867213f9164a4d23a9983e3b72ee9f1fd1..02f7319524a56e57218e68c6974fe9b51727c03c 100644 (file)
--- a/adoc/p_branch.adoc
+++ b/adoc/p_branch.adoc
@@ -11,3 +11,13 @@ Data stack: ( -- )
 "BRANCH" is a function word that implements execution transfer by
 means of adding the subsequent branch offset to the point of
 execution.
+
+Note that the branch offset is a byte count and each FORTH word of a
+definition take up a cell of 8 bytes. The offset is relative to the
+cell address immediately subsequent to the offset cell. In other
+words, offset 0 is not branching anywhere and an offset of -16 would
+make a tight loop back to the branch instruction itself. The latter
+would pull data stack values until and including the first zero value.
+
+See also <<p_0branch,0BRANCH>>, <<p_1branch,1BRANCH>>, <<p_if,IF>>,
+<<p_else,ELSE>>, <<p_ifbreak,IFBREAK>> and <<p_ifagain,IFAGAIN>>.

diff --git a/adoc/p_break.adoc b/adoc/p_break.adoc
index f7da196579288ed75bcf2696fc105735941730c1..dec6fd78242b901701eed5156ab84f033cd1fe7e 100644 (file)
--- a/adoc/p_break.adoc
+++ b/adoc/p_break.adoc
@@ -9,3 +9,24 @@ branch out of an enclosing xef:p_begin[BEGIN]-xref:p_end[END] block.
 Similar to xref:p_ifbreak[IFBREAK] it lays out the branch cell
 followed by a reserved cell for the branch offset, and inserts the
 resolution address just above the required 0 on the data stack.
+
+====
+.Usage example {counter:example}: unconditional break with a condition.
+----
+: WTELL ( tfa -- ; Print word pname )
+  24 + DUP 8 + SWAP @ TELL SP EMIT
+;
+
+: WORDS ( wordlist -- ; Print all words of word list )
+  BEGIN
+    @ DUP IF DUP WTELL ELSE BREAK THEN
+  END
+  DROP
+  NL EMIT
+;
+----
+====
+
+See also <<p_branch,BRANCH>>, <<p_0branch,0BRANCH>>,
+<<p_1branch,1BRANCH>>, <<p_if,IF>>, <<p_else,ELSE>>,
+<<p_ifbreak,IFBREAK>> and <<p_ifagain,IFAGAIN>>.

diff --git a/adoc/p_colon.adoc b/adoc/p_colon.adoc
index 3a5acecd2ec6695b980c14b449dd32279b5f4044..86b910449ff0e7ed8dfec00554bd99217b6a624c 100644 (file)
--- a/adoc/p_colon.adoc
+++ b/adoc/p_colon.adoc
@@ -14,11 +14,10 @@ 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}: ']
-----
+.Definition concept for :
+****
 : : doFORTH READ-WORD CREATE TFA>CFA ! ] ;
-----
+****
 ====
 
 See also <<p_doforth,doFORTH>>, <<p_read_word,READ-WORD>>,

diff --git a/adoc/p_comma.adoc b/adoc/p_comma.adoc
index ae000355431e11c80fcf157eb4944029f20d4ac1..f3064b720db5868d798c21c23cb17b31bbd40d76 100644 (file)
--- a/adoc/p_comma.adoc
+++ b/adoc/p_comma.adoc
@@ -13,11 +13,10 @@ Data stack: ( v -- )
 <<p_here,HERE>> heap.
 
 ====
-.Word: ,
-[caption='Definition concept{counter:exec}: ']
-----
+.Definition concept for ,
+****
 : , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )
-----
+****
 ====
 
 See also <<p_colon,:>>, <<p_Ccomma>>. <<p_here,HERE>>, <<p_get,@>>,

diff --git a/adoc/p_create.adoc b/adoc/p_create.adoc
index cf8914e7b9afb27f0315a414e8f36a50e693aade..5fdfe27d3caa6536bededd5473358779baf49ec0 100644 (file)
--- a/adoc/p_create.adoc
+++ b/adoc/p_create.adoc
@@ -14,6 +14,8 @@ indicated [n:char*] print name, and returns the "TFA" (Token Field
 Address) of the word. The header memory layout is as follows:
 
 ====
+.rrqforth word structure
+[caption='Layout {counter:layout}: ']
 ----
 struct WORD
 TFA  8 link ; tfa of previous word
@@ -42,9 +44,8 @@ function words initiated by ":" (aka "COLON") or changed to "dovalue"
 for RRQFORTH constants created by "CONSTANT".
 
 ====
-.Word: CREATE
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for CREATE
+****
 HERE @ R> ( save tfa on RS )
   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
   DUP 49 + R@ + ,             ( pCFA )
@@ -54,13 +55,16 @@ HERE @ R> ( save tfa on RS )
   R@ ,                        ( pTFA )
   0 ,                         ( OFF )
   doVARIABLE                  ( CFA, default semantics )
-----
+****
 ====
 
-.Usage example: a possible definition of CONSTANT
-****
+====
+.a possible definition of CONSTANT
+[caption='Usage example {counter:example}: ']
+----
 : 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>>,

diff --git a/adoc/p_current_wordlist.adoc b/adoc/p_current_wordlist.adoc
index 91d9240e380e67d5b54fa080b5ab234d629adeba..a5ab03145a5a731927d4e8600cdc0788ef3d39c2 100644 (file)
--- a/adoc/p_current_wordlist.adoc
+++ b/adoc/p_current_wordlist.adoc
@@ -10,6 +10,7 @@ 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}: ']

diff --git a/adoc/p_decimal.adoc b/adoc/p_decimal.adoc
index b06e5f25fc4a6e9b089921594effd88b38dfef86..292565393e2de44081f827b027c9a34e3bb77894 100644 (file)
--- a/adoc/p_decimal.adoc
+++ b/adoc/p_decimal.adoc
@@ -12,9 +12,8 @@ Data stack: ( -- )
 "DECIMAL" is a function word that sets <<p_base,BASE>> to 10.
 
 ====
-.Word: DECIMAL
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for DECIMAL
+****
 : DECIMAL 10 BASE ! ;
-----
+****
 ====

diff --git a/adoc/p_does.adoc b/adoc/p_does.adoc
index a9ac349c73fdf116ce13ae9bbf609a89fe0ebc0c..b31b42b274f0f803ef9e8ec7c7a33fe12769d85b 100644 (file)
--- a/adoc/p_does.adoc
+++ b/adoc/p_does.adoc
@@ -15,8 +15,8 @@ offset to the current heap address. I.e., the word being defined will
 have its execution start at whatever comes after "DOES>".
 
 ====
-.Word: DOES>
-----
+.Defintion concept for DOES>
+****
 : DOES> IMMEDIATE
 STATE @ != IF ( only for compilation mode )
   CURRENT-WORDLIST @ @ TFA>CFA    ( cfa of current word )
@@ -24,7 +24,7 @@ STATE @ != IF ( only for compilation mode )
     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset
   THEN
 ;
-----
+****
 ====
 
 See also

diff --git a/adoc/p_evaluate_stream.adoc b/adoc/p_evaluate_stream.adoc
index ec54379864b17054f94919289861dd045fec5823..abd86d5f40bce9063f415012d79c12fa251aaecf 100644 (file)
--- a/adoc/p_evaluate_stream.adoc
+++ b/adoc/p_evaluate_stream.adoc
@@ -42,12 +42,3 @@ 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}: ']
-----
-( too complex to include here )
-----
-====
-
-

diff --git a/adoc/p_get_n_decrement.adoc b/adoc/p_get_n_decrement.adoc
index b41909901ed520cbc27128cf87952162b3366d31..9f22ca3dcf8e25fcae46e6dba01cf2142cf7afee 100644 (file)
--- a/adoc/p_get_n_decrement.adoc
+++ b/adoc/p_get_n_decrement.adoc
@@ -12,9 +12,8 @@ Data stack: ( a n -- v )
 then decrements the cell at that address by n.
 
 ====
-.Word: @n++
-[caption='Defintion concept {counter:exec}']
-----
+.Defintion concept for @n++
+****
 : @n++ OVER @ DUP ROT - ROT ! ;
-----
+****
 ====

diff --git a/adoc/p_here.adoc b/adoc/p_here.adoc
index 5a6c41609ffd4bdf8dbbe08622f609a0f8df809d..66aa8edcafceb6e0014e43e652c35203a14e72c3 100644 (file)
--- a/adoc/p_here.adoc
+++ b/adoc/p_here.adoc
@@ -12,9 +12,12 @@ Data stack: ( -- a )
 allocation space. It get updated by all words that allocate memory.
 
 
-.Usage example
+====
+.allocate 1024 bytes on the heap
+[caption='Usage example {counter:example} ']
 ****
-1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )
+1024 HEAP @ + HEAP !
 ****
+====
 
 See also <<p_allot,ALLOT>>.

diff --git a/adoc/p_hex.adoc b/adoc/p_hex.adoc
index 35ef0ff4130a6fccf13ecbfe1096d526933f2e63..cdefe59f8bd5df5a0108c859a461a2e68a663c40 100644 (file)
--- a/adoc/p_hex.adoc
+++ b/adoc/p_hex.adoc
@@ -13,9 +13,8 @@ letters a-f as additional digits. (Uppercase letter are also accepted
 on input).
 
 ====
-.Word: HEX
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for HEX
+****
 : HEX 16 BASE ! ;
-----
+****
 ====

diff --git a/adoc/p_immediate.adoc b/adoc/p_immediate.adoc
index 5e887fee6da6f726b2bb548d7ee5fa1c5913f7cd..154aa3aa2ee6b4cfb25eb46d22c0ee809a3010b4 100644 (file)
--- a/adoc/p_immediate.adoc
+++ b/adoc/p_immediate.adoc
@@ -12,11 +12,10 @@ Data stack: ( -- )
 the most recent word to 1, thereby making that word an immediate word.
 
 ====
-.Word: IMMEDIATE
-[caption='Definition concept {counter:exec}:']
-----
+.Definition concept for IMMEDIATE
+****
 : IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;
-----
+****
 ====
 
 See also <<p_colon,:>>, <<p_current_wordlist,CURRENT-WORDLIST>>,

diff --git a/adoc/p_left_bracket.adoc b/adoc/p_left_bracket.adoc
index ead7d3bbe25cd90913b2eb3b55e2a92bb0abff8b..ecd77bf77350a25e03957e690d0a0288369cd01d 100644 (file)
--- a/adoc/p_left_bracket.adoc
+++ b/adoc/p_left_bracket.adoc
@@ -13,10 +13,8 @@ mode to be intepreting. In this mode, words are executed immediately
 after parsing, by invoking their "doer".
 
 ====
-.Word: [
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for [
+****
 : [ IMMEDIATE 0 STATE ! ;
-----
+****
 ====
-

diff --git a/adoc/p_literal.adoc b/adoc/p_literal.adoc
index 35d98da0d2fc69c244fe51752a29d9c868514763..5a50f2d5ab3fb7f0807c637a078862e441e1a799 100644 (file)
--- a/adoc/p_literal.adoc
+++ b/adoc/p_literal.adoc
@@ -17,11 +17,10 @@ with the CFA pointer following the value.
 It's not a good idea to use "LIT" interactively.
 
 ====
-.Word: LIT
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for LIT
+****
 : LIT R> DUP 8 + >R @ ;
-----
+****
 ====
 
 

diff --git a/adoc/p_literal_string.adoc b/adoc/p_literal_string.adoc
index 218f443e7bab945ce1bedf8550502cb890129a04..ba94b0f3f7abadf97db4013aaba77123e5909f6a 100644 (file)
--- a/adoc/p_literal_string.adoc
+++ b/adoc/p_literal_string.adoc
@@ -13,11 +13,9 @@ 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}: ']
-----
+.Definition concept for LIT
+****
 : LIT R> DUP @ 2DUP + 8 + >R SWAP 8 + SWAP ;
-----
+****
 ====
 
-

diff --git a/adoc/p_nip.adoc b/adoc/p_nip.adoc
index 8e1494666fca9efed6ee8b21ae0eced2bea94c05..1f997109152f07c4b73874c873fd7b777e775f39 100644 (file)
--- a/adoc/p_nip.adoc
+++ b/adoc/p_nip.adoc
@@ -12,9 +12,8 @@ Data stack: ( v1 v2 -- v2 )
 on the data stack.
 
 ====
-.Word: NIP
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for NIP
+****
 : NIP SWAP DROP ;
-----
+****
 ====

diff --git a/adoc/p_number.adoc b/adoc/p_number.adoc
index d3bcce5890e329c5335d61371ebbc300e4e82d2e..c8759716967d089851d28c9e3c7c55c5ee4a5111 100644 (file)
--- a/adoc/p_number.adoc
+++ b/adoc/p_number.adoc
@@ -18,10 +18,3 @@ 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}: ']
-----
-( too complex to include here )
-----
-====

diff --git a/adoc/p_right_bracket.adoc b/adoc/p_right_bracket.adoc
index 218873a0272c87180ae0a2f308938b9ae1b62d18..580d7bfec11e1dea7d0300c3ce80d937824eaa7b 100644 (file)
--- a/adoc/p_right_bracket.adoc
+++ b/adoc/p_right_bracket.adoc
@@ -19,9 +19,8 @@ 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.
 
 ====
-.Word: ]
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for ]
+****
 : ] 1 STATE ! ;
-----
+****
 ====

diff --git a/adoc/p_semicolon.adoc b/adoc/p_semicolon.adoc
index 1818e8058f577e76cb087fecb475308ca455ffa2..c16e147357d5b94484d02ae89a6da10f63305fde 100644 (file)
--- a/adoc/p_semicolon.adoc
+++ b/adoc/p_semicolon.adoc
@@ -13,10 +13,8 @@ Data stack: ( -- )
 by means of adding an <<p_exit,EXIT>>
 
 ====
-.Word: :
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for ;
+****
 : ; IMMEDIATE ' EXIT , ;
-----
+****
 ====
-

diff --git a/adoc/p_stream.adoc b/adoc/p_stream.adoc
index cec3e9a1227bb3917d2e5e3e005c3e582c0f557b..6143ef0f7b15559b7536f2be0da9402f90be2e80 100644 (file)
--- a/adoc/p_stream.adoc
+++ b/adoc/p_stream.adoc
@@ -16,8 +16,8 @@ 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 ']
+.file descriptor stream
+[caption='Layout {counter:layout}: ']
 ----
   8 bytes = size of buffer (excluding the 32 byte header)
   8 bytes source file descriptor
@@ -33,8 +33,8 @@ A memory block stream is only the header (though allocated via
 following layout:
 
 ====
-.memory block
-[caption='Stream layout {counter:layout}, for ']
+.memory block stream
+[caption='Layout {counter:layout}: ']
 ----
   8 bytes = block address
   8 -1 (indicates memory block)

diff --git a/adoc/p_tfa2flags_get.adoc b/adoc/p_tfa2flags_get.adoc
index 5ded0d4f4055ff1eb0c323a0b43e88d56fb7dcee..8e5ed3395568dc54f83078205f79236df3bc95f3 100644 (file)
--- a/adoc/p_tfa2flags_get.adoc
+++ b/adoc/p_tfa2flags_get.adoc
@@ -11,9 +11,8 @@ Data stack: ( tfa -- flags )
 "TFA>FLAGS@" is a function word that pushes word flags of the given tfa.
 
 ====
-.Word: TFA>FLAGS@
-[caption='Defintion concept {counter:exec}']
-----
+.Defintion concept for TFA>FLAGS@
+****
 : TFA>FLAGS@ 16 + @ ;
-----
+****
 ====

diff --git a/adoc/p_tfa2namez.adoc b/adoc/p_tfa2namez.adoc
index 074ead9ff37c82fd32c7216053e884825e4faf01..16db5db860a0992339f782ca394f1654448014e8 100644 (file)
--- a/adoc/p_tfa2namez.adoc
+++ b/adoc/p_tfa2namez.adoc
@@ -14,7 +14,7 @@ terminated as well as preceded by a length cell.
 
 ====
 .Defintion concept for TFA>NAMEZ
-----
+****
 : TFA>NAMEZ 32 + ;
-----
+****
 ====

diff --git a/adoc/p_tuck.adoc b/adoc/p_tuck.adoc
index 965f0d3c73d993849cadd6972c7a45c6a92533ca..452d163a2ca3d576ee8b3c5e4638e7a22d5c15b0 100644 (file)
--- a/adoc/p_tuck.adoc
+++ b/adoc/p_tuck.adoc
@@ -12,9 +12,8 @@ Data stack ( v1 v2 -- v2 v1 v2 )
 cell on the data stack.
 
 ====
-.Word: TUCK
-[caption='Definition concept {counter:exec}: ']
-----
+.Definition concept for TUCK
+****
 : TUCK SWAP OVER ;
-----
+****
 ====

diff --git a/adoc/p_within.adoc b/adoc/p_within.adoc
index 911325f0fff828e8d985e038dafb722869b78b1b..ca2314685de174eca51c17dce7632017928fffa8 100644 (file)
--- a/adoc/p_within.adoc
+++ b/adoc/p_within.adoc
@@ -13,9 +13,8 @@ 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}: ']
-----
+.Definition concept for WITHIN
+****
 : WITHIN 2 PICK > ROT ROT <= AND ;
-----
+****
 ====

diff --git a/reference.html b/reference.html
index f57f5c8805811feb0fa67dcb88aee1b7a7ee5d6d..e07df55fc602666ca9823713d05b0677b8251d12 100644 (file)
--- a/reference.html
+++ b/reference.html
@@ -905,6 +905,8 @@ RRQFORTH executon by means of the following instruction sequence:</p></div>
 forthcode:</code></pre>\r
 </div></div>\r
 </div></div>\r
+<div class="paragraph"><p>Note that the FORTH compiler does not invoke an assembler so any\r
+inline assembly code must be provided in its binary form.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -921,6 +923,15 @@ means of optionally adding the subsequent branch offset, or not, to
 the point of execution. If the value, v, is 0 then the branch offset\r
 is added, and otherwise execution continues with the cell following\r
 the branch offset in the definition.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first non-zero\r
+value.</p></div>\r
+<div class="paragraph"><p>See also <a href="#p_1branch">1BRANCH</a>, <a href="#p_branch">BRANCH</a>, <a href="#p_if">IF</a>,\r
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -935,7 +946,7 @@ _______________________________________________________
 <div class="paragraph"><p>"0=" is a function word that replaces a value with its logical\r
 complement; the result is zero if the value non-zero, and the result\r
 is non-zero if the value is zero.</p></div>\r
-<div class="paragraph"><p>Compare with <a href="#p_not">NOT</a>.</p></div>\r
+<div class="paragraph"><p>This is the same function as <a href="#p_not">NOT</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -951,14 +962,13 @@ _______________________________________________________
 less than 0, and 0 otherwise.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 1: Word: 0&lt;</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: 0= 0 SWAP &lt; ;</code></pre>\r
+<div class="title">Definition concept for 0&lt;</div>\r
+<div class="paragraph"><p>( v&#8201;&#8212;&#8201;0/1 ) : 0= 0 SWAP &lt; ;</p></div>\r
 </div></div>\r
 </div></div>\r
-<div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and\r
-<a href="#p_lessthan">&lt;</a>.</p></div>\r
+<div class="paragraph"><p>See also <a href="#p_swap">SWAP</a> and <a href="#p_lessthan">&lt;</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -975,6 +985,14 @@ means of optionally adding the subsequent branch offset, or not, to
 the point of execution. If the value, v, is non-zero then the branch\r
 offset is added, and otherwise execution continues with the cell\r
 following the branch offset in the definition.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first zero value.</p></div>\r
+<div class="paragraph"><p>See also <a href="#p_0branch">0BRANCH</a>, <a href="#p_branch">BRANCH</a>, <a href="#p_if">IF</a>,\r
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1003,10 +1021,10 @@ _______________________________________________________
 stack.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 2: Word: 2DUP</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: 2DUP OVER OVER ;</code></pre>\r
+<div class="title">Definition concept for 2DUP</div>\r
+<div class="paragraph"><p>( v1 v2&#8201;&#8212;&#8201;v1 v2 v1 v2 ) : 2DUP OVER OVER ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -1039,10 +1057,10 @@ onto the top of the data stack. This is similar to <a href="#p_over">OVER</a> bu
 working with cell pairs rather than single cells.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 3: Word: 2OVER</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: 2OVER 3 PICK 3 PICK ;</code></pre>\r
+<div class="title">Definition concept for 2OVER</div>\r
+<div class="paragraph"><p>( v1 v2 v3 v4&#8201;&#8212;&#8201;v1 v2 v3 v4 v1 v2 ) : 2OVER 3 PICK 3 PICK ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -1075,10 +1093,10 @@ the upper and lower pair. This is similar to <a href="#p_swap">SWAP</a> but
 working with cell pairs rather than single cells.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 4: Word: 2SWAP</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: 2SWAP 3 ROLL 3 ROOL ;</code></pre>\r
+<div class="title">Definition concept for 2SWAP</div>\r
+<div class="paragraph"><p>( v1 v2 v3 v4&#8201;&#8212;&#8201;v3 v4 v1 v2 ) : 2SWAP 3 ROLL 3 ROLL ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -1097,10 +1115,10 @@ _______________________________________________________
 at the current free head address, which also is incremented.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 5: Word: C,</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: C, HERE @ 1 ALLOT C! ;  ( v -- ; Claim 1 byte and put lsb value there )</code></pre>\r
+<div class="title">Definition concept for C,</div>\r
+<div class="paragraph"><p>: C, HERE @ 1 ALLOT C! ;  ( v&#8201;&#8212;&#8201;; Claim 1 byte and put lsb value there )</p></div>\r
 </div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_comma">[p_comma]</a>. <a href="#p_here">HERE</a>, <a href="#p_get">@</a>,\r
@@ -1253,10 +1271,6 @@ numerical base is set to 10 or 16 by <a href="#p_decimal">DECIMAL</a> and
 supported.</p></div>\r
 <div class="paragraph"><p>See also <a href="#p_digits">DIGITS</a>, which holds the mapping table from\r
 digits to text.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="paragraph"><div class="title">Usage example 3: claim 16 bytes for variable FOO</div><p>CREATE FOO BASE</p></div>\r
-</div></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1274,6 +1288,25 @@ implement structured execution control. BEGIN simply places the
 address for resolving branches back to this point during execution,\r
 and then a 0 as a marker so as to allow for an unknown number of block\r
 exit points.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 3:</div>\r
+<div class="content">\r
+<pre><code>: WTELL ( tfa -- ; Print word pname )\r
+  24 + DUP 8 + SWAP @ TELL SP EMIT\r
+;\r
+\r
+: WORDS ( wordlist -- ; Print all words of word list )\r
+  BEGIN\r
+    @ DUP 0= IFBREAK\r
+    DUP WTELL\r
+  END\r
+  DROP\r
+  NL EMIT\r
+;</code></pre>\r
+</div></div>\r
+</div></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1287,6 +1320,14 @@ _______________________________________________________
 </div></div>\r
 <div class="paragraph"><p>"[']" is an immediate function word that reads the next word on the\r
 input stream and pushes its cfa.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="sidebarblock">\r
+<div class="content">\r
+<div class="title">Definition concept for [']</div>\r
+<div class="paragraph"><p>: ['] IMMEDIATE ' ;</p></div>\r
+</div></div>\r
+</div></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1301,6 +1342,14 @@ _______________________________________________________
 <div class="paragraph"><p>"BRANCH" is a function word that implements execution transfer by\r
 means of adding the subsequent branch offset to the point of\r
 execution.</p></div>\r
+<div class="paragraph"><p>Note that the branch offset is a byte count and each FORTH word of a\r
+definition take up a cell of 8 bytes. The offset is relative to the\r
+cell address immediately subsequent to the offset cell. In other\r
+words, offset 0 is not branching anywhere and an offset of -16 would\r
+make a tight loop back to the branch instruction itself. The latter\r
+would pull data stack values until and including the first zero value.</p></div>\r
+<div class="paragraph"><p>See also <a href="#p_0branch">0BRANCH</a>, <a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>,\r
+<a href="#p_else">ELSE</a>, <a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1313,6 +1362,27 @@ branch out of an enclosing xef:p_begin[BEGIN]-<a href="#p_end">END</a> block.
 Similar to <a href="#p_ifbreak">IFBREAK</a> it lays out the branch cell\r
 followed by a reserved cell for the branch offset, and inserts the\r
 resolution address just above the required 0 on the data stack.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 4: unconditional break with a condition.</div>\r
+<div class="content">\r
+<pre><code>: WTELL ( tfa -- ; Print word pname )\r
+  24 + DUP 8 + SWAP @ TELL SP EMIT\r
+;\r
+\r
+: WORDS ( wordlist -- ; Print all words of word list )\r
+  BEGIN\r
+    @ DUP IF DUP WTELL ELSE BREAK THEN\r
+  END\r
+  DROP\r
+  NL EMIT\r
+;</code></pre>\r
+</div></div>\r
+</div></div>\r
+<div class="paragraph"><p>See also <a href="#p_branch">BRANCH</a>, <a href="#p_0branch">0BRANCH</a>,\r
+<a href="#p_1branch">1BRANCH</a>, <a href="#p_if">IF</a>, <a href="#p_else">ELSE</a>,\r
+<a href="#p_ifbreak">IFBREAK</a> and <a href="#p_ifagain">IFAGAIN</a>.</p></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -1373,10 +1443,10 @@ This includes reading the next word for making a new dictionary entry
 and setting evaluation state to compiling mode.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 6: Word: :</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: : doFORTH READ-WORD CREATE TFA&gt;CFA ! ] ;</code></pre>\r
+<div class="title">Definition concept for :</div>\r
+<div class="paragraph"><p>: : doFORTH READ-WORD CREATE TFA&gt;CFA ! ] ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_doforth">doFORTH</a>, <a href="#p_read_word">READ-WORD</a>,\r
@@ -1397,10 +1467,10 @@ _______________________________________________________
 <a href="#p_here">HERE</a> heap.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept7: Word: ,</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: , HERE @ 8 ALLOT ! ; ( v -- ; Claim 8 bytes and put value there )</code></pre>\r
+<div class="title">Definition concept for ,</div>\r
+<div class="paragraph"><p>: , HERE @ 8 ALLOT ! ; ( v&#8201;&#8212;&#8201;; Claim 8 bytes and put value there )</p></div>\r
 </div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_Ccomma">[p_Ccomma]</a>. <a href="#p_here">HERE</a>, <a href="#p_get">@</a>,\r
@@ -1422,6 +1492,7 @@ Address) of the word. The header memory layout is as follows:</p></div>
 <div class="exampleblock">\r
 <div class="content">\r
 <div class="listingblock">\r
+<div class="title">Layout 1: rrqforth word structure</div>\r
 <div class="content">\r
 <pre><code>struct WORD\r
 TFA  8 link ; tfa of previous word\r
@@ -1448,10 +1519,10 @@ function words initiated by ":" (aka "COLON") or changed to "dovalue"
 for RRQFORTH constants created by "CONSTANT".</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 8: Word: CREATE</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>HERE @ R&gt; ( save tfa on RS )\r
+<div class="title">Definition concept for CREATE</div>\r
+<div class="paragraph"><p>HERE @ R&gt; ( save tfa on RS )\r
   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )\r
   DUP 49 + R@ + ,             ( pCFA )\r
   0 ,                         ( flags )\r
@@ -1459,13 +1530,16 @@ for RRQFORTH constants created by "CONSTANT".</p></div>
   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )\r
   R@ ,                        ( pTFA )\r
   0 ,                         ( OFF )\r
-  doVARIABLE                  ( CFA, default semantics )</code></pre>\r
+  doVARIABLE                  ( CFA, default semantics )</p></div>\r
 </div></div>\r
 </div></div>\r
-<div class="sidebarblock">\r
+<div class="exampleblock">\r
+<div class="content">\r
+<div class="listingblock">\r
+<div class="title">Usage example 5: a possible definition of CONSTANT</div>\r
 <div class="content">\r
-<div class="title">Usage example: a possible definition of CONSTANT</div>\r
-<div class="paragraph"><p>: CONSTANT READ-WORD CREATE TFA&gt;DFA doVALUE OVER 8 - ! ! ;</p></div>\r
+<pre><code>: CONSTANT READ-WORD CREATE TFA&gt;DFA doVALUE OVER 8 - ! ! ;</code></pre>\r
+</div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_put">!</a>, <a href="#p_plus">+</a>, <a href="#p_comma">[p_comma]</a>, <a href="#p_get">@</a>,\r
 <a href="#p_Ccomma">[p_Ccomma]</a>, <a href="#p_current_word">CURRENT-WORD</a>, <a href="#p_dup">DUP</a>,\r
@@ -1490,7 +1564,7 @@ word list word content is as follows:</p></div>
 <div class="exampleblock">\r
 <div class="content">\r
 <div class="listingblock">\r
-<div class="title">Layout 1: word list word content</div>\r
+<div class="title">Layout 2: word list word content</div>\r
 <div class="content">\r
 <pre><code>  8 TFA of latest word in the word list\r
   8 DFA of the/a subsequent word list to search through</code></pre>\r
@@ -1525,10 +1599,10 @@ _______________________________________________________
 <div class="paragraph"><p>"DECIMAL" is a function word that sets <a href="#p_base">BASE</a> to 10.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 9: Word: DECIMAL</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: DECIMAL 10 BASE ! ;</code></pre>\r
+<div class="title">Definition concept for DECIMAL</div>\r
+<div class="paragraph"><p>: DECIMAL 10 BASE ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -1652,16 +1726,16 @@ offset to the current heap address. I.e., the word being defined will
 have its execution start at whatever comes after "DOES&gt;".</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Word: DOES&gt;</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: DOES&gt; IMMEDIATE\r
+<div class="title">Defintion concept for DOES&gt;</div>\r
+<div class="paragraph"><p>: DOES&gt; IMMEDIATE\r
 STATE @ != IF ( only for compilation mode )\r
   CURRENT-WORDLIST @ @ TFA&gt;CFA    ( cfa of current word )\r
     doDOES OVER !                 ( set up doer )\r
     HERE @ OVER 8 + - SWAP 8 - !  ( set up offset\r
   THEN\r
-;</code></pre>\r
+;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also\r
@@ -1936,14 +2010,6 @@ execution.</p></div>
 stack while reading, parsing and executing.</p></div>\r
 <div class="paragraph"><p>If "EVALUATE-STREAM" ends with 0, then <a href="#p_this_word">THIS-WORD</a> holds\r
 the [n:chars] reference of the offending word in the stream buffer.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 10: Word: EVALUATE-STREAM</div>\r
-<div class="content">\r
-<pre><code>( too complex to include here )</code></pre>\r
-</div></div>\r
-</div></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -2082,10 +2148,10 @@ _______________________________________________________
 then decrements the cell at that address by n.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept 11Word: @n++</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: @n++ OVER @ DUP ROT - ROT ! ;</code></pre>\r
+<div class="title">Defintion concept for @n++</div>\r
+<div class="paragraph"><p>: @n++ OVER @ DUP ROT - ROT ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2163,10 +2229,13 @@ _______________________________________________________
 </div></div>\r
 <div class="paragraph"><p>"HERE" is a variable word that keeps the lowest address of the free\r
 allocation space. It get updated by all words that allocate memory.</p></div>\r
+<div class="exampleblock">\r
+<div class="content">\r
 <div class="sidebarblock">\r
 <div class="content">\r
-<div class="title">Usage example</div>\r
-<div class="paragraph"><p>1024 HEAP @ + HEAP ! ( allocate 1024 bytes on the heap )</p></div>\r
+<div class="title">allocate 1024 bytes on the heap</div>\r
+<div class="paragraph"><p>1024 HEAP @ + HEAP !</p></div>\r
+</div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_allot">ALLOT</a>.</p></div>\r
 <div style="text-align:center">\r
@@ -2185,10 +2254,10 @@ letters a-f as additional digits. (Uppercase letter are also accepted
 on input).</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 12: Word: HEX</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: HEX 16 BASE ! ;</code></pre>\r
+<div class="title">Definition concept for HEX</div>\r
+<div class="paragraph"><p>: HEX 16 BASE ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2257,10 +2326,10 @@ _______________________________________________________
 the most recent word to 1, thereby making that word an immediate word.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 13:Word: IMMEDIATE</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</code></pre>\r
+<div class="title">Definition concept for IMMEDIATE</div>\r
+<div class="paragraph"><p>: IMMEDIATE IMMEDIATE 1 CURRENT-WORDLIST @ @ 16 + ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div class="paragraph"><p>See also <a href="#p_colon">:</a>, <a href="#p_current_wordlist">CURRENT-WORDLIST</a>,\r
@@ -2281,10 +2350,10 @@ mode to be intepreting. In this mode, words are executed immediately
 after parsing, by invoking their "doer".</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 14: Word: [</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: [ IMMEDIATE 0 STATE ! ;</code></pre>\r
+<div class="title">Definition concept for [</div>\r
+<div class="paragraph"><p>: [ IMMEDIATE 0 STATE ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2334,10 +2403,10 @@ with the CFA pointer following the value.</p></div>
 <div class="paragraph"><p>It&#8217;s not a good idea to use "LIT" interactively.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 15: Word: LIT</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: LIT R&gt; DUP 8 + &gt;R @ ;</code></pre>\r
+<div class="title">Definition concept for LIT</div>\r
+<div class="paragraph"><p>: LIT R&gt; DUP 8 + &gt;R @ ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2356,10 +2425,10 @@ inlined subsequently to it in the containing definition. This is
 similar to <a href="#p_lit">LIT</a> but for a string literal.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 16: Word: LIT</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: LIT R&gt; DUP @ 2DUP + 8 + &gt;R SWAP 8 + SWAP ;</code></pre>\r
+<div class="title">Definition concept for LIT</div>\r
+<div class="paragraph"><p>: LIT R&gt; DUP @ 2DUP + 8 + &gt;R SWAP 8 + SWAP ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2470,10 +2539,10 @@ _______________________________________________________
 on the data stack.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 17: Word: NIP</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: NIP SWAP DROP ;</code></pre>\r
+<div class="title">Definition concept for NIP</div>\r
+<div class="paragraph"><p>: NIP SWAP DROP ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2521,14 +2590,6 @@ a 1 on top, or just a 0 if the word didn&#8217;t parse.</p></div>
 base, letters a-f or A-F for values 10-15. I.e. the normal positive or\r
 negative decimal integers or normal (positive only) hexadecimal\r
 integers.</p></div>\r
-<div class="exampleblock">\r
-<div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 18: Word: NUMBER</div>\r
-<div class="content">\r
-<pre><code>( too complex to include here )</code></pre>\r
-</div></div>\r
-</div></div>\r
 <div style="text-align:center">\r
 _______________________________________________________\r
 </div>\r
@@ -2758,10 +2819,10 @@ left on the stack.</p></div>
 wordlist; i.e., the word list may contain definitions for numbers.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 19: Word: ]</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: ] 1 STATE ! ;</code></pre>\r
+<div class="title">Definition concept for ]</div>\r
+<div class="paragraph"><p>: ] 1 STATE ! ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2823,10 +2884,10 @@ _______________________________________________________
 by means of adding an <a href="#p_exit">EXIT</a></p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 20: Word: :</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: ; IMMEDIATE ' EXIT , ;</code></pre>\r
+<div class="title">Definition concept for ;</div>\r
+<div class="paragraph"><p>: ; IMMEDIATE ' EXIT , ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -2941,7 +3002,7 @@ prefixed by a 32 byte STREAM header of the following layout:</p></div>
 <div class="exampleblock">\r
 <div class="content">\r
 <div class="listingblock">\r
-<div class="title">Stream layout 2, for file descriptor</div>\r
+<div class="title">Layout 3: file descriptor stream</div>\r
 <div class="content">\r
 <pre><code>  8 bytes = size of buffer (excluding the 32 byte header)\r
   8 bytes source file descriptor\r
@@ -2958,7 +3019,7 @@ following layout:</p></div>
 <div class="exampleblock">\r
 <div class="content">\r
 <div class="listingblock">\r
-<div class="title">Stream layout 3, for memory block</div>\r
+<div class="title">Layout 4: memory block stream</div>\r
 <div class="content">\r
 <pre><code>  8 bytes = block address\r
   8 -1 (indicates memory block)\r
@@ -3134,10 +3195,10 @@ _______________________________________________________
 <div class="paragraph"><p>"TFA&gt;FLAGS@" is a function word that pushes word flags of the given tfa.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept 21Word: TFA&gt;FLAGS@</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: TFA&gt;FLAGS@ 16 + @ ;</code></pre>\r
+<div class="title">Defintion concept for TFA&gt;FLAGS@</div>\r
+<div class="paragraph"><p>: TFA&gt;FLAGS@ 16 + @ ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -3156,10 +3217,10 @@ pointer to the word pname&#8217;s character sequence, which is zero
 terminated as well as preceded by a length cell.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Defintion concept for TFA&gt;NAMEZ</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: TFA&gt;NAMEZ 32 + ;</code></pre>\r
+<div class="title">Defintion concept for TFA&gt;NAMEZ</div>\r
+<div class="paragraph"><p>: TFA&gt;NAMEZ 32 + ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -3222,10 +3283,10 @@ _______________________________________________________
 cell on the data stack.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 22: Word: TUCK</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: TUCK SWAP OVER ;</code></pre>\r
+<div class="title">Definition concept for TUCK</div>\r
+<div class="paragraph"><p>: TUCK SWAP OVER ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r
@@ -3272,10 +3333,10 @@ of the the first, v, is within the value range spanned by the second,
 lo, inclusive and third, hi, exclusive.</p></div>\r
 <div class="exampleblock">\r
 <div class="content">\r
-<div class="listingblock">\r
-<div class="title">Definition concept 23: Word: WITHIN</div>\r
+<div class="sidebarblock">\r
 <div class="content">\r
-<pre><code>: WITHIN 2 PICK &gt; ROT ROT &lt;= AND ;</code></pre>\r
+<div class="title">Definition concept for WITHIN</div>\r
+<div class="paragraph"><p>: WITHIN 2 PICK &gt; ROT ROT &#8656; AND ;</p></div>\r
 </div></div>\r
 </div></div>\r
 <div style="text-align:center">\r