tmdoc::tmdoc - Literate Programming with Tcl and Markdown. Flexible framework for mixing Markdown text and Tcl code for automatic report generation. The results of the Tcl code evaluation are embedded into the output document.
Usage as package:
package require tmdoc::tmdoc
namespace import tmdoc::tmdoc
tmdoc infile ?-outfile outputfile -mode tangle?
Usage as command line application:
tclsh tmdoc.tcl infile ?--outfile outputfile --mode tangle?
tmdoc::tmdoc is a tool for literate programming. It either evaluates Tcl code embedded within Markdown documents in weave mode or it alternativly extracts Tcl code from such documents in tangle mode. The results of the Tcl code written in code chunks using backticks as code indicators oas well as the Tcl code can be displayed or hidden by setting code chunk options. tmdoc::tmdoc can be used as Tcl package or standalone as a console application.
| tmdoc::tmdoc infile ?-outfile filename -mode weave | tangle? |
|---|
Reads the inputfile infile and either evaluates the Tcl code within ' the code chunks in the infile document and adds the evaluation results if the given mode is weave, which is default. If the given mode is tangle
the tcl code within code chunks is written out. The output is either send to the stdout channel or to the given outfile. The following arguments or options can be given:
- infile (mandatory) the file which contains Tcl code embedded with Markdown code, usually the file has an extension .tmd
- -outfile filename (optional) the file where the output is written to, default: stdout.
- -mode weave|tangle (optional) either weave for evaluating the Tcl code or tangle for extracting the Tcl code, default: weave.
package require tmdoc
namespace import tmdoc::tmdoc
tmdoc tmdoc-example.tmd --outfile tmdoc-example.md
tmdoc tmdoc-example.tmd --mode tangle --outfile tmdoc-example.tcl
For a complete list of Markdown formatting commands consult the basic Markdown syntax at https://daringfireball.net.
Tcl code is embedded as chunks into the Markdown documents using backticks. Code blocks are started with triple backticks and indicated with the the string "tcl" within curly braces. See the following example.
```{tcl}
set x 1
```
This would show both the Tcl code as well the output of the last statement.
Within the curly braces a few chunk options can be placed in the form of prop=value like in the example below:
```{tcl label=mlabel,echo=false,results=hide}
set x 1
```
Short Tcl codes can be as well evaluated within the standard text flow. For instance:
The current date is `tcl clock format [clock seconds] -format "%Y-%m-%d"`
Would insert the current date into the text. So text inline code chunks are possible using single backticks such as here \tcl set x` `.
Inside standard code chunks as well images with Tcl can be generated with normal Tcl code.
To support the standard chunk properties fig=true, optionally with include=false however a Tcl procedure proc must be provided. Below is an example to use the tklib package canvas::snap to create images using the Tk canvas.
```{tcl}
package require Tk
package require canvas::snap
pack [canvas .c -background beige] \
-padx 5 -pady 5 -side top -fill both -expand yes
proc figure {outfile}
set img [canvas::snap .c]
$img write $outfile -format png
}
```
After preparing the canvas and the figure procedure the canvas can be used for making images like in the example below:
```{tcl,fig=true,results=hide}
.c create rectangle 60 60 90 90 -fill blue
```
The code above will create a canvas figure and embeds it automatically. If you need more control on the figure placement you can use the option include=false
```{tcl,label=mfig,fig=true,results=hide,include=false}
.c create rectangle 65 65 85 85 -fill blue
```
You can now manually place the figure. The filename of the figure will
be automatically created, it is the basename of the tmd-file and the label.
So in principle: basename-label.png. You can embed the figure using Markdown
figure markup such as:
For a detailed tutorial on how to do literate programming with Tcl have a look at the Tcl Markdown tutorial
The tmdoc::tmdoc package needs a working installation of Tcl8.6 or Tcl8.7. Tcl 8.4 and 8.5 might wortk but are untested and not supported.
The tmdoc::tmdoc package can be installed either as command line application or as a Tcl module.
Installation as command line application can be done by copying the tmdoc.tcl as
tmdoc to a directory which is in your executable path. You should make this file executable using chmod.
Installation as Tcl module is achieved by copying the file tmdoc.tcl to a place
which is your Tcl module path as tmdoc/tmdoc-0.3.tm for instance. See the tm manual page
Installation as Tcl package is done if you copy the tmdoc folder with all it's files to a path that belongs to the list of your Tcl library paths.
The script contains it's own documentation written in Markdown. The documentation can be extracted by using the commandline swith --man
tclsh tmdoc.tcl --man
The documentation can be converted to HTML, PDF or Unix manual pages with the aid of a Markdown processor such as pandoc ot the Tcl application mkdoc. Here an example for the conversion using mkdoc
The tmdoc::tmdoc package was written by Dr. Detlef Groth, Schwielowsee, Germany.
Tcl Markdown processor tmdoc::tmdoc, version 0.3
Copyright (c) 2020 Dr. Detlef Groth, E-mail: <detlef(at)dgroth(dot)de>
This library is free software; you can use, modify, and redistribute it for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions.
This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.