I've read technical books that say the code samples are actually executed to avoid typos. I wonder if you could use cog for that. Probably there are LaTeX packages that can do it, but what if I'm writing in markdown?
This is a perfect use case for org[1] and org-babel[2] and actually one of the reasons I've switched from vim to emacs.
I wonder whether there's something similar that executes code fences in markdown? After a cursory search I found markdown-exec[3], which seems to be a more editor-agnostic solution, although I don't know whether it can compete with org-babel in terms of language support and being maintained.
It uses Pandoc, so it supports many formats (I've personally used it with Markdown code fences and with HTML <code> elements). The idea is pretty simple and powerful: if a code block has an attribute/annotation like `pipe="foo"` then that value is executed as a shell command, and the contents of the code block gets piped through it and replaced by the stdout.
This supports running basically all programming languages, by giving their interpreter as the value of `pipe`. I use this for my web site ( chriswarbo.net ) to execute code in PHP, Haskell, Racket, Bash, Coq, etc. It can also run things indirectly, e.g. if you want to compile and run C you could do something like this:
Here is my C program:
```{pipe="tee myfile.c"}
int main() etc etc.
```
Here is its output:
```{pipe="sh"}
gcc -o myfile myfile.c 1>&2 || exit 1
./myfile
```
A more scalable alternative, for documents which will run many such snippets, is to write a helper script to use as our command, e.g.
```{pipe="cat > runC && chmod +x runC"}
#!/usr/bin/env bash
set -e
cat > myfile.c
gcc -o myfile myfile.c 1>&2
./myfile
```
Here is the output of my C program:
```{pipe="./runC"}
int main() etc. etc.
```
Panhandle allows the contents of a code block (annotated with class `unwrap`) to be spliced into its containing document. This is useless on its own (since we could just write that part of the document directly, rather than putting it inside a code block); but it allows us to generate markup using panpipe, and insert it into the document. For example, the following is a HTML page containing a <p> element and a <code> element; panpipe can execute the contents of the <code> element, which generates HTML for an <img> element, but that HTML is stuck as the text of a <code> element. Panhandle lets us "unwrap" it, to become a real <img> element in the document:
<p>Here is a checkerboard:</p>
<code class="unwrap" pipe="sh | pandoc -f html -t json">
printf '<img src="data:image/png;base64,'
{
echo "P1 101 100"
for N in $(seq 10100); do echo $(( N % 2 )); done
} > checker.pbm
convert checker.pbm checker.png
base64 -w0 < checker.png
printf '" />'
</code>
Note that panhandle needs to parse the content of a code block in order to unwrap it; to keep things simple and unambiguous it only supports Pandoc JSON format (a serialisation of Pandoc's internal AST). Since the above shell code generates HTML, we pipe it through `pandoc -f html -t json` to get the required JSON format.
Pandoc even poses codeblock execution as an exercise in their custom-filter documentation: https://pandoc.org/filters.html
The python package panflute is also really nice if you don't want to play around with haskell or the AST JSON directly.
This approach is sometimes referred to as literate programming.
Emacs's org-babel package implements it for a variety of languages but only within org-mode files (.org).
You might be able to find a 3rd party package/script that works for you or you might find it easy to write/modify existing scripts depending on your particular use case.
I've created Codebraid (https://codebraid.org/) for writing in Markdown. It makes inline code and code blocks executable, and includes support for Jupyter kernels. It uses Pandoc internally to parse the Markdown. There's also a VS Code extension that provides a live preview with scroll sync.
I don't think that would fall within the scope of a utility like cog.
I wrote a minimal tool long back which I used to extract parts of code from my test suite as json which I could then use within my documentation generator to embed these snippets as example.
The examples then are guaranteed to be correct because they are quite literally pulled from the project's test suite. The util is written i n ts but should work with any lang. that supports C or Python style comments.
I wonder whether there's something similar that executes code fences in markdown? After a cursory search I found markdown-exec[3], which seems to be a more editor-agnostic solution, although I don't know whether it can compete with org-babel in terms of language support and being maintained.
[1] https://orgmode.org/
[2] https://orgmode.org/worg/org-contrib/babel/
[3] https://github.com/pawamoy/markdown-exec