Improve documentation for string replacement and file listing macros

Copilot · chrisrueger · Copilot · commit 2055b9445d04 · 2025-11-20T08:07:27.000Z
Co-authored-by: chrisrueger &lt;188422+chrisrueger@users.noreply.github.com&gt;
diff --git a/docs/_macros/env.md b/docs/_macros/env.md
@@ -2,9 +2,70 @@
 layout: default
 class: Macro
 title: env ';' KEY (';' STRING)?
-summary: The given environment variable or a default if the environment variable is not defined. The default is an empty string if not specified.
+summary: Get an environment variable with an optional default
 ---
 
-The specified key is looked up in `System.env` and returned. If the environment variable specified
-by key is not set, then the default string is returned. The default is an empty string if not
-specified. 
+## Summary
+
+The `env` macro looks up an environment variable and returns its value, or returns a default value if the variable is not set. The default is an empty string if not specified.
+
+## Syntax
+
+```
+${env;<variable>[;<default>]}
+```
+
+## Parameters
+
+- `variable` - The environment variable name to look up
+- `default` (optional) - Value to return if variable not set (default: empty string)
+
+## Behavior
+
+- Looks up environment variable via `System.getenv()`
+- Returns variable value if set
+- Returns default if variable not set
+- Default is empty string if not specified
+- Case-sensitive on Unix/Linux, case-insensitive on Windows
+
+## Examples
+
+Get environment variable with default:
+```
+${env;JAVA_HOME;/usr/lib/jvm/default}
+```
+
+Check if variable exists:
+```
+${if;${env;CI};running-in-ci;local-build}
+```
+
+Use in paths:
+```
+user.home=${env;HOME;/home/default}
+```
+
+Empty default:
+```
+${env;OPTIONAL_VAR}
+# Returns value or "" if not set
+```
+
+## Use Cases
+
+- Accessing environment configuration
+- CI/CD environment detection
+- User-specific paths
+- System configuration
+- Platform differences
+- Secure credentials (with caution)
+
+## Notes
+
+- Accesses system environment variables
+- Case sensitivity varies by OS
+- Returns default for undefined variables
+- Empty string is valid default
+- **Security**: Be cautious with credentials
+- See also: `${def}` for properties
+- See also: `${system}` for system commands 
diff --git a/docs/_macros/lsa.md b/docs/_macros/lsa.md
@@ -2,9 +2,69 @@
 layout: default
 class: Macro
 title: lsa ';' DIR (';' SELECTORS )
-summary: A list of absolute paths for files in the given directory optionally filtered by  selectors.
+summary: List files with absolute paths, optionally filtered
 ---
 
-The `lsa` macro returns a list of absolute paths for the files in the given directory. The optional selectors can be used to filter the result.
+## Summary
 
-    lsa ; <dir> [ ; <selector> ] *
+The `lsa` macro returns a comma-separated list of absolute file paths from a directory, with optional filtering using selectors.
+
+## Syntax
+
+```
+${lsa;<directory>[;<selector>...]}
+```
+
+## Parameters
+
+- `directory` - Directory path to list (relative to project base)
+- `selector` (optional) - One or more file selectors/patterns to filter results
+
+## Behavior
+
+- Lists files in the specified directory
+- Returns absolute paths
+- Optional filtering with selectors
+- Comma-separated output
+- Non-recursive (single directory level)
+
+## Examples
+
+List all files:
+```
+${lsa;src/main/java}
+# Returns absolute paths
+```
+
+Filter by pattern:
+```
+${lsa;lib;*.jar}
+# Lists all JAR files with absolute paths
+```
+
+Multiple filters:
+```
+${lsa;resources;*.xml;*.properties}
+```
+
+Use in manifest:
+```
+Resources: ${lsa;config}
+```
+
+## Use Cases
+
+- File discovery with absolute paths
+- Build input collection
+- Resource gathering
+- File listing for processing
+- Dependency collection
+
+## Notes
+
+- Returns absolute paths
+- Non-recursive listing
+- Selectors use file patterns
+- See also: `${lsr}` for relative paths
+- See also: `${glob}` for pattern matching
+- See also: `${findfile}` for recursive search
diff --git a/docs/_macros/lsr.md b/docs/_macros/lsr.md
@@ -2,9 +2,70 @@
 layout: default
 class: Macro
 title: lsr ';' DIR (';' SELECTORS )
