upgrade

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

diff --git a/adoc/p_branch.adoc b/adoc/p_branch.adoc
index 9e4d0d27c0fe5bc672899cd70b87ae538861f9f8..02f7319524a56e57218e68c6974fe9b51727c03c 100644 (file)
--- a/adoc/p_branch.adoc
+++ b/adoc/p_branch.adoc
@@ -1,4 +1,4 @@
-// rrqforth.asm:       WORD p_branch,'BRANCH',fasm
+// control.asm:        WORD p_branch,'BRANCH',fasm
 
 anchor:p_branch[]
 
@@ -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>>.