-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
340 lines (334 loc) · 17 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<meta name="author" content="Detlef Groth" />
<meta name="dcterms.date" content="2024-11-28" />
<title>Pantcl README</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<link rel="stylesheet" href="mini.css" />
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header id="title-block-header">
<h1 class="title">Pantcl README</h1>
<p class="author">Detlef Groth</p>
<p class="date">2024-11-28</p>
</header>
<h1 id="pantcl">Pantcl <img
src="https://github.com/mittelmark/pantcl/actions/workflows/main.yml/badge.svg" /></h1>
<p><strong>Currently the filter for function for pandoc version larger
than 3.0 is broken, only the standalone line filtering does
work!</strong></p>
<p>Standalone Tcl application for document conversion with support for
Tcl based filters using the Pandoc document processor or Tcl only.</p>
<p>For a overview about the Pandoc Tcl filter you can see as well the
presentation at the presentation at <a
href="https://raw.githubusercontent.com/mittelmark/DGTcl/master/pandoc-tcl-filter/doc/Groth-S-and-T-2021.pdf">S
& T 2021</a>.</p>
<p>The application <code>pantcl(.bin)</code> is a command line tool
which can be used as a standalone tool for document conversion from
Markdown to HTML. In the Markdown document as well code for programming
languages like Tcl, Python, C++, Go or other tools like diagram creation
tools, image creation tools or for instance music note processors can be
embedded. For processing other input formats like ReStructuredText, Wiki
Syntax, LaTeX it can be used as well as a filter for the pandoc document
processor. This way it is as well possible to target other output format
like docx, pdf and many others. The tools contains as well a graphical
user interface for direct editing of code for graphical tools like
GraphViz, PlantUml and many others.</p>
<p>So in summary pantcl allows you:</p>
<ul>
<li>document conversion from Markdown to HTNML with evaluation of
internal code chunks without pandoc</li>
<li>document conversion from many input (Markdown, ReStructuredText,
Wiki formats, …) to many output formats (HTML, DOCX, PDF, …) with
evaluation of internal code chunks</li>
<li>writing code documentation inside source code using a
<code>#'</code> prefix followed by Markdown code</li>
<li>write filters for other graphical or programming tools using the Tcl
programming language</li>
<li>use a graphical interface to edit Markdown files with embedded code
chunks</li>
<li>use a graphical interface to edit diagram code with real time
preview</li>
</ul>
<h1 id="processing-schema">Processing schema</h1>
<p><img
src="https://kroki.io/graphviz/svg/eNqNUstOwzAQvPMVq55LRXoCWUZCQoIDSAh6i3JIYzex6tjBdksK4t9Z20mbhlLRQx3Pzo5nH0yUJm8qeICvC4A6N6VQ9GqWELwpzXi60sqpvOZ08iTUpoUnseTGCcUnxIes-OQ0uc72fFvlDadL3U6t20lOV0JKzog_Ci21oXa9W8oNn34I5iqazObTiouycvjqTUYAfyj1BSZXa2rxYQKv1qWl0ZuGllfTgVAua60yID4B4F4XLfS85DcPSd9j5Wd2TrhXbnLFdIG3u7dFggcyHTfpIaHQRlkh11nkzPGIOXMCUeLR1fKMNzhlbsHbf5T9wlZnhHuz9pRb0j8bB_0H4cgT0w4f5u-KQO14i3WKwv-tCZhGakfA2W1JvChODS5v--bhV-gentFRh8wPnPDpGwV-mZ7ZIeLv2I1joNOPvC6K9tK4dkJthc2C0kDd78gIwv4FVlif3kCH4-HLOZIcpKcyX3JJ4y0Eus2I-AQDrpCTQcQe6veg7-YesMEGtnYM-UYPsGBAFGMWzuAI8qMLIxml-oKGEFx8_wB6nUqY" /></p>
<h1 id="documentation">Documentation</h1>
<p>Here are links to the documentation:</p>
<ul>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/pantcl.html">pantcl.html</a>
- main documentation</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/pantcl-tutorial.html">pantcl-tutorial.html</a>
- more extensive tutorial</li>
</ul>
<p><a name="filterlist" /> Filter documentation:</p>
<ul>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-abc.html">filter-abc</a>
- visualize <a href="https://abcnotation.com/">ABC music
notation</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-cmd.html">filter-cmd</a>
- execute shell scripts for instance <a
href="http://lilypond.org/">Lilypond music scripts</a>, <a
href="https://www.graphviz.org">GraphViz</a> scripts, Python, Lua, R
scripts, <a href="https://www.sqlite.org">sqlite3</a> scripts, or code
for languages like C, C++, Go, Rust, V etc.</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-dot.html">filter-dot</a>
- <a href="https://www.graphviz.org">GraphViz dot</a> filter</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-emf.html">filter-emf</a>
- <a href="http://www.jasspa.com">Jasspa MicroEmacs macros</a>
filter</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-eqn.html">filter-eqn</a>
- visualize mathematical equations using eqn2graph, see here <a
href="https://lists.gnu.org/archive/html/groff/2013-10/pdfTyBN2VWR1c.pdf">Guide
for typesetting using eqn</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-julia.html">filter-julia</a>
- statistical language Julia (slow for embedding, use R instead) <a
href="https://julialang.org/">Julia Website</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-kroki.html">filter-kroki</a>
- visualize diagram code using the <a href="https://kroki.io">kroki
webservice</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-mmd.html">filter-mmd</a>
- visualize diagram code using the <a
href="https://github.com/mermaidjs/mermaid.cli">mermaid command line
tool</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-mtex.html">filter-mtex</a>
- visualize mathematical equations using LaTeX</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-pic.html">filter-pic</a>
- visualize diagram and flowcharts using the <a
href="https://en.wikipedia.org/wiki/PIC_(markup_language)">PIC
language</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-pik.html">filter-pik</a>
- visualize diagram code or flowcharts uing <a
href="https://fossil-scm.org/home/doc/trunk/www/pikchr.md">pikchr</a> or
<a
href="https://fossil-scm.org/home/doc/trunk/www/index.wiki">fossil</a></li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-pipe.html">filter-pipe</a>
- embed R, Python or Octave code or plots into Markdown</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-puml.html">filter-puml</a>
- embed <a href="http://www.plantuml.com">PlantUML</a> code</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-rplot.html">filter-rplot</a>
- embed R plots</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-sqlite.html">filter-sqlite</a>
- embed <a href="https://www.sqlite.org">Sqlite3 SQL database</a>
statements</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-tcl.html">filter-tcl</a>
- embed Tcl statements</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-tcrd.html">filter-tcrd</a>
- embed Tcl music chords.</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-tdot.html">filter-tdot</a>
- embed Tcl GraphViz diaragrams</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/lib/tclfilters/filter-tsvg.html">filter-tsvg</a>
- embed Tcl created SVG code</li>
</ul>
<p>External filter(s):</p>
<ul>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/user/user-filter.html">user-filter</a>
- documentation on how to create and use a filter not embedded directly
within the pantcl executable</li>
<li><a
href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/mittelmark/pantcl/master/user/filter-geasy.html">filter-geasy</a>
- example for an external user defined filter not embedded directly
within the pantcl executable</li>
</ul>
<h1 id="installation">Installation</h1>
<p>Please note, that you must have a tclsh executable in your PATH to
use this tool. On Ubuntu systems you can install Tcl using your package
managers like this: <code>sudo apt install Tcl</code>. If you have a
<code>tclsh</code> executable in your <code>PATH</code> you then
download the latest build from the Github page here:</p>
<p><a
href="https://github.com/mittelmark/pantcl/files/11603113/pantcl.bin.gz">https://github.com/mittelmark/pantcl/files/11603113/pantcl.bin.gz</a></p>
<p>Unpack the Gzip file and make the file pantcl.bin executable using
chmod. You can as rename it for instance to just <code>pantcl</code>.
Then move it to a folder within belonging to your <code>PATH</code>
variable. For instance “~./bin” or “~/.local/bin”.</p>
<p>Before you continue check if you executable is working by writing in
the terminal something like this:</p>
<pre><code>$ pantcl --version
0.9.12
$ pandoc --version
pandoc 2.14.2
...</code></pre>
<p>For Windows you should download the standalone executable which
contains a Tcl library and all required libraries and files within. <a
href="https://github.com/mittelmark/pantcl/releases/download/0.9.11/pantcl.exe">https://github.com/mittelmark/pantcl/releases/download/0.9.11/pantcl.exe</a>.
Just dowload the file to your harddisk and place it somewhere in your
PATH. The in a terminal window, Powershell, Cmd, etc. type
<code>pantcl --version</code> if this works you should be able to use it
a Pandoc filter.</p>
<p>Without an installed pandoc executable only conversion from Markdown
to HTML can be performed.</p>
<p>The file <code>pantcl.bin</code> contains embedded all the filters
mentioned above. You can try out the installation by creating a simple
Markdown file with some embedded Tcl code like this:</p>
<pre><code> ---
title: Test Markdown witch embedded Tcl code.
author: Detlef Groth
date: 2023-01-11
tcl:
eval: 1
---
## Header
This is some text.
```{.tcl eval=true}
set x 1
set x
```
Here some inline Tcl expression x is now `tcl set x`.
This document was compiled at
`tcl clock format [clock seconds] -format "%Y-%m-%d %H:%M:%S"` CET.</code></pre>
<p>Save this code in a file <code>test.md</code> removing the leading
whitespaces and try to convert the file using the command line:</p>
<pre><code>pantcl.bin test.md test.html -s</code></pre>
<p>The output <code>test.html</code> should then look like this:</p>
<p><img src="examples/test1.png" /></p>
<p>If this works you can continue and try to use other code filters from
the list shown <a href="#filterlist">above</a>.</p>
<p>Please note, that since version 0.9.2 the filter evaluation is per
default set to false to avoid interpretation just by accident. You must
enable filter evaluation either on individual code chunks by setting
<code>eval=true</code> as the code chunk option as shown above or if you
like to have it globally enabbled by writing it in the YAML header of a
Markdown document like this:</p>
<pre><code>---
title: xyz
author: nn
date: 2023-03-11
tcl:
eval: 1
dot:
eval: 1
---</code></pre>
<p>Which would enable code evaluation for Tcl and graphics generation
for every GraphViz dot code chunk.</p>
<h2 id="rst-files">Rst files</h2>
<p>If your input document does not support YAML headers you can provide
a YAML configuration in an external file, an example can be seen in the
file <a href="tests/sample.yaml">tests/sample.yaml</a>. You then provide
the required argument for the pandoc document converter in the command
line like this:</p>
<pre><code>pandoc sample.rst --filter pantcl -o sample-rst.html -s \
--metadata-file sample.yaml</code></pre>
<p>How to define chunk options in Rst files can be seen here in the file
<a
href="https://raw.githubusercontent.com/mittelmark/pantcl/main/tests/sample.rst">tests/sample.rst</a>.</p>
<p>Here an example for an inserted GraphViz dot code chunk in such an
Rst file:</p>
<pre><code>.. code-block:: dot
:caption: GraphViz dot example
:eval: true
digraph g {
A -> B ;
}
</code></pre>
<p>To create a PDF file you could use a command line like this:</p>
<pre><code>pandoc sample.rst --filter pantcl.tcl -o sample-rst.pdf \
--metadata documentclass=scrartcl --metadata-file sample.yaml</code></pre>
<p>Here the resulting output file <a
href="https://github.com/mittelmark/pantcl/files/10951380/sample-rst.pdf">sample-rst.pdf</a>.</p>
<h2 id="latex-files">LaTeX files</h2>
<p>There is as well support for LaTeX as input file format. You just
must use the <code>Verbatim</code> (uppercase V) environment together
with the chunk options in brackets. The filtertype will be declared
giving the filter option. Here an example for a dot filter in your LaTeX
code:</p>
<pre><code>\begin{Verbatim}[filter=dot,eval=true]
digraph g {
rankdir="LR";
node[style=filled,fillcolor=skyblue,shape=box];
A -> B
}
\end{Verbatim}</code></pre>
<p>If you like to hide the source code just specify
<code>echo=false</code> as an additional code chunk option. Here an
example input file <a
href="https://raw.githubusercontent.com/mittelmark/pantcl/main/tests/sample.tex">tests/sample.tex</a>
and here the output <a
href="https://github.com/mittelmark/pantcl/files/10953559/sample-tex.pdf">sample-tex.pdf</a>.</p>
<p>The pdf document can be created with the following command line:</p>
<pre><code>pandoc sample.tex --filter pantcl -o sample-tex.pdf \
--metadata documentclass=scrartcl</code></pre>
<h2 id="gui-application">GUI application</h2>
<p>You can as well run a graphical user interace to edit separate
diagram code files or to edit several code chunks in a Markdown
document. Just call pantcl with a option <code>--gui</code> like
this:</p>
<pre><code>pantcl --gui test.md</code></pre>
<p>Here you see a running session where you can go with your cursor into
the different code chunks and if you press Ctrl-s for file saving the
current code chunk is evaluated and the output is visible in the image
window on top:</p>
<p><img
src="https://user-images.githubusercontent.com/75636/224667970-d99b787d-4174-48eb-be79-1076c33f4bc1.png" /></p>
<h2 id="license">LICENSE</h2>
<p>BSD 2-Clause License</p>
<p>Copyright (c) 2023, Detlef Groth</p>
<p>Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:</p>
<ol type="1">
<li><p>Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.</p></li>
<li><p>Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the
distribution.</p></li>
</ol>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
“AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</body>
</html>