markdown_exec 3.2.0 → 3.3.0

data/docs/dev/hexdump_format.md

@@ -0,0 +1,267 @@
+```bash :(document_shell)
+##
+# hexdump_format
+#
+# Produce a per-byte hex dump of a string in two-line blocks:
+#  • First line shows up to sixteen characters.
+#  • Second line shows the corresponding hex values.
+# An optional LABEL is prepended on the first line, and the second
+# line is padded to align its colon under the first.
+# Uses only Bash built-ins.
+#
+# Usage:
+#   hexdump_format [STRING] [--label LABEL] [--width BYTES] [--offset-width DIGITS] [--start-offset OFFSET] [--end-offset OFFSET] [--character-ansi COLOR] [--hex-ansi COLOR] [--offset-ansi COLOR] [--help]
+#   Options:
+#     STRING                The string to dump (optional first positional argument)
+#     --label LABEL         Optional label to display
+#     --width BYTES         Number of bytes per line (default: 16)
+#     --offset-width DIGITS Number of digits in offset display
+#     --start-offset OFFSET Start offset into the string (default: 0)
+#     --end-offset OFFSET   End offset into the string (default: string length)
+#     --character-ansi COLOR ANSI color code for character display (default: 35)
+#     --hex-ansi COLOR      ANSI color code for hex display (default: 36)
+#     --offset-ansi COLOR   ANSI color code for offset display (default: 33)
+#     --help               Show this help message
+##
+hexdump_format () {
+  # Default values
+  local data=""
+  local label=""
+  local width="16"
+  local offset_width=""
+  local start_offset="0"
+  local end_offset=""
+  local char_ansi_color="35"  # Default character color (magenta)
+  local hex_ansi_color="36"   # Default hex color (cyan)
+  local offset_ansi_color="33" # Default offset color (yellow)
+
+  # Show help if no arguments provided
+  if [[ $# -eq 0 ]]; then
+    echo "Usage: hexdump_format [STRING] [OPTIONS]"
+    echo
+    echo "Display a hex dump of a string with optional formatting."
+    echo
+    echo "Arguments:"
+    echo "  STRING                The string to dump (optional first positional argument)"
+    echo
+    echo "Options:"
+    echo "  --data DATA           The string to dump"
+    echo "  --label LABEL         Optional label to display"
+    echo "  --width BYTES         Number of bytes per line (default: 16)"
+    echo "  --offset-width DIGITS Number of digits in offset display"
+    echo "  --start-offset OFFSET Start offset into the string (default: 0)"
+    echo "  --end-offset OFFSET   End offset into the string (default: string length)"
+    echo "  --character-ansi COLOR ANSI color code for character display (default: 35)"
+    echo "  --hex-ansi COLOR      ANSI color code for hex display (default: 36)"
+    echo "  --offset-ansi COLOR   ANSI color code for offset display (default: 33)"
+    echo "  --help               Show this help message"
+    echo
+    echo "Examples:"
+    echo "  hexdump_format \"Hello World\""
+    echo "  hexdump_format --data \"Hello World\" --width 8"
+    echo "  hexdump_format \"Hello World\" --character-ansi 32 --hex-ansi 31"
+    return 0
+  fi
+
+  # Check if first argument is --help
+  if [[ "$1" == "--help" ]]; then
+    hexdump_format
+    return 0
+  fi
+
+  # Check if first argument is not an option (starts with --)
+  if [[ "$1" != --* ]]; then
+    data="$1"
+    shift
+  fi
+
+  # Process all options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --data)
+        if [[ -z "$2" ]]; then
+          echo "Error: --data requires a value" >&2
+          return 1
+        fi
+        data="$2"
+        shift 2
+        ;;
+      --label)
+        if [[ -z "$2" ]]; then
+          echo "Error: --label requires a value" >&2
+          return 1
+        fi
+        label="$2 "
+        shift 2
+        ;;
+      --width)
+        if [[ -z "$2" ]]; then
+          echo "Error: --width requires a value" >&2
+          return 1
+        fi
+        width="$2"
+        shift 2
+        ;;
+      --offset-width)
+        if [[ -z "$2" ]]; then
+          echo "Error: --offset-width requires a value" >&2
+          return 1
+        fi
+        offset_width="$2"
+        shift 2
+        ;;
+      --start-offset)
+        if [[ -z "$2" ]]; then
+          echo "Error: --start-offset requires a value" >&2
+          return 1
+        fi
+        start_offset="$2"
+        shift 2
+        ;;
+      --end-offset)
+        if [[ -z "$2" ]]; then
+          echo "Error: --end-offset requires a value" >&2
+          return 1
+        fi
+        end_offset="$2"
+        shift 2
+        ;;
+      --character-ansi)
+        if [[ -z "$2" ]]; then
+          echo "Error: --character-ansi requires a value" >&2
+          return 1
+        fi
+        char_ansi_color="$2"
+        shift 2
+        ;;
+      --hex-ansi)
+        if [[ -z "$2" ]]; then
+          echo "Error: --hex-ansi requires a value" >&2
+          return 1
+        fi
+        hex_ansi_color="$2"
+        shift 2
+        ;;
+      --offset-ansi)
+        if [[ -z "$2" ]]; then
+          echo "Error: --offset-ansi requires a value" >&2
+          return 1
+        fi
+        offset_ansi_color="$2"
+        shift 2
+        ;;
+      --help)
+        hexdump_format
+        return 0
+        ;;
+      *)
+        echo "Error: Unknown option: $1" >&2
+        return 1
+        ;;
+    esac
+  done
+
+  # Validate required parameters
+  if [[ -z "$data" ]]; then
+    echo "Error: No data provided. Use --data or provide a string as the first argument." >&2
+    echo "Use --help for usage information." >&2
+    return 1
+  fi
+
+  # Set end_offset to string length if not provided
+  if [[ -z "$end_offset" ]]; then
+    end_offset="${#data}"
+  fi
+
+  local len=${#data}
+  local -i idx=0
+  local esc=$'\e'
+  local char_color="${esc}[${char_ansi_color}m"
+  local hex_color="${esc}[${hex_ansi_color}m"
+  local offset_color="${esc}[${offset_ansi_color}m"
+  local reset="${esc}[0m"
+
+  # Convert offsets to decimal integers
+  if [[ $start_offset =~ ^0[xX][0-9a-fA-F]+$ ]]; then
+    # Convert hex to decimal - strip 0x prefix first
+    start_offset=$((16#${start_offset#0x}))
+  elif [[ $start_offset =~ ^0[0-7]+$ ]]; then
+    # Convert octal to decimal
+    start_offset=$((8#$start_offset))
+  fi
+
+  if [[ $end_offset =~ ^0[xX][0-9a-fA-F]+$ ]]; then
+    # Convert hex to decimal - strip 0x prefix first
+    end_offset=$((16#${end_offset#0x}))
+  elif [[ $end_offset =~ ^0[0-7]+$ ]]; then
+    # Convert octal to decimal
+    end_offset=$((8#$end_offset))
+  fi
+
+  # Calculate actual start and end positions
+  if (( start_offset < 0 )); then
+    start_offset=$((len + start_offset))
+  fi
+  if (( end_offset < 0 )); then
+    end_offset=$((len + end_offset))
+  fi
+
+  # Validate and adjust offsets
+  start_offset=$((start_offset < 0 ? 0 : start_offset))
+  end_offset=$((end_offset > len ? len : end_offset))
+  if (( start_offset >= end_offset )); then
+    return 0
+  fi
+
+  # Adjust data to start from the correct offset
+  data="${data:start_offset:end_offset-start_offset}"
+  len=${#data}
+
+  while (( idx < len )); do
+    local chars=() hexs=()
+
+    # collect up to width bytes
+    for (( j=0; j<$width && idx<len; j++, idx++ )); do
+      local ch="${data:idx:1}"
+      local ord
+      printf -v ord '%d' "'$ch"
+      chars+=( "$ch" )
+      hexs+=( "$(printf '%02X' "$ord")" )
+    done
+
+    # first line: label only on the very first block
+    if (( idx <= j )); then
+      printf '%s' "$label"
+    else
+      printf '%*s' "${#label}" ""
+    fi
+
+    # print offset if width is specified
+    if [[ -n "$offset_width" ]]; then
+      printf '%b%0*x:%b ' "$offset_color" "$offset_width" $((start_offset + idx-j)) "$reset"
+    fi
+
+    # print characters, two spaces between each
+    printf ' %b%s' "$char_color" "${chars[0]}"
+    for (( k=1; k<${#chars[@]}; k++ )); do
+      printf '  %s' "${chars[k]}"
+    done
+    printf '%s\n' "$reset"
+
+    # second line: pad to align colon under first line
+    printf '%*s' "${#label}" ""
+
+    # print offset padding if width is specified
+    if [[ -n "$offset_width" ]]; then
+      printf '%*s' $((offset_width + 2)) "" # +2 for the colon and space
+    fi
+
+    # print hex values, single space between each
+    printf '%b%s' "$hex_color" "${hexs[0]}"
+    for (( k=1; k<${#hexs[@]}; k++ )); do
+      printf ' %s' "${hexs[k]}"
+    done
+    printf '%s\n' "$reset"
+  done
+}
+```

