more and better documentation and some reorganisation

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

diff --git a/adoc/p_allot.adoc b/adoc/p_allot.adoc
index cf6e3b9e1e27f553b3e021259ce77be2a31e127e..304ce2ab65fa0439111e69fc4e2ef5220e0762b9 100644 (file)
--- a/adoc/p_allot.adoc
+++ b/adoc/p_allot.adoc
@@ -1,26 +1,24 @@
-anchor:p_allot[]
+// compile.asm:        WORD p_allot,'ALLOT',fasm
 
-Word: ALLOT
------------
+anchor:p_allot[]
 
-----
-compile.asm:   WORD p_allot,'ALLOT',fasm
-----
+=== Word: ALLOT
 
+....
 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 !
-;
+.Defintion concept for ALLOT
+****
+( n -- ) : ALLOT HERE @ + HERE ! ;
+****
 ====
 
-.Usage example
 ====
-HERE @ 16 ALLOT ( -- p ; Claiming 16 bytes )
+.Usage example {counter:example}: claim 16 bytes for variable FOO
+CREATE FOO DROP HERE @ 16 ALLOT
 ====
-