pandoc-plot 0.7.2.1 → 0.8.0.0
raw patch · 22 files changed
+1338/−693 lines, 22 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
+ Text.Pandoc.Filter.Plot: HTML :: SaveFormat
+ Text.Pandoc.Filter.Plot: [bokehExe] :: Configuration -> !FilePath
+ Text.Pandoc.Filter.Plot: [bokehPreamble] :: Configuration -> !Script
+ Text.Pandoc.Filter.Plot: [plotsjlExe] :: Configuration -> !FilePath
+ Text.Pandoc.Filter.Plot: [plotsjlPreamble] :: Configuration -> !Script
+ Text.Pandoc.Filter.Plot: pandocPlotVersion :: Version
+ Text.Pandoc.Filter.Plot.Internal: Bokeh :: Toolkit
+ Text.Pandoc.Filter.Plot.Internal: HTML :: SaveFormat
+ Text.Pandoc.Filter.Plot.Internal: Plotsjl :: Toolkit
+ Text.Pandoc.Filter.Plot.Internal: [bokehExe] :: Configuration -> !FilePath
+ Text.Pandoc.Filter.Plot.Internal: [bokehPreamble] :: Configuration -> !Script
+ Text.Pandoc.Filter.Plot.Internal: [plotsjlExe] :: Configuration -> !FilePath
+ Text.Pandoc.Filter.Plot.Internal: [plotsjlPreamble] :: Configuration -> !Script
- Text.Pandoc.Filter.Plot: Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration
+ Text.Pandoc.Filter.Plot: Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration
- Text.Pandoc.Filter.Plot.Internal: Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration
+ Text.Pandoc.Filter.Plot.Internal: Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration
Files
- CHANGELOG.md +20/−0
- MANUAL.md +532/−0
- README.md +6/−615
- docs/MANUAL.html +455/−0
- example-config.yml +15/−5
- executable/Main.hs +27/−19
- executable/ManPage.hs +11/−22
- pandoc-plot.cabal +6/−1
- src/Text/Pandoc/Filter/Plot.hs +15/−2
- src/Text/Pandoc/Filter/Plot/Configuration.hs +28/−3
- src/Text/Pandoc/Filter/Plot/Monad.hs +5/−1
- src/Text/Pandoc/Filter/Plot/Monad/Types.hs +8/−0
- src/Text/Pandoc/Filter/Plot/Renderers.hs +33/−16
- src/Text/Pandoc/Filter/Plot/Renderers/Bokeh.hs +73/−0
- src/Text/Pandoc/Filter/Plot/Renderers/PlotlyPython.hs +10/−3
- src/Text/Pandoc/Filter/Plot/Renderers/PlotlyR.hs +20/−3
- src/Text/Pandoc/Filter/Plot/Renderers/Plotsjl.hs +47/−0
- src/Text/Pandoc/Filter/Plot/Renderers/Prelude.hs +2/−1
- src/Text/Pandoc/Filter/Plot/Scripting.hs +11/−1
- stack.yaml +5/−1
- tests/Common.hs +8/−0
- tests/Main.hs +1/−0
CHANGELOG.md view
@@ -2,6 +2,26 @@ pandoc-plot uses [Semantic Versioning](http://semver.org/spec/v2.0.0.html) +Release 0.8.0.0 +--------------- + +* Added a new output format, HTML, to produce interactive plots. Not all renderers support it. You can try with Plotly/Python and Plotly/R as follows: + +````markdown + +```{.plotly_python format=html} +import plotly.express as px +df = px.data.election() +fig = px.scatter_ternary(df, a="Joly", b="Coderre", c="Bergeron") +``` + +```` + +* Added a new toolkit, [`bokeh`](https://bokeh.org/). This toolkit can take advantage of the new HTML interactive output. +* Added a new toolkit, [`plotsjl`](http://docs.juliaplots.org/latest/). +* Separated the detailed information from `README.md` and into a proper `MANUAL.md`. This is now the information which will be shown with `pandoc-plot --manual`. +* Exposed the `pandoc-plot` version via `Text.Pandoc.Filter.Plot.pandocPlotVersion`. + Release 0.7.2.1 ---------------
+ MANUAL.md view
@@ -0,0 +1,532 @@+<!-- +The file MANUAL.md is automatically generated by the mkmanual.ps1 script +Do not edit manually +--> + +# pandoc-plot 0.8.0.0 + +## A Pandoc filter to generate figures from code blocks in documents + +`pandoc-plot` turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more. + + - [Features Overview](#features-overview) + - [Captions](#captions) + - [Link to source code](#link-to-source-code) + - [Preamble scripts](#preamble-scripts) + - [Support for interative plots](#support-for-interative-plots) + - [Performance](#performance) + - [Compatibility with pandoc-crossref](#compatibility-with-pandoc-crossref) + - [Detailed usage](#detailed-usage) + - [As a filter](#as-a-filter) + - [Syntax](#syntax) + - [Parameters and options](#parameters-and-options) + - [Configuration](#configuration) + - [Other commands](#other-commands) + - [Warning](#warning) + +## Features Overview + +### Captions + +You can also specify a caption for your image. This is done using the optional `caption` parameter. + +**Markdown**: + +```` markdown +```{.matlabplot caption="This is a simple figure with a **Markdown** caption"} +x = 0: .1 : 2*pi; +y1 = cos(x); +y2 = sin(x); + +figure +plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2) +``` +```` + +**LaTex**: + +``` latex +\begin{minted}[caption=This is a simple figure with a caption]{matlabplot} +x = 0: .1 : 2*pi; +y1 = cos(x); +y2 = sin(x); + +figure +plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2) +\end{minted} +``` + +Caption formatting unfortunately cannot be determined automatically. To specify a caption format (e.g. “markdown”, “LaTeX”, etc.), see [Configuration](#configuration). + +### Link to source code + +In case of an output format that supports links (e.g. HTML), the embedded image generated by `pandoc-plot` can show a link to the source code which was used to generate the file. Therefore, other people can see what code was used to create your figures. + +You can turn this on via the `source=true` key: + +**Markdown**: + +```` markdown +```{.mathplot source=true} +... +``` +```` + +**LaTex**: + +``` latex +\begin{minted}[source=true]{mathplot} +... +\end{minted} +``` + +or via a [configuration file](#Configuration). + +### Preamble scripts + +If you find yourself always repeating some steps, inclusion of scripts is possible using the `preamble` parameter. For example, if you want all Matplotlib plots to have the [`ggplot`](https://matplotlib.org/tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py) style, you can write a very short preamble `style.py` like so: + +``` python +import matplotlib.pyplot as plt +plt.style.use('ggplot') +``` + +and include it in your document as follows: + +```` markdown +```{.matplotlib preamble=style.py} +plt.figure() +plt.plot([0,1,2,3,4], [1,2,3,4,5]) +plt.title('This is an example figure') +``` +```` + +Which is equivalent to writing the following markdown: + +```` markdown +```{.matplotlib} +import matplotlib.pyplot as plt +plt.style.use('ggplot') + +plt.figure() +plt.plot([0,1,2,3,4], [1,2,3,4,5]) +plt.title('This is an example figure') +``` +```` + +The equivalent LaTeX usage is as follows: + +``` latex +\begin{minted}[include=style.py]{matplotlib} + +\end{minted} +``` + +This `preamble` parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script\! You can also import packages this way, or define functions you often use. + +### Support for interative plots + +Starting with version 0.8.0.0, `pandoc-plot` supports the creation of interactive plots (if a toolkit supports it). All you need to do is set the save format to `html`. The resulting plot is fully self-contained, so it can be displayed offline. + +### Performance + +`pandoc-plot` minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. `pandoc-plot` will save the hash of the source code used to generate a figure in its filename. Before generating a figure, `pandoc-plot` will check it this figure already exists based on the hash of its source\! This also means that there is no way to directly name figures. + +Moreover, starting with version 0.5.0.0, `pandoc-plot` takes advantage of multicore CPUs, rendering figures **in parallel**. + +Therefore, you can confidently run the filter on very large documents containing hundreds of figures, like a book or a thesis. + +### Compatibility with pandoc-crossref + +[`pandoc-crossref`](https://github.com/lierdakil/pandoc-crossref) is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents. + +You can use `pandoc-crossref` in conjunction with `pandoc-plot` for the ultimate figure-making pipeline. You can combine both in a figure like so: + +```` markdown +```{#fig:myexample .plotly_python caption="This is a caption"} +# Insert figure script here +``` + +As you can see in @fig:myexample, ... +```` + +If the above source is located in file `myfile.md`, you can render the figure and references by applying `pandoc-plot` **first**, and then `pandoc-crossref`. For example: + +``` bash +pandoc --filter pandoc-plot --filter pandoc-crossref -i myfile.md -o myfile.html +``` + +## Detailed usage + +`pandoc-plot` is a command line executable with a few functions. You can take a look at the help using the `-h`/`--help` flag: + +``` bash +pandoc-plot 0.8.0.0 - generate figures directly in documents + +Usage: pandoc-plot.EXE [(-v|--version) | --full-version | (-m|--manual)] + [COMMAND] [AST] + This pandoc filter generates plots from code blocks using a multitude of + possible renderers. This allows to keep documentation and figures in perfect + synchronicity. + +Available options: + -v,--version Show version number and exit. + --full-version Show full version information and exit. + -m,--manual Open the manual page in the default web browser and + exit. + -h,--help Show this help text + +Available commands: + toolkits Show information on toolkits and exit. + clean Clean output directories where figures from FILE and + log files might be stored. WARNING: All files in + those directories will be deleted. + write-example-config Write example configuration to a file and exit. + +More information can be found via the manual (pandoc-plot --manual) or the +repository README, located at https://github.com/LaurentRDC/pandoc-plot +``` + +### As a filter + +The most common use for `pandoc-plot` is as a pandoc filter, in which case it should be called without arguments. For example: + +``` bash +pandoc --filter pandoc-plot -i input.md -o output.html +``` + +If `pandoc-plot` fails to render a code block into a figure, the filtering will not stop. Your code blocks will stay unchanged. + +You can chain other filters with it (e.g., [`pandoc-crossref`](https://github.com/lierdakil/pandoc-crossref)) like so: + +``` bash +pandoc --filter pandoc-plot --filter pandoc-crossref -i input.md -o output.html +``` + +### Syntax + +The syntax for code blocks in documents is shown below. `pandoc-plot` looks for code blocks with a specific class, depending on the toolkit you want to use. `pandoc-plot` will run the code and capture the figure output. There can only be **one** figure per code block. + +The possible parameters and options are described in [further below](#parameters-and-options). + +#### Markdown + +```` markdown + ```{.cls param1=value1 param2=value2 ...} + # script content + ``` +```` + +#### LaTeX + +Note that the `minted` LaTeX package need not be installed. + +``` latex +\begin{minted}[param1=value1, param2=value2, ...]{cls} +... +\end{minted} +``` + +### Parameters and options + +There are parameters that affect the figure that will be included in your document. Here are all the possible general parameters, in Markdown syntax: + +```` markdown + ```{.cls + .language + directory=(path) + caption=(text) + format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP|HTML) + source=(true|false) + preamble=(path) + dpi=(integer) + executable=(path) + caption_format=(text) + } + # script content + ``` +```` + + - `cls` must be one of the following: `matplotlib`, `matlabplot`, `plotly_python`, `plotly_r`, `mathplot`, `octaveplot`, `ggplot2`, `gnuplot`, `graphviz`, `bokeh`, `plotsjl`. + +All following parameters are optional, with their default values controlled by the [configuration](#configuration) + + - `language` specifies the programming language used in this block. This parameter is ignored by `pandoc-plot`, but your text editor may use it to highlight code. See [Code highlighting](#code-highlighting) below. + - `directory` is a path to the directory where the figure and source code will be saved. You cannot control the file name. This path is either absolute, or relative from the working directory where you call `pandoc-plot`. + - `caption` is the caption text. The format of the caption is specified in the `caption_format` parameter, described below. + - `format` is the desired filetype for the resulting figure. Possible values for `format` are \[`PNG`, `PDF`, `SVG`, `JPG`, `EPS`, `GIF`, `TIF`, `WEBP`, `HTML`\]. Not all toolkits support all formats. See `pandoc-plot toolkits` for toolkit-specific information regarding save formats. The `HTML` format is special; it can produce standalone, offline, interactive plots. As such, it only makes sense to use this format when creating HTML documents. + - `source` is a boolean toggle that determines whether the source code should be linked in the caption or not. Possible values are \[`true`, `True`, `false`, `False`\]. + - `preamble` is a path to a script that will be included as a preamble to the content of the code block. This path is either absolute, or relative from the working directory where you call `pandoc-plot`. + - `dpi` is the pixel density of the figure in dots-per-inch. Possible values are positive integers. Not all toolkits respect this. + - `executable` is a path to the executable to use (e.g. `C:\\python3.exe`) or the name of the executable (e.g. `python3`). + - `caption_format` is the text format of the caption. Possible values are exactly the same as `pandoc`’s format specification, usually `FORMAT+EXTENSION-EXTENSION`. For example, captions in Markdown with raw LaTeX would be parsed correctly provided that `caption_format=markdown+raw_tex`. See Pandoc’s guide on [Specifying formats](https://pandoc.org/MANUAL.html#specifying-formats). + +#### Code highlighting + +If your editor supports code highlighting in code blocks, you can also include the programming language. In Markdown: + +```` markdown + ```{.language .cls (options)} + # script content + ``` +```` + +or Latex: + +``` latex + \begin{minted}[(options)]{language, cls} + # script content + \end{minted} +``` + +For example, for GGPlot2 figures: + +```` markdown + ```{.r .ggplot2 caption=Highlighted code block} + # script content + ``` +```` + +or (Latex): + +``` latex + \begin{minted}[caption=Highlighted code block]{r, ggplot2} + # script content + \end{minted} +``` + +This way, you benefit from code highlighting *and* `pandoc-plot`. + +### Configuration + +To avoid repetition, `pandoc-plot` can be configured using simple YAML +files. Here are **all** the possible parameters: + +``` yaml + +# This is an example configuration. Everything in this file is optional. +# Please refer to the documentation to know about the parameters herein. +# +# The `executable` parameter for all toolkits can be either the +# executable name (if it is present on the PATH), or +# the full path to the executable. +# E.g.: +# executable: python3 +# executable: "C:\Python37\Scripts\python.exe" + +# The following parameters affect all toolkits +# Directory where to save the plots. The path can be relative to pandoc-plot's +# current working directory, or absolute. +directory: plots/ + +# Whether or not to include a link to the source script in the caption. +# Particularly useful for HTML output. +source: false + +# Default density of figures in dots per inches (DPI). +# This can be changed in the document specifically as well. +dpi: 80 + +# Default format in which to save the figures. This can be specified +# individually as well. +format: PNG + +# Text format for the captions. Unfortunately, there is no way to detect +# this automatically. You can use the same notation as Pandoc's --from +# parameter, specified here: +# https://pandoc.org/MANUAL.html#option--from +# Example: markdown, rst+raw_tex +caption_format: markdown+tex_math_dollars + +# Logging configuration +logging: + # Possible verbosity values: debug, error, warning, info, silent + verbosity: warning + # If the filepath below is not present, then pandoc-plot will log to stderr + # Otherwise, log messages will be appended to the filepath. + # filepath: path/to/file.txt + +# The possible parameters for the Matplotlib toolkit +matplotlib: + # preamble: matplotlib.py + tight_bbox: false + transparent: false + executable: python + +# The possible parameters for the MATLAB toolkit +matlabplot: + # preamble: matlab.m + executable: matlab + +# The possible parameters for the Plotly/Python toolkit +plotly_python: + # preamble: plotly-python.py + executable: python + +# The possible parameters for the Plotly/R toolkit +plotly_r: + # preamble: plotly-r.r + executable: Rscript + +# The possible parameters for the Mathematica toolkit +mathplot: + # preamble: mathematica.m + executable: math + +# The possible parameters for the GNU Octave toolkit +octaveplot: + # preamble: octave.m + executable: octave + +# The possible parameters for the ggplot2 toolkit +ggplot2: + # preamble: ggplot2.r + executable: Rscript + +# The possible parameters for the gnuplot toolkit +gnuplot: + # preamble: gnuplot.gp + executable: gnuplot + +# The possible parameters for the graphviz toolkit +graphviz: + # preamble: graphviz.dot + executable: dot + +bokeh: + # preamble: bokeh.py + executable: python + +plotsjl: + # preamble: plotsjl.jl + executable: julia +``` + +A file like the above sets the **default** values; you can still override them in documents directly. + +The easiest way to specify configuration for `pandoc-plot` is to place a `.pandoc-plot.yml` file in the current working directory. You can also specify a configuration file in document metadata, under the `plot-configuration` key. For example, in Markdown: + +``` markdown +--- +title: My document +author: John Doe +plot-configuration: /path/to/file.yml +--- +``` + +or on the command line, using the pandoc `-M/--metadata` flag: + +``` bash +pandoc --filter pandoc-plot -M plot-configuration=/path/to/file.yml ... +``` + +The hierarchy of configuration files is as follows: + +1. A configuration file specified in the metadata under the `plot-configuration` key; +2. Otherwise, a file in the current working directory named `.pandoc-plot.yml`; +3. Finally, the default configuration is used. + +#### Executables + +The `executable` parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable. + +Examples: + +``` yaml +matplotlib: + executable: python3 +``` + +``` yaml +matlabplot: + executable: "C:\Program Files\Matlab\R2019b\bin\matlab.exe" +``` + +#### Toolkit-specific options + +##### Matplotlib + + - `tight_bbox` is a boolean that determines whether to use `bbox_inches="tight"` or not when saving Matplotlib figures. For example, `tight_bbox: true`. See [here](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.savefig.html) for details. + - `transparent` is a boolean that determines whether to make Matplotlib figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, `transparent: true`. + +#### Logging + +If you are running `pandoc-plot` on a large document, you might want to turn on logging. You can do so via the configuration file as follows: + +``` yaml +logging: + # Possible verbosity values: debug, error, warning, info, silent + # debug level shows all messages + # error level shows all but debug messages, etc. + verbosity: info + + # OPTIONAL: log to file + # Remove line below to log to stderr + filepath: log.txt +``` + +By default, `pandoc-plot` logs warnings and errors to the standard error stream only. + +### Other commands + +#### Finding installed toolkits + +You can determine which toolkits are available on your current machine using the `pandoc-plot toolkits` command. Here is the full help text: + +``` bash +Usage: pandoc-plot.EXE toolkits [--config PATH] + Show information on toolkits and exit. + +Available options: + --config PATH Path to optional configuration file. + -h,--help Show this help text +``` + +#### Cleaning output + +Figures produced by `pandoc-plot` can be placed in a few different locations. You can set a default location in the [Configuration](#configuration), but you can also re-direct specific figures in other directories if you use the `directory=...` argument in code blocks. These figures will build up over time. You can use the `clean` command to scan documents and delete the associated `pandoc-plot` output files. For example, to delete the figures generated from the `input.md` file: + +``` bash +pandoc-plot clean input.md +``` + +This sill remove all directories where a figure *could* have been placed. **WARNING**: all files will be removed. + +Here is the full help text for the `clean` command: + +``` bash +Usage: pandoc-plot.EXE clean [--config PATH] FILE + Clean output directories where figures from FILE and log files might be + stored. WARNING: All files in those directories will be deleted. + +Available options: + --config PATH Path to optional configuration file. + -h,--help Show this help text +``` + +#### Configuration template + +Because `pandoc-plot` supports a few toolkits, there are a lot of configuration options. Don’t start from scratch\! The `write-example-config` command will create a file for you, which you can then modify: + +``` bash +pandoc-plot write-example-config +``` + +You will need to re-name the file to `.pandoc-ploy.yml` to be able to use it, so don’t worry about overwriting your own configuration. + +Here is the full help text for the `write-example-config` command: + +``` bash +Usage: pandoc-plot.EXE write-example-config [--path FILE] + Write example configuration to a file and exit. + +Available options: + --path FILE Target location of the configuration file. Default is + ".example-pandoc-plot.yml" + -h,--help Show this help text +``` + +## Warning + +Do not run this filter on unknown documents. There is nothing in +`pandoc-plot` that can stop a script from performing **evil actions**.
README.md view
@@ -1,8 +1,3 @@-<!-- -The file README.md is automatically generated by the mkreadme.ps1 script -Do not edit manually ---> - # pandoc-plot ## A Pandoc filter to generate figures from code blocks in documents @@ -11,29 +6,6 @@ `pandoc-plot` turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more. - - [Overview](#overview) - - [Supported toolkits](#supported-toolkits) - - [Features](#features) - - [Captions](#captions) - - [Link to source code](#link-to-source-code) - - [Preamble scripts](#preamble-scripts) - - [Performance](#performance) - - [Compatibility with - pandoc-crossref](#compatibility-with-pandoc-crossref) - - [Detailed usage](#detailed-usage) - - [As a filter](#as-a-filter) - - [Syntax](#syntax) - - [Parameters and options](#parameters-and-options) - - [Configuration](#configuration) - - [Other commands](#other-commands) - - [Installation](#installation) - - [Binaries and Installers](#binaries-and-installers) - - [conda](#conda) - - [winget](#winget) - - [From Hackage/Stackage](#from-hackagestackage) - - [From source](#from-source) - - [Warning](#warning) - ## Overview This program is a [Pandoc](https://pandoc.org/) filter. It can therefore @@ -85,7 +57,9 @@ Octave](https://www.gnu.org/software/octave/); - `ggplot2`: plots using [ggplot2](https://ggplot2.tidyverse.org/); - `gnuplot`: plots using [gnuplot](http://www.gnuplot.info/); - - `graphviz`: graphs using the [Graphviz](http://graphviz.org/) + - `graphviz`: graphs using [Graphviz](http://graphviz.org/); + - `bokeh`: plots using the [Bokeh](https://bokeh.org/) visualization library; + - `plotsjl`: plots using the [Julia `Plots.jl`](http://docs.plotsjl.org/latest/) package. To know which toolkits are useable on *your machine* (and which ones are not available), you can check with the `toolkits` command: @@ -99,588 +73,10 @@ **Wish your plotting toolkit of choice was available? Please [raise an issue](https://github.com/LaurentRDC/pandoc-plot/issues)\!** -## Features - -### Captions - -You can also specify a caption for your image. This is done using the -optional `caption` parameter. - -**Markdown**: - -```` markdown -```{.matlabplot caption="This is a simple figure with a **Markdown** caption"} -x = 0: .1 : 2*pi; -y1 = cos(x); -y2 = sin(x); - -figure -plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2) -``` -```` - -**LaTex**: - -``` latex -\begin{minted}[caption=This is a simple figure with a caption]{matlabplot} -x = 0: .1 : 2*pi; -y1 = cos(x); -y2 = sin(x); - -figure -plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2) -\end{minted} -``` - -Caption formatting unfortunately cannot be determined automatically. To -specify a caption format (e.g. “markdown”, “LaTeX”, etc.), see -[Configuration](#configuration). - -### Link to source code - -In case of an output format that supports links (e.g. HTML), the -embedded image generated by `pandoc-plot` can show a link to the source -code which was used to generate the file. Therefore, other people can -see what code was used to create your figures. - -You can turn this on via the `source=true` key: - -**Markdown**: - -```` markdown -```{.mathplot source=true} -... -``` -```` - -**LaTex**: - -``` latex -\begin{minted}[source=true]{mathplot} -... -\end{minted} -``` - -or via a [configuration file](#Configuration). - -### Preamble scripts - -If you find yourself always repeating some steps, inclusion of scripts -is possible using the `preamble` parameter. For example, if you want all -Matplotlib plots to have the -[`ggplot`](https://matplotlib.org/tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py) -style, you can write a very short preamble `style.py` like so: - -``` python -import matplotlib.pyplot as plt -plt.style.use('ggplot') -``` - -and include it in your document as follows: - -```` markdown -```{.matplotlib preamble=style.py} -plt.figure() -plt.plot([0,1,2,3,4], [1,2,3,4,5]) -plt.title('This is an example figure') -``` -```` - -Which is equivalent to writing the following markdown: - -```` markdown -```{.matplotlib} -import matplotlib.pyplot as plt -plt.style.use('ggplot') - -plt.figure() -plt.plot([0,1,2,3,4], [1,2,3,4,5]) -plt.title('This is an example figure') -``` -```` - -The equivalent LaTeX usage is as follows: - -``` latex -\begin{minted}[include=style.py]{matplotlib} - -\end{minted} -``` - -This `preamble` parameter is perfect for longer documents with many -plots. Simply define the style you want in a separate script\! You can -also import packages this way, or define functions you often use. - -### Performance - -`pandoc-plot` minimizes work, only generating figures if it absolutely -must, i.e. if the content has changed. `pandoc-plot` will save the hash -of the source code used to generate a figure in its filename. Before -generating a figure, `pandoc-plot` will check it this figure already -exists based on the hash of its source\! This also means that there is -no way to directly name figures. - -Moreover, starting with version 0.5.0.0, `pandoc-plot` takes advantage -of multicore CPUs, rendering figures **in parallel**. - -Therefore, you can confidently run the filter on very large documents -containing hundreds of figures, like a book or a thesis. - -### Compatibility with pandoc-crossref - -[`pandoc-crossref`](https://github.com/lierdakil/pandoc-crossref) is a -pandoc filter that makes it effortless to cross-reference objects in -Markdown documents. - -You can use `pandoc-crossref` in conjunction with `pandoc-plot` for the -ultimate figure-making pipeline. You can combine both in a figure like -so: - -```` markdown -```{#fig:myexample .plotly_python caption="This is a caption"} -# Insert figure script here -``` - -As you can see in @fig:myexample, ... -```` - -If the above source is located in file `myfile.md`, you can render the -figure and references by applying `pandoc-plot` **first**, and then -`pandoc-crossref`. For example: - -``` bash -pandoc --filter pandoc-plot --filter pandoc-crossref -i myfile.md -o myfile.html -``` - -## Detailed usage - -`pandoc-plot` is a command line executable with a few functions. You can -take a look at the help using the `-h`/`--help` flag: - -``` bash -pandoc-plot - generate figures directly in documents using your plotting toolkit -of choice. - -Usage: pandoc-plot.exe [(-v|--version) | --full-version | (-m|--manual)] - [COMMAND] [AST] - This pandoc filter generates plots from code blocks using a multitude of - possible renderers. This allows to keep documentation and figures in perfect - synchronicity. - -Available options: - -v,--version Show version number and exit. - --full-version Show full version information and exit. - -m,--manual Open the manual page in the default web browser and - exit. - -h,--help Show this help text - -Available commands: - toolkits Show information on toolkits and exit. - clean Clean output directories where figures from FILE and - log files might be stored. WARNING: All files in - those directories will be deleted. - write-example-config Write example configuration to a file and exit. - -More information can be found via the manual (pandoc-plot --manual) or the repository README, located at - https://github.com/LaurentRDC/pandoc-plot - -``` - -### As a filter - -The most common use for `pandoc-plot` is as a pandoc filter, in which -case it should be called without arguments. For example: - -``` bash -pandoc --filter pandoc-plot -i input.md -o output.html -``` - -If `pandoc-plot` fails to render a code block into a figure, the -filtering will not stop. Your code blocks will stay unchanged. - -You can chain other filters with it (e.g., -[`pandoc-crossref`](https://github.com/lierdakil/pandoc-crossref)) like -so: - -``` bash -pandoc --filter pandoc-plot --filter pandoc-crossref -i input.md -o output.html -``` - -### Syntax - -The syntax for code blocks in documents is shown below. `pandoc-plot` -looks for code blocks with a specific class, depending on the toolkit -you want to use. `pandoc-plot` will run the code and capture the figure -output. There can only be **one** figure per code block. - -The possible parameters and options are described in [further -below](#parameters-and-options). - -#### Markdown - -```` markdown - ```{.cls param1=value1 param2=value2 ...} - # script content - ``` -```` - -#### LaTeX - -Note that the `minted` LaTeX package need not be installed. - -``` latex -\begin{minted}[param1=value1, param2=value2, ...]{cls} -... -\end{minted} -``` - -### Parameters and options - -There are parameters that affect the figure that will be included in -your document. Here are all the possible general parameters, in Markdown -syntax: - -```` markdown - ```{.cls - .language - directory=(path) - caption=(text) - format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) - source=(true|false) - preamble=(path) - dpi=(integer) - executable=(path) - caption_format=(text) - } - # script content - ``` -```` - - - `cls` must be one of the following: `matplotlib`, `matlabplot`, - `plotly_python`, `plotly_r`, `mathplot`, `octaveplot`, `ggplot2`, - `gnuplot`, or `graphviz`. - -All following parameters are optional, with their default values -controlled by the [configuration](#configuration) - - - `language` specifies the programming language used in this block. - This parameter is ignored by `pandoc-plot`, but your text editor may - use it to highlight code. See [Code - highlighting](#code-highlighting) below. - - `directory` is a path to the directory where the figure and source - code will be saved. You cannot control the file name. This path is - either absolute, or relative from the working directory where you - call `pandoc-plot`. - - `caption` is the caption text. The format of the caption is - specified in the `caption_format` parameter, described below. - - `format` is the desired filetype for the resulting figure. Possible - values for `format` are \[`PNG`, `PDF`, `SVG`, `JPG`, `EPS`, `GIF`, - `TIF`, `WEBP`\]. Not all toolkits support all formats. See - `pandoc-plot toolkits` for toolkit-specific information regarding - save formats. - - `source` is a boolean toggle that determines whether the source code - should be linked in the caption or not. Possible values are - \[`true`, `True`, `false`, `False`\]. - - `preamble` is a path to a script that will be included as a preamble - to the content of the code block. This path is either absolute, or - relative from the working directory where you call `pandoc-plot`. - - `dpi` is the pixel density of the figure in dots-per-inch. Possible - values are positive integers. Not all toolkits respect this. - - `executable` is a path to the executable to use - (e.g. `C:\\python3.exe`) or the name of the executable - (e.g. `python3`). - - `caption_format` is the text format of the caption. Possible values - are exactly the same as `pandoc`’s format specification, usually - `FORMAT+EXTENSION-EXTENSION`. For example, captions in Markdown with - raw LaTeX would be parsed correctly provided that - `caption_format=markdown+raw_tex`. See Pandoc’s guide on [Specifying - formats](https://pandoc.org/MANUAL.html#specifying-formats). - -#### Code highlighting - -If your editor supports code highlighting in code blocks, you can also -include the programming language. In Markdown: - -```` markdown - ```{.language .cls (options)} - # script content - ``` -```` - -or Latex: - -``` latex - \begin{minted}[(options)]{language, cls} - # script content - \end{minted} -``` - -For example, for GGPlot2 figures: - -```` markdown - ```{.r .ggplot2 caption=Highlighted code block} - # script content - ``` -```` - -or (Latex): - -``` latex - \begin{minted}[caption=Highlighted code block]{r, ggplot2} - # script content - \end{minted} -``` - -This way, you benefit from code highlighting *and* `pandoc-plot`. - -### Configuration - -To avoid repetition, `pandoc-plot` can be configured using simple YAML -files. Here are **all** the possible parameters: - -``` yaml - -# This is an example configuration. Everything in this file is optional. -# Please refer to the documentation to know about the parameters herein. -# -# The `executable` parameter for all toolkits can be either the -# executable name (if it is present on the PATH), or -# the full path to the executable. -# E.g.: -# executable: python3 -# executable: "C:\Python37\Scripts\python.exe" - -# The following parameters affect all toolkits -# Directory where to save the plots. The path can be relative to pandoc-plot's -# current working directory, or absolute. -directory: plots/ - -# Whether or not to include a link to the source script in the caption. -# Particularly useful for HTML output. -source: false - -# Default density of figures in dots per inches (DPI). -# This can be changed in the document specifically as well. -dpi: 80 - -# Default format in which to save the figures. This can be specified individually as well. -format: PNG - -# Text format for the captions. Unfortunately, there is no way to detect this automatically. -# You can use the same notation as Pandoc's --from parameter, specified here: -# https://pandoc.org/MANUAL.html#option--from -# Example: markdown, rst+raw_tex -caption_format: markdown+tex_math_dollars - -# Logging configuration -logging: - # Possible verbosity values: debug, error, warning, info, silent - verbosity: warning - # If the filepath below is not present, then pandoc-plot will log to stderr - # Otherwise, log messages will be appended to the filepath. - # filepath: path/to/file.txt - -# The possible parameters for the Matplotlib toolkit -matplotlib: - # preamble: matplotlib.py - tight_bbox: false - transparent: false - executable: python - -# The possible parameters for the MATLAB toolkit -matlabplot: - # preamble: matlab.m - executable: matlab - -# The possible parameters for the Plotly/Python toolkit -plotly_python: - # preamble: plotly-python.py - executable: python - -# The possible parameters for the Plotly/R toolkit -plotly_r: - # preamble: plotly-r.r - executable: Rscript - -# The possible parameters for the Mathematica toolkit -mathplot: - # preamble: mathematica.m - executable: math - -# The possible parameters for the GNU Octave toolkit -octaveplot: - # preamble: octave.m - executable: octave - -# The possible parameters for the ggplot2 toolkit -ggplot2: - # preamble: ggplot2.r - executable: Rscript - -# The possible parameters for the gnuplot toolkit -gnuplot: - # preamble: gnuplot.gp - executable: gnuplot - -# The possible parameters for the graphviz toolkit -graphviz: - # preamble: graphviz.dot - executable: dot -``` - -A file like the above sets the **default** values; you can still -override them in documents directly. - -The easiest way to specify configuration for `pandoc-plot` is to place a -`.pandoc-plot.yml` file in the current working directory. You can also -specify a configuration file in document metadata, under the -`plot-configuration` key. For example, in Markdown: - -``` markdown ---- -title: My document -author: John Doe -plot-configuration: /path/to/file.yml ---- -``` - -or on the command line, using pandoc’s `-M/--metadata` flag: - -``` bash -pandoc --filter pandoc-plot -M plot-configuration=/path/to/file.yml ... -``` - -The hierarchy of configuration files is as follows: - -1. A configuration file specified in the metadata under the - `plot-configuration` key; -2. Otherwise, a file in the current working directory named - `.pandoc-plot.yml`; -3. Finally, the default configuration is used. - -#### Executables - -The `executable` parameter for all toolkits can be either the executable -name (if it is present on the PATH), or the full path to the executable. - -Examples: - -``` yaml -matplotlib: - executable: python3 -``` - -``` yaml -matlabplot: - executable: "C:\Program Files\Matlab\R2019b\bin\matlab.exe" -``` - -#### Toolkit-specific options - -##### Matplotlib - - - `tight_bbox` is a boolean that determines whether to use - `bbox_inches="tight"` or not when saving Matplotlib figures. For - example, `tight_bbox: true`. See - [here](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.savefig.html) - for details. - - `transparent` is a boolean that determines whether to make - Matplotlib figure background transparent or not. This is useful, for - example, for displaying a plot on top of a colored background on a - web page. High-resolution figures are not affected. For example, - `transparent: true`. - -#### Logging - -If you are running `pandoc-plot` on a large document, you might want to -turn on logging. You can do so via the configuration file as follows: - -``` yaml -logging: - # Possible verbosity values: debug, error, warning, info, silent - # debug level shows all messages - # error level shows all but debug messages, etc. - verbosity: info - - # OPTIONAL: log to file - # Remove line below to log to stderr - filepath: log.txt -``` - -By default, `pandoc-plot` logs warnings and errors to the standard error -stream only. - -### Other commands - -#### Finding installed toolkits - -You can determine which toolkits are available on your current machine -using the `pandoc-plot toolkits` command. Here is the full help text: - -``` bash -Usage: pandoc-plot.exe toolkits [--config PATH] - Show information on toolkits and exit. - -Available options: - --config PATH Path to optional configuration file. - -h,--help Show this help text -``` - -#### Cleaning output - -Figures produced by `pandoc-plot` can be placed in a few different -locations. You can set a default location in the -[Configuration](#configuration), but you can also re-direct specific -figures in other directories if you use the `directory=...` argument in -code blocks. These figures will build up over time. You can use the -`clean` command to scan documents and delete the associated -`pandoc-plot` output files. For example, to delete the figures generated -from the `input.md` file: - -``` bash -pandoc-plot clean input.md -``` - -This sill remove all directories where a figure *could* have been -placed. **WARNING**: all files will be removed. - -Here is the full help text for the `clean` command: - -``` bash -Usage: pandoc-plot.exe clean [--config PATH] FILE - Clean output directories where figures from FILE and log files might be - stored. WARNING: All files in those directories will be deleted. - -Available options: - --config PATH Path to optional configuration file. - -h,--help Show this help text -``` - -#### Configuration template - -Because `pandoc-plot` supports a few toolkits, there are a lot of -configuration options. Don’t start from scratch\! The -`write-example-config` command will create a file for you, which you can -then modify: - -``` bash -pandoc-plot write-example-config -``` - -You will need to re-name the file to `.pandoc-ploy.yml` to be able to -use it, so don’t worry about overwriting your own configuration. - -Here is the full help text for the `write-example-config` command: - -``` bash -Usage: pandoc-plot.exe write-example-config [--path FILE] - Write example configuration to a file and exit. +## Documentation -Available options: - --path FILE Target location of the configuration file. Default is - ".example-pandoc-plot.yml" - -h,--help Show this help text -``` +You can find more information in the documentation, available either in the +source repository file `MANUAL.md`, on the [webpage](https://laurentrdc.github.io/pandoc-plot/MANUAL.html), or via the command `pandoc-plot --manual`. ## Installation @@ -745,8 +141,3 @@ cd pandoc-plot stack install # Alternatively, `cabal install` ``` - -## Warning - -Do not run this filter on unknown documents. There is nothing in -`pandoc-plot` that can stop a script from performing **evil actions**.
+ docs/MANUAL.html view
@@ -0,0 +1,455 @@+<!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" /> + <title>MANUAL</title> + <style> + code{white-space: pre-wrap;} + span.smallcaps{font-variant: small-caps;} + span.underline{text-decoration: underline;} + div.column{display: inline-block; vertical-align: top; width: 50%;} + div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} + ul.task-list{list-style: none;} + pre > code.sourceCode { white-space: pre; position: relative; } + pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } + pre > code.sourceCode > span:empty { height: 1.2em; } + code.sourceCode > span { color: inherit; text-decoration: inherit; } + div.sourceCode { margin: 1em 0; } + pre.sourceCode { margin: 0; } + @media screen { + div.sourceCode { overflow: auto; } + } + @media print { + pre > code.sourceCode { white-space: pre-wrap; } + pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } + } + pre.numberSource code + { counter-reset: source-line 0; } + pre.numberSource code > span + { position: relative; left: -4em; counter-increment: source-line; } + pre.numberSource code > span > a:first-child::before + { content: counter(source-line); + position: relative; left: -1em; text-align: right; vertical-align: baseline; + border: none; display: inline-block; + -webkit-touch-callout: none; -webkit-user-select: none; + -khtml-user-select: none; -moz-user-select: none; + -ms-user-select: none; user-select: none; + padding: 0 4px; width: 4em; + color: #aaaaaa; + } + pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } + div.sourceCode + { } + @media screen { + pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } + } + code span.al { color: #ff0000; font-weight: bold; } /* Alert */ + code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ + code span.at { color: #7d9029; } /* Attribute */ + code span.bn { color: #40a070; } /* BaseN */ + code span.bu { } /* BuiltIn */ + code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ + code span.ch { color: #4070a0; } /* Char */ + code span.cn { color: #880000; } /* Constant */ + code span.co { color: #60a0b0; font-style: italic; } /* Comment */ + code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ + code span.do { color: #ba2121; font-style: italic; } /* Documentation */ + code span.dt { color: #902000; } /* DataType */ + code span.dv { color: #40a070; } /* DecVal */ + code span.er { color: #ff0000; font-weight: bold; } /* Error */ + code span.ex { } /* Extension */ + code span.fl { color: #40a070; } /* Float */ + code span.fu { color: #06287e; } /* Function */ + code span.im { } /* Import */ + code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ + code span.kw { color: #007020; font-weight: bold; } /* Keyword */ + code span.op { color: #666666; } /* Operator */ + code span.ot { color: #007020; } /* Other */ + code span.pp { color: #bc7a00; } /* Preprocessor */ + code span.sc { color: #4070a0; } /* SpecialChar */ + code span.ss { color: #bb6688; } /* SpecialString */ + code span.st { color: #4070a0; } /* String */ + code span.va { color: #19177c; } /* Variable */ + code span.vs { color: #4070a0; } /* VerbatimString */ + code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ + .display.math{display: block; text-align: center; margin: 0.5rem auto;} + </style> + <style type="text/css">html { font-size: 100%; overflow-y: scroll; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }body{color:#444;font-family:Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;font-size:12px;line-height:1.5em;padding:1em;margin:auto;max-width:42em;background:#fefefe;}a{ color: #0645ad; text-decoration:none;}a:visited{ color: #0b0080; }a:hover{ color: #06e; }a:active{ color:#faa700; }a:focus{ outline: thin dotted; }a:hover, a:active{ outline: 0; }::-moz-selection{background:rgba(255,255,0,0.3);color:#000}::selection{background:rgba(255,255,0,0.3);color:#000}a::-moz-selection{background:rgba(255,255,0,0.3);color:#0645ad}a::selection{background:rgba(255,255,0,0.3);color:#0645ad}p{margin:1em 0;}img{max-width:100%;}h1,h2,h3,h4,h5,h6{font-weight:normal;color:#111;line-height:1em;}h4,h5,h6{ font-weight: bold; }h1{ font-size:2.5em; }h2{ font-size:2em; }h3{ font-size:1.5em; }h4{ font-size:1.2em; }h5{ font-size:1em; }h6{ font-size:0.9em; }blockquote{color:#666666;margin:0;padding-left: 3em;border-left: 0.5em #EEE solid;}hr { display: block; height: 2px; border: 0; border-top: 1px solid #aaa;border-bottom: 1px solid #eee; margin: 1em 0; padding: 0; }pre, code, kbd, samp { color: #000; font-family: monospace, monospace; _font-family: 'courier new', monospace; font-size: 0.98em; }pre { white-space: pre; white-space: pre-wrap; word-wrap: break-word; }b, strong { font-weight: bold; }dfn { font-style: italic; }ins { background: #ff9; color: #000; text-decoration: none; }mark { background: #ff0; color: #000; font-style: italic; font-weight: bold; }sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }sup { top: -0.5em; }sub { bottom: -0.25em; }ul, ol { margin: 1em 0; padding: 0 0 0 2em; }li p:last-child { margin:0 }dd { margin: 0 0 0 2em; }img { border: 0; -ms-interpolation-mode: bicubic; vertical-align: middle; }table {border-collapse: collapse;border-spacing: 0;width: 100%;}th { border-bottom: 1px solid black; }td { vertical-align: top; }@media only screen and (min-width: 480px) {body{font-size:14px;}}@media only screen and (min-width: 768px) {body{font-size:16px;}}@media print {* { background: transparent !important; color: black !important; filter:none !important; -ms-filter: none !important; }body{font-size:12pt; max-width:100%;}a, a:visited { text-decoration: underline; }hr { height: 1px; border:0; border-bottom:1px solid black; }a[href]:after { content: " (" attr(href) ")"; }abbr[title]:after { content: " (" attr(title) ")"; }.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; }pre, blockquote { border: 1px solid #999; padding-right: 1em; page-break-inside: avoid; }tr, img { page-break-inside: avoid; }img { max-width: 100% !important; }@page :left { margin: 15mm 20mm 15mm 10mm; }@page :right { margin: 15mm 10mm 15mm 20mm; }p, h2, h3 { orphans: 3; widows: 3; }h2, h3 { page-break-after: avoid; }}</style> + <!--[if lt IE 9]> + <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script> + <![endif]--> +</head> +<body> +<!-- +The file MANUAL.md is automatically generated by the mkmanual.ps1 script +Do not edit manually +--> +<h1 id="pandoc-plot-0.8.0.0">pandoc-plot 0.8.0.0</h1> +<h2 id="a-pandoc-filter-to-generate-figures-from-code-blocks-in-documents">A Pandoc filter to generate figures from code blocks in documents</h2> +<p><code>pandoc-plot</code> turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more.</p> +<ul> +<li><a href="#features-overview">Features Overview</a> +<ul> +<li><a href="#captions">Captions</a></li> +<li><a href="#link-to-source-code">Link to source code</a></li> +<li><a href="#preamble-scripts">Preamble scripts</a></li> +<li><a href="#support-for-interative-plots">Support for interative plots</a></li> +<li><a href="#performance">Performance</a></li> +<li><a href="#compatibility-with-pandoc-crossref">Compatibility with pandoc-crossref</a></li> +</ul></li> +<li><a href="#detailed-usage">Detailed usage</a> +<ul> +<li><a href="#as-a-filter">As a filter</a></li> +<li><a href="#syntax">Syntax</a></li> +<li><a href="#parameters-and-options">Parameters and options</a></li> +<li><a href="#configuration">Configuration</a></li> +<li><a href="#other-commands">Other commands</a></li> +</ul></li> +<li><a href="#warning">Warning</a></li> +</ul> +<h2 id="features-overview">Features Overview</h2> +<h3 id="captions">Captions</h3> +<p>You can also specify a caption for your image. This is done using the optional <code>caption</code> parameter.</p> +<p><strong>Markdown</strong>:</p> +<div class="sourceCode" id="cb1"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true"></a><span class="in">```{.matlabplot caption="This is a simple figure with a **Markdown** caption"}</span></span> +<span id="cb1-2"><a href="#cb1-2" aria-hidden="true"></a><span class="in">x = 0: .1 : 2*pi;</span></span> +<span id="cb1-3"><a href="#cb1-3" aria-hidden="true"></a><span class="in">y1 = cos(x);</span></span> +<span id="cb1-4"><a href="#cb1-4" aria-hidden="true"></a><span class="in">y2 = sin(x);</span></span> +<span id="cb1-5"><a href="#cb1-5" aria-hidden="true"></a></span> +<span id="cb1-6"><a href="#cb1-6" aria-hidden="true"></a><span class="in">figure</span></span> +<span id="cb1-7"><a href="#cb1-7" aria-hidden="true"></a><span class="in">plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)</span></span> +<span id="cb1-8"><a href="#cb1-8" aria-hidden="true"></a><span class="in">```</span></span></code></pre></div> +<p><strong>LaTex</strong>:</p> +<div class="sourceCode" id="cb2"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[caption=This is a simple figure with a caption]{matlabplot}</span> +<span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a><span class="vs">x = 0: .1 : 2*pi;</span></span> +<span id="cb2-3"><a href="#cb2-3" aria-hidden="true"></a><span class="vs">y1 = cos(x);</span></span> +<span id="cb2-4"><a href="#cb2-4" aria-hidden="true"></a><span class="vs">y2 = sin(x);</span></span> +<span id="cb2-5"><a href="#cb2-5" aria-hidden="true"></a></span> +<span id="cb2-6"><a href="#cb2-6" aria-hidden="true"></a><span class="vs">figure</span></span> +<span id="cb2-7"><a href="#cb2-7" aria-hidden="true"></a><span class="vs">plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)</span></span> +<span id="cb2-8"><a href="#cb2-8" aria-hidden="true"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<p>Caption formatting unfortunately cannot be determined automatically. To specify a caption format (e.g. “markdown”, “LaTeX”, etc.), see <a href="#configuration">Configuration</a>.</p> +<h3 id="link-to-source-code">Link to source code</h3> +<p>In case of an output format that supports links (e.g. HTML), the embedded image generated by <code>pandoc-plot</code> can show a link to the source code which was used to generate the file. Therefore, other people can see what code was used to create your figures.</p> +<p>You can turn this on via the <code>source=true</code> key:</p> +<p><strong>Markdown</strong>:</p> +<div class="sourceCode" id="cb3"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a><span class="in">```{.mathplot source=true}</span></span> +<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a><span class="in">...</span></span> +<span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a><span class="in">```</span></span></code></pre></div> +<p><strong>LaTex</strong>:</p> +<div class="sourceCode" id="cb4"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[source=true]{mathplot}</span> +<span id="cb4-2"><a href="#cb4-2" aria-hidden="true"></a><span class="vs">...</span></span> +<span id="cb4-3"><a href="#cb4-3" aria-hidden="true"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<p>or via a <a href="#Configuration">configuration file</a>.</p> +<h3 id="preamble-scripts">Preamble scripts</h3> +<p>If you find yourself always repeating some steps, inclusion of scripts is possible using the <code>preamble</code> parameter. For example, if you want all Matplotlib plots to have the <a href="https://matplotlib.org/tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py"><code>ggplot</code></a> style, you can write a very short preamble <code>style.py</code> like so:</p> +<div class="sourceCode" id="cb5"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true"></a><span class="im">import</span> matplotlib.pyplot <span class="im">as</span> plt</span> +<span id="cb5-2"><a href="#cb5-2" aria-hidden="true"></a>plt.style.use(<span class="st">'ggplot'</span>)</span></code></pre></div> +<p>and include it in your document as follows:</p> +<div class="sourceCode" id="cb6"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true"></a><span class="in">```{.matplotlib preamble=style.py}</span></span> +<span id="cb6-2"><a href="#cb6-2" aria-hidden="true"></a><span class="in">plt.figure()</span></span> +<span id="cb6-3"><a href="#cb6-3" aria-hidden="true"></a><span class="in">plt.plot([0,1,2,3,4], [1,2,3,4,5])</span></span> +<span id="cb6-4"><a href="#cb6-4" aria-hidden="true"></a><span class="in">plt.title('This is an example figure')</span></span> +<span id="cb6-5"><a href="#cb6-5" aria-hidden="true"></a><span class="in">```</span></span></code></pre></div> +<p>Which is equivalent to writing the following markdown:</p> +<div class="sourceCode" id="cb7"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"></a><span class="in">```{.matplotlib}</span></span> +<span id="cb7-2"><a href="#cb7-2" aria-hidden="true"></a><span class="in">import matplotlib.pyplot as plt</span></span> +<span id="cb7-3"><a href="#cb7-3" aria-hidden="true"></a><span class="in">plt.style.use('ggplot')</span></span> +<span id="cb7-4"><a href="#cb7-4" aria-hidden="true"></a></span> +<span id="cb7-5"><a href="#cb7-5" aria-hidden="true"></a><span class="in">plt.figure()</span></span> +<span id="cb7-6"><a href="#cb7-6" aria-hidden="true"></a><span class="in">plt.plot([0,1,2,3,4], [1,2,3,4,5])</span></span> +<span id="cb7-7"><a href="#cb7-7" aria-hidden="true"></a><span class="in">plt.title('This is an example figure')</span></span> +<span id="cb7-8"><a href="#cb7-8" aria-hidden="true"></a><span class="in">```</span></span></code></pre></div> +<p>The equivalent LaTeX usage is as follows:</p> +<div class="sourceCode" id="cb8"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[include=style.py]{matplotlib}</span> +<span id="cb8-2"><a href="#cb8-2" aria-hidden="true"></a></span> +<span id="cb8-3"><a href="#cb8-3" aria-hidden="true"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<p>This <code>preamble</code> parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script! You can also import packages this way, or define functions you often use.</p> +<h3 id="support-for-interative-plots">Support for interative plots</h3> +<p>Starting with version 0.8.0.0, <code>pandoc-plot</code> supports the creation of interactive plots (if a toolkit supports it). All you need to do is set the save format to <code>html</code>. The resulting plot is fully self-contained, so it can be displayed offline.</p> +<h3 id="performance">Performance</h3> +<p><code>pandoc-plot</code> minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. <code>pandoc-plot</code> will save the hash of the source code used to generate a figure in its filename. Before generating a figure, <code>pandoc-plot</code> will check it this figure already exists based on the hash of its source! This also means that there is no way to directly name figures.</p> +<p>Moreover, starting with version 0.5.0.0, <code>pandoc-plot</code> takes advantage of multicore CPUs, rendering figures <strong>in parallel</strong>.</p> +<p>Therefore, you can confidently run the filter on very large documents containing hundreds of figures, like a book or a thesis.</p> +<h3 id="compatibility-with-pandoc-crossref">Compatibility with pandoc-crossref</h3> +<p><a href="https://github.com/lierdakil/pandoc-crossref"><code>pandoc-crossref</code></a> is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents.</p> +<p>You can use <code>pandoc-crossref</code> in conjunction with <code>pandoc-plot</code> for the ultimate figure-making pipeline. You can combine both in a figure like so:</p> +<div class="sourceCode" id="cb9"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true"></a><span class="in">```{#fig:myexample .plotly_python caption="This is a caption"}</span></span> +<span id="cb9-2"><a href="#cb9-2" aria-hidden="true"></a><span class="in"># Insert figure script here</span></span> +<span id="cb9-3"><a href="#cb9-3" aria-hidden="true"></a><span class="in">```</span></span> +<span id="cb9-4"><a href="#cb9-4" aria-hidden="true"></a></span> +<span id="cb9-5"><a href="#cb9-5" aria-hidden="true"></a>As you can see in @fig:myexample, ...</span></code></pre></div> +<p>If the above source is located in file <code>myfile.md</code>, you can render the figure and references by applying <code>pandoc-plot</code> <strong>first</strong>, and then <code>pandoc-crossref</code>. For example:</p> +<div class="sourceCode" id="cb10"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true"></a><span class="ex">pandoc</span> --filter pandoc-plot --filter pandoc-crossref -i myfile.md -o myfile.html</span></code></pre></div> +<h2 id="detailed-usage">Detailed usage</h2> +<p><code>pandoc-plot</code> is a command line executable with a few functions. You can take a look at the help using the <code>-h</code>/<code>--help</code> flag:</p> +<div class="sourceCode" id="cb11"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true"></a><span class="ex">pandoc-plot</span> 0.8.0.0 - generate figures directly in documents</span> +<span id="cb11-2"><a href="#cb11-2" aria-hidden="true"></a></span> +<span id="cb11-3"><a href="#cb11-3" aria-hidden="true"></a><span class="ex">Usage</span>: pandoc-plot.EXE [(-v<span class="kw">|</span><span class="ex">--version</span>) <span class="kw">|</span> <span class="ex">--full-version</span> <span class="kw">|</span> <span class="kw">(</span><span class="ex">-m</span><span class="kw">|</span><span class="ex">--manual</span><span class="kw">)</span>] </span> +<span id="cb11-4"><a href="#cb11-4" aria-hidden="true"></a> [<span class="ex">COMMAND</span>] [AST]</span> +<span id="cb11-5"><a href="#cb11-5" aria-hidden="true"></a> <span class="ex">This</span> pandoc filter generates plots from code blocks using a multitude of</span> +<span id="cb11-6"><a href="#cb11-6" aria-hidden="true"></a> <span class="ex">possible</span> renderers. This allows to keep documentation and figures in perfect</span> +<span id="cb11-7"><a href="#cb11-7" aria-hidden="true"></a> <span class="ex">synchronicity.</span></span> +<span id="cb11-8"><a href="#cb11-8" aria-hidden="true"></a></span> +<span id="cb11-9"><a href="#cb11-9" aria-hidden="true"></a><span class="ex">Available</span> options:</span> +<span id="cb11-10"><a href="#cb11-10" aria-hidden="true"></a> <span class="ex">-v</span>,--version Show version number and exit.</span> +<span id="cb11-11"><a href="#cb11-11" aria-hidden="true"></a> <span class="ex">--full-version</span> Show full version information and exit.</span> +<span id="cb11-12"><a href="#cb11-12" aria-hidden="true"></a> <span class="ex">-m</span>,--manual Open the manual page in the default web browser and</span> +<span id="cb11-13"><a href="#cb11-13" aria-hidden="true"></a> <span class="ex">exit.</span></span> +<span id="cb11-14"><a href="#cb11-14" aria-hidden="true"></a> <span class="ex">-h</span>,--help Show this help text</span> +<span id="cb11-15"><a href="#cb11-15" aria-hidden="true"></a></span> +<span id="cb11-16"><a href="#cb11-16" aria-hidden="true"></a><span class="ex">Available</span> commands:</span> +<span id="cb11-17"><a href="#cb11-17" aria-hidden="true"></a> <span class="ex">toolkits</span> Show information on toolkits and exit.</span> +<span id="cb11-18"><a href="#cb11-18" aria-hidden="true"></a> <span class="ex">clean</span> Clean output directories where figures from FILE and</span> +<span id="cb11-19"><a href="#cb11-19" aria-hidden="true"></a> <span class="ex">log</span> files might be stored. WARNING: All files in</span> +<span id="cb11-20"><a href="#cb11-20" aria-hidden="true"></a> <span class="ex">those</span> directories will be deleted.</span> +<span id="cb11-21"><a href="#cb11-21" aria-hidden="true"></a> <span class="ex">write-example-config</span> Write example configuration to a file and exit.</span> +<span id="cb11-22"><a href="#cb11-22" aria-hidden="true"></a></span> +<span id="cb11-23"><a href="#cb11-23" aria-hidden="true"></a><span class="ex">More</span> information can be found via the manual (pandoc-plot --manual) <span class="ex">or</span> the</span> +<span id="cb11-24"><a href="#cb11-24" aria-hidden="true"></a><span class="ex">repository</span> README, located at https://github.com/LaurentRDC/pandoc-plot</span></code></pre></div> +<h3 id="as-a-filter">As a filter</h3> +<p>The most common use for <code>pandoc-plot</code> is as a pandoc filter, in which case it should be called without arguments. For example:</p> +<div class="sourceCode" id="cb12"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true"></a><span class="ex">pandoc</span> --filter pandoc-plot -i input.md -o output.html</span></code></pre></div> +<p>If <code>pandoc-plot</code> fails to render a code block into a figure, the filtering will not stop. Your code blocks will stay unchanged.</p> +<p>You can chain other filters with it (e.g., <a href="https://github.com/lierdakil/pandoc-crossref"><code>pandoc-crossref</code></a>) like so:</p> +<div class="sourceCode" id="cb13"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true"></a><span class="ex">pandoc</span> --filter pandoc-plot --filter pandoc-crossref -i input.md -o output.html</span></code></pre></div> +<h3 id="syntax">Syntax</h3> +<p>The syntax for code blocks in documents is shown below. <code>pandoc-plot</code> looks for code blocks with a specific class, depending on the toolkit you want to use. <code>pandoc-plot</code> will run the code and capture the figure output. There can only be <strong>one</strong> figure per code block.</p> +<p>The possible parameters and options are described in <a href="#parameters-and-options">further below</a>.</p> +<h4 id="markdown">Markdown</h4> +<div class="sourceCode" id="cb14"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true"></a> <span class="in">```{.cls param1=value1 param2=value2 ...}</span></span> +<span id="cb14-2"><a href="#cb14-2" aria-hidden="true"></a><span class="in"> # script content</span></span> +<span id="cb14-3"><a href="#cb14-3" aria-hidden="true"></a><span class="in"> ```</span></span></code></pre></div> +<h4 id="latex">LaTeX</h4> +<p>Note that the <code>minted</code> LaTeX package need not be installed.</p> +<div class="sourceCode" id="cb15"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true"></a><span class="kw">\begin</span>{<span class="ex">minted</span>}[param1=value1, param2=value2, ...]{cls}</span> +<span id="cb15-2"><a href="#cb15-2" aria-hidden="true"></a><span class="vs">...</span></span> +<span id="cb15-3"><a href="#cb15-3" aria-hidden="true"></a><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<h3 id="parameters-and-options">Parameters and options</h3> +<p>There are parameters that affect the figure that will be included in your document. Here are all the possible general parameters, in Markdown syntax:</p> +<div class="sourceCode" id="cb16"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true"></a> <span class="in">```{.cls </span></span> +<span id="cb16-2"><a href="#cb16-2" aria-hidden="true"></a><span class="in"> .language</span></span> +<span id="cb16-3"><a href="#cb16-3" aria-hidden="true"></a><span class="in"> directory=(path) </span></span> +<span id="cb16-4"><a href="#cb16-4" aria-hidden="true"></a><span class="in"> caption=(text) </span></span> +<span id="cb16-5"><a href="#cb16-5" aria-hidden="true"></a><span class="in"> format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP|HTML) </span></span> +<span id="cb16-6"><a href="#cb16-6" aria-hidden="true"></a><span class="in"> source=(true|false) </span></span> +<span id="cb16-7"><a href="#cb16-7" aria-hidden="true"></a><span class="in"> preamble=(path) </span></span> +<span id="cb16-8"><a href="#cb16-8" aria-hidden="true"></a><span class="in"> dpi=(integer) </span></span> +<span id="cb16-9"><a href="#cb16-9" aria-hidden="true"></a><span class="in"> executable=(path) </span></span> +<span id="cb16-10"><a href="#cb16-10" aria-hidden="true"></a><span class="in"> caption_format=(text)</span></span> +<span id="cb16-11"><a href="#cb16-11" aria-hidden="true"></a><span class="in"> }</span></span> +<span id="cb16-12"><a href="#cb16-12" aria-hidden="true"></a><span class="in"> # script content</span></span> +<span id="cb16-13"><a href="#cb16-13" aria-hidden="true"></a><span class="in"> ```</span></span></code></pre></div> +<ul> +<li><code>cls</code> must be one of the following: <code>matplotlib</code>, <code>matlabplot</code>, <code>plotly_python</code>, <code>plotly_r</code>, <code>mathplot</code>, <code>octaveplot</code>, <code>ggplot2</code>, <code>gnuplot</code>, <code>graphviz</code>, <code>bokeh</code>, <code>plotsjl</code>.</li> +</ul> +<p>All following parameters are optional, with their default values controlled by the <a href="#configuration">configuration</a></p> +<ul> +<li><code>language</code> specifies the programming language used in this block. This parameter is ignored by <code>pandoc-plot</code>, but your text editor may use it to highlight code. See <a href="#code-highlighting">Code highlighting</a> below.</li> +<li><code>directory</code> is a path to the directory where the figure and source code will be saved. You cannot control the file name. This path is either absolute, or relative from the working directory where you call <code>pandoc-plot</code>.</li> +<li><code>caption</code> is the caption text. The format of the caption is specified in the <code>caption_format</code> parameter, described below.</li> +<li><code>format</code> is the desired filetype for the resulting figure. Possible values for <code>format</code> are [<code>PNG</code>, <code>PDF</code>, <code>SVG</code>, <code>JPG</code>, <code>EPS</code>, <code>GIF</code>, <code>TIF</code>, <code>WEBP</code>, <code>HTML</code>]. Not all toolkits support all formats. See <code>pandoc-plot toolkits</code> for toolkit-specific information regarding save formats. The <code>HTML</code> format is special; it can produce standalone, offline, interactive plots. As such, it only makes sense to use this format when creating HTML documents.</li> +<li><code>source</code> is a boolean toggle that determines whether the source code should be linked in the caption or not. Possible values are [<code>true</code>, <code>True</code>, <code>false</code>, <code>False</code>].</li> +<li><code>preamble</code> is a path to a script that will be included as a preamble to the content of the code block. This path is either absolute, or relative from the working directory where you call <code>pandoc-plot</code>.</li> +<li><code>dpi</code> is the pixel density of the figure in dots-per-inch. Possible values are positive integers. Not all toolkits respect this.</li> +<li><code>executable</code> is a path to the executable to use (e.g. <code>C:\\python3.exe</code>) or the name of the executable (e.g. <code>python3</code>).</li> +<li><code>caption_format</code> is the text format of the caption. Possible values are exactly the same as <code>pandoc</code>’s format specification, usually <code>FORMAT+EXTENSION-EXTENSION</code>. For example, captions in Markdown with raw LaTeX would be parsed correctly provided that <code>caption_format=markdown+raw_tex</code>. See Pandoc’s guide on <a href="https://pandoc.org/MANUAL.html#specifying-formats">Specifying formats</a>.</li> +</ul> +<h4 id="code-highlighting">Code highlighting</h4> +<p>If your editor supports code highlighting in code blocks, you can also include the programming language. In Markdown:</p> +<div class="sourceCode" id="cb17"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true"></a> <span class="in">```{.language .cls (options)}</span></span> +<span id="cb17-2"><a href="#cb17-2" aria-hidden="true"></a><span class="in"> # script content</span></span> +<span id="cb17-3"><a href="#cb17-3" aria-hidden="true"></a><span class="in"> ```</span></span></code></pre></div> +<p>or Latex:</p> +<div class="sourceCode" id="cb18"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true"></a> <span class="kw">\begin</span>{<span class="ex">minted</span>}[(options)]{language, cls}</span> +<span id="cb18-2"><a href="#cb18-2" aria-hidden="true"></a><span class="vs"> # script content</span></span> +<span id="cb18-3"><a href="#cb18-3" aria-hidden="true"></a><span class="vs"> </span><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<p>For example, for GGPlot2 figures:</p> +<div class="sourceCode" id="cb19"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true"></a> <span class="in">```{.r .ggplot2 caption=Highlighted code block}</span></span> +<span id="cb19-2"><a href="#cb19-2" aria-hidden="true"></a><span class="in"> # script content</span></span> +<span id="cb19-3"><a href="#cb19-3" aria-hidden="true"></a><span class="in"> ```</span></span></code></pre></div> +<p>or (Latex):</p> +<div class="sourceCode" id="cb20"><pre class="sourceCode latex"><code class="sourceCode latex"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true"></a> <span class="kw">\begin</span>{<span class="ex">minted</span>}[caption=Highlighted code block]{r, ggplot2}</span> +<span id="cb20-2"><a href="#cb20-2" aria-hidden="true"></a><span class="vs"> # script content</span></span> +<span id="cb20-3"><a href="#cb20-3" aria-hidden="true"></a><span class="vs"> </span><span class="kw">\end</span>{<span class="ex">minted</span>}</span></code></pre></div> +<p>This way, you benefit from code highlighting <em>and</em> <code>pandoc-plot</code>.</p> +<h3 id="configuration">Configuration</h3> +<p>To avoid repetition, <code>pandoc-plot</code> can be configured using simple YAML +files. Here are <strong>all</strong> the possible parameters:</p> +<div class="sourceCode" id="cb21"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true"></a></span> +<span id="cb21-2"><a href="#cb21-2" aria-hidden="true"></a><span class="co"># This is an example configuration. Everything in this file is optional.</span></span> +<span id="cb21-3"><a href="#cb21-3" aria-hidden="true"></a><span class="co"># Please refer to the documentation to know about the parameters herein.</span></span> +<span id="cb21-4"><a href="#cb21-4" aria-hidden="true"></a><span class="co">#</span></span> +<span id="cb21-5"><a href="#cb21-5" aria-hidden="true"></a><span class="co"># The `executable` parameter for all toolkits can be either the</span></span> +<span id="cb21-6"><a href="#cb21-6" aria-hidden="true"></a><span class="co"># executable name (if it is present on the PATH), or</span></span> +<span id="cb21-7"><a href="#cb21-7" aria-hidden="true"></a><span class="co"># the full path to the executable.</span></span> +<span id="cb21-8"><a href="#cb21-8" aria-hidden="true"></a><span class="co"># E.g.:</span></span> +<span id="cb21-9"><a href="#cb21-9" aria-hidden="true"></a><span class="co"># executable: python3</span></span> +<span id="cb21-10"><a href="#cb21-10" aria-hidden="true"></a><span class="co"># executable: "C:\Python37\Scripts\python.exe"</span></span> +<span id="cb21-11"><a href="#cb21-11" aria-hidden="true"></a></span> +<span id="cb21-12"><a href="#cb21-12" aria-hidden="true"></a><span class="co"># The following parameters affect all toolkits</span></span> +<span id="cb21-13"><a href="#cb21-13" aria-hidden="true"></a><span class="co"># Directory where to save the plots. The path can be relative to pandoc-plot's</span></span> +<span id="cb21-14"><a href="#cb21-14" aria-hidden="true"></a><span class="co"># current working directory, or absolute.</span></span> +<span id="cb21-15"><a href="#cb21-15" aria-hidden="true"></a><span class="fu">directory</span><span class="kw">:</span><span class="at"> plots/</span></span> +<span id="cb21-16"><a href="#cb21-16" aria-hidden="true"></a></span> +<span id="cb21-17"><a href="#cb21-17" aria-hidden="true"></a><span class="co"># Whether or not to include a link to the source script in the caption. </span></span> +<span id="cb21-18"><a href="#cb21-18" aria-hidden="true"></a><span class="co"># Particularly useful for HTML output.</span></span> +<span id="cb21-19"><a href="#cb21-19" aria-hidden="true"></a><span class="fu">source</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span> +<span id="cb21-20"><a href="#cb21-20" aria-hidden="true"></a></span> +<span id="cb21-21"><a href="#cb21-21" aria-hidden="true"></a><span class="co"># Default density of figures in dots per inches (DPI). </span></span> +<span id="cb21-22"><a href="#cb21-22" aria-hidden="true"></a><span class="co"># This can be changed in the document specifically as well.</span></span> +<span id="cb21-23"><a href="#cb21-23" aria-hidden="true"></a><span class="fu">dpi</span><span class="kw">:</span><span class="at"> </span><span class="dv">80</span></span> +<span id="cb21-24"><a href="#cb21-24" aria-hidden="true"></a></span> +<span id="cb21-25"><a href="#cb21-25" aria-hidden="true"></a><span class="co"># Default format in which to save the figures. This can be specified </span></span> +<span id="cb21-26"><a href="#cb21-26" aria-hidden="true"></a><span class="co"># individually as well.</span></span> +<span id="cb21-27"><a href="#cb21-27" aria-hidden="true"></a><span class="fu">format</span><span class="kw">:</span><span class="at"> PNG</span></span> +<span id="cb21-28"><a href="#cb21-28" aria-hidden="true"></a></span> +<span id="cb21-29"><a href="#cb21-29" aria-hidden="true"></a><span class="co"># Text format for the captions. Unfortunately, there is no way to detect</span></span> +<span id="cb21-30"><a href="#cb21-30" aria-hidden="true"></a><span class="co"># this automatically. You can use the same notation as Pandoc's --from </span></span> +<span id="cb21-31"><a href="#cb21-31" aria-hidden="true"></a><span class="co"># parameter, specified here: </span></span> +<span id="cb21-32"><a href="#cb21-32" aria-hidden="true"></a><span class="co"># https://pandoc.org/MANUAL.html#option--from</span></span> +<span id="cb21-33"><a href="#cb21-33" aria-hidden="true"></a><span class="co"># Example: markdown, rst+raw_tex</span></span> +<span id="cb21-34"><a href="#cb21-34" aria-hidden="true"></a><span class="fu">caption_format</span><span class="kw">:</span><span class="at"> markdown+tex_math_dollars</span></span> +<span id="cb21-35"><a href="#cb21-35" aria-hidden="true"></a></span> +<span id="cb21-36"><a href="#cb21-36" aria-hidden="true"></a><span class="co"># Logging configuration</span></span> +<span id="cb21-37"><a href="#cb21-37" aria-hidden="true"></a><span class="fu">logging</span><span class="kw">:</span></span> +<span id="cb21-38"><a href="#cb21-38" aria-hidden="true"></a><span class="co"> # Possible verbosity values: debug, error, warning, info, silent</span></span> +<span id="cb21-39"><a href="#cb21-39" aria-hidden="true"></a><span class="at"> </span><span class="fu">verbosity</span><span class="kw">:</span><span class="at"> warning</span></span> +<span id="cb21-40"><a href="#cb21-40" aria-hidden="true"></a><span class="co"> # If the filepath below is not present, then pandoc-plot will log to stderr</span></span> +<span id="cb21-41"><a href="#cb21-41" aria-hidden="true"></a><span class="co"> # Otherwise, log messages will be appended to the filepath.</span></span> +<span id="cb21-42"><a href="#cb21-42" aria-hidden="true"></a><span class="co"> # filepath: path/to/file.txt</span></span> +<span id="cb21-43"><a href="#cb21-43" aria-hidden="true"></a></span> +<span id="cb21-44"><a href="#cb21-44" aria-hidden="true"></a><span class="co"># The possible parameters for the Matplotlib toolkit</span></span> +<span id="cb21-45"><a href="#cb21-45" aria-hidden="true"></a><span class="fu">matplotlib</span><span class="kw">:</span></span> +<span id="cb21-46"><a href="#cb21-46" aria-hidden="true"></a><span class="co"> # preamble: matplotlib.py</span></span> +<span id="cb21-47"><a href="#cb21-47" aria-hidden="true"></a><span class="at"> </span><span class="fu">tight_bbox</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span> +<span id="cb21-48"><a href="#cb21-48" aria-hidden="true"></a><span class="at"> </span><span class="fu">transparent</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span> +<span id="cb21-49"><a href="#cb21-49" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span> +<span id="cb21-50"><a href="#cb21-50" aria-hidden="true"></a></span> +<span id="cb21-51"><a href="#cb21-51" aria-hidden="true"></a><span class="co"># The possible parameters for the MATLAB toolkit</span></span> +<span id="cb21-52"><a href="#cb21-52" aria-hidden="true"></a><span class="fu">matlabplot</span><span class="kw">:</span></span> +<span id="cb21-53"><a href="#cb21-53" aria-hidden="true"></a><span class="co"> # preamble: matlab.m</span></span> +<span id="cb21-54"><a href="#cb21-54" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> matlab</span></span> +<span id="cb21-55"><a href="#cb21-55" aria-hidden="true"></a></span> +<span id="cb21-56"><a href="#cb21-56" aria-hidden="true"></a><span class="co"># The possible parameters for the Plotly/Python toolkit</span></span> +<span id="cb21-57"><a href="#cb21-57" aria-hidden="true"></a><span class="fu">plotly_python</span><span class="kw">:</span></span> +<span id="cb21-58"><a href="#cb21-58" aria-hidden="true"></a><span class="co"> # preamble: plotly-python.py</span></span> +<span id="cb21-59"><a href="#cb21-59" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span> +<span id="cb21-60"><a href="#cb21-60" aria-hidden="true"></a></span> +<span id="cb21-61"><a href="#cb21-61" aria-hidden="true"></a><span class="co"># The possible parameters for the Plotly/R toolkit</span></span> +<span id="cb21-62"><a href="#cb21-62" aria-hidden="true"></a><span class="fu">plotly_r</span><span class="kw">:</span></span> +<span id="cb21-63"><a href="#cb21-63" aria-hidden="true"></a><span class="co"> # preamble: plotly-r.r</span></span> +<span id="cb21-64"><a href="#cb21-64" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> Rscript</span></span> +<span id="cb21-65"><a href="#cb21-65" aria-hidden="true"></a></span> +<span id="cb21-66"><a href="#cb21-66" aria-hidden="true"></a><span class="co"># The possible parameters for the Mathematica toolkit</span></span> +<span id="cb21-67"><a href="#cb21-67" aria-hidden="true"></a><span class="fu">mathplot</span><span class="kw">:</span></span> +<span id="cb21-68"><a href="#cb21-68" aria-hidden="true"></a><span class="co"> # preamble: mathematica.m</span></span> +<span id="cb21-69"><a href="#cb21-69" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> math</span></span> +<span id="cb21-70"><a href="#cb21-70" aria-hidden="true"></a></span> +<span id="cb21-71"><a href="#cb21-71" aria-hidden="true"></a><span class="co"># The possible parameters for the GNU Octave toolkit</span></span> +<span id="cb21-72"><a href="#cb21-72" aria-hidden="true"></a><span class="fu">octaveplot</span><span class="kw">:</span></span> +<span id="cb21-73"><a href="#cb21-73" aria-hidden="true"></a><span class="co"> # preamble: octave.m</span></span> +<span id="cb21-74"><a href="#cb21-74" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> octave</span></span> +<span id="cb21-75"><a href="#cb21-75" aria-hidden="true"></a></span> +<span id="cb21-76"><a href="#cb21-76" aria-hidden="true"></a><span class="co"># The possible parameters for the ggplot2 toolkit</span></span> +<span id="cb21-77"><a href="#cb21-77" aria-hidden="true"></a><span class="fu">ggplot2</span><span class="kw">:</span></span> +<span id="cb21-78"><a href="#cb21-78" aria-hidden="true"></a><span class="co"> # preamble: ggplot2.r</span></span> +<span id="cb21-79"><a href="#cb21-79" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> Rscript</span></span> +<span id="cb21-80"><a href="#cb21-80" aria-hidden="true"></a></span> +<span id="cb21-81"><a href="#cb21-81" aria-hidden="true"></a><span class="co"># The possible parameters for the gnuplot toolkit</span></span> +<span id="cb21-82"><a href="#cb21-82" aria-hidden="true"></a><span class="fu">gnuplot</span><span class="kw">:</span></span> +<span id="cb21-83"><a href="#cb21-83" aria-hidden="true"></a><span class="co"> # preamble: gnuplot.gp</span></span> +<span id="cb21-84"><a href="#cb21-84" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> gnuplot</span></span> +<span id="cb21-85"><a href="#cb21-85" aria-hidden="true"></a></span> +<span id="cb21-86"><a href="#cb21-86" aria-hidden="true"></a><span class="co"># The possible parameters for the graphviz toolkit</span></span> +<span id="cb21-87"><a href="#cb21-87" aria-hidden="true"></a><span class="fu">graphviz</span><span class="kw">:</span></span> +<span id="cb21-88"><a href="#cb21-88" aria-hidden="true"></a><span class="co"> # preamble: graphviz.dot</span></span> +<span id="cb21-89"><a href="#cb21-89" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> dot</span></span> +<span id="cb21-90"><a href="#cb21-90" aria-hidden="true"></a></span> +<span id="cb21-91"><a href="#cb21-91" aria-hidden="true"></a><span class="fu">bokeh</span><span class="kw">:</span></span> +<span id="cb21-92"><a href="#cb21-92" aria-hidden="true"></a><span class="co"> # preamble: bokeh.py</span></span> +<span id="cb21-93"><a href="#cb21-93" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python</span></span> +<span id="cb21-94"><a href="#cb21-94" aria-hidden="true"></a></span> +<span id="cb21-95"><a href="#cb21-95" aria-hidden="true"></a><span class="fu">plotsjl</span><span class="kw">:</span></span> +<span id="cb21-96"><a href="#cb21-96" aria-hidden="true"></a><span class="co"> # preamble: plotsjl.jl</span></span> +<span id="cb21-97"><a href="#cb21-97" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> julia</span></span></code></pre></div> +<p>A file like the above sets the <strong>default</strong> values; you can still override them in documents directly.</p> +<p>The easiest way to specify configuration for <code>pandoc-plot</code> is to place a <code>.pandoc-plot.yml</code> file in the current working directory. You can also specify a configuration file in document metadata, under the <code>plot-configuration</code> key. For example, in Markdown:</p> +<div class="sourceCode" id="cb22"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true"></a><span class="co">---</span></span> +<span id="cb22-2"><a href="#cb22-2" aria-hidden="true"></a><span class="an">title:</span><span class="co"> My document</span></span> +<span id="cb22-3"><a href="#cb22-3" aria-hidden="true"></a><span class="an">author:</span><span class="co"> John Doe</span></span> +<span id="cb22-4"><a href="#cb22-4" aria-hidden="true"></a><span class="an">plot-configuration:</span><span class="co"> /path/to/file.yml</span></span> +<span id="cb22-5"><a href="#cb22-5" aria-hidden="true"></a><span class="co">---</span></span></code></pre></div> +<p>or on the command line, using the pandoc <code>-M/--metadata</code> flag:</p> +<div class="sourceCode" id="cb23"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true"></a><span class="ex">pandoc</span> --filter pandoc-plot -M plot-configuration=/path/to/file.yml ...</span></code></pre></div> +<p>The hierarchy of configuration files is as follows:</p> +<ol type="1"> +<li>A configuration file specified in the metadata under the <code>plot-configuration</code> key;</li> +<li>Otherwise, a file in the current working directory named <code>.pandoc-plot.yml</code>;</li> +<li>Finally, the default configuration is used.</li> +</ol> +<h4 id="executables">Executables</h4> +<p>The <code>executable</code> parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable.</p> +<p>Examples:</p> +<div class="sourceCode" id="cb24"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true"></a><span class="fu">matplotlib</span><span class="kw">:</span></span> +<span id="cb24-2"><a href="#cb24-2" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> python3</span></span></code></pre></div> +<div class="sourceCode" id="cb25"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true"></a><span class="fu">matlabplot</span><span class="kw">:</span></span> +<span id="cb25-2"><a href="#cb25-2" aria-hidden="true"></a><span class="at"> </span><span class="fu">executable</span><span class="kw">:</span><span class="at"> </span><span class="st">"C:\Program Files\Matlab\R2019b</span><span class="sc">\b</span><span class="st">in\matlab.exe"</span></span></code></pre></div> +<h4 id="toolkit-specific-options">Toolkit-specific options</h4> +<h5 id="matplotlib">Matplotlib</h5> +<ul> +<li><code>tight_bbox</code> is a boolean that determines whether to use <code>bbox_inches="tight"</code> or not when saving Matplotlib figures. For example, <code>tight_bbox: true</code>. See <a href="https://matplotlib.org/api/_as_gen/matplotlib.pyplot.savefig.html">here</a> for details.</li> +<li><code>transparent</code> is a boolean that determines whether to make Matplotlib figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, <code>transparent: true</code>.</li> +</ul> +<h4 id="logging">Logging</h4> +<p>If you are running <code>pandoc-plot</code> on a large document, you might want to turn on logging. You can do so via the configuration file as follows:</p> +<div class="sourceCode" id="cb26"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true"></a><span class="fu">logging</span><span class="kw">:</span></span> +<span id="cb26-2"><a href="#cb26-2" aria-hidden="true"></a><span class="co"> # Possible verbosity values: debug, error, warning, info, silent</span></span> +<span id="cb26-3"><a href="#cb26-3" aria-hidden="true"></a><span class="co"> # debug level shows all messages</span></span> +<span id="cb26-4"><a href="#cb26-4" aria-hidden="true"></a><span class="co"> # error level shows all but debug messages, etc.</span></span> +<span id="cb26-5"><a href="#cb26-5" aria-hidden="true"></a><span class="at"> </span><span class="fu">verbosity</span><span class="kw">:</span><span class="at"> info</span></span> +<span id="cb26-6"><a href="#cb26-6" aria-hidden="true"></a><span class="at"> </span></span> +<span id="cb26-7"><a href="#cb26-7" aria-hidden="true"></a><span class="co"> # OPTIONAL: log to file</span></span> +<span id="cb26-8"><a href="#cb26-8" aria-hidden="true"></a><span class="co"> # Remove line below to log to stderr</span></span> +<span id="cb26-9"><a href="#cb26-9" aria-hidden="true"></a><span class="at"> </span><span class="fu">filepath</span><span class="kw">:</span><span class="at"> log.txt</span></span></code></pre></div> +<p>By default, <code>pandoc-plot</code> logs warnings and errors to the standard error stream only.</p> +<h3 id="other-commands">Other commands</h3> +<h4 id="finding-installed-toolkits">Finding installed toolkits</h4> +<p>You can determine which toolkits are available on your current machine using the <code>pandoc-plot toolkits</code> command. Here is the full help text:</p> +<div class="sourceCode" id="cb27"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true"></a><span class="ex">Usage</span>: pandoc-plot.EXE toolkits [--config PATH]</span> +<span id="cb27-2"><a href="#cb27-2" aria-hidden="true"></a> <span class="ex">Show</span> information on toolkits and exit.</span> +<span id="cb27-3"><a href="#cb27-3" aria-hidden="true"></a></span> +<span id="cb27-4"><a href="#cb27-4" aria-hidden="true"></a><span class="ex">Available</span> options:</span> +<span id="cb27-5"><a href="#cb27-5" aria-hidden="true"></a> <span class="ex">--config</span> PATH Path to optional configuration file.</span> +<span id="cb27-6"><a href="#cb27-6" aria-hidden="true"></a> <span class="ex">-h</span>,--help Show this help text</span></code></pre></div> +<h4 id="cleaning-output">Cleaning output</h4> +<p>Figures produced by <code>pandoc-plot</code> can be placed in a few different locations. You can set a default location in the <a href="#configuration">Configuration</a>, but you can also re-direct specific figures in other directories if you use the <code>directory=...</code> argument in code blocks. These figures will build up over time. You can use the <code>clean</code> command to scan documents and delete the associated <code>pandoc-plot</code> output files. For example, to delete the figures generated from the <code>input.md</code> file:</p> +<div class="sourceCode" id="cb28"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true"></a><span class="ex">pandoc-plot</span> clean input.md</span></code></pre></div> +<p>This sill remove all directories where a figure <em>could</em> have been placed. <strong>WARNING</strong>: all files will be removed.</p> +<p>Here is the full help text for the <code>clean</code> command:</p> +<div class="sourceCode" id="cb29"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true"></a><span class="ex">Usage</span>: pandoc-plot.EXE clean [--config PATH] FILE</span> +<span id="cb29-2"><a href="#cb29-2" aria-hidden="true"></a> <span class="ex">Clean</span> output directories where figures from FILE and log files might be</span> +<span id="cb29-3"><a href="#cb29-3" aria-hidden="true"></a> <span class="ex">stored.</span> WARNING: All files in those directories will be deleted.</span> +<span id="cb29-4"><a href="#cb29-4" aria-hidden="true"></a></span> +<span id="cb29-5"><a href="#cb29-5" aria-hidden="true"></a><span class="ex">Available</span> options:</span> +<span id="cb29-6"><a href="#cb29-6" aria-hidden="true"></a> <span class="ex">--config</span> PATH Path to optional configuration file.</span> +<span id="cb29-7"><a href="#cb29-7" aria-hidden="true"></a> <span class="ex">-h</span>,--help Show this help text</span></code></pre></div> +<h4 id="configuration-template">Configuration template</h4> +<p>Because <code>pandoc-plot</code> supports a few toolkits, there are a lot of configuration options. Don’t start from scratch! The <code>write-example-config</code> command will create a file for you, which you can then modify:</p> +<div class="sourceCode" id="cb30"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true"></a><span class="ex">pandoc-plot</span> write-example-config</span></code></pre></div> +<p>You will need to re-name the file to <code>.pandoc-ploy.yml</code> to be able to use it, so don’t worry about overwriting your own configuration.</p> +<p>Here is the full help text for the <code>write-example-config</code> command:</p> +<div class="sourceCode" id="cb31"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true"></a><span class="ex">Usage</span>: pandoc-plot.EXE write-example-config [--path FILE]</span> +<span id="cb31-2"><a href="#cb31-2" aria-hidden="true"></a> <span class="ex">Write</span> example configuration to a file and exit.</span> +<span id="cb31-3"><a href="#cb31-3" aria-hidden="true"></a></span> +<span id="cb31-4"><a href="#cb31-4" aria-hidden="true"></a><span class="ex">Available</span> options:</span> +<span id="cb31-5"><a href="#cb31-5" aria-hidden="true"></a> <span class="ex">--path</span> FILE Target location of the configuration file. Default is</span> +<span id="cb31-6"><a href="#cb31-6" aria-hidden="true"></a> <span class="st">".example-pandoc-plot.yml"</span></span> +<span id="cb31-7"><a href="#cb31-7" aria-hidden="true"></a> <span class="ex">-h</span>,--help Show this help text</span></code></pre></div> +<h2 id="warning">Warning</h2> +<p>Do not run this filter on unknown documents. There is nothing in +<code>pandoc-plot</code> that can stop a script from performing <strong>evil actions</strong>.</p> +</body> +</html>
example-config.yml view
@@ -22,12 +22,14 @@ # This can be changed in the document specifically as well. dpi: 80 -# Default format in which to save the figures. This can be specified individually as well. +# Default format in which to save the figures. This can be specified +# individually as well. format: PNG -# Text format for the captions. Unfortunately, there is no way to detect this automatically. -# You can use the same notation as Pandoc's --from parameter, specified here: -# https://pandoc.org/MANUAL.html#option--from +# Text format for the captions. Unfortunately, there is no way to detect +# this automatically. You can use the same notation as Pandoc's --from +# parameter, specified here: +# https://pandoc.org/MANUAL.html#option--from # Example: markdown, rst+raw_tex caption_format: markdown+tex_math_dollars @@ -84,4 +86,12 @@ # The possible parameters for the graphviz toolkit graphviz: # preamble: graphviz.dot - executable: dot+ executable: dot + +bokeh: + # preamble: bokeh.py + executable: python + +plotsjl: + # preamble: plotsjl.jl + executable: julia
executable/Main.hs view
@@ -1,7 +1,9 @@ {-# LANGUAGE ApplicativeDo #-} {-# LANGUAGE LambdaCase #-} +{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE RecordWildCards #-} +{-# LANGUAGE CPP #-} module Main where @@ -26,7 +28,8 @@ import Text.Pandoc.Filter.Plot (availableToolkits, plotTransform, defaultConfiguration, - configuration, Configuration(..)) + configuration, Configuration(..), + pandocPlotVersion) import Text.Pandoc.Filter.Plot.Internal (cls, supportedSaveFormats, toolkits, readDoc, cleanOutputDirs, @@ -42,7 +45,6 @@ import OpenFile (openFile) import qualified Data.Version as V -import Paths_pandoc_plot (version) import ManPage (embedManualHtml) import ExampleConfig (embedExampleConfig) @@ -65,9 +67,13 @@ where opts = info (optparse <**> helper) (fullDesc - <> progDesc "This pandoc filter generates plots from code blocks using a multitude of possible renderers. \ - \This allows to keep documentation and figures in perfect synchronicity." - <> header "pandoc-plot - generate figures directly in documents using your plotting toolkit of choice." + <> progDesc (unlines + ["This pandoc filter generates plots from code blocks using a multitude of " + , "possible renderers. This allows to keep documentation and figures in" + , "perfect synchronicity." + ] + ) + <> header (mconcat ["pandoc-plot ", V.showVersion pandocPlotVersion, " - generate figures directly in documents"]) <> footerDoc (Just footer') ) @@ -81,7 +87,7 @@ return $ go flag_ command_ input go :: Maybe Flag -> Maybe Command -> Maybe String -> IO () - go (Just Version) _ _ = putStrLn (V.showVersion version) + go (Just Version) _ _ = putStrLn (V.showVersion pandocPlotVersion) go (Just FullVersion) _ _ = showFullVersion go (Just Manual) _ _ = showManPage go _ (Just (Toolkits mfp)) _ = showAvailableToolkits mfp @@ -116,10 +122,13 @@ ) , command "clean" ( info (cleanP <**> helper) ( - progDesc "Clean output directories where figures from FILE and log files might be stored.\ - \ WARNING: All files in those directories will be deleted." - ) + progDesc (unlines + [ "Clean output directories where figures from FILE and log files might be stored." + , "WARNING: All files in those directories will be deleted." + ] + ) ) + ) , command "write-example-config" ( info (writeConfigP <**> helper) (progDesc "Write example configuration to a file and exit.") ) @@ -195,13 +204,13 @@ showFullVersion :: IO () showFullVersion = do - putStrLn $ "pandoc-plot " <> (V.showVersion version) + putStrLn $ "pandoc-plot " <> (V.showVersion pandocPlotVersion) putStrLn $ "Git revision " <> gitrev - putStrLn $ mconcat [ "Compiled with pandoc " - , (unpack pandocVersion) - , " and pandoc-types " - , V.showVersion pandocTypesVersion - ] + putStrLn $ mconcat + [ "Compiled with pandoc " , (unpack pandocVersion) + , " and pandoc-types " , V.showVersion pandocTypesVersion + , " using GHC ", TOOL_VERSION_ghc -- Constant defined by CPP + ] where -- In certain environments (e.g. Hackage when building documentation), -- there is no git information. @@ -263,8 +272,7 @@ -- | Use Doc type directly because of newline formatting footer' :: P.Doc footer' = mconcat - [ P.text "More information can be found via the manual (pandoc-plot --manual) or the repository README, located at" - , P.line - , P.indent 4 $ P.text "https://github.com/LaurentRDC/pandoc-plot" - , P.line + [ P.text "More information can be found via the manual (pandoc-plot --manual) or the" + , P.line + , P.text "repository README, located at https://github.com/LaurentRDC/pandoc-plot" ]
executable/ManPage.hs view
@@ -1,41 +1,30 @@-{-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE OverloadedStrings #-} {-| This module was inspired by pandoc-crossref |-} module ManPage ( embedManualHtml ) where -import Data.String -import qualified Data.Text as T +import Data.String (fromString) +import Data.Text (unpack) import qualified Data.Text.IO as TIO -import Language.Haskell.TH.Syntax +import System.FilePath ((</>)) -import qualified Text.Pandoc as P -import Text.Pandoc.Highlighting (pygments) +import Language.Haskell.TH.Syntax docFile :: FilePath -docFile = "README.md" +docFile = "docs" </> "MANUAL.html" readDocFile :: IO String -readDocFile = TIO.readFile docFile >>= return . T.unpack - -readerOpts :: P.ReaderOptions -readerOpts = P.def { P.readerExtensions = P.githubMarkdownExtensions - , P.readerStandalone = True - } +readDocFile = TIO.readFile docFile >>= return . unpack -embedManual :: (P.Pandoc -> P.PandocPure T.Text) -> Q Exp -embedManual fmt = do +embedManualHtml :: Q Exp +embedManualHtml = do qAddDependentFile docFile d <- runIO readDocFile - let pd = either (error . show) id $ P.runPure $ P.readMarkdown readerOpts (T.pack d) - txt = either (error . show) id $ P.runPure $ fmt pd - strToExp $ T.unpack txt + strToExp d where strToExp :: String -> Q Exp strToExp s = return $ VarE 'fromString `AppE` LitE (StringL s) - -embedManualHtml :: Q Exp -embedManualHtml = do - embedManual $ P.writeHtml5String P.def { P.writerHighlightStyle = Just pygments }
pandoc-plot.cabal view
@@ -1,6 +1,6 @@ cabal-version: 2.2 name: pandoc-plot -version: 0.7.2.1 +version: 0.8.0.0 synopsis: A Pandoc filter to include figures generated from code blocks using your plotting toolkit of choice. description: A Pandoc filter to include figures generated from code blocks. Keep the document and code in the same location. Output is captured and included as a figure. category: Text @@ -17,6 +17,8 @@ CHANGELOG.md LICENSE README.md + MANUAL.md + docs/MANUAL.html stack.yaml example-config.yml @@ -45,6 +47,8 @@ Text.Pandoc.Filter.Plot.Renderers.GGPlot2 Text.Pandoc.Filter.Plot.Renderers.GNUPlot Text.Pandoc.Filter.Plot.Renderers.Graphviz + Text.Pandoc.Filter.Plot.Renderers.Bokeh + Text.Pandoc.Filter.Plot.Renderers.Plotsjl Text.Pandoc.Filter.Plot.Monad Text.Pandoc.Filter.Plot.Monad.Logging Text.Pandoc.Filter.Plot.Monad.Types @@ -84,6 +88,7 @@ ghc-options: -Wall -Wcompat -threaded -rtsopts -with-rtsopts=-N build-depends: base >= 4.11 && <5 + , containers , directory , filepath , githash >= 0.1.3.0 && < 1
src/Text/Pandoc/Filter/Plot.hs view
@@ -25,7 +25,9 @@ * @octaveplot@ for GNU Octave plots; * @ggplot2@ for ggplot2-based R plots; * @gnuplot@ for gnuplot plots; -* @graphviz@ for Graphviz graphs. +* @graphviz@ for Graphviz graphs; +* @bokeh@ for Bokeh-based Python plots; +* @plotsjl@ for Plots.jl-based Julia plots; For example, in Markdown: @@ -82,6 +84,8 @@ -- * Determining available plotting toolkits , availableToolkits , unavailableToolkits + -- * Version information + , pandocPlotVersion -- * For testing and internal purposes ONLY , make , makeEither @@ -91,13 +95,15 @@ import Control.Concurrent.Async.Lifted (mapConcurrently) import Data.Text (Text, unpack) +import Data.Version (Version) +import Paths_pandoc_plot (version) + import Text.Pandoc.Definition (Pandoc(..), Block) import Text.Pandoc.Walk (walkM, Walkable) import Text.Pandoc.Filter.Plot.Internal - -- | Walk over an entire Pandoc document, transforming appropriate code blocks -- into figures. This function will operate on blocks in parallel if possible. -- @@ -127,6 +133,13 @@ -> a -- ^ Input block or document -> IO a makePlot conf = runPlotM conf . walkM make + + +-- | The version of the pandoc-plot package. +-- +-- @since 0.8.0.0 +pandocPlotVersion :: Version +pandocPlotVersion = version -- | Try to process the block with `pandoc-plot`. If a failure happens (or the block)
src/Text/Pandoc/Filter/Plot/Configuration.hs view
@@ -62,21 +62,26 @@ , ggplot2Preamble = mempty , gnuplotPreamble = mempty , graphvizPreamble = mempty + , bokehPreamble = mempty + , plotsjlPreamble = mempty - , matplotlibExe = if isWindows then "python" else "python3" + , matplotlibExe = python , matlabExe = "matlab" - , plotlyPythonExe = if isWindows then "python" else "python3" + , plotlyPythonExe = python , plotlyRExe = "Rscript" , mathematicaExe = "math" , octaveExe = "octave" , ggplot2Exe = "Rscript" , gnuplotExe = "gnuplot" , graphvizExe = "dot" + , bokehExe = python + , plotsjlExe = "julia" , matplotlibTightBBox = False , matplotlibTransparent = False } - + where + python = if isWindows then "python" else "python3" -- | Extact path to configuration from the metadata in a Pandoc document. -- The path to the configuration file should be under the @plot-configuration@ key. @@ -126,6 +131,8 @@ , _ggplot2Prec :: !GGPlot2Precursor , _gnuplotPrec :: !GNUPlotPrecursor , _graphvizPrec :: !GraphvizPrecursor + , _bokehPrec :: !BokehPrecursor + , _plotsjlPrec :: !PlotsjlPrecursor } defaultConfigPrecursor :: ConfigPrecursor @@ -148,6 +155,8 @@ , _ggplot2Prec = GGPlot2Precursor Nothing (ggplot2Exe defaultConfiguration) , _gnuplotPrec = GNUPlotPrecursor Nothing (gnuplotExe defaultConfiguration) , _graphvizPrec = GraphvizPrecursor Nothing (graphvizExe defaultConfiguration) + , _bokehPrec = BokehPrecursor Nothing (bokehExe defaultConfiguration) + , _plotsjlPrec = PlotsjlPrecursor Nothing (plotsjlExe defaultConfiguration) } @@ -170,6 +179,8 @@ data GGPlot2Precursor = GGPlot2Precursor {_ggplot2Preamble :: !(Maybe FilePath), _ggplot2Exe :: !FilePath} data GNUPlotPrecursor = GNUPlotPrecursor {_gnuplotPreamble :: !(Maybe FilePath), _gnuplotExe :: !FilePath} data GraphvizPrecursor = GraphvizPrecursor {_graphvizPreamble :: !(Maybe FilePath), _graphvizExe :: !FilePath} +data BokehPrecursor = BokehPrecursor {_bokehPreamble :: !(Maybe FilePath), _bokehExe :: !FilePath} +data PlotsjlPrecursor = PlotsjlPrecursor {_plotsjlPreamble :: !(Maybe FilePath), _plotsjlExe :: !FilePath} instance FromJSON LoggingPrecursor where parseJSON (Object v) = @@ -218,7 +229,15 @@ parseJSON (Object v) = GraphvizPrecursor <$> v .:? (tshow PreambleK) <*> v .:? (tshow ExecutableK) .!= (graphvizExe defaultConfiguration) parseJSON _ = fail $ mconcat ["Could not parse ", show Graphviz, " configuration."] +instance FromJSON BokehPrecursor where + parseJSON (Object v) = BokehPrecursor <$> v .:? (tshow PreambleK) <*> v .:? (tshow ExecutableK) .!= (bokehExe defaultConfiguration) + parseJSON _ = fail $ mconcat ["Could not parse ", show Bokeh, " configuration."] +instance FromJSON PlotsjlPrecursor where + parseJSON (Object v) = PlotsjlPrecursor <$> v .:? (tshow PreambleK) <*> v .:? (tshow ExecutableK) .!= (plotsjlExe defaultConfiguration) + parseJSON _ = fail $ mconcat ["Could not parse ", show Plotsjl, " configuration."] + + instance FromJSON ConfigPrecursor where parseJSON (Null) = return defaultConfigPrecursor -- In case of empty file parseJSON (Object v) = do @@ -240,6 +259,8 @@ _ggplot2Prec <- v .:? (cls GGPlot2) .!= _ggplot2Prec defaultConfigPrecursor _gnuplotPrec <- v .:? (cls GNUPlot) .!= _gnuplotPrec defaultConfigPrecursor _graphvizPrec <- v .:? (cls Graphviz) .!= _graphvizPrec defaultConfigPrecursor + _bokehPrec <- v .:? (cls Bokeh) .!= _bokehPrec defaultConfigPrecursor + _plotsjlPrec <- v .:? (cls Plotsjl) .!= _plotsjlPrec defaultConfigPrecursor return $ ConfigPrecursor{..} parseJSON _ = fail "Could not parse configuration." @@ -268,6 +289,8 @@ ggplot2Exe = _ggplot2Exe _ggplot2Prec gnuplotExe = _gnuplotExe _gnuplotPrec graphvizExe = _graphvizExe _graphvizPrec + bokehExe = _bokehExe _bokehPrec + plotsjlExe = _plotsjlExe _plotsjlPrec matplotlibPreamble <- readPreamble (_matplotlibPreamble _matplotlibPrec) matlabPreamble <- readPreamble (_matlabPreamble _matlabPrec) @@ -278,6 +301,8 @@ ggplot2Preamble <- readPreamble (_ggplot2Preamble _ggplot2Prec) gnuplotPreamble <- readPreamble (_gnuplotPreamble _gnuplotPrec) graphvizPreamble <- readPreamble (_graphvizPreamble _graphvizPrec) + bokehPreamble <- readPreamble (_bokehPreamble _bokehPrec) + plotsjlPreamble <- readPreamble (_plotsjlPreamble _plotsjlPrec) return Configuration{..} where
src/Text/Pandoc/Filter/Plot/Monad.hs view
@@ -114,7 +114,7 @@ debug $ mconcat [ "Running command\n" , " ", command, "\n" , "ended with exit code ", pack . show $ ec - , if processOutput /= mempty then " and output\n" <> " " <> processOutput else mempty + , if processOutput /= mempty then (" and output\n" <> " " <> processOutput) else mempty , "\n" ] return (ec, processOutput) @@ -159,6 +159,8 @@ , ggplot2Preamble :: !Script -- ^ The default preamble script for the GGPlot2 toolkit. , gnuplotPreamble :: !Script -- ^ The default preamble script for the gnuplot toolkit. , graphvizPreamble :: !Script -- ^ The default preamble script for the Graphviz toolkit. + , bokehPreamble :: !Script -- ^ The default preamble script for the Python/Bokeh toolkit. + , plotsjlPreamble :: !Script -- ^ The default preamble script for the Julia/Plots.jl toolkit. , matplotlibExe :: !FilePath -- ^ The executable to use to generate figures using the matplotlib toolkit. , matlabExe :: !FilePath -- ^ The executable to use to generate figures using the MATLAB toolkit. @@ -169,6 +171,8 @@ , ggplot2Exe :: !FilePath -- ^ The executable to use to generate figures using the GGPlot2 toolkit. , gnuplotExe :: !FilePath -- ^ The executable to use to generate figures using the gnuplot toolkit. , graphvizExe :: !FilePath -- ^ The executable to use to generate figures using the Graphviz toolkit. + , bokehExe :: !FilePath -- ^ The executable to use to generate figures using the Python/Bokeh toolkit. + , plotsjlExe :: !FilePath -- ^ The executable to use to generate figures using the Julia/Plots.jl toolkit. , matplotlibTightBBox :: !Bool -- ^ Whether or not to make Matplotlib figures tight by default. , matplotlibTransparent :: !Bool -- ^ Whether or not to make Matplotlib figures transparent by default.
src/Text/Pandoc/Filter/Plot/Monad/Types.hs view
@@ -58,6 +58,8 @@ | GGPlot2 | GNUPlot | Graphviz + | Bokeh + | Plotsjl deriving (Bounded, Eq, Enum, Generic) @@ -72,6 +74,8 @@ show GGPlot2 = "ggplot2" show GNUPlot = "gnuplot" show Graphviz = "graphviz" + show Bokeh = "Python/Bokeh" + show Plotsjl = "Julia/Plots.jl" -- | Class name which will trigger the filter @@ -85,6 +89,8 @@ cls GGPlot2 = "ggplot2" cls GNUPlot = "gnuplot" cls Graphviz = "graphviz" +cls Bokeh = "bokeh" +cls Plotsjl = "plotsjl" type Script = Text @@ -179,6 +185,7 @@ | GIF -- ^ GIF format | TIF -- ^ Tagged image format | WEBP -- ^ WebP image format + | HTML -- ^ HTML for interactive plots. deriving (Bounded, Enum, Eq, Show, Generic) instance IsString SaveFormat where @@ -194,6 +201,7 @@ | s `elem` ["jpg", "jpeg", "JPG", "JPEG", ".jpg", ".jpeg"] = JPG | s `elem` ["tif", "tiff", "TIF", "TIFF", ".tif", ".tiff"] = TIF | s `elem` ["webp", "WEBP", ".webp"] = WEBP + | s `elem` ["html", "HTML", ".html"] = HTML | otherwise = error $ mconcat [ s , " is not one of valid save format : "
src/Text/Pandoc/Filter/Plot/Renderers.hs view
@@ -30,25 +30,27 @@ , OutputSpec(..) ) where -import Control.Concurrent.Async.Lifted (forConcurrently) +import Control.Concurrent.Async.Lifted (forConcurrently) -import Data.List ((\\)) -import Data.Map.Strict (Map) -import Data.Maybe (catMaybes) -import Data.Text (Text) +import Data.List ((\\)) +import Data.Map.Strict (Map) +import Data.Maybe (catMaybes) +import Data.Text (Text) -import Text.Pandoc.Filter.Plot.Renderers.Mathematica -import Text.Pandoc.Filter.Plot.Renderers.Matlab -import Text.Pandoc.Filter.Plot.Renderers.Matplotlib -import Text.Pandoc.Filter.Plot.Renderers.Octave -import Text.Pandoc.Filter.Plot.Renderers.PlotlyPython -import Text.Pandoc.Filter.Plot.Renderers.PlotlyR -import Text.Pandoc.Filter.Plot.Renderers.GGPlot2 -import Text.Pandoc.Filter.Plot.Renderers.GNUPlot -import Text.Pandoc.Filter.Plot.Renderers.Graphviz -import Text.Pandoc.Filter.Plot.Renderers.Prelude (executable, OutputSpec(..)) +import Text.Pandoc.Filter.Plot.Renderers.Mathematica +import Text.Pandoc.Filter.Plot.Renderers.Matlab +import Text.Pandoc.Filter.Plot.Renderers.Matplotlib +import Text.Pandoc.Filter.Plot.Renderers.Octave +import Text.Pandoc.Filter.Plot.Renderers.PlotlyPython +import Text.Pandoc.Filter.Plot.Renderers.PlotlyR +import Text.Pandoc.Filter.Plot.Renderers.GGPlot2 +import Text.Pandoc.Filter.Plot.Renderers.GNUPlot +import Text.Pandoc.Filter.Plot.Renderers.Graphviz +import Text.Pandoc.Filter.Plot.Renderers.Bokeh +import Text.Pandoc.Filter.Plot.Renderers.Plotsjl +import Text.Pandoc.Filter.Plot.Renderers.Prelude (executable, OutputSpec(..)) -import Text.Pandoc.Filter.Plot.Monad +import Text.Pandoc.Filter.Plot.Monad -- Extension for script files, e.g. ".py", or ".m". @@ -62,6 +64,8 @@ scriptExtension GGPlot2 = ".r" scriptExtension GNUPlot = ".gp" scriptExtension Graphviz = ".dot" +scriptExtension Bokeh = ".py" +scriptExtension Plotsjl = ".jl" -- Make a string into a comment @@ -75,6 +79,8 @@ comment GGPlot2 = mappend "# " comment GNUPlot = mappend "# " comment Graphviz = mappend "// " +comment Bokeh = mappend "# " +comment Plotsjl = mappend "# " -- | The function that maps from configuration to the preamble. @@ -88,6 +94,8 @@ preambleSelector GGPlot2 = ggplot2Preamble preambleSelector GNUPlot = gnuplotPreamble preambleSelector Graphviz = graphvizPreamble +preambleSelector Bokeh = bokehPreamble +preambleSelector Plotsjl = plotsjlPreamble -- | Save formats supported by this renderer. @@ -101,6 +109,8 @@ supportedSaveFormats GGPlot2 = ggplot2SupportedSaveFormats supportedSaveFormats GNUPlot = gnuplotSupportedSaveFormats supportedSaveFormats Graphviz = graphvizSupportedSaveFormats +supportedSaveFormats Bokeh = bokehSupportedSaveFormats +supportedSaveFormats Plotsjl = plotsjlSupportedSaveFormats -- Checks to perform before running a script. If ANY check fails, @@ -108,6 +118,7 @@ -- blocking operations to occur. scriptChecks :: Toolkit -> [Script -> CheckResult] scriptChecks Matplotlib = [matplotlibCheckIfShow] +scriptChecks Bokeh = [bokehCheckIfShow] scriptChecks _ = mempty @@ -132,6 +143,8 @@ command GGPlot2 = ggplot2Command command GNUPlot = gnuplotCommand command Graphviz = graphvizCommand +command Bokeh = bokehCommand +command Plotsjl = plotsjlCommand -- | Script fragment required to capture a figure. @@ -145,6 +158,8 @@ capture GGPlot2 = ggplot2Capture capture GNUPlot = gnuplotCapture capture Graphviz = graphvizCapture +capture Bokeh = bokehCapture +capture Plotsjl = plotsjlCapture -- | Check if a toolkit is available, based on the current configuration @@ -158,6 +173,8 @@ toolkitAvailable GGPlot2 = ggplot2Available toolkitAvailable GNUPlot = gnuplotAvailable toolkitAvailable Graphviz = graphvizAvailable +toolkitAvailable Bokeh = bokehAvailable +toolkitAvailable Plotsjl = plotsjlAvailable -- | List of toolkits available on this machine.
+ src/Text/Pandoc/Filter/Plot/Renderers/Bokeh.hs view
@@ -0,0 +1,73 @@+{-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE RecordWildCards #-} +{-| +Module : $header$ +Copyright : (c) Laurent P René de Cotret, 2020 +License : GNU GPL, version 2 or above +Maintainer : laurent.decotret@outlook.com +Stability : internal +Portability : portable + +Rendering Bokeh code blocks +-} + +module Text.Pandoc.Filter.Plot.Renderers.Bokeh ( + bokehSupportedSaveFormats + , bokehCommand + , bokehCapture + , bokehAvailable + , bokehCheckIfShow +) where + +import Data.Monoid (Any(..)) +import qualified Data.Text as T +import Text.Pandoc.Filter.Plot.Renderers.Prelude + + +bokehSupportedSaveFormats :: [SaveFormat] +bokehSupportedSaveFormats = [PNG, HTML] + + +bokehCommand :: OutputSpec -> PlotM Text +bokehCommand OutputSpec{..} = do + exe <- executable Bokeh + return [st|#{exe} "#{oScriptPath}"|] + + +bokehAvailable :: PlotM Bool +bokehAvailable = do + exe <- executable Bokeh + commandSuccess [st|#{exe} -c "import bokeh; import selenium"|] + + +-- | Check if `matplotlib.pyplot.show()` calls are present in the script, +-- which would halt pandoc-plot +bokehCheckIfShow :: Script -> CheckResult +bokehCheckIfShow s = + if getAny $ mconcat showPresent + then CheckFailed "encountered a call to `bokeh.io.show`." + else CheckPassed + where + showPresent = (\n -> Any (T.isInfixOf n s)) <$> [ + "bokeh.io.show(" + , "show(" + ] + + +-- TODO: should we capture a Document instead of a Plot? +-- For some reason, saving the current document was not working +bokehCapture :: FigureSpec -> FilePath -> Script +bokehCapture FigureSpec{..} fname = [st| +from bokeh.io import export_png, export_svgs, save +from bokeh.models import Plot +from bokeh.resources import INLINE +__current_plot = next(obj for obj in globals().values() if isinstance(obj, Plot)) +#{write} +|] + where + write = case saveFormat of + HTML -> [st|save(__current_plot, filename=r"#{fname}", resources=INLINE)|] + PNG -> [st|export_png(obj = __current_plot, filename=r"#{fname}")|] + fmt -> error $ "Save format not supported: " <> show fmt
src/Text/Pandoc/Filter/Plot/Renderers/PlotlyPython.hs view
@@ -24,7 +24,7 @@ plotlyPythonSupportedSaveFormats :: [SaveFormat] -plotlyPythonSupportedSaveFormats = [PNG, JPG, WEBP, PDF, SVG, EPS] +plotlyPythonSupportedSaveFormats = [PNG, JPG, WEBP, PDF, SVG, EPS, HTML] plotlyPythonCommand :: OutputSpec -> PlotM Text @@ -40,8 +40,15 @@ plotlyPythonCapture :: FigureSpec -> FilePath -> Script -plotlyPythonCapture _ fname = [st| +plotlyPythonCapture FigureSpec{..} fname = [st| import plotly.graph_objects as go __current_plotly_figure = next(obj for obj in globals().values() if type(obj) == go.Figure) -__current_plotly_figure.write_image(r"#{fname}") +__current_plotly_figure.#{write_method}(r"#{fname}") |] + where + -- Note: the default behaviour for HTML export is + -- to embed the entire Plotly.js content. This means + -- that the resulting file can be used completely offline + write_method = case saveFormat of + HTML -> "write_html"::Text + _ -> "write_image"::Text
src/Text/Pandoc/Filter/Plot/Renderers/PlotlyR.hs view
@@ -24,7 +24,7 @@ plotlyRSupportedSaveFormats :: [SaveFormat] -plotlyRSupportedSaveFormats = [PNG, PDF, SVG, JPG, EPS] +plotlyRSupportedSaveFormats = [PNG, PDF, SVG, JPG, EPS, HTML] plotlyRCommand :: OutputSpec -> PlotM Text @@ -39,10 +39,27 @@ commandSuccess [st|#{exe} -e 'library("plotly")'|] +plotlyRCapture :: FigureSpec -> FilePath -> Script +plotlyRCapture spec@FigureSpec{..} fname = case saveFormat of + HTML -> plotlyRCaptureHtml spec fname + _ -> plotlyRCaptureStatic spec fname + + +-- Based on the following discussion: +-- https://stackoverflow.com/q/34580095 +plotlyRCaptureHtml :: FigureSpec -> FilePath -> Script +plotlyRCaptureHtml _ fname = [st| +library(plotly) # just in case +library(htmlwidgets) +p <- last_plot() +htmlwidgets::saveWidget(as_widget(p), "#{fname}") +|] + + -- Based on the following documentation: -- https://plotly.com/r/static-image-export/ -plotlyRCapture :: FigureSpec -> FilePath -> Script -plotlyRCapture _ fname = [st| +plotlyRCaptureStatic :: FigureSpec -> FilePath -> Script +plotlyRCaptureStatic _ fname = [st| library(plotly) # just in case if (!require("processx")) install.packages("processx") orca(last_plot(), file = "#{fname}")
+ src/Text/Pandoc/Filter/Plot/Renderers/Plotsjl.hs view
@@ -0,0 +1,47 @@+{-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE RecordWildCards #-} +{-| +Module : $header$ +Copyright : (c) Laurent P René de Cotret, 2020 +License : GNU GPL, version 2 or above +Maintainer : laurent.decotret@outlook.com +Stability : internal +Portability : portable + +Rendering Julia/Plots.jl code blocks +-} + +module Text.Pandoc.Filter.Plot.Renderers.Plotsjl ( + plotsjlSupportedSaveFormats + , plotsjlCommand + , plotsjlCapture + , plotsjlAvailable +) where + +import Text.Pandoc.Filter.Plot.Renderers.Prelude + + +-- Save formats support by most backends +-- https://docs.plotsjl.org/latest/output/#Supported-output-file-formats-1 +plotsjlSupportedSaveFormats :: [SaveFormat] +plotsjlSupportedSaveFormats = [PNG, SVG, PDF] + + +plotsjlCommand :: OutputSpec -> PlotM Text +plotsjlCommand OutputSpec{..} = do + exe <- executable Plotsjl + return [st|#{exe} "#{oScriptPath}"|] + + +plotsjlAvailable :: PlotM Bool +plotsjlAvailable = do + exe <- executable Plotsjl + commandSuccess [st|#{exe} -e "using Plots"|] + + +plotsjlCapture :: FigureSpec -> FilePath -> Script +plotsjlCapture _ fname = [st| +savefig(raw"#{fname}") +|]
src/Text/Pandoc/Filter/Plot/Renderers/Prelude.hs view
@@ -9,7 +9,6 @@ Prelude for renderers, containing some helpful utilities. -} - module Text.Pandoc.Filter.Plot.Renderers.Prelude ( module Prelude @@ -65,6 +64,8 @@ executable GGPlot2 = asksConfig ggplot2Exe >>= liftIO . tryToFindExe executable GNUPlot = asksConfig gnuplotExe >>= liftIO . tryToFindExe executable Graphviz = asksConfig graphvizExe >>= liftIO . tryToFindExe +executable Bokeh = asksConfig bokehExe >>= liftIO . tryToFindExe +executable Plotsjl = asksConfig plotsjlExe >>= liftIO . tryToFindExe -- | Internal description of all information
src/Text/Pandoc/Filter/Plot/Scripting.hs view
@@ -126,13 +126,23 @@ -- must be "fig:" -- Janky? yes where - attrs' = blockAttrs spec + attrs' = withInteractiveAttrs $ blockAttrs spec target' = figurePath spec withSource' = withSource spec srcLink = link (pack $ replaceExtension target' ".txt") mempty "Source code" captionText = fromList $ fromMaybe mempty (captionReader fmt $ caption spec) captionLinks = mconcat [" (", srcLink, ")"] caption' = if withSource' then captionText <> captionLinks else captionText + -- for HTML plots, pandoc will replace the <img> tag with an <embed> tag + -- We include extra attributes with the <embed> tag in mind. + -- TODO: find way to have HTML "figure" full-width without hardcoding width + withInteractiveAttrs (a, b, c) = + if saveFormat spec == HTML + then (a, b, c <> [ ("type", "text/html") + , ("width", "600") + , ("height", "600") + ]) + else (a, b, c) -- | Determine the temp script path from Figure specifications
stack.yaml view
@@ -7,7 +7,11 @@ - pandoc-2.10 - hslua-1.1.2@sha256:6c231b2af447430d1ed04f065d40bb6882ece93cc7f32f4051dc99deb69beeae,9694 - jira-wiki-markup-1.3.2@sha256:b5f0901208a0ee07aff60f5356aeb851b7aa7950c75a18a15fd34247a35886d8,3819 - +# For development +- git: https://github.com/LaurentRDC/pandoc-include-code.git + commit: 162ae92edc80601bde8450bf933c0127e8c2b53a +- ghc-check-0.3.0.1@sha256:651d9b2b75a5cbdb3c942117801bfa566079bcaf20360e4d0959f9e575c30b39,1070 + # Faster compilation. # See here: # https://downloads.haskell.org/ghc/latest/docs/html/users_guide/flags.html#miscellaneous-compiler-options
tests/Common.hs view
@@ -9,6 +9,7 @@ import Data.Monoid ((<>)) import Data.String (fromString) import Data.Text (Text, pack, unpack) +import qualified Data.Text as T import Test.Tasty import Test.Tasty.HUnit @@ -72,6 +73,8 @@ include GGPlot2 = "tests/includes/ggplot2.r" include GNUPlot = "tests/includes/gnuplot.gp" include Graphviz = "tests/includes/graphviz.dot" + include Bokeh = "tests/includes/bokeh.py" + include Plotsjl = "tests/includes/plotsjl.jl" ------------------------------------------------------------------------------- -- Test that the files are saved in the appropriate format @@ -266,6 +269,11 @@ trivialContent GGPlot2 = "library(ggplot2)\nggplot()\n" trivialContent GNUPlot = "plot sin(x)" trivialContent Graphviz = "digraph {A -> B [label=\"test\"];}" +trivialContent Bokeh = T.unlines [ "from bokeh.plotting import figure" + , "p = figure(title='simple line example')" + , "p.line([1,2,3,4], [5,6,7,8])" + ] +trivialContent Plotsjl = "using Plots; x = 1:10; y = rand(10); plot(x, y);" addCaption :: String -> Block -> Block
tests/Main.hs view
@@ -75,6 +75,7 @@ -- even on other OSes let config = defaultConfiguration { matplotlibExe = "python" , plotlyPythonExe = "python" + , bokehExe = "python" } parsedConfig <- configuration "example-config.yml"