157 lines
2.9 KiB
Markdown
157 lines
2.9 KiB
Markdown
# 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)
|
|
|
|
## Project Structure
|
|
|
|
c-md supports mixed projects with both documented (`.c.md`) and regular (`.c`) files:
|
|
|
|
```
|
|
project/
|
|
srcs/
|
|
main.c.md <- documented source
|
|
legacy.c <- regular source
|
|
includes/
|
|
api.h.md <- documented header
|
|
types.h <- regular header
|
|
build/
|
|
srcs/
|
|
main.c <- transpiled
|
|
legacy.c <- symlinked
|
|
includes/
|
|
api.h <- transpiled
|
|
types.h <- symlinked
|
|
objs/
|
|
*.o
|
|
maps/
|
|
main.map <- line mapping (for tooling)
|
|
api.map
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Options
|
|
|
|
```
|
|
-h, --help Show help message
|
|
-e, --ext <ext> Extension to filter
|
|
-t, --transpile File mode: transpile <input>
|
|
-o <file> Output file
|
|
-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 -e c -t main.c.md -o build/main.c
|
|
|
|
# With line mapping
|
|
c-md -e c -t main.c.md -o build/main.c -m build/maps/main.map
|
|
```
|
|
|
|
### Makefile Integration
|
|
|
|
```makefile
|
|
BUILD_DIR = build
|
|
SRC_DIR = src
|
|
|
|
$(BUILD_DIR)/%.c: $(SRC_DIR)/%.c.md
|
|
c-md -e c -t $< -o $@ -m $(BUILD_DIR)/maps/$*.map
|
|
```
|
|
|
|
## Code Block Rules
|
|
|
|
Only code blocks with a matching extension are extracted:
|
|
|
|
```
|
|
File: main.c.md (extension = c)
|
|
|
|
'''c <- extracted (c == c)
|
|
int foo(void);
|
|
'''
|
|
|
|
'''bash <- ignored (bash != c)
|
|
echo "hello"
|
|
'''
|
|
|
|
''' <- ignored (no extension)
|
|
some text
|
|
'''
|
|
```
|
|
|
|
Multiple 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
|
|
|
|
|
|
## License
|
|
|
|
[GPL3](LICENSE)
|