From 733c17ad3aeed08e37c10b35bf56812c893904ac Mon Sep 17 00:00:00 2001
From: Irmen de Jong <irmen@razorvine.net>
Date: Wed, 19 Oct 2022 23:53:15 +0200
Subject: [PATCH] improve docs on if syntax. fixes #81

---
 docs/source/programming.rst     | 26 ++++++++++++++++++--------
 docs/source/syntaxreference.rst | 14 +++++++++-----
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/docs/source/programming.rst b/docs/source/programming.rst
index 8b4de1021..e3770b8dd 100644
--- a/docs/source/programming.rst
+++ b/docs/source/programming.rst
@@ -514,16 +514,26 @@ if statements
 Conditional execution means that the flow of execution changes based on certiain conditions,
 rather than having fixed gotos or subroutine calls::
 
-	if aa>4 goto overflow
+    if xx==5 {
+        yy = 99
+        zz = 42
+    } else {
+        aa = 3
+        bb = 9
+    }
 
-	if xx==3  yy = 4
-	if xx==3  yy = 4 else  aa = 2
+    if xx==5
+        yy = 42
+    else if xx==6
+        yy = 43
+    else
+        yy = 44
 
-	if xx==5 {
-		yy = 99
-	} else {
-		aa = 3
-	}
+    if aa>4 goto some_label
+
+    if xx==3  yy = 4
+
+    if xx==3  yy = 4 else  aa = 2
 
 
 Conditional jumps (``if condition goto label``) are compiled using 6502's branching instructions (such as ``bne`` and ``bcc``) so
diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst
index 4f708359a..cb185e5f6 100644
--- a/docs/source/syntaxreference.rst
+++ b/docs/source/syntaxreference.rst
@@ -783,19 +783,23 @@ Note: to do an indirect *JSR* to a routine with a varying address, you can use t
 (which is not very efficient) or you have to write a small piece of inline assembly.
 
 
-Conditional execution
-^^^^^^^^^^^^^^^^^^^^^
+if statements
+^^^^^^^^^^^^^
 
 With the 'if' / 'else' statement you can execute code depending on the value of a condition::
 
 	if  <expression>  <statements>  [else  <statements> ]
 
-where <statements> can be just a single statement for instance just a ``goto``, or it can be a block such as this::
+If  <statements> is just a single statement, for instance just a ``goto`` or a single assignment,
+it's possible to just write the statement without any curly braces.
+However if <statements> is a block of multiple statements, you'll have to enclose it in curly braces::
 
 	if  <expression> {
 		<statements>
+	} else if <expression> {
+		<statements>
 	} else {
-	  	<alternative statements>
+		<statements>
 	}
 
 
@@ -807,7 +811,7 @@ itself defines on what status register bit it should branch on::
 
 	if_XX  <statements>  [else  <statements> ]
 
-where <statements> can be just a single statement for instance just a ``goto``, or it can be a block such as this::
+where <statements> can be just a single statement or a block again::
 
 	if_XX {
 		<statements>