diff options
Diffstat (limited to 'paper/lua-filters/diagram-generator')
| -rw-r--r-- | paper/lua-filters/diagram-generator/.gitignore | 2 | ||||
| -rw-r--r-- | paper/lua-filters/diagram-generator/Makefile | 13 | ||||
| -rw-r--r-- | paper/lua-filters/diagram-generator/README.md | 252 | ||||
| -rw-r--r-- | paper/lua-filters/diagram-generator/diagram-generator.lua | 295 | ||||
| -rw-r--r-- | paper/lua-filters/diagram-generator/sample.md | 244 |
5 files changed, 0 insertions, 806 deletions
diff --git a/paper/lua-filters/diagram-generator/.gitignore b/paper/lua-filters/diagram-generator/.gitignore deleted file mode 100644 index 01e67c0..0000000 --- a/paper/lua-filters/diagram-generator/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -sample.html -tmp-latex diff --git a/paper/lua-filters/diagram-generator/Makefile b/paper/lua-filters/diagram-generator/Makefile deleted file mode 100644 index ccd79c8..0000000 --- a/paper/lua-filters/diagram-generator/Makefile +++ /dev/null @@ -1,13 +0,0 @@ -.PHONY: test -test: sample.html - -sample.html: sample.md - @pandoc --self-contained \ - --lua-filter=diagram-generator.lua \ - --metadata=pythonPath:"python3" \ - --metadata=title:"README" \ - --output=$@ $< - -clean: - rm -f sample.html - rm -rf tmp-latex diff --git a/paper/lua-filters/diagram-generator/README.md b/paper/lua-filters/diagram-generator/README.md deleted file mode 100644 index d04e204..0000000 --- a/paper/lua-filters/diagram-generator/README.md +++ /dev/null @@ -1,252 +0,0 @@ -# Diagram Generator Lua Filter - -## Introduction -This Lua filter is used to create images with or without captions from code -blocks. Currently PlantUML, Graphviz, Ti*k*Z and Python can be processed. -This document also serves as a test document, which is why the subsequent -test diagrams are integrated in every supported language. - -## Prerequisites -To be able to use this Lua filter, the respective external tools must be -installed. However, it is sufficient if the tools to be used are installed. -If you only want to use PlantUML, you don't need LaTeX or Python, etc. - -### PlantUML -To use PlantUML, you must install PlantUML itself. See the -[PlantUML website](http://plantuml.com/) for more details. It should be -noted that PlantUML is a Java program and therefore Java must also -be installed. - -By default, this filter expects the plantuml.jar file to be in the -working directory. Alternatively, the environment variable -`PLANTUML` can be set with a path. If, for example, a specific -PlantUML version is to be used per pandoc document, the -`plantumlPath` meta variable can be set. - -Furthermore, this filter assumes that Java is located in the -system or user path. This means that from any place of the system -the `java` command is understood. Alternatively, the `JAVA_HOME` -environment variable gets used. To use a specific Java version per -pandoc document, use the `javaPath` meta variable. Please notice -that `JAVA_HOME` must be set to the java's home directory e.g. -`c:\Program Files\Java\jre1.8.0_201\` whereas `javaPath` must be -set to the absolute path of `java.exe` e.g. -`c:\Program Files\Java\jre1.8.0_201\bin\java.exe`. - -Example usage: - -~~~~~~~~~~~~~~~~ -```{.plantuml caption="This is an image, created by **PlantUML**."} -@startuml -Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response -Alice -> Bob: Another authentication Request Alice <-- Bob: another Response -@enduml -``` -~~~~~~~~~~~~~~~~ - -### Graphviz -To use Graphviz you only need to install Graphviz, as you can read -on its [website](http://www.graphviz.org/). There are no other -dependencies. - -This filter assumes that the `dot` command is located in the path -and therefore can be used from any location. Alternatively, you can -set the environment variable `DOT` or use the pandoc's meta variable -`dotPath`. - -Example usage from [the Graphviz -gallery](https://graphviz.gitlab.io/_pages/Gallery/directed/fsm.html): - -~~~~~~~~~~~~~~~~ -```{.graphviz caption="This is an image, created by **Graphviz**'s dot."} -digraph finite_state_machine { - rankdir=LR; - size="8,5" - node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8; - node [shape = circle]; - LR_0 -> LR_2 [ label = "SS(B)" ]; - LR_0 -> LR_1 [ label = "SS(S)" ]; - LR_1 -> LR_3 [ label = "S($end)" ]; - LR_2 -> LR_6 [ label = "SS(b)" ]; - LR_2 -> LR_5 [ label = "SS(a)" ]; - LR_2 -> LR_4 [ label = "S(A)" ]; - LR_5 -> LR_7 [ label = "S(b)" ]; - LR_5 -> LR_5 [ label = "S(a)" ]; - LR_6 -> LR_6 [ label = "S(b)" ]; - LR_6 -> LR_5 [ label = "S(a)" ]; - LR_7 -> LR_8 [ label = "S(b)" ]; - LR_7 -> LR_5 [ label = "S(a)" ]; - LR_8 -> LR_6 [ label = "S(b)" ]; - LR_8 -> LR_5 [ label = "S(a)" ]; -} -``` -~~~~~~~~~~~~~~~~ - -### Ti*k*Z -Ti*k*Z (cf. [Wikipedia](https://en.wikipedia.org/wiki/PGF/TikZ)) is a -description language for graphics of any kind that can be used within -LaTeX (cf. [Wikipedia](https://en.wikipedia.org/wiki/LaTeX)). - -Therefore a LaTeX system must be installed on the system. The Ti*k*Z code is -embedded into a dynamic LaTeX document. This temporary document gets -translated into a PDF document using LaTeX (`pdflatex`). Finally, -Inkscape is used to convert the PDF file to the desired format. - -Note: We are using Inkscape here to use a stable solution for the -convertion. Formerly ImageMagick was used instead. ImageMagick is -not able to convert PDF files. Hence, it uses Ghostscript to do -so, cf. [1](https://stackoverflow.com/a/6599718/2258393). -Unfortunately, Ghostscript behaves unpredictable during Windows and -Linux tests cases, cf. [2](https://stackoverflow.com/questions/21774561/some-pdfs-are-converted-improperly-using-imagemagick), -[3](https://stackoverflow.com/questions/9064706/imagemagic-convert-command-pdf-convertion-with-bad-size-orientation), [4](https://stackoverflow.com/questions/18837093/imagemagic-renders-image-with-black-background), -[5](https://stackoverflow.com/questions/37392798/pdf-to-svg-is-not-perfect), -[6](https://stackoverflow.com/q/10288065/2258393), etc. By using Inkscape, -we need one dependency less and get rid of unexpected Ghostscript issues. - -Due to this more complicated process, the use of Ti*k*Z is also more -complicated overall. The process is error-prone: An insufficiently -configured LaTeX installation or an insufficiently configured -Inkscape installation can lead to errors. Overall, this results in -the following dependencies: - -- Any LaTeX installation. This should be configured so that -missing packages are installed automatically. This filter uses the -`pdflatex` command which is available by the system's path. Alternatively, -you can set the `PDFLATEX` environment variable. In case you have to use -a specific LaTeX version on a pandoc document basis, you might set the -`pdflatexPath` meta variable. - -- An installation of [Inkscape](https://inkscape.org/). -It is assumed that the `inkscape` command is in the path and can be -executed from any location. Alternatively, the environment -variable `INKSCAPE` can be set with a path. If a specific -version per pandoc document is to be used, the `inkscapePath` -meta-variable can be set. - -In order to use additional LaTeX packages, use the optional -`additionalPackages` attribute in your document, as in the -example below. - -Example usage from [TikZ -examples](http://www.texample.net/tikz/examples/parallelepiped/) by -[Kjell Magne Fauske](http://www.texample.net/tikz/examples/nav1d/): - -~~~~~~~~~~~~~~~~ -```{.tikz caption="This is an image, created by **TikZ i.e. LaTeX**." - additionalPackages="\usepackage{adjustbox}"} -\usetikzlibrary{arrows} -\tikzstyle{int}=[draw, fill=blue!20, minimum size=2em] -\tikzstyle{init} = [pin edge={to-,thin,black}] - -\resizebox{16cm}{!}{% - \trimbox{3.5cm 0cm 0cm 0cm}{ - \begin{tikzpicture}[node distance=2.5cm,auto,>=latex'] - \node [int, pin={[init]above:$v_0$}] (a) {$\frac{1}{s}$}; - \node (b) [left of=a,node distance=2cm, coordinate] {a}; - \node [int, pin={[init]above:$p_0$}] at (0,0) (c) - [right of=a] {$\frac{1}{s}$}; - \node [coordinate] (end) [right of=c, node distance=2cm]{}; - \path[->] (b) edge node {$a$} (a); - \path[->] (a) edge node {$v$} (c); - \draw[->] (c) edge node {$p$} (end) ; - \end{tikzpicture} - } -} -``` -~~~~~~~~~~~~~~~~ - -### Python -In order to use Python to generate a diagram, your Python code must store the -final image data in a temporary file with the correct format. In case you use -matplotlib for a diagram, add the following line to do so: - -```python -plt.savefig("$DESTINATION$", dpi=300, fomat="$FORMAT$") -``` - -The placeholder `$FORMAT$` gets replace by the necessary format. Most of the -time, this will be `png` or `svg`. The second placeholder, `$DESTINATION$` -gets replaced by the path and file name of the destination. Both placeholders -can be used as many times as you want. Example usage from the [Matplotlib -examples](https://matplotlib.org/gallery/lines_bars_and_markers/cohere.html#sphx-glr-gallery-lines-bars-and-markers-cohere-py): - -~~~~~~~~~~~~~~~~ -```{.py2image caption="This is an image, created by **Python**."} -import matplotlib -matplotlib.use('Agg') - -import sys -import numpy as np -import matplotlib.pyplot as plt - -# Fixing random state for reproducibility -np.random.seed(19680801) - -dt = 0.01 -t = np.arange(0, 30, dt) -nse1 = np.random.randn(len(t)) # white noise 1 -nse2 = np.random.randn(len(t)) # white noise 2 - -# Two signals with a coherent part at 10Hz and a random part -s1 = np.sin(2 * np.pi * 10 * t) + nse1 -s2 = np.sin(2 * np.pi * 10 * t) + nse2 - -fig, axs = plt.subplots(2, 1) -axs[0].plot(t, s1, t, s2) -axs[0].set_xlim(0, 2) -axs[0].set_xlabel('time') -axs[0].set_ylabel('s1 and s2') -axs[0].grid(True) - -cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt) -axs[1].set_ylabel('coherence') - -fig.tight_layout() -plt.savefig("$DESTINATION$", dpi=300, fomat="$FORMAT$") -``` -~~~~~~~~~~~~~~~~ - -Precondition to use Python is a Python environment which contains all -necessary libraries you want to use. To use, for example, the standard -[Anaconda Python](https://www.anaconda.com/distribution/) environment -on a Microsoft Windows system ... - -- set the environment variable `PYTHON` or the meta key `pythonPath` -to `c:\ProgramData\Anaconda3\python.exe` - -- set the environment variable `PYTHON_ACTIVATE` or the meta -key `activatePythonPath` to `c:\ProgramData\Anaconda3\Scripts\activate.bat`. - -Pandoc will activate this Python environment and starts Python with your code. - -## How to run pandoc -This section will show, how to call Pandoc in order to use this filter with -meta keys. The following command assume, that the filters are stored in the -subdirectory `filters`. Further, this is a example for a Microsoft Windows -system. - -Command to use PlantUML (a single line): - -``` -pandoc.exe README.md -f markdown -t docx --self-contained --standalone --lua-filter=filters\diagram-generator.lua --metadata=plantumlPath:"c:\ProgramData\chocolatey\lib\plantuml\tools\plantuml.jar" --metadata=javaPath:"c:\Program Files\Java\jre1.8.0_201\bin\java.exe" -o README.docx -``` - -All available environment variables: - -- `PLANTUML` e.g. `c:\ProgramData\chocolatey\lib\plantuml\tools\plantuml.jar`; Default: `plantuml.jar` -- `INKSCAPE` e.g. `c:\Program Files\Inkscape\inkscape.exe`; Default: `inkscape` -- `PYTHON` e.g. `c:\ProgramData\Anaconda3\python.exe`; Default: n/a -- `PYTHON_ACTIVATE` e.g. `c:\ProgramData\Anaconda3\Scripts\activate.bat`; Default: n/a -- `JAVA_HOME` e.g. `c:\Program Files\Java\jre1.8.0_201`; Default: n/a -- `DOT` e.g. `c:\ProgramData\chocolatey\bin\dot.exe`; Default: `dot` -- `PDFLATEX` e.g. `c:\Program Files\MiKTeX 2.9\miktex\bin\x64\pdflatex.exe`; Default: `pdflatex` - -All available meta keys: - -- `plantumlPath` -- `inkscapePath` -- `pythonPath` -- `activatePythonPath` -- `javaPath` -- `dotPath` -- `pdflatexPath` diff --git a/paper/lua-filters/diagram-generator/diagram-generator.lua b/paper/lua-filters/diagram-generator/diagram-generator.lua deleted file mode 100644 index aef2ea4..0000000 --- a/paper/lua-filters/diagram-generator/diagram-generator.lua +++ /dev/null @@ -1,295 +0,0 @@ ---[[ - This Lua filter is used to create images with or without captions from - code blocks. Currently PlantUML, GraphViz, Tikz, and Python can be - processed. For further details, see README.md. - - Thanks to @floriandd2ba and @jgm for the initial implementation of - the PlantUML filter, which I used as a template. Thanks also @muxueqz - for the code to generate a GraphViz image. -]] - --- The PlantUML path. If set, uses the environment variable PLANTUML or the --- value "plantuml.jar" (local PlantUML version). In order to define a --- PlantUML version per pandoc document, use the meta data to define the key --- "plantumlPath". -local plantumlPath = os.getenv("PLANTUML") or "plantuml.jar" - --- The Inkscape path. In order to define an Inkscape version per pandoc --- document, use the meta data to define the key "inkscapePath". -local inkscapePath = os.getenv("INKSCAPE") or "inkscape" - --- The Python path. In order to define a Python version per pandoc document, --- use the meta data to define the key "pythonPath". -local pythonPath = os.getenv("PYTHON") - --- The Python environment's activate script. Can be set on a per document --- basis by using the meta data key "activatePythonPath". -local pythonActivatePath = os.getenv("PYTHON_ACTIVATE") - --- The Java path. In order to define a Java version per pandoc document, --- use the meta data to define the key "javaPath". -local javaPath = os.getenv("JAVA_HOME") -if javaPath then - javaPath = javaPath .. package.config:sub(1,1) .. "bin" - .. package.config:sub(1,1) .. "java" -else - javaPath = "java" -end - --- The dot (Graphviz) path. In order to define a dot version per pandoc --- document, use the meta data to define the key "dotPath". -local dotPath = os.getenv("DOT") or "dot" - --- The pdflatex path. In order to define a pdflatex version per pandoc --- document, use the meta data to define the key "pdflatexPath". -local pdflatexPath = os.getenv("PDFLATEX") or "pdflatex" - --- The default format is SVG i.e. vector graphics: -local filetype = "svg" -local mimetype = "image/svg+xml" - --- Check for output formats that potentially cannot use SVG --- vector graphics. In these cases, we use a different format --- such as PNG: -if FORMAT == "docx" then - filetype = "png" - mimetype = "image/png" -elseif FORMAT == "pptx" then - filetype = "png" - mimetype = "image/png" -elseif FORMAT == "rtf" then - filetype = "png" - mimetype = "image/png" -end - --- Execute the meta data table to determine the paths. This function --- must be called first to get the desired path. If one of these --- meta options was set, it gets used instead of the corresponding --- environment variable: -function Meta(meta) - plantumlPath = meta.plantumlPath or plantumlPath - inkscapePath = meta.inkscapePath or inkscapePath - pythonPath = meta.pythonPath or pythonPath - pythonActivatePath = meta.activatePythonPath or pythonActivatePath - javaPath = meta.javaPath or javaPath - dotPath = meta.dotPath or dotPath - pdflatexPath = meta.pdflatexPath or pdflatexPath -end - --- Call plantuml.jar with some parameters (cf. PlantUML help): -local function plantuml(puml, filetype) - local final = pandoc.pipe(javaPath, {"-jar", plantumlPath, "-t" .. filetype, "-pipe", "-charset", "UTF8"}, puml) - return final -end - --- Call dot (GraphViz) in order to generate the image --- (thanks @muxueqz for this code): -local function graphviz(code, filetype) - local final = pandoc.pipe(dotPath, {"-T" .. filetype}, code) - return final -end - --- Compile LaTeX with Tikz code to an image: -local function tikz2image(src, filetype, additionalPackages) - - -- Define file names: - local outfile = string.format("./tmp-latex/file.%s", filetype) - local tmp = "./tmp-latex/file" - local tmpDir = "./tmp-latex/" - - -- Ensure, that the tmp directory exists: - os.execute("mkdir -p tmp-latex") - - -- Build and write the LaTeX document: - local f = io.open(tmp .. ".tex", 'w') - f:write("\\documentclass{standalone}\n\\usepackage{tikz}\n") - - -- Any additional package(s) are desired? - if additionalPackages then - f:write(additionalPackages) - end - - f:write("\\begin{document}\n") - f:write(src) - f:write("\n\\end{document}\n") - f:close() - - -- Execute the LaTeX compiler: - pandoc.pipe(pdflatexPath, {'-output-directory', tmpDir, tmp}, '') - - -- Build the basic Inkscape command for the conversion: - local baseCommand = " --without-gui --file=" .. tmp .. ".pdf" - local knownFormat = false - - if filetype == "png" then - - -- Append the subcommands to convert into a PNG file: - baseCommand = baseCommand .. " --export-png=" - .. tmp .. ".png --export-dpi=300" - knownFormat = true - - elseif filetype == "svg" then - - -- Append the subcommands to convert into a SVG file: - baseCommand = baseCommand .. " --export-plain-svg=" .. tmp .. ".svg" - knownFormat = true - - end - - -- Unfortunately, continuation is only possible, if we know the actual - -- format: - local imgData = nil - if knownFormat then - - -- We know the desired format. Thus, execute Inkscape: - os.execute("\"" .. inkscapePath .. "\"" .. baseCommand) - - -- Try to open the image: - local r = io.open(tmp .. "." .. filetype, 'rb') - - -- Read the image, if available: - if r then - imgData = r:read("*all") - r:close() - end - - -- Delete the image tmp file: - os.remove(outfile) - end - - -- Remove the temporary files: - os.remove(tmp .. ".tex") - os.remove(tmp .. ".pdf") - os.remove(tmp .. ".log") - os.remove(tmp .. ".aux") - - return imgData -end - --- Run Python to generate an image: -local function py2image(code, filetype) - - -- Define the temp files: - local outfile = string.format('%s.%s', os.tmpname(), filetype) - local pyfile = os.tmpname() - - -- Replace the desired destination's file type in the Python code: - local extendedCode = string.gsub(code, "%$FORMAT%$", filetype) - - -- Replace the desired destination's path in the Python code: - extendedCode = string.gsub(extendedCode, "%$DESTINATION%$", outfile) - - -- Write the Python code: - local f = io.open(pyfile, 'w') - f:write(extendedCode) - f:close() - - -- Execute Python in the desired environment: - local pycmd = pythonPath .. ' ' .. pyfile - local command = pythonActivatePath - and pythonActivatePath .. ' && ' .. pycmd - or pycmd - os.execute(command) - - -- Try to open the written image: - local r = io.open(outfile, 'rb') - local imgData = nil - - -- When the image exist, read it: - if r then - imgData = r:read("*all") - r:close() - else - io.stderr:write(string.format("File '%s' could not be opened", outfile)) - end - - -- Delete the tmp files: - os.remove(pyfile) - os.remove(outfile) - - return imgData -end - --- Executes each document's code block to find matching code blocks: -function CodeBlock(block) - - -- Predefine a potential image: - local fname = nil - - -- Using a table with all known generators i.e. converters: - local converters = { - plantuml = plantuml, - graphviz = graphviz, - tikz = tikz2image, - py2image = py2image, - } - - -- Check if a converter exists for this block. If not, return the block - -- unchanged. - local img_converter = converters[block.classes[1]] - if not img_converter then - return nil - end - - -- Call the correct converter which belongs to the used class: - local success, img = pcall(img_converter, block.text, - filetype, block.attributes["additionalPackages"] or nil) - - -- Was ok? - if success and img then - -- Hash the figure name and content: - fname = pandoc.sha1(img) .. "." .. filetype - - -- Store the data in the media bag: - pandoc.mediabag.insert(fname, mimetype, img) - - else - - -- an error occured; img contains the error message - io.stderr:write(tostring(img)) - io.stderr:write('\n') - - end - - -- Case: This code block was an image e.g. PlantUML or dot/Graphviz, etc.: - if fname then - - -- Define the default caption: - local caption = {} - local enableCaption = nil - - -- If the user defines a caption, use it: - if block.attributes["caption"] then - caption = pandoc.read(block.attributes.caption).blocks[1].content - - -- This is pandoc's current hack to enforce a caption: - enableCaption = "fig:" - end - - -- Create a new image for the document's structure. Attach the user's - -- caption. Also use a hack (fig:) to enforce pandoc to create a - -- figure i.e. attach a caption to the image. - local imgObj = pandoc.Image(caption, fname, enableCaption) - - -- Now, transfer the attribute "name" from the code block to the new - -- image block. It might gets used by the figure numbering lua filter. - -- If the figure numbering gets not used, this additional attribute - -- gets ignored as well. - if block.attributes["name"] then - imgObj.attributes["name"] = block.attributes["name"] - end - - -- Finally, put the image inside an empty paragraph. By returning the - -- resulting paragraph object, the source code block gets replaced by - -- the image: - return pandoc.Para{ imgObj } - end -end - --- Normally, pandoc will run the function in the built-in order Inlines -> --- Blocks -> Meta -> Pandoc. We instead want Meta -> Blocks. Thus, we must --- define our custom order: -return { - {Meta = Meta}, - {CodeBlock = CodeBlock}, -} diff --git a/paper/lua-filters/diagram-generator/sample.md b/paper/lua-filters/diagram-generator/sample.md deleted file mode 100644 index 231ccdc..0000000 --- a/paper/lua-filters/diagram-generator/sample.md +++ /dev/null @@ -1,244 +0,0 @@ -# Diagram Generator Lua Filter - -## Introduction -This Lua filter is used to create images with or without captions from code -blocks. Currently PlantUML, Graphviz, Ti*k*Z and Python can be processed. -This document also serves as a test document, which is why the subsequent -test diagrams are integrated in every supported language. - -## Prerequisites -To be able to use this Lua filter, the respective external tools must be -installed. However, it is sufficient if the tools to be used are installed. -If you only want to use PlantUML, you don't need LaTeX or Python, etc. - -### PlantUML -To use PlantUML, you must install PlantUML itself. See the -[PlantUML website](http://plantuml.com/) for more details. It should be -noted that PlantUML is a Java program and therefore Java must also -be installed. - -By default, this filter expects the plantuml.jar file to be in the -working directory. Alternatively, the environment variable -`PLANTUML` can be set with a path. If, for example, a specific -PlantUML version is to be used per pandoc document, the -`plantumlPath` meta variable can be set. - -Furthermore, this filter assumes that Java is located in the -system or user path. This means that from any place of the system -the `java` command is understood. Alternatively, the `JAVA_HOME` -environment variable gets used. To use a specific Java version per -pandoc document, use the `javaPath` meta variable. Please notice -that `JAVA_HOME` must be set to the java's home directory e.g. -`c:\Program Files\Java\jre1.8.0_201\` whereas `javaPath` must be -set to the absolute path of `java.exe` e.g. -`c:\Program Files\Java\jre1.8.0_201\bin\java.exe`. - -Example usage: - -```{.plantuml caption="This is an image, created by **PlantUML**."} -@startuml -Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response -Alice -> Bob: Another authentication Request Alice <-- Bob: another Response -@enduml -``` - -### Graphviz -To use Graphviz you only need to install Graphviz, as you can read -on its [website](http://www.graphviz.org/). There are no other -dependencies. - -This filter assumes that the `dot` command is located in the path -and therefore can be used from any location. Alternatively, you can -set the environment variable `DOT` or use the pandoc's meta variable -`dotPath`. - -Example usage from [the Graphviz -gallery](https://graphviz.gitlab.io/_pages/Gallery/directed/fsm.html): - -```{.graphviz caption="This is an image, created by **Graphviz**'s dot."} -digraph finite_state_machine { - rankdir=LR; - size="8,5" - node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8; - node [shape = circle]; - LR_0 -> LR_2 [ label = "SS(B)" ]; - LR_0 -> LR_1 [ label = "SS(S)" ]; - LR_1 -> LR_3 [ label = "S($end)" ]; - LR_2 -> LR_6 [ label = "SS(b)" ]; - LR_2 -> LR_5 [ label = "SS(a)" ]; - LR_2 -> LR_4 [ label = "S(A)" ]; - LR_5 -> LR_7 [ label = "S(b)" ]; - LR_5 -> LR_5 [ label = "S(a)" ]; - LR_6 -> LR_6 [ label = "S(b)" ]; - LR_6 -> LR_5 [ label = "S(a)" ]; - LR_7 -> LR_8 [ label = "S(b)" ]; - LR_7 -> LR_5 [ label = "S(a)" ]; - LR_8 -> LR_6 [ label = "S(b)" ]; - LR_8 -> LR_5 [ label = "S(a)" ]; -} -``` - -### Ti*k*Z -Ti*k*Z (cf. [Wikipedia](https://en.wikipedia.org/wiki/PGF/TikZ)) is a -description language for graphics of any kind that can be used within -LaTeX (cf. [Wikipedia](https://en.wikipedia.org/wiki/LaTeX)). - -Therefore a LaTeX system must be installed on the system. The Ti*k*Z code is -embedded into a dynamic LaTeX document. This temporary document gets -translated into a PDF document using LaTeX (`pdflatex`). Finally, -Inkscape is used to convert the PDF file to the desired format. - -Note: We are using Inkscape here to use a stable solution for the -convertion. Formerly ImageMagick was used instead. ImageMagick is -not able to convert PDF files. Hence, it uses Ghostscript to do -so, cf. [1](https://stackoverflow.com/a/6599718/2258393). -Unfortunately, Ghostscript behaves unpredictable during Windows and -Linux tests cases, cf. [2](https://stackoverflow.com/questions/21774561/some-pdfs-are-converted-improperly-using-imagemagick), -[3](https://stackoverflow.com/questions/9064706/imagemagic-convert-command-pdf-convertion-with-bad-size-orientation), [4](https://stackoverflow.com/questions/18837093/imagemagic-renders-image-with-black-background), -[5](https://stackoverflow.com/questions/37392798/pdf-to-svg-is-not-perfect), -[6](https://stackoverflow.com/q/10288065/2258393), etc. By using Inkscape, -we need one dependency less and get rid of unexpected Ghostscript issues. - -Due to this more complicated process, the use of Ti*k*Z is also more -complicated overall. The process is error-prone: An insufficiently -configured LaTeX installation or an insufficiently configured -Inkscape installation can lead to errors. Overall, this results in -the following dependencies: - -- Any LaTeX installation. This should be configured so that -missing packages are installed automatically. This filter uses the -`pdflatex` command which is available by the system's path. Alternatively, -you can set the `PDFLATEX` environment variable. In case you have to use -a specific LaTeX version on a pandoc document basis, you might set the -`pdflatexPath` meta variable. - -- An installation of [Inkscape](https://inkscape.org/). -It is assumed that the `inkscape` command is in the path and can be -executed from any location. Alternatively, the environment -variable `INKSCAPE` can be set with a path. If a specific -version per pandoc document is to be used, the `inkscapePath` -meta-variable can be set. - -In order to use additional LaTeX packages, use the optional -`additionalPackages` attribute in your document, as in the -example below. - -Example usage from [TikZ -examples](http://www.texample.net/tikz/examples/parallelepiped/) by -[Kjell Magne Fauske](http://www.texample.net/tikz/examples/nav1d/): - -```{.tikz caption="This is an image, created by **TikZ i.e. LaTeX**." - additionalPackages="\usepackage{adjustbox}"} -\usetikzlibrary{arrows} -\tikzstyle{int}=[draw, fill=blue!20, minimum size=2em] -\tikzstyle{init} = [pin edge={to-,thin,black}] - -\resizebox{16cm}{!}{% - \trimbox{3.5cm 0cm 0cm 0cm}{ - \begin{tikzpicture}[node distance=2.5cm,auto,>=latex'] - \node [int, pin={[init]above:$v_0$}] (a) {$\frac{1}{s}$}; - \node (b) [left of=a,node distance=2cm, coordinate] {a}; - \node [int, pin={[init]above:$p_0$}] at (0,0) (c) - [right of=a] {$\frac{1}{s}$}; - \node [coordinate] (end) [right of=c, node distance=2cm]{}; - \path[->] (b) edge node {$a$} (a); - \path[->] (a) edge node {$v$} (c); - \draw[->] (c) edge node {$p$} (end) ; - \end{tikzpicture} - } -} -``` - -### Python -In order to use Python to generate an diagram, your Python code must store the -final image data in a temporary file with the correct format. In case you use -matplotlib for a diagram, add the following line to do so: - -```python -plt.savefig("$DESTINATION$", dpi=300, fomat="$FORMAT$") -``` - -The placeholder `$FORMAT$` gets replace by the necessary format. Most of the -time, this will be `png` or `svg`. The second placeholder, `$DESTINATION$` -gets replaced by the path and file name of the destination. Both placeholders -can be used as many times as you want. Example usage from the [Matplotlib -examples](https://matplotlib.org/gallery/lines_bars_and_markers/cohere.html#sphx-glr-gallery-lines-bars-and-markers-cohere-py): - -```{.py2image caption="This is an image, created by **Python**."} -import matplotlib -matplotlib.use('Agg') - -import sys -import numpy as np -import matplotlib.pyplot as plt - -# Fixing random state for reproducibility -np.random.seed(19680801) - -dt = 0.01 -t = np.arange(0, 30, dt) -nse1 = np.random.randn(len(t)) # white noise 1 -nse2 = np.random.randn(len(t)) # white noise 2 - -# Two signals with a coherent part at 10Hz and a random part -s1 = np.sin(2 * np.pi * 10 * t) + nse1 -s2 = np.sin(2 * np.pi * 10 * t) + nse2 - -fig, axs = plt.subplots(2, 1) -axs[0].plot(t, s1, t, s2) -axs[0].set_xlim(0, 2) -axs[0].set_xlabel('time') -axs[0].set_ylabel('s1 and s2') -axs[0].grid(True) - -cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt) -axs[1].set_ylabel('coherence') - -fig.tight_layout() -plt.savefig("$DESTINATION$", dpi=300, fomat="$FORMAT$") -``` - -Precondition to use Python is a Python environment which contains all -necessary libraries you want to use. To use, for example, the standard -[Anaconda Python](https://www.anaconda.com/distribution/) environment -on a Microsoft Windows system ... - -- set the environment variable `PYTHON` or the meta key `pythonPath` -to `c:\ProgramData\Anaconda3\python.exe` - -- set the environment variable `PYTHON_ACTIVATE` or the meta -key `activatePythonPath` to `c:\ProgramData\Anaconda3\Scripts\activate.bat`. - -Pandoc will activate this Python environment and starts Python with your code. - -## How to run pandoc -This section will show, how to call Pandoc in order to use this filter with -meta keys. The following command assume, that the filters are stored in the -subdirectory `filters`. Further, this is a example for a Microsoft Windows -system. - -Command to use PlantUML (a single line): - -``` -pandoc.exe README.md -f markdown -t docx --self-contained --standalone --lua-filter=filters\diagram-generator.lua --metadata=plantumlPath:"c:\ProgramData\chocolatey\lib\plantuml\tools\plantuml.jar" --metadata=javaPath:"c:\Program Files\Java\jre1.8.0_201\bin\java.exe" -o README.docx -``` - -All available environment variables: - -- `PLANTUML` e.g. `c:\ProgramData\chocolatey\lib\plantuml\tools\plantuml.jar`; Default: `plantuml.jar` -- `INKSCAPE` e.g. `c:\Program Files\Inkscape\inkscape.exe`; Default: `inkscape` -- `PYTHON` e.g. `c:\ProgramData\Anaconda3\python.exe`; Default: n/a -- `PYTHON_ACTIVATE` e.g. `c:\ProgramData\Anaconda3\Scripts\activate.bat`; Default: n/a -- `JAVA_HOME` e.g. `c:\Program Files\Java\jre1.8.0_201`; Default: n/a -- `DOT` e.g. `c:\ProgramData\chocolatey\bin\dot.exe`; Default: `dot` -- `PDFLATEX` e.g. `c:\Program Files\MiKTeX 2.9\miktex\bin\x64\pdflatex.exe`; Default: `pdflatex` - -All available meta keys: - -- `plantumlPath` -- `inkscapePath` -- `pythonPath` -- `activatePythonPath` -- `javaPath` -- `dotPath` -- `pdflatexPath`
\ No newline at end of file |