data/docs/dev/import/parameter-symbols.md

@@ -0,0 +1,6 @@
+/ use MDE 3.3.0 import parameter symbols
+/
+/ import parameter-symbols.md    __PS_STEM_SPECIES:   __PS_STEM_GENUS:   PS_STEM=
+/
+Stem: PS_STEM
+Species: __PS_STEM_SPECIES

data/docs/dev/import-directive-parameter-symbols.md

@@ -0,0 +1,9 @@
+/ use MDE 3.3.0 import parameter symbols
+/
+@import ./import/parameter-symbols.md   __PS_STEM_SPECIES:q='Illacme tobini'   __PS_STEM_GENUS:q=Illacme   PS_STEM=U1
+Genus: ${__U1_GENUS}
+/
+@import ./import/parameter-symbols.md   __PS_STEM_SPECIES:q='Hydrodynastes bicinctus'   __PS_STEM_GENUS:q=Hydrodynastes   PS_STEM=U2
+Genus: ${__U2_GENUS}
+/
+@import ./bats-document-configuration.md

data/docs/dev/import-parameter-symbols-template.md

@@ -0,0 +1,24 @@
+**Command substitution:** `NAMEC`
+```bash
+echo "Command substitution: NAMEC"
+```
+
+**Evaluated expression:** `NAMEE`
+```bash
+echo "Evaluated expression: NAMEE"
+```
+
+**Raw literal:** `NAMEL`
+```bash
+echo "Raw literal: NAMEL"
+```
+
+**Force-quoted literal:** `NAMEQ`
+```bash
+echo "Force-quoted literal: NAMEQ"
+```
+
+**Variable reference:** `NAMEV`
+```bash
+echo "Variable reference: NAMEV"
+```

