From dd880c8dea31e102a2648eec2af9282597de4239 Mon Sep 17 00:00:00 2001
From: Charles Haley <cbhaley@i.wont.say.com>
Date: Mon, 15 Sep 2025 13:20:35 +0100
Subject: [PATCH] Update the template language documentation to include the new
 'with' statement

---
 manual/template_lang.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/manual/template_lang.rst b/manual/template_lang.rst
index 069dd327bc..c8ad504fa1 100644
--- a/manual/template_lang.rst
+++ b/manual/template_lang.rst
@@ -279,6 +279,7 @@ General Program Mode
     for_range       ::= 'for' identifier 'in' range_expr ':' expression_list 'rof'
     range_expr      ::= 'range' '(' [ start_expr ',' ] stop_expr
                         [ ',' step_expr [ ',' limit_expr ] ] ')'
+    with_expr       ::= 'with' top_expression ':' expression_list 'htiw'
     list_expr       ::= top_expression
     break_expr      ::= 'break'
     continue_expr   ::= 'continue'
@@ -381,6 +382,29 @@ If the original Genre is `History.Military, Science Fiction.Alternate History, R
 
 Note: the last line in the template, ``new_tags``, isn't strictly necessary in this case because ``for`` returns the value of the last top_expression in the expression list. The value of an assignment is the value of its expression, so the value of the ``for`` statement is what was assigned to ``new_tags``.
 
+**with expressions**
+
+The ``with`` expression:
+
+#. changes the current book to the book with calibre book id (an integer) produced by valuating the ``top_expression``.
+#. runs the ``expression_list``.
+#. then resets the current book back to what it was.
+
+The ``with`` expression returns the result of the last ``top_expression`` in the evaluated
+``expression_list``, or the empty string if no expression list was evaluated.
+
+For example, this template returns a list of the titles of each book selected in the GUI::
+
+  program:
+    res = '';
+    ids = selected_books();
+    for id in ids:
+        with id:
+            res = (if res then res & ', ' fi) & $title
+        htiw
+    rof;
+    res
+
 **Return stmt**
 
 Return the value of the ``expression``. If executed in a function then it returns the value of the expression to the caller. If executed in the outermost context (the template) then it sets the value of the template to the value of the expression and exits the template.