tmdoc

Literate programming using R, Python, Octave, Julia or Tcl. Embed Diagram code and the output, LaTeX equation, literature references, shell script output, Youtube videos and code chunks for many different programming languages while adding the evaluation results into your Markdown, AsciiDoc, Typst or LaTeX documents.

Description

The package tmdoc and the standalone application of it provide facilities to evaluate embedded Diagram code, LaTeX equations, YAML defined abbreviations, or Julia, R, Python, Octave, Shell or Tcl code within documents of Markup languages like Markdown, AsciiDoc, Typst or LaTeX and add the resulting output to the document for creating dynamic documents, a technique as well known as literate programming.

Main Features

• single file approach: the required small (approx. 250kb) single file (tmdoc-0.1X.X.bin) just requires an existing Tcl/Tk installation
• Abbreviations: expand YAML defined abbreviations - Abbreviation Filter
• Alerts: Markdown alerts - Alert Section in the Tutorial
• Chemical Equations: simple chemical equations like C₆H₁₂O₆ or H₃O⁺ string instruments
• Chord shapes and sheets: display chord sheets and chord shapes for string instruments
• Citations: reference management using BibTeX files - Citation Section in the Tutorial
• Comments: sections between HTLM comments are truly excluded, not only hidden in the display
• CSV Tables: create tables using CSV data - CSV Tables Section in the Tutorial
• Diagrams: evaluate diagram code and embed create graphics using the Kroki webservice - Kroki Section in the Tutorial
• Graphic generation: create graphics using the tsvg package - tsvg section in the tutorial
• Figure numbering: support for automatic figure numbering using the `nfig label` syntax
• Includes: Markdown file includes - include section in the tutorial or code chunk includes
• Julia reports: writing statistical reports using the Julia programming language
• LaTeX equations: can be embedded using the latex.codecs.com web servcie
• Octave reports: writing statistical reports using the Octave programming language
• Python reports: writing statistical reports using the Python programming language
• R reports: writing statistical reports using the R programming language
• Shell code: evaluate embedded shell code to create graphics or text to be used within the output - shell section in the tutorial
• Table numbering: support for automatic table numbering using the `ntab label` syntax
• Tcl programming: evaluate Tcl and other programming language code
• Table of Content generation: creating a table of content (toc) file ready to be included into the main document

Examples

| Code | HTML-Output | |:-----------------:|:-----------:| | abcmusic.tmd | abcmusic.html | | asciidoc.tdoc | asciidoc.html | | c.tmd | c.html | | cpp.tmd | cpp.html | | dot.tmd | dot.html | | emf.tmd | emf.html | | literature.tmd | literature.html | | mtex.tmd | mtex.html | | pipe.tmd | pipe.html | | py.tmd | py.html |

Installation

On Linux, MacOS and on Windows with installed Msys2 or Cygwin download the latest tmdoc-VERSION.bin binary (150-200kb in size), rename the bin file to tmdoc and copy the file to a folder belonging to your PATH variable. Thereafter make the file executable and check that it is correctly installed. Since version 0.14.0 there is an install script which installs both tmdoc and mndoc into ~/.local/bin. You can execute it like this:

/bin/bash -c "$(curl -fsSL https://github.com/mittelmark/tmdoc/releases/latest/download/install-tmdoc.sh)"

Since version 0.19.0: After you used this installer you might as well use the installed command tmdoc-update to check for a newer version and install that if it is available.

In case you would like to use your own Markdown to HTML converter, you can as well just install tmdoc alone without mndoc like this:

### download to your local bin folder
wget https://github.com/mittelmark/tmdoc/releases/download/v0.19.1/tmdoc-0.19.1.bin \
  -O ~/.local/bin/tmdoc
### make the Tcl script executable
chmod 755 ~/.local/bin/tmdoc
### check the installation
tmdoc --version
## 0.19.1

If the folder ~/.local/bin does not exists you should create it and add this to your PATH variable.

That approach should as well work on Windows-Cygwin or Windows-Msys2 with installed Tcl interpreter.

To check the document processing create a simple file, let's say test.tmd with the following content:

---
title: Test file for tmdoc
author: Max Musterman
date: 2025-12-10 09:13
---

## Testing Tmdoc Installation

Remove the single qotes for the code block below:

'```{.tcl}
puts "Hello Tcl World!"
'```

Thereafter you can process the file like this:

tmdoc test.tmd test.md

which should create the file test.md with the following content:

---
title: Tes