X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=adoc%2Fp_branch.adoc;h=02f7319524a56e57218e68c6974fe9b51727c03c;hb=42844a6fe395162a374bd7bb6e8ed9a04b8d580c;hp=b555fd6cc2c1d6b2baf3ae80222d4e6735bd52bf;hpb=b7da3f7bbd1cb10241163abdb950472e539e796d;p=rrq%2Frrqforth.git

diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc
index b555fd6..02f7319 100644
--- a/adoc/p_branch.adoc
+++ b/adoc/p_branch.adoc
@@ -1,9 +1,23 @@
+// control.asm:	WORD p_branch,'BRANCH',fasm
+
 anchor:p_branch[]
 
-Word: BRANCH
-----------
+=== Word: BRANCH
+
+....
+Data stack: ( -- )
+....
+
+"BRANCH" is a function word that implements execution transfer by
+means of adding the subsequent branch offset to the point of
+execution.
 
-----
-rrqforth.asm:	WORD p_branch,'BRANCH',fasm
-----
+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>>.