data/docs/dev/import-parameter-symbols.md

@@ -0,0 +1,6 @@
+```ux
+echo: Tapanuli Orangutan
+name: COMMON_NAME
+```
+@import import-parameter-symbols-template.md   NAMEC:c='printf %s "$COMMON_NAME"'   NAMEE:e=$COMMON_NAME   NAMEL="Tapanuli Orangutan"   NAMEQ:q="Tapanuli Orangutan"   NAMEV:v=COMMON_NAME
+@import bats-document-configuration.md

data/docs/dev/load-vars-state-demo.md

@@ -0,0 +1,35 @@
+# LOAD Block State Modification Demo
+
+This document demonstrates how a LOAD block can modify the inherited state that was initially set by VARS blocks.
+
+First, establish baseline variables using a VARS block:
+
+```vars :(document_vars)
+var1: line1
+var3: line6
+```
+
+Use a LOAD block to modify the initial state:
+
+```load :load-mode-default
+directory: docs/dev
+glob: load1.sh
+```
+```load :load-mode-append
+directory: docs/dev
+glob: load1.sh
+mode: append
+```
+```load :load-mode-replace
+directory: docs/dev
+glob: load1.sh
+mode: replace
+```
+/
+@import bats-document-configuration.md
+```opts :(document_opts)
+dump_inherited_lines: true
+# menu_for_saved_lines: true
+
+screen_width: 64
+```

data/docs/ux-blocks-examples.md

