Improve macro docs with copilot

- all .md files and java snippets replaced with summaries, examples and use cases.
- examples in the macro docs are verified via a test case MacroTestsForDocsExamples.java
- fix bytes macro and test and make it just work for a single value.
- use InjectTemporaryDirectory

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

Add test case references to macro documentation files

Macro: add ${bytes} example for a list of bytes

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

reviewed batch of macros

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

macro apply: review and add test

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

Add tests for 67 additional macros to MacroTestsForDocsExamples

Add test case reference footers to 67 newly tested macro documentation files

review and improve tests for macros

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>

review and implement tests for ${p_* macros

Signed-off-by: Christoph Rueger <chrisrueger@gmail.com>
Co-Authored-By: chrisrueger <188422+chrisrueger@users.noreply.github.com>

Author: Copilot

.github/copilot-instructions.md

@@ -180,7 +180,11 @@ Bridge between Eclipse extension registry and OSGi Declarative Services:
 - Documentation in `docs/` directory
 - Jekyll-based site at https://bnd.bndtools.org
 - Instructions documented in `docs/_instructions/`
-- Changes/releases documented in wiki
+- Macros documented in `docs/_macros/` and tested in `biz.aQute.bndlib.tests/test/MacroTestsForDocsExamples.java` (also see `biz.aQute.bndlib.tests/test/test/MACRO_TESTING_README.md` for instructions keeping examples in sync with `MacroTestsForDocsExamples.java`)
+- bnd CLI commands documented in `docs/_commands/`
+- bnd and OSGi MANIFEST headers documented in `docs/_heads/`
+- Changes/releases documented in wiki (https://github.com/bndtools/bnd/wiki)
+- Release Process documented in https://github.com/bndtools/bnd/wiki/Release-Process
 
 ## Contribution Workflow
 

DEV_README.md

@@ -551,4 +551,97 @@ tar -xzf "$JDK_FILE" --strip-components=1 -C "$JDK_EXTRACT_DIR"
 rm "$JDK_FILE"  # Clean up downloaded archive
 
 echo "All JDKs downloaded and extracted!"
-```
+```
+
+
+## Macro Documentation Testing
+
+### Overview
+
+The test `/biz.aQute.bndlib.tests/test/test/MacroTestsForDocsExamples.java` is a comprehensive test suite for validating macro documentation examples in `docs/_macros/*.md` files.
+
+### Purpose
+
+The goal of test suite is that:
+1. All macro examples in documentation actually work
+2. Expected outputs match actual macro behavior
+3. Syntax errors in documentation are caught
+4. Users can rely on documentation examples
+
+
+### Test Structure
+
+Each test follows this pattern:
+
+```java
+// ===== filename.md =====
+@Test
+public void testMacroName() throws IOException {
+    try (Processor p = new Processor()) {
+        String result = p.getReplacer().process("${macro;args}");
+        assertThat(result).isEqualTo("expected");
+    }
+}
+```
+
+The comment indicates which documentation file the test validates.
+
+### Running Tests
+
+```bash
+# Run all macro documentation tests
+./gradlew :biz.aQute.bndlib.tests:test --tests "test.MacroTestsForDocsExamples"
+
+# Run specific test
+./gradlew :biz.aQute.bndlib.tests:test --tests "test.MacroTestsForDocsExamples.testAverage_SimpleList"
+
+# Run with more detail
+./gradlew :biz.aQute.bndlib.tests:test --tests "test.MacroTestsForDocsExamples" --info
+```
+
+### Macro Behavior Reference
+
+#### Common Patterns:
+
+**Boolean-like Returns**:
+- `startswith`, `endswith`: Return original string (truthy) or empty (falsy), not "true"/"false"
+- `def`: Returns property value, not boolean
+- `is`: Returns "true" or "false"
+
+**Numeric Returns**:
+- `average`, `sum`: Strip `.0` from whole numbers (3 not 3.0)
+- `rand`: Returns integer
+- `random`: Returns string identifier (different macro!)
+
+**List Operations**:
+- Most combine multiple list arguments first
+- Zero-based indexing
+- Negative indices count from end
+
+**File Operations**:
+- Often require absolute paths
+- Platform-specific behavior (Windows vs Unix)
+- Path separator differences
+
+### Contributing Macro Documentation and Examples
+
+If you create a new macro then add a new file in `docs/_macros/*.md` with the filename being the name of the macro.
+
+When adding examples to documentation (`docs/_macros/*.md` files):
+1. Add corresponding test to this file
+2. Run test to verify example works
+3. Include comment indicating which .md file
+4. Test both success and failure cases where applicable
+
+## See Also
+
+- `MacroTest.java` - Original comprehensive macro tests
+- `docs/_macros/` - Macro documentation files
+- `biz.aQute.bndlib/src/aQute/bnd/osgi/Macro.java` - Macro implementations
+
+Macros are in the following classes, recognized by methods starting with an underscore:
+
+- `biz.aQute.bndlib/src/aQute/bnd/build/Project.java`
+- `biz.aQute.bndlib/src/aQute/bnd/osgi/Analyzer.java`
+- `biz.aQute.bndlib/src/aQute/bnd/osgi/Builder.java`
+- `biz.aQute.bndlib/src/aQute/bnd/build/Workspace.java`