Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mittelmark/pantcl

Document conversion with Tcl based filters using pandoc or Tcl only. Example filter for ABC music, GraphViz, PlantUML, R, Python etc are provided.
https://github.com/mittelmark/pantcl

diagram graphviz markdown pandoc pandoc-filter plantuml python r r-programming tcl

Last synced: 7 months ago
JSON representation

Document conversion with Tcl based filters using pandoc or Tcl only. Example filter for ABC music, GraphViz, PlantUML, R, Python etc are provided.

Awesome Lists containing this project

README 

          



Pantcl README



    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;}

  



Pantcl README


Detlef Groth


2024-12-24



Pantcl


License Release Downloads Latest Downloads All Commits 


Supports for example embedding and evaluating …


       


Standalone Tcl application for document conversion with support for

Tcl based filters or using the Pandoc document processor as filter

application.


The application pantcl(.bin) 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.


For a overview about the Pandoc Tcl filter you can see as well the

presentation at the presentation at S

& T 2021.


So in summary the pantcl application allows you:


    

  • perform document conversion from Markdown to HTML with evaluation of

    internal code chunks without pandoc
    • 

  • perform document conversion from many input (Markdown,

    ReStructuredText, Wiki formats, …) to many output formats (HTML, DOCX,

    PDF, …) with evaluation of internal code chunks
    • 

  • writing code documentation inside source code using a

    #' prefix followed by Markdown code
    • 

  • write filters for other graphical or programming tools using the Tcl

    programming language
    • 

  • use a graphical interface to edit Markdown files with embedded code

    chunks
    • 

  • use a graphical interface to edit diagram code with real time

    preview
    • 



Installation


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: sudo apt install Tcl. If you have a

tclsh executable in your PATH you then

download the latest build and place the application

pantcl.bin (pandoc filter enabled) or

pantcl.mbin (not usable as pandoc filter) as well into a

folder belonging to your PATH variable.


The easiest way to install the application is to use the online

installer. Copy and paste the following line into your terminal:


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


That should have installed an application pantcl into

~/.local/bin. Try to check the installation with:


pantcl --version


Hint: Without an installed pandoc executable only conversion from

Markdown to HTML can be performed.


Alternatively you can manually download and install the file pantcl.bin

as a file pantcl somewhere in your PATH. Use this file in case you like

to use it as a pandoc filter application with a syntax like this:


pandoc --filter pantcl [pandoc arguments]

pantcl infile outfile [pandoc and pantcl arguments]

pantcl --help


Or if you just like to convert your Markdown documentation with

embedded programming language, or diagram tool codes you download the

standalone version: pantcl.mbin.

Use this file if you do not want or you cant install pandoc for instance

if you have only a local account on a machine. You then use the

application like this:


pantcl infile outfile [pantcl arguments]

pantcl --help


Processing schema




Documentation


Here are links to the documentation:




 Filter documentation:




External filter(s):


    

  • 

    user-filter

    - documentation on how to create and use a filter not embedded directly

    within the pantcl executable
    • 

  • 

    filter-geasy

    - example for an external user defined filter not embedded directly

    within the pantcl executable
    • 



Example


The file pantcl.bin 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:


    ---

    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.


Save this code in a file test.md removing the leading

whitespaces and try to convert the file using the command line:


pantcl.bin test.md test.html -s


The output test.html should then look like this:




If this works you can continue and try to use other code filters from

the list shown above.


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

eval=true 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:


---

title: xyz

author: nn

date: 2023-03-11

tcl:

    eval: 1

dot:

    eval: 1

---


Which would enable code evaluation for Tcl and graphics generation

for every GraphViz dot code chunk.


Rst files


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 tests/sample.yaml. You then provide

the required argument for the pandoc document converter in the command

line like this:


pandoc sample.rst --filter pantcl -o sample-rst.html -s \

        --metadata-file sample.yaml


How to define chunk options in Rst files can be seen here in the file

tests/sample.rst.


Here an example for an inserted GraphViz dot code chunk in such an

Rst file:


.. code-block:: dot

   :caption: GraphViz dot example

   :eval: true



   digraph g {

      A -> B ;

   }



To create a PDF file you could use a command line like this:


pandoc sample.rst --filter pantcl.tcl -o sample-rst.pdf \

    --metadata documentclass=scrartcl --metadata-file sample.yaml


Here the resulting output file sample-rst.pdf.


LaTeX files


There is as well support for LaTeX as input file format. You just

must use the Verbatim (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:


\begin{Verbatim}[filter=dot,eval=true]

digraph g {

  rankdir="LR";

  node[style=filled,fillcolor=skyblue,shape=box];

  A -> B

}

\end{Verbatim}


If you like to hide the source code just specify

echo=false as an additional code chunk option. Here an

example input file tests/sample.tex

and here the output sample-tex.pdf.


The pdf document can be created with the following command line:


pandoc sample.tex --filter pantcl -o sample-tex.pdf \

     --metadata documentclass=scrartcl


GUI application


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 --gui like

this:


pantcl --gui test.md


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:




LICENSE


BSD 2-Clause License


Copyright (c) 2023-2024, Detlef Groth, University of Potsdam,

Germany


Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are

met:


    

  1. Redistributions of source code must retain the above copyright

    notice, this list of conditions and the following disclaimer.
    2. 

  2. 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.
    3. 



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.