-summary: A list of file names in the given directory optionally filtered by selectors.
+summary: List files with relative paths, optionally filtered
 ---
 
-The `lsr` macro returns a list of file names in the given directory. The optional selectors can be used to filter the result.
+## Summary
 
-    lsr ; <dir> [ ; <selector> ] *
+The `lsr` macro returns a comma-separated list of relative file paths from a directory, with optional filtering using selectors.
+
+## Syntax
+
+```
+${lsr;<directory>[;<selector>...]}
+```
+
+## Parameters
+
+- `directory` - Directory path to list (relative to project base)
+- `selector` (optional) - One or more file selectors/patterns to filter results
+
+## Behavior
+
+- Lists files in the specified directory
+- Returns relative paths (from the directory)
+- Optional filtering with selectors
+- Comma-separated output
+- Recursive by default
+
+## Examples
+
+List all files:
+```
+${lsr;src/main/java}
+# Returns relative paths
+```
+
+Filter by pattern:
+```
+${lsr;lib;*.jar}
+# Lists all JAR files with relative paths
+```
+
+Find source files:
+```
+${lsr;src;*.java}
+# All Java source files
+```
+
+Multiple patterns:
+```
+${lsr;resources;*.xml;*.properties}
+```
+
+## Use Cases
+
+- File discovery with relative paths
+- Source file collection
+- Resource listing
+- Build inputs
+- Pattern-based file selection
+
+## Notes
+
+- Returns relative paths
+- Recursive listing
+- Selectors use file patterns
+- See also: `${lsa}` for absolute paths
+- See also: `${glob}` for pattern matching
+- See also: `${findfile}` for filtered recursive search
diff --git a/docs/_macros/replace.md b/docs/_macros/replace.md
@@ -2,17 +2,75 @@
 layout: default
 class: Macro
 title: replace ';' LIST ';' REGEX (';' STRING (';' STRING)? )?
-summary: Replace elements in a list when it matches a regular expression
+summary: Replace parts of list elements using regex patterns
 ---
 
-    replace ; <list> ; <regex> [ ; <replacement> [ ; <delimiter> ] ]
+## Summary
 
