Literate programming tool using Markdown (since version 0.1), LaTeX (since version 0.4), AsciiDoc or Typst as markup languages and R, Python, Tcl, Octave, Shell or Julia programming languages or tools like GraphViz, PlantUML. Tcl, Python, Octave or Julia code can be embedded directly in the text using single backticks or as code blocks using triple backticks. A good example is the extensive tutorial for the tmdoc::tmdoc package at http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/modules/tmdoc/tmdoc-tutorial.html
Usage: Intermixed Markup (Markdown, AsciiDoc, Typst or LaTeX) and programming code (R, Python, Tcl, Octave, GraphViz, PlantUML or Shell) in a .Rmd, .tmd or .tnw file that can converted to Markdown/LaTeX/Typst/Asciidoc using the tmdoc command line application. Afterwards the Markdown document can converted to other documentation formats like HTML, PDF or Unix manual pages for instance using the mndoc or pandoc or pdflatex/xelatex command line tools.
tmdoc docu.tmd docu.md # afterwards Markdown can be converted to HTML or PDF for instance using mndoc mdnoc doc.md doc.html --css dgw.css # processing a LaTeX command with backticked embedded Tcl code tmdoc docu.tnw docu.tex pdflatex docu.tex
Code chunks:
tmdoc supports three type of code chunks, programming code chunks which uses pipes, so that the next code chunks knows about variables created before (R, Octave, Python, Tcl and Julia), generic command line tool code chunks for tools like GraphViz or PlantUML or Kroki code chunks using the https://kroki.io web service.
Are starting after three backticks and a {LANGUAGE} indication of the programming language. Here an example:
```{tcl echo=false}
set x 1
puts $x
```Further short Code fragments can be embedded directly within the text using single backticks:
The current date and time is: `tcl clock format [clock seconds] -format "%Y-%m-%d %H:%M"`
Should embed the current date and time in the text.
The manual states as well support for images created from Tcl for instance using commands from gdtcl or the canvas widget. For more information have a look at the tutorial http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/modules/tmdoc/tmdoc-tutorial.html and the manual pages for the package http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/modules/tmdoc/tmdoc.html and the tmdoc application http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/apps/tmdoc.html
You can as well embed other programming languages like R, Python, Julia or Octave:
So this is possible:
Here some R code:
```{r}
print("Hello R World!")
```
Now same document Tcl code:
```{tcl}
puts "Hello Tcl World";
```Since Version 0.8.0 you can embed as well command line applications like this:
```{.cmd cmd="dot -Tpng -o%o %i" echo=false}
digraph g {
rankdir="LR"
node[shape=box,style=filled]
A->B->C
}
```The code above will embed the GraphViz image within your documentation but will hide the diagram code. Obviously you need to have GraphViz dot to be installed on your system.
This syntax can be as well used to embed R (or Python, or Octave code) to perform statistical analysis. Here an example from the tutorial for using R:
```{.shell cmd="Rscript %i %o"}
### outfile is the argument %o
outfile=commandArgs(trailingOnly=TRUE)[1]
png(outfile)
par(mai=rep(0.1,4))
pie(rep(1,20),col=rainbow(20))
dev.off()
```Since version 0.18.0 as well external files can be included in code chunks, even with giving a line range. So assuming that your GraphViz code is in external files, flowcharts made with graphviz can be embedded like this:
```{.cmd cmd="dot -Tpng -o%o %i" echo=false}
#INCLUDE sample.dot
```More examples can be seen in the tutorial .
R package tmdoc4r
There exists as well a R package tmdoc4r . This package demonstrates how we can embed Tcl code as the main driver of R packages.
Changes:
See the project README https://github.com/mittelmark/tmdoc/ See also:
Discussion:
Please discuss here ...
DDG 2020-02-19: Please note, that this is a work in progress. I am open for suggestions. But tmdoc should basically have a reasonable subset of the functionality of R's Sweave https://stat.ethz.ch/R-manual/R-devel/library/utils/doc/Sweave.pdf and R markdown https://rmarkdown.rstudio.com/
DDG 2020-11-09: With version 0.4 LaTeX support was added. Project now as well on Github.
DDG 2025-01-19: Tcl 9 aware version as well with support for results=asis code chunk option and include and listmdtab functions
DDG 2025-10-23: version 0.15.0 AsciiDoc, Typst support, updated version changes with many new features since January.
DDG 2025-11-03: version 0.16.0 adding Julia support
DDG 2025-12-01: version 0.17.0 True HTML comments support in Markdown documents
DDG 2026-01-18: version 0.18.0 direct support for Music chord sheets and Guitar and Ukulele chord graphics, includes in code chunks