@@ -67,14 +67,13 @@ prompt: "Select or enter branch name"
 ```
 
 ### Environment Configuration with Dependencies
-```ux @attrs[:body]
+```ux
 name: DATABASE_URL
 require:
   - ENVIRONMENT
   - DB_HOST
   - DB_PORT
-format: "postgresql://${DB_USER}:${DB_PASS}@${DATABASE_URL}:${DB_PORT}/${DB_NAME}"
-#format: "postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
+format: "postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
 ```
 
 ### Multi-step Configuration

data/examples/import_with_substitution_demo.md

@@ -1,48 +1,152 @@
 # Import with Text Substitution Demo
 
-This demonstrates the new enhanced `@import` functionality that supports text substitution parameters with **raw replacement** as the primary mode, using biological entity data.
+This demonstrates the enhanced `@import` functionality that supports **five types of parameter processing** for flexible template substitution, using biological entity data as examples.
 
-## Primate Classification Examples
+## Parameter Processing Types
 
-@import imports/organism_template.md COMMON_NAME="Tapanuli Orangutan" SPECIES="Pongo tapanuliensis" GENUS=Pongo FAMILY=Hominidae ORDER=Primates CLASS=Mammalia YEAR_DISCOVERED=2017
+__1. Raw Literal (=)__
+Use `=` for raw literal replacement (baseline behavior).
 
-@import imports/organism_template.md COMMON_NAME="Homo luzonensis" SPECIES="Homo luzonensis" GENUS=Homo FAMILY=Hominidae ORDER=Primates CLASS=Mammalia YEAR_DISCOVERED=2019
+__2. Force-Quoted Literal (:q=)__
+Use `:q=` to force-quote the value with double quotes.
 
-## Marine Life Classification
+__3. Variable Reference (:v=)__
+Use `:v=` to substitute with the value of a variable from the main document.
 
-@import imports/organism_template.md COMMON_NAME="Yeti Crab" SPECIES="Kiwa hirsuta" GENUS=Kiwa FAMILY=Kiwaidae ORDER=Decapoda CLASS=Malacostraca YEAR_DISCOVERED=2005
+__4. Evaluated Expression (:e=)__
+Use `:e=` for printf-safe string expressions with variable expansion.
 
-The imported template file uses **raw text placeholders** (just the key name) that get replaced with the biological data specified in the @import line.
+__5. Command Substitution (:c=)__
+Use `:c=` to execute a command and use its output.
 
-## Primary Mode: Raw Replacement
+## Comprehensive Example
 
-By default, template placeholders are just the key names without any delimiters:
+@import imports/organism_template.md COMMON_NAME:q="Tapanuli Orangutan" PLAIN_SPECIES:q="Pongo tapanuliensis" GENUS:v=orangutan_genus FAMILY:q="Hominidae" ORDER:q="Primates" CLASS:q="Mammalia" YEAR_DISCOVERED:v=discovery_year_2017 REPORT_TITLE:q="Primate Species Report" CLASSIFICATION_TYPE:q="Endangered Species" QUOTED_SPECIES:q="Pongo tapanuliensis" QUOTED_NAME:q="Tapanuli Orangutan" BASE_NAME:v=orangutan_base DOC_YEAR:v=discovery_year_2017 GENERATED_FILE:e="report-${COMMON_NAME// /_}-$(date +%Y%m%d).md" DESCRIPTION:e="Classification report for ${COMMON_NAME} (${PLAIN_SPECIES})" TIMESTAMP:c="date '+%Y-%m-%d %H:%M:%S'" LATEST_REPORT:c="find reports -name '*.md' -type f -exec ls -t {} + | head -n 1"
 
