improve recipes

Author: zspitzer

docs/recipes/ai.md

@@ -161,7 +161,7 @@ This feature is still a work in progress, and we are working to improve the qual
 ### Monitor Documentation Tab
 
 In the Monitor's Documentation tab, AI can answer questions about Lucee based on retrieval-augmented generation (RAG) with available documentation and links to related documents.
-This feature is also in development for enhanced input quality (read more about [https://github.com/lucee/lucee-docs/blob/master/docs/recipes/monitoring-debugging.md](Monitor Documentation) ).
+This feature is also in development for enhanced input quality (read more about [Monitor Documentation](monitoring-debugging.md)).
 
 ## Future Development
 

docs/recipes/archives-creating-and-deploy.md

@@ -10,7 +10,7 @@
 
 # Archives - Creating and deploying Lucee Archives (.lar files)
 
-This document explains how to deploy an Application on a live server without using a single CFML file.
+Deploy applications using compiled Lucee Archives (.lar files) without exposing CFML source.
 
 ## Using CFC file
 

docs/recipes/basic-date.md

@@ -20,8 +20,6 @@
 
 # Basic Date - Output the current date
 
-The following examples show you how to output the current date.
-
 ```run
 <cfoutput>
    <p>The time is #lsdateTimeFormat(now())#</p>

docs/recipes/cached-within-request.md

@@ -22,7 +22,7 @@
 
 # Cache a Query for the current request
 
-Perhaps you're familiar with the "cachedwithin" attribute of the tag [tag-query], which is normally used as follows:
+The `cachedWithin` attribute of [tag-query] is normally used like this:
 
 ```coldfusion
 <cfquery cachedWithin="#createTimeSpan(0,0,0,1)#">

docs/recipes/check-for-changes.md

@@ -19,9 +19,7 @@
 
 ## Check for changes in your configuration file automatically
 
-Lucee can automatically check for changes in your configuration files from the complete server or a single web context.
-
-This is useful if you are doing scripted deploys and/or synchronization from, for example, a master instance to many slave instances of Lucee.
+Lucee can automatically check for changes in configuration files - useful for scripted deploys and syncing from a primary instance to many replica instances.
 
 ### Check for Changes - CFconfig.json (6+)
 

docs/recipes/dynamic-proxy-enhancements.md

@@ -26,7 +26,7 @@
 
 # Dynamic Proxy Enhancements in Lucee 7
 
-Lucee 7 introduces significant improvements to dynamic proxy creation, making Java interoperability more seamless and predictable when components implement Java interfaces.
+All component functions and properties are now always included in dynamic proxies, making Java interoperability more predictable.
 
 ## What Changed in Lucee 7
 

docs/recipes/event-gateway-create.md

@@ -19,11 +19,7 @@
 
 # Custom Event Gateways
 
-Here you will find a short introduction into writing your own Event Gateway type.
-
-Since you can write these in pure CFML (and Java when you want it), it is really simple to do.
-
-There are 2 to 3 files you need to create:
+Write custom Event Gateways in pure CFML (or Java). You need 2-3 files:
 
 - the Gateway CFC
 - the Gateway Driver CFC
@@ -37,18 +33,18 @@ Also, it is the file which is instantiated by Lucee when the gateway starts.
 
 You can take the following files as an example:
 
-- {Lucee-install}/lib/lucee-server/context/gateway/lucee/extension/gateway/DirectoryWatcher.cfc
-- {Lucee-install}/lib/lucee-server/context/gateway/lucee/extension/gateway/MailWatcher.cfc
+- `{lucee-server}/context/gateway/DirectoryWatcher.cfc` ([source](https://github.com/lucee/Lucee/blob/7.0/core/src/main/cfml/context/gateway/DirectoryWatcher.cfc))
+- `{lucee-server}/context/gateway/MailWatcher.cfc` ([source](https://github.com/lucee/Lucee/blob/7.0/core/src/main/cfml/context/gateway/MailWatcher.cfc))
 
-The example code shown underneath is a modified version of the DirectoryWatcher.cfc, which, at time of writing, is in line for reviewing at the Lucee team.
+The example code shown underneath is based on `DirectoryWatcher.cfc`.
 
 By default, you need to have the following functions:
 
-- An init function, which receives the necessary config data.
-- A start function, which continues to run while variables.state="running".
-- A stop and restart function.
-- A getState function, which returns the current state of the gateway instance (running, stopping, stopped).
-- A sendMessage function, which will be called when the CFML sendGatewayMessage function is used.
+- An `init` function, which receives the necessary config data.
+- A `start` function, which continues to run while `variables.state="running"`.
+- A `stop` and `restart` function.
+- A `getState` function, which returns the current state of the gateway instance (`running`, `stopping`, `stopped`).
+- A `sendMessage` function, which will be called when the CFML `sendGatewayMessage` function is used.
 
 The following is all the code you need:
 
@@ -98,8 +94,8 @@ The following is all the code you need:
         <cfquery name="qFile" datasource="#variables.config.datasource#">
             SELECT *
             FROM FILE
-            WHERE directory = "#getDirectoryFromPath(variables.config.filepath)#"
-            AND name = "#getFileFromPath(variables.config.filepath)#"
+            WHERE directory = <cfqueryparam value="#getDirectoryFromPath(variables.config.filepath)#" cfsqltype="cf_sql_varchar">
+            AND name = <cfqueryparam value="#getFileFromPath(variables.config.filepath)#" cfsqltype="cf_sql_varchar">
         </cfquery>
 
         <!--- call the listener CFC if the file size meets the minimum requirement --->
@@ -110,11 +106,11 @@ The following is all the code you need:
 </cfcomponent>
 ```
 
-We will save the file as {Lucee-install}/lib/lucee-server/context/gateway/filesizechecker/FileSizeWatcher.cfc.
+We will save the file as `{lucee-server}/context/gateway/filesizechecker/FileSizeWatcher.cfc`.
 
-The variables.listener and variables.config variables did not just come falling from the sky; instead, it was saved to the variables scope in the init() function.
+The `variables.listener` and `variables.config` variables did not just come falling from the sky; instead, they were saved to the variables scope in the `init()` function.
 
-Lastly, we need to create the Gateway driver. We can use the Gateway driver code shown before, and then save it as {Lucee-install}/lib/lucee-server/context/admin/gdriver/FileSizeWatcher.cfc.
+Lastly, we need to create the Gateway driver. We can use the Gateway driver code shown before, and then save it as `{lucee-server}/context/admin/gdriver/FileSizeWatcher.cfc`.
 
 Now we are almost good to go! We do need to restart Lucee to have it pick up the new Gateway driver. So just go to the server admin, click on the menu-item "Restart", and then hit the "Restart Lucee" button.
 

docs/recipes/event-gateways-how-they-work.md

@@ -27,7 +27,7 @@ This looping and sleeping does not count for all types of event gateways. For ex
 
 This "doing what it is designed for" will be explained in more detail underneath.
 
-# Which gateways are available?
+## Which gateways are available?
 
 Lucee comes with 2 gateways: a Directory watcher and a Mail watcher.
 

docs/recipes/exception-output.md

@@ -23,11 +23,11 @@
 }
 -->
 
-# Exceptions Output
+# Exception Output
 
 How to catch and display exceptions
 
-## Example
+## Using dump() for Full Exception Details
 
 ```run
 <cfscript>
@@ -41,9 +41,9 @@ catch ( any e ){
 Go on with your code
 ```
 
-[tag-Dump] shows the full exception structure without blocking your code. Dump includes all stack trace with it.
+[[tag-dump]] shows the full exception structure without blocking your code. Dump includes the full stack trace.
 
-## Example 2
+## Using echo() for Simple Output
 
 ```lucee
 <cfscript>

docs/recipes/function-systemoutput.md

@@ -22,70 +22,47 @@
 
 # Function SystemOutput
 
-This document explains the systemOutput function with some simple examples.
+[[function-systemOutput]] is like [[tag-dump]] for your console - supports complex types. Visible in Docker logs.
 
-It's like dump() for your console, including support for complex types.
-
-For example, if you are using Docker, you can see this output in the console logs.
-
-## Example 1:
+## Browser vs Console
 
 ```luceescript
-<cfscript>
-directory action="list" directory=getDirectoryFromPath(getCurrentTemplatePath()) filter="example*.cfm" name="dir";
-loop query=dir {
-	echo('<a href="#dir.name#">#dir.name#</a><br>');
-}
-</cfscript>
-```
-
-```lucee
-<cfscript>
-dump(cgi); // or writedump if you love to write more
-echo(now()); // or writeoutput if you love to write more
-</cfscript>
+dump(cgi); // browser output (or writeDump if you love to write more)
+echo(now()); // browser output (or writeOutput if you love to write more)
+systemOutput(cgi, true); // console output
+systemOutput(now(), true); // console output
 ```
 
-This example has a simple dump with CGI. It displays normally in the browser while we are running example1.cfm.
-
-## Example 2:
+## New Line
 
 ```luceescript
-// example2.cfm
-systemOutput(now(),true); // with new line
+systemOutput(now(), true); // with new line
 ```
 
-systemOutput() creates output content in the web browser (console). Here the systemoutput has two arguments: first argument _now()_ for current date and time, and second argument _true_ for a new line. Run this in the browser and see the content in the console.
+Second argument `true` adds a newline.
 
-## Example 3:
+## Error Stream
 
 ```luceescript
-// example3.cfm
-systemOutput(now(),true,true); // send to error stream
+systemOutput(now(), true, true); // send to error stream
 ```
 
-This example uses three arguments: first argument `now()` for current date and time, second argument `true` for a new line, and third argument for the stream. The stream argument indicates which stream the output should go. There are two streams to choose from: "Output stream" and "Error stream". A value of true in the third argument indicates the output should go to the error stream. Run this in the browser and see the contents with the output stream in the console.
+Third argument `true` writes to stderr instead of stdout.
 
-## Example 4:
+## Complex Objects
 
 ```luceescript
-// example4.cfm
-systemOutput(cgi,true); // complex object
+systemOutput(cgi, true); // complex object
 ```
 
-In addition to simple strings or simple values, you can also pass complex objects to the SystemOutput() function. In this example we pass CGI as the argument. When you run this in the browser, you get a serialized output in the console.
+Outputs serialized representation of structs, queries, etc.
 
-## Example 5:
+## Stack Trace
 
 ```luceescript
-// example5.cfm
-systemOutput("Here we are:<print-stack-trace>",true); // complex object
+systemOutput("Here we are:<print-stack-trace>", true);
 ```
 
-SystemOutput() has another good feature too. There is `<print-stack-trace>` used to show helpful information (where it is, which template, on which line number) while we mouse over the dump content. Lucee will detect and show the stack-trace if we add `<print-stack-trace>` to the SystemOutput() function in our code. When we run this in the browser, we see the stack-trace in the console.
-
-## Footnotes
-
-Here you can see these details on video also:
+The `<print-stack-trace>` placeholder outputs the current stack trace.
 
-[Function SystemOutput](https://www.youtube.com/watch?v=X_BQPFPD320)
+Video: [Function SystemOutput](https://www.youtube.com/watch?v=X_BQPFPD320)