-Replace all parts within elements of the list that match the regular expression regex with the replacement. The `replace` macro uses a simple splitter, the regular expression `\s*,\s*`, to split the list into elements. So any comma in the input list will be use to split the list into elements. See [replacelist](replacelist.html) for an equivalent macro which has a more sophisticated splitter which takes quoted sections of the string into account.
+The `replace` macro applies regex-based replacement to each element in a comma-separated list. Uses simple comma splitting (doesn't handle quoted sections).
 
-The replacement can use the `$[0-9]` back references defined in the regular expressions. The macro uses `element.replaceAll(regex,replacement)` method to do the replacement. The default replacement is the empty string. The default delimiter is ",".
+## Syntax
+
+```
+${replace;<list>;<regex>[;<replacement>[;<delimiter>]]}
+```
+
+## Parameters
+
+- `list` - Comma-separated list of elements
+- `regex` - Regular expression pattern to match
+- `replacement` (optional) - Replacement string with `$1-$9` back-references (default: empty)
+- `delimiter` (optional) - Output delimiter (default: ",")
+
+## Behavior
+
+- Splits list on commas (simple: `\s*,\s*`)
+- Applies `element.replaceAll(regex, replacement)` to each
+- Supports regex back-references (`$1`, `$2`, etc.)
+- Cannot handle commas within quoted sections
+- Returns delimited result
 
 ## Examples
 
-    impls: foo,bar
-    ${replace;${impls};$;.jar} => foo.jar,bar.jar
+Add file extension:
+```
+impls: foo,bar
+${replace;${impls};$;.jar}
+# Returns: "foo.jar,bar.jar"
+```
+
+Replace pattern:
+```
+${replace;v1.0,v2.0,v3.0;^v;version-}
+# Returns: "version-1.0,version-2.0,version-3.0"
+```
+
+Using back-references:
+```
+${replace;com.example.api,com.example.impl;com\.example\.(.+);$1}
+# Returns: "api,impl"
+```
+
+Custom delimiter:
+```
+${replace;a,b,c;$;-suffix;;}
+# Returns: "a-suffix;b-suffix;c-suffix"
+```
+
+## Use Cases
+
+- Adding prefixes/suffixes to list elements
+- Pattern-based transformations
+- File extension handling
+- List element modification
+- Bulk string operations
+
+## Notes
+
+- Simple comma splitting only
+- For quoted sections, use `${replacelist}`
+- Regex uses Java syntax
+- Empty replacement removes matched text
+- See also: `${replacelist}` for quoted section support
+- See also: `${replacestring}` for single string replacement
 
diff --git a/docs/_macros/replacelist.md b/docs/_macros/replacelist.md
@@ -2,18 +2,68 @@
 layout: default
 class: Macro
 title: replacelist ';' LIST ';' REGEX (';' STRING (';' STRING)? )?
-summary: Replace elements in a list when it matches a regular expression
+summary: Replace parts of list elements using regex with quoted section support
 ---
 
-    replacelist ; <list> ; <regex> [ ; <replacement> [ ; <delimiter> ] ]
+## Summary
 
-Replace all parts within elements of the list that match the regular expression regex with the replacement. The `replacelist` macro uses a sophisticated splitter to split the list into elements. This splitter understands quoted sections within the list and does not split on commas inside the quoted sections.
+The `replacelist` macro applies regex-based replacement to each element in a list. Unlike `${replace}`, it uses a sophisticated splitter that handles quoted sections, preserving commas within quotes.
 
-The replacement can use the `$[0-9]` back references defined in the regular expressions. The macro uses `element.replaceAll(regex,replacement)` method to do the replacement. The default replacement is the empty string. The default delimiter is ",".
+## Syntax
+
+```
+${replacelist;<list>;<regex>[;<replacement>[;<delimiter>]]}
+```
+
+## Parameters
+
+- `list` - List of elements (can contain quoted sections with commas)
+- `regex` - Regular expression pattern to match
+- `replacement` (optional) - Replacement string with `$1-$9` back-references (default: empty)
+- `delimiter` (optional) - Output delimiter (default: ",")
+
+## Behavior
+
+- Splits list intelligently (respects quoted sections)
+- Applies `element.replaceAll(regex, replacement)` to each
+- Supports regex back-references (`$1`, `$2`, etc.)
+- Preserves quoted sections during splitting
+- Returns delimited result
 
 ## Examples
 
-    impls: foo;version="[1,2)", bar;version="[1.2,2)"
-    ${replacelist;${list;impls};$;\\;strategy=highest} =>
-      foo;version="[1,2)";strategy=highest,bar;version="[1.2,2)";strategy=highest
+Add to quoted elements:
+```
+impls: foo;version="[1,2)", bar;version="[1.2,2)"
+${replacelist;${list;impls};$;\\;strategy=highest}
+# Returns: foo;version="[1,2)";strategy=highest,bar;version="[1.2,2)";strategy=highest
+```
+
+Process dependencies:
+```
+deps: lib;version="1.0,2.0",tool;version="2.0"
+${replacelist;${deps};$;,optional}
+```
+
+Back-references with quotes:
+```
+${replacelist;a="x,y",b="z";(.+)="(.+)";$1:$2}
+```
+
+## Use Cases
+
+- OSGi manifest attribute manipulation
+- Dependency list processing
+- Version range handling
+- Complex list transformations
+- Preserving structured data
+
+## Notes
+
+- Handles quoted sections properly
+- More robust than `${replace}` for OSGi attributes
+- Regex uses Java syntax
+- Empty replacement removes matched text
+- See also: `${replace}` for simple splitting
+- See also: `${replacestring}` for single strings
 
diff --git a/docs/_macros/replacestring.md b/docs/_macros/replacestring.md
