From ab6c756d9d82d90c5624d793132b1b1a40a7fc50 Mon Sep 17 00:00:00 2001
From: michaeloffner <michaeloffner@users.noreply.github.com>
Date: Thu, 14 Nov 2024 15:06:12 +0100
Subject: [PATCH] extend recipe

---
 docs/recipes/tag-syntax.md | 70 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/docs/recipes/tag-syntax.md b/docs/recipes/tag-syntax.md
index ce3f7d74a..9766ff143 100644
--- a/docs/recipes/tag-syntax.md
+++ b/docs/recipes/tag-syntax.md
@@ -13,6 +13,9 @@
     "tag",
     "function",
     "Script"
+    "throw"
+    "abort"
+    "return"
   ]
 }
 -->
@@ -92,3 +95,70 @@ loop from="1" to=max index="i" {
 ```
 
 In this case, the `max` variable is evaluated properly, and the code runs without errors.
+
+## Exceptions to the rules
+
+Because some keywords already existed in script, before support for script tags was added to Lucee, this tags could not be added with migration syntax, because they would conflict with the existing keywords.
+This includes the following keywords
+- throw
+- return 
+- abort
+
+So for example this code
+```html
+<cfabort showError="Upsi Dupsi!">
+<cfabort>
+<cfthrow message="Upsi Dupsi!">
+<cfreturn "Upsi Dupsi!">
+```
+
+translates to migration syntax like this (this are not tags)
+```javascript
+abort "Upsi Dupsi!";
+abort;
+throw "Upsi Dupsi!";
+return "Upsi Dupsi!";
+```
+so you can for example not translate this
+```html
+<cfthrow message="Upsi Dupsi!" detail="Upsi dasy!">
+```
+
+to migration syntax, but you can to function syntax like this
+```javascript
+cfthrow (message="Upsi Dupsi!", detail="Upsi dasy!");
+```
+
+
+## Exceptions to Tag-to-Script Migration
+Certain tags cannot be directly translated into migration syntax due to conflicts with existing keywords in Lucee’s script language. This applies to tags that use keywords already reserved in script, such as throw, return, and abort. These keywords function differently in script and don’t support direct migration syntax translation.
+
+### Unsupported Migration Syntax for Specific Tags
+For example, the following tags in tag syntax:
+
+```html
+<cfabort showError="Oops!">
+<cfabort>
+<cfthrow message="Oops!">
+<cfreturn "Oops!">
+```
+translate to the following in script syntax (note: these are not actual tags in script but standalone statements):
+
+```javascript
+abort "Oops!";
+abort;
+throw "Oops!";
+return "Oops!";
+```
+### Example of Syntax Limitation
+Since the throw tag uses additional attributes like message and detail, it cannot be fully expressed in migration syntax. Instead, you’ll need to use function syntax for more complex cases. For example:
+
+```html
+<cfthrow message="Oops!" detail="More details here.">
+```
+would translate to function syntax as follows:
+
+```javascript
+cfthrow(message="Oops!", detail="More details here.");
+```
+Using function syntax here allows you to specify multiple attributes, overcoming the limitations of migration syntax. This flexibility makes function syntax ideal when using tags with additional parameters or complex functionality.