+## Parameter Type Examples
+
+### Example 1: Mixed Parameter Types
+
+@import imports/organism_template.md COMMON_NAME:q="Homo luzonensis" PLAIN_SPECIES:q="Homo luzonensis" GENUS:v=homo_genus FAMILY:q="Hominidae" ORDER:q="Primates" CLASS:q="Mammalia" YEAR_DISCOVERED:v=discovery_year_2019 REPORT_TITLE:q="Human Ancestor Documentation" CLASSIFICATION_TYPE:q="Extinct Hominin" QUOTED_SPECIES:q="Homo luzonensis" QUOTED_NAME:q="Homo luzonensis" BASE_NAME:v=homo_base DOC_YEAR:v=discovery_year_2019 GENERATED_FILE:e="homo-luzonensis-$(date +%Y%m%d).md" DESCRIPTION:e="Recent human ancestor discovered in ${YEAR_DISCOVERED}" TIMESTAMP:c="date -u '+%Y-%m-%dT%H:%M:%SZ'" LATEST_REPORT:c="ls -t *.md | head -n 1"
+
+### Example 2: Marine Life with Command Evaluation
+
+@import imports/organism_template.md COMMON_NAME:q="Yeti Crab" PLAIN_SPECIES:q="Kiwa hirsuta" GENUS:v=kiwa_genus FAMILY:q="Kiwaidae" ORDER:q="Decapoda" CLASS:q="Malacostraca" YEAR_DISCOVERED:v=discovery_year_2005 REPORT_TITLE:q="Deep Sea Species Catalog" CLASSIFICATION_TYPE:q="Marine Arthropod" QUOTED_SPECIES:q="Kiwa hirsuta" QUOTED_NAME:q="Yeti Crab" BASE_NAME:v=kiwa_base DOC_YEAR:v=discovery_year_2005 GENERATED_FILE:e="marine-${COMMON_NAME// /-}-report.md" DESCRIPTION:e="Deep sea crab species found near hydrothermal vents" TIMESTAMP:c="date '+%B %d, %Y at %I:%M %p'" LATEST_REPORT:c="find . -name '*marine*.md' -type f -printf '%T@ %p\n' | sort -n | tail -1 | cut -d' ' -f2-"
+
+The imported template file uses **parameter placeholders** that get replaced based on the processing type specified in the @import directive.
+
+## Parameter Processing Syntax Reference
+
+__1. Raw Literal (=)__
+```
+PARAM=value
+```
+**Usage:** Replace `PARAM` with `value` (baseline behavior).
+
+**Examples:**
+```
+COMMON_NAME="Tapanuli Orangutan"
+FAMILY="Hominidae"
+CLASSIFICATION_TYPE=Endangered
+```
+
+__2. Force-Quoted Literal (:q=)__
+```
+PARAM:q=value
+```
+**Usage:** Replace `PARAM` with `"value"` (automatically adds double quotes).
+
+**Examples:**
+```
+QUOTED_SPECIES:q=Pongo tapanuliensis
+QUOTED_NAME:q=Tapanuli Orangutan
+```
+
+__3. Variable Reference (:v=)__
+```
+PARAM:v=VAR_NAME
+```
+**Usage:** Replace `PARAM` with `${VAR_NAME}` from the main document.
+
+**Examples:**
+```
+GENUS:v=orangutan_genus
+YEAR_DISCOVERED:v=discovery_year_2017
+```
+
+__4. Evaluated Expression (:e=)__
+```
+PARAM:e=expr
+```
+**Usage:** Replace `PARAM` with `$(printf %s "expr")` (printf-safe string processing).
+
+**Examples:**
 ```
-Common Name: COMMON_NAME
-Species: SPECIES  
-Genus: GENUS
-Family: FAMILY
+GENERATED_FILE:e="report-${COMMON_NAME// /_}-$(date +%Y%m%d).md"
+DESCRIPTION:e="Classification report for ${COMMON_NAME} (${PLAIN_SPECIES})"
+FILENAME:e="${GENUS,,}-${PLAIN_SPECIES,,}.md"
 ```
 
-Gets transformed to:
+__5. Command Substitution (:c=)__
+```
+PARAM:c=command
+```
+**Usage:** Replace `PARAM` with `$(command)` (raw command execution).
 
+**Examples:**
 ```
-Common Name: Tapanuli Orangutan
-Species: Pongo tapanuliensis
-Genus: Pongo
-Family: Hominidae
+TIMESTAMP:c="date '+%Y-%m-%d %H:%M:%S'"
+LATEST_REPORT:c="ls -t *.md | head -n 1"
+FILE_COUNT:c="find . -name '*.md' | wc -l"
+CURRENT_USER:c="whoami"
 ```
 
-## Usage Examples
+## Complete Parameter Processing Example
 
-Here are different ways to specify biological data:
+```
+@import imports/organism_template.md COMMON_NAME="Tapanuli Orangutan" PLAIN_SPECIES="Pongo tapanuliensis" GENUS:v=orangutan_genus FAMILY="Hominidae" ORDER="Primates" CLASS="Mammalia" YEAR_DISCOVERED:v=discovery_year_2017 REPORT_TITLE="Primate Species Report" CLASSIFICATION_TYPE="Endangered Species" QUOTED_SPECIES:q="Pongo tapanuliensis" QUOTED_NAME:q="Tapanuli Orangutan" BASE_NAME:v=orangutan_base DOC_YEAR:v=discovery_year_2017 GENERATED_FILE:e="report-${COMMON_NAME// /_}-$(date +%Y%m%d).md" DESCRIPTION:e="Classification report for ${COMMON_NAME} (${PLAIN_SPECIES})" TIMESTAMP:c="date '+%Y-%m-%d %H:%M:%S'" LATEST_REPORT:c="find reports -name '*.md' -type f -exec ls -t {} + | head -n 1"
+```
+
+## Template Placeholder Format
+
+Template placeholders are raw key names without delimiters:
+
+```markdown
+**Common Name:** COMMON_NAME
+**Species:** PLAIN_SPECIES
+**Quoted Species:** QUOTED_SPECIES
+**Quoted Name:** QUOTED_NAME
+**Base Name:** BASE_NAME
+**Doc Year:** DOC_YEAR
+**Report:** REPORT_TITLE
+**Generated File:** GENERATED_FILE
+**Description:** DESCRIPTION
+**Timestamp:** TIMESTAMP
+**Latest Report:** LATEST_REPORT
+```
+
+Gets transformed based on parameter processing type:
+
+```markdown
+**Common Name:** Tapanuli Orangutan
+**Species:** Pongo tapanuliensis
+**Quoted Species:** "Pongo tapanuliensis"
+**Quoted Name:** "Tapanuli Orangutan"
+**Base Name:** Great Ape
+**Doc Year:** 2017
+**Report:** Primate Species Report
+**Generated File:** report-Tapanuli_Orangutan-20240115.md
+**Description:** Classification report for Tapanuli Orangutan (Pongo tapanuliensis)
+**Timestamp:** 2024-01-15 14:30:22
+**Latest Report:** reports/primates-2024.md
+```
 
-- Simple values: `@import imports/organism_template.md GENUS=Pongo CLASS=Mammalia`
-- Quoted values with spaces: `@import imports/organism_template.md COMMON_NAME="Psychedelic Frogfish"`  
-- Multiple taxonomic parameters: `@import imports/organism_template.md SPECIES="Pongo tapanuliensis" GENUS=Pongo FAMILY=Hominidae`
-- Mixed quoting: `@import imports/organism_template.md COMMON_NAME='Ruby Seadragon' SPECIES="Phyllopteryx dewysea" GENUS=Phyllopteryx`
+## Rationale for Syntax Design
 
-## Optional: Template Delimiters
+- **`=`** → Raw literal (baseline behavior, simple and clean)
+- **`:q=`** → Force-quoted literal (`:q` clearly indicates quoting)
+- **`:v=`** → Variable reference (`:v` indicates variable lookup)
+- **`:e=`** → Evaluated expression (`:e` indicates expression evaluation with printf safety)
+- **`:c=`** → Command substitution (`:c` indicates command execution)
 
-For cases where you need `${}` or `{{}}` style placeholders, you can use the template delimiter mode (requires code configuration). 
+This scheme is unambiguous and provides clear visual cues for each processing type. The `=` operator handles the most common case with minimal syntax, while the `:prefix=` operators use descriptive suffixes (q=quote, v=variable, e=expression, c=command) that make the intent immediately clear. The colon-based syntax is familiar from many configuration systems and provides consistent visual grouping. 

data/examples/imports/organism_template.md

@@ -1,42 +1,99 @@
 # COMMON_NAME Classification
 
-**Common Name:** COMMON_NAME  
-**Species:** SPECIES  
-**Genus:** GENUS  
-**Family:** FAMILY  
-**Order:** ORDER  
-**Class:** CLASS  
-**Year Discovered:** YEAR_DISCOVERED
+**Common Name:** ${COMMON_NAME}
+**Species:** ${PLAIN_SPECIES}
+**Genus:** ${GENUS}
+**Family:** ${FAMILY}
+**Order:** ${ORDER}
+**Class:** ${CLASSIFICATION_TYPE}
+**Year Discovered:** ${YEAR_DISCOVERED}
+
+## Parameter Processing Examples
+
+__Raw Literal (=)__
+- Report title: `REPORT_TITLE`
+- Fixed classification: `CLASSIFICATION_TYPE`
+
+__Force-Quoted Literal (:q=)__
+- Quoted species name: `QUOTED_SPECIES`
+- Quoted common name: `QUOTED_NAME`
+
+__Variable Reference (:v=)__
+- Common name from variable: `BASE_NAME`
+- Discovery year from document: `DOC_YEAR`
+
+__Evaluated Expression (:e=)__
+- Generated filename: `GENERATED_FILE`
+- Formatted description: `DESCRIPTION`
+
+__Command Substitution (:c=)__
+- Current timestamp: `TIMESTAMP`
+- Latest report file: `LATEST_REPORT`
 
 ## Taxonomic Classification
 
 ```bash
-# Biological classification data
-export COMMON_NAME="COMMON_NAME"
-export SPECIES="SPECIES"
-export GENUS="GENUS"
-export FAMILY="FAMILY"
-export ORDER="ORDER"
-export CLASS="CLASS"
-export YEAR_DISCOVERED="YEAR_DISCOVERED"
-
-echo "Organism: COMMON_NAME"
-echo "Scientific name: SPECIES"
-echo "Discovered in: YEAR_DISCOVERED"
+# Biological classification data with different parameter types
+export common_name=COMMON_NAME
+export species="PLAIN_SPECIES"
+export genus="GENUS"
+export family="FAMILY"
+export order="ORDER"
+export class="CLASSIFICATION_TYPE"
+export year_discovered="YEAR_DISCOVERED"
+
+# Examples of parameter processing types
+echo "Report: REPORT_TITLE"
+echo "Quoted species: QUOTED_SPECIES"
+echo "Quoted name: QUOTED_NAME"
+echo "Base name from var: BASE_NAME"
+echo "Doc year from var: DOC_YEAR"
+echo "Generated file: GENERATED_FILE"
+echo "Description: DESCRIPTION"
+echo "Timestamp: TIMESTAMP"
+echo "Latest report: LATEST_REPORT"
+
+echo "Organism: $common_name"
+echo "Scientific name: $species"
+echo "Discovered in: $year_discovered"
+echo "Classification: $class"
 ```
 
 ## Classification Hierarchy
 
-```yaml
 organism:
-  common_name: COMMON_NAME
-  scientific_name: SPECIES
+  common_name: ${COMMON_NAME}
+  scientific_name: ${PLAIN_SPECIES}
   taxonomy:
-    genus: GENUS
-    family: FAMILY
-    order: ORDER
-    class: CLASS
-  discovery_year: YEAR_DISCOVERED
-```
+    genus: ${GENUS}
+    family: ${FAMILY}
+    order: ${ORDER}
+    class: ${CLASSIFICATION_TYPE}
+  discovery_year: ${YEAR_DISCOVERED}
+  
+metadata:
+  report_title: ${REPORT_TITLE}
+  classification_type: ${CLASSIFICATION_TYPE}
+  quoted_species: ${QUOTED_SPECIES}
+  quoted_name: ${QUOTED_NAME}
+  base_name: ${BASE_NAME}
+  doc_year: ${DOC_YEAR}
+  generated_file: ${GENERATED_FILE}
+  description: ${DESCRIPTION}
+  timestamp: ${TIMESTAMP}
+  latest_report: ${LATEST_REPORT}
+
+## Generated Documentation
+
+**Report:** ${REPORT_TITLE}  
+**Classification:** ${CLASSIFICATION_TYPE}  
+**Quoted Species:** ${QUOTED_SPECIES}  
+**Quoted Name:** ${QUOTED_NAME}  
+**Base Name:** ${BASE_NAME}  
+**Doc Year:** ${DOC_YEAR}  
+**Generated File:** ${GENERATED_FILE}  
+**Description:** ${DESCRIPTION}  
+**Timestamp:** ${TIMESTAMP}  
+**Latest Report:** ${LATEST_REPORT}  
 
-Biological organism template using raw replacement for taxonomic data. 
+Biological organism template demonstrating all five parameter processing modes: raw literal (=), force-quoted literal (:q=), variable reference (:v=), evaluated expression (:e=), and command substitution (:c=).