Literate programming tool using [Markdown] (since version 0.1) or [LaTeX] (since version 0.4) as markup languages and Tcl as programming language. Tcl 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/DGTtmdocl/blob/master/modulibes/tmdoc/tmdoc-tutorial/tmd.html
* Author: [Detlef Groth]
* Homepage: https://github.com/mittelmark/tmdoc/
* Download: https://github.com/mittelmark/tmdoc/archive/master.zip
* Tutorial Markdown: http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/modules/tmdoc/tmdoc-tutorial.html
* Tutorial LaTeX: https://github.com/mittelmark/DGTcl/blob/master/lib/tmdoc/latex/tmdoc-template.pdf
* Manual Package: http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/modules/tmdoc/tmdoc.html
* Manual App: http://htmlpreview.github.io/?https://github.com/mittelmark/tmdoc/blob/master/apps/tmdoc.html
* Version: 0.7
* License: BSD
Usage: Intermixed Markdown or LaTeX markup and Tcl code in a tmd or .tnw file that can converted to Markdown/LaTeX 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 [pandoc] or pdflatex/xelatex command line tool.
======
tmdoc docu.tmd docu.md
# afterwards Markdown can be converted to HTML or PDF for instance using pandoc
pandoc -i doc.md -s --highlight-style pygments -c dgw.css -o docu.html
# processing a LaTeX command with backticked embedded Tcl code
tmdoc docu.tnw --outfile docu.tex
pdflatex docu.tex
======
'''Code chunks:'''
Are starting after three backticks and a {tcl} indication of the programming language. Here an example:
======
```{tcl echo=false}
set x 1
puts $x
```
======
Further short Tcl code can be embedded directly within the text using single backticks:
======
The curent 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/DGTtmdocl/blob/master/modulibes/tmdoc/tmdoc-tutorial/tmd.html and the manual pages for the package http://htmlpreview.github.io/?https://github.com/mittelmark/DGTtmdocl/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 if you use the knitr tool:
So this is possible:
Here some R code:
```{r}
print("Hello R World!")
```
Now same document Tcl code:
```{tcl}
puts "Hello Tcl World";
```
If you mix R and Tcl you must first run tmdoc and afterwards https://yihui.name/knitr%|%knitr%|% . My Makefile for another tutorial looks like this:
======
default:
tmdoc ../t3-tut.tmd > t3-tut.rmd
echo "library(knitr);knitr::knit('t3-tut.rmd',output='t3-tut.md');" | R --slave
pandoc -i t3-tut.md -s --highlight-style pygments -c ../dgw.css -o t3-tut.html
======
You can not start knitr first, as it can't handle Tcl commands.
----
'''Changes:'''
* 2020-02-19: 0.1 first release
* 2020-02-21: 0.2 release
** puts -nonewline fix in the output
** outfile and tangle options
** manual page ready
* 2020-02-23: 0.3 release
** fix for puts into channels
* 2020-11-08: 0.4 release
** LaTeX support
** project moved to github
* 2021-12-19 0.5 release - making code structure like in tcllib
* 2025-01-04 0.6 - tcllib and Tcl 9 aware version
* 2025-01-18 0.7
** support for results="asis" for instance to create Markdown or SVG code
** function include to include other Markdown files
** function list2mdtab to add tables within code chunks
'''See also:'''
* [Source Documentation Tools]
* [mkdoc::mkdoc] for doing the inverse embedding Markdown into Tcl code for creating source code documentation
* [Literate programming]
----
'''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
<<categories>> Documentation