From 5246daeb5d517ef4d68834537862e928961f6a41 Mon Sep 17 00:00:00 2001
From: Steve Bennett <steveb@workware.net.au>
Date: Sat, 13 May 2023 15:32:40 +1000
Subject: docs: document multi-level break, continue

Signed-off-by: Steve Bennett <steveb@workware.net.au>
---
 jim_tcl.txt | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/jim_tcl.txt b/jim_tcl.txt
index af232c5..0f8569a 100644
--- a/jim_tcl.txt
+++ b/jim_tcl.txt
@@ -3,7 +3,7 @@ Jim Tcl(n)
 
 NAME
 ----
-Jim Tcl v0.82 - reference manual for the Jim Tcl scripting language
+Jim Tcl v0.82+ - reference manual for the Jim Tcl scripting language
 
 SYNOPSIS
 --------
@@ -52,6 +52,10 @@ Some notable differences with Tcl 8.5/8.6/8.7 are:
 
 RECENT CHANGES
 --------------
+Changes since 0.82
+~~~~~~~~~~~~~~~~~~
+1. Multi-level `break` and `continue` are now supported
+
 Changes between 0.81 and 0.82
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 1. `try` now supports trap to match on errorcode
@@ -1882,12 +1886,26 @@ command.  The legal +'options'+ (which may be abbreviated) are:
 
 break
 ~~~~~
-+*break*+
++*break* ?n?+
 
 This command may be invoked only inside the body of a loop command
-such as `for` or `foreach` or `while`.  It returns a +JIM_BREAK+ code
+such as `for`, `foreach`, `while` or `loop`.  It returns a +JIM_BREAK+ code
 to signal the innermost containing loop command to return immediately.
 
+If +'n'+ is given it breaks out of that many loops. +'break 1'+ is equivalent
+to a simple +'break'+ while in the following example, +'break'+ will exit both
+loops.
+
+----
+    loop i 5 {
+        loop j 6 {
+            if {$i == 3 && $j == 2} {
+                break 2
+            }
+        }
+    }
+----
+
 case
 ~~~~
 The obsolete '+*case*+' command has been removed from Jim Tcl since v0.75.
@@ -2032,13 +2050,16 @@ as its result.
 
 continue
 ~~~~~~~~
-+*continue*+
++*continue* ?n?+
 
 This command may be invoked only inside the body of a loop command such
-as `for` or `foreach` or `while`.  It returns a  +JIM_CONTINUE+ code to
+as `for`, `foreach`, `while` or `loop`.  It returns a  +JIM_CONTINUE+ code to
 signal the innermost containing loop command to skip the remainder of
 the loop's body but continue with the next iteration of the loop.
 
+If +'n'+ is given it breaks out of +'n-1'+ loops and then continues the +'nth'+ loop.
++'continue 1'+ is equivalent to a simple +'continue'+. (See also `break`).
+
 curry
 ~~~~~
 +*alias* 'args\...'+
-- 
cgit v1.1