🔧 XMD Troubleshooting Guide

Common issues and solutions for XMD processing.

Fixed Issues (v0.0.2)

✅ Segmentation Fault with –no-exec

Issue: Using --no-exec option caused segmentation fault.

Solution: Fixed in v0.0.2 with proper memory allocation and NULL checks.

# Now works correctly
xmd process document.md --no-exec

✅ Variables Not Working from Command Line

Issue: Variables set with -v option were not being used in document processing.

Solution: Fixed in v0.0.2 with proper variable storage and propagation.

# Now works correctly
xmd process template.md -v name="Alice" -v env="production"

# Variables  and  are properly substituted

✅ Config File Validation Missing

Issue: --config option accepted non-existent files without error.

Solution: Fixed in v0.0.2 with file existence validation.

# Now properly validates config file exists
xmd process doc.md --config missing.conf
# Error: Cannot open config file 'missing.conf'

✅ Output Formats Not Working

Issue: All --format options produced identical output.

Solution: Fixed in v0.0.2 with proper format-specific processing.

# Now produces different outputs
xmd process doc.md --format html    # HTML document with CSS
xmd process doc.md --format json    # Structured JSON response
xmd process doc.md --format markdown # Plain markdown (default)

✅ Trace Functionality Not Working

Issue: --trace option was parsed but did nothing.

Solution: Fixed in v0.0.2 with integration to debugger trace system.

# Now generates detailed trace files
xmd process doc.md --trace
# Creates doc.md.trace with processing details

Current Issues & Solutions

Variables Not Substituted

Symptoms:

`` appears literally in output
No error messages

Diagnosis:

# Check if variable is set
xmd process doc.md -v debug=true --debug

# Use trace to see variable processing
xmd process doc.md --trace

Solutions:

Check variable syntax:

<!-- Correct -->
<!-- xmd:set name="Alice" -->
Hello !
   
<!-- Incorrect -->
<!-- xmd:set name=Alice -->  <!-- Missing quotes for strings -->
Hello {name}!               <!-- Wrong interpolation syntax -->

Verify command-line variables:

# Correct format
xmd process doc.md -v name="Alice" -v count=5
   
# Incorrect
xmd process doc.md -v name Alice    # Missing = 
xmd process doc.md -v "name=Alice"  # Don't quote the whole thing

Range Syntax Not Working

Symptoms:

 doesn’t expand
Loop variable appears literally

Solutions:

Use correct HTML comment syntax:

<!-- Correct -->
<!-- xmd:for i in 1..3 -->
Item 
<!-- xmd:endfor -->
   
<!-- Incorrect -->
xmd:for i in 1..3    <!-- Missing HTML comment wrapper -->
<!-- xmd:for i in 1...3 -->  <!-- Triple dots not supported -->

Check range limits:

<!-- This works (under 1000 limit) -->
<!-- xmd:for i in 1..100 -->
   
<!-- This is skipped (over limit) -->
<!-- xmd:for i in 1..5000 -->

Command Execution Not Working

Symptoms:

 appears literally
No command output

Solutions:

Check if commands are disabled:

# Don't use --no-exec if you want commands to run
xmd process doc.md              # Commands enabled
xmd process doc.md --no-exec    # Commands disabled

Verify command exists:

<!-- Test with simple command -->
<!-- xmd:exec echo "test" -->
   
<!-- Check command exists -->
<!-- xmd:exec which ls -->

File Processing Errors

Symptoms:

“Failed to process file” error
Empty output

Diagnosis:

# Check file exists and is readable
ls -la document.md

# Validate syntax first
xmd validate document.md

# Use debug mode for details
xmd process document.md --debug

Solutions:

File permissions:

# Ensure file is readable
chmod +r document.md

File encoding:

# Check for binary/encoding issues
file document.md
   
# Convert if needed
iconv -f utf-8 -t utf-8 document.md

Output Format Issues

Symptoms:

Unexpected output format
HTML tags in markdown output
JSON parsing errors

Solutions:

Specify format explicitly:

# Be explicit about desired format
xmd process doc.md --format markdown
xmd process doc.md --format html
xmd process doc.md --format json

Validate JSON output:

# Check JSON is valid
xmd process doc.md --format json | jq .

Performance Issues

Slow Processing

Symptoms:

Long processing times
High memory usage

Diagnosis:

# Check processing stats
xmd process doc.md --debug

# Generate trace to find bottlenecks
xmd process doc.md --trace

Solutions:

Optimize loops:

<!-- Avoid large ranges -->
<!-- xmd:for i in 1..10 -->     <!-- Good -->
<!-- xmd:for i in 1..1000 -->   <!-- Slower -->

Cache expensive operations:

<!-- Cache command results -->
<!-- xmd:set timestamp=now -->
Time:   <!-- Reuse instead of multiple exec calls -->

Reduce command execution:

# Use --no-exec for content-only processing
xmd process doc.md --no-exec

Debug Strategies

General Debugging Steps

Start simple:

# Test with minimal document
echo "Hello " | xmd process /dev/stdin -v name="World"

Use validation:

# Check syntax first
xmd validate document.md

Enable tracing:

# See detailed processing
xmd process document.md --trace
cat document.md.trace

Check debug output:

# View processing stats
xmd process document.md --debug

Systematic Debugging

Isolate the problem:
- Comment out sections to find problematic code
- Test with minimal examples
- Check each directive individually
Verify assumptions:
- Check variable values with debug output
- Verify command execution with simple tests
- Validate file paths and permissions
Use incremental testing:
- Start with basic processing
- Add complexity gradually
- Test each new feature

Getting Help

Information to Include

When reporting issues, include:

XMD version:
```
xmd version
```

Command used:

xmd process document.md -v var=value --format html

Input document (minimal example):
```

Result: 
```
Expected vs actual output
Error messages

Debug information:

xmd process document.md --debug --trace

Support Channels

📖 Documentation: akaoio.github.io/xmd
💬 Discord: discord.gg/xmd
🐛 Issues: github.com/akaoio/xmd/issues
💡 Discussions: github.com/akaoio/xmd/discussions

Before Reporting

Check this troubleshooting guide
Search existing issues on GitHub
Test with minimal example
Include all requested information