# c-md

A transpiler for literate programming in C (and other compiled languages).

Write documentation and code in a single Markdown file. The transpiler extracts
the code for compilation while keeping your source readable and
well-documented.

## Concept

Inspired by Donald Knuth's literate programming, c-md lets you write files like
`main.c.md` that combine Markdown documentation with code blocks. The
transpiler extracts the code into pure `.c` files ready for compilation.

## File Format

Source files use the pattern `<name>.<ext>.md`:

```
main.c.md   ->  main.c
utils.h.md  ->  utils.h
```

### Example: main.c.md

```markdown
# Main Entry Point

This file contains the program entry point.
It initializes the system and starts the main loop.

## Dependencies

- stdlib.h for memory allocation
- stdio.h for I/O operations

## Implementation

'''c
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    printf("Hello, World\n");
    return 0;
}
'''
```

(Note: Use standard triple backticks ` ``` ` in actual files)

## Usage

### Options

```
-h, --help            Show help message
-e, --ext <ext>       Extension to extract (c, h, py, etc.)
-i, --input <file>    Input file (default: stdin)
-o, --output <file>   Output file (default: stdout)
-m, --map <file>      Generate line mapping file
```

### Pipe Mode (stdin/stdout)

```bash
# Basic transpilation
cat main.c.md | c-md -e c > main.c

# With line mapping
cat main.c.md | c-md -e c -m build/maps/main.map > main.c
```

### File Mode

```bash
# Basic transpilation
c-md -i main.c.md -o build/main.c

# With line mapping
c-md -i main.c.md -o build/main.c -m build/maps/main.map

# Extension auto-inferred from filename
c-md -i main.c.md -o build/main.c
```

### Makefile Integration

```makefile
BUILD_DIR = build
SRC_DIR = src

$(BUILD_DIR)/%.c: $(SRC_DIR)/%.c.md
	c-md -i $< -o $@ -m $(BUILD_DIR)/maps/$*.map
```

## Code Block Filtering

The transpiler extracts only code blocks matching the specified extension.

For file `main.c.md` with `-e c`:
- ` ```c ` blocks are extracted
- ` ```python ` blocks are ignored
- ` ``` ` blocks (no language) are ignored

Multiple matching code blocks are concatenated with a blank line separator.

## Line Mapping

The transpiler generates `.map` files that track the correspondence between
source lines (`.c.md`) and output lines (`.c`). This enables:

- Accurate error reporting back to original files
- IDE/LSP integration (WIP)
- Debugging with correct source locations

## Status

**v1.0.0** - Initial stable release

## License

[GPL3](LICENSE)