| Copyright | (c) Laurent P René de Cotret 2020 |
|---|---|
| License | GNU GPL, version 2 or above |
| Maintainer | laurent.decotret@outlook.com |
| Stability | unstable |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Text.Pandoc.Filter.Plot
Contents
Description
This module defines a Pandoc filter makePlot and related functions
that can be used to walk over a Pandoc document and generate figures from
code blocks using a multitude of plotting toolkits.
The syntax for code blocks is simple, Code blocks with the appropriate class attribute will trigger the filter:
matplotlibfor matplotlib-based Python plots;plotly_pythonfor Plotly-based Python plots;matlabplotfor MATLAB plots;mathplotfor Mathematica plots;octaveplotfor GNU Octave plots;ggplot2for ggplot2-based R plots;gnuplotfor gnuplot plots;
The code block will be reworked into a script and the output figure will be captured. Optionally, the source code used to generate the figure will be linked in the caption.
Here are the possible attributes what pandoc-plot understands for ALL toolkits:
directory=...: Directory where to save the figure.source=true|false: Whether or not to link the source code of this figure in the caption. Ideal for web pages, for example. Default is false.format=...: Format of the generated figure. This can be an extension or an acronym, e.g.format=PNG.caption="...": Specify a plot caption (or alternate text). Captions should be formatted in Markdown, with LaTeX math.dpi=...: Specify a value for figure resolution, or dots-per-inch. Certain toolkits ignore this.preamble=...: Path to a file to include before the code block. Ideal to avoid repetition over many figures.
Default values for the above attributes are stored in the Configuration datatype. These can be specified in a
YAML file which must be named ".pandoc-plot.yml".
Here is an example code block which will render a figure using gnuplot, in Markdown:
```{.gnuplot format=png caption="Sinusoidal function"}
sin(x)
set xlabel "x"
set ylabel "y"
```
Synopsis
- makePlot :: Configuration -> Block -> IO Block
- plotTransform :: Configuration -> Pandoc -> IO Pandoc
- configuration :: FilePath -> IO Configuration
- data Configuration = Configuration {
- defaultDirectory :: !FilePath
- defaultWithSource :: !Bool
- defaultDPI :: !Int
- defaultSaveFormat :: !SaveFormat
- captionFormat :: Format
- matplotlibPreamble :: !Script
- plotlyPythonPreamble :: !Script
- matlabPreamble :: !Script
- mathematicaPreamble :: !Script
- octavePreamble :: !Script
- ggplot2Preamble :: !Script
- gnuplotPreamble :: !Script
- matplotlibExe :: !FilePath
- matlabExe :: !FilePath
- plotlyPythonExe :: !FilePath
- mathematicaExe :: !FilePath
- octaveExe :: !FilePath
- ggplot2Exe :: !FilePath
- gnuplotExe :: !FilePath
- matplotlibTightBBox :: !Bool
- matplotlibTransparent :: !Bool
- data SaveFormat
- type Script = Text
- make :: Toolkit -> Configuration -> Block -> IO Block
- availableToolkits :: Configuration -> IO [Toolkit]
- unavailableToolkits :: Configuration -> IO [Toolkit]
Operating on single Pandoc blocks
Arguments
| :: Configuration | Configuration for default values |
| -> Block | |
| -> IO Block |
Highest-level function that can be walked over a Pandoc tree.
All code blocks that have the .plot / .plotly class will be considered
figures.
The target document format determines how the figure captions should be parsed.
By default (i.e. if Nothing), captions will be parsed as Markdown with LaTeX math $...$,
Operating on whole Pandoc documents
Arguments
| :: Configuration | Configuration for default values |
| -> Pandoc | Input document |
| -> IO Pandoc |
Walk over an entire Pandoc document, changing appropriate code blocks into figures. Default configuration is used.
Runtime configuration
configuration :: FilePath -> IO Configuration Source #
Read configuration from a YAML file. The keys are exactly the same as for code blocks.
If a key is either not present, its value will be set to the default value. Parsing errors result in thrown exceptions.
data Configuration Source #
The Configuration type holds the default values to use
when running pandoc-plot. These values can be overridden in code blocks.
Constructors
| Configuration | |
Fields
| |
Instances
| Eq Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Types Methods (==) :: Configuration -> Configuration -> Bool # (/=) :: Configuration -> Configuration -> Bool # | |
| Show Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Types Methods showsPrec :: Int -> Configuration -> ShowS # show :: Configuration -> String # showList :: [Configuration] -> ShowS # | |
| Default Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Types Methods def :: Configuration # | |
data SaveFormat Source #
Generated figure file format supported by pandoc-plot. Note that not all formats are supported by all toolkits.
Instances
For testing purposes ONLY
Arguments
| :: Toolkit | Plotting toolkit. |
| -> Configuration | Configuration for default values. |
| -> Block | |
| -> IO Block |
Force to use a particular toolkit to render appropriate code blocks.
Failing to render a figure does not stop the filter, so that you may run the filter on documents without having all necessary toolkits installed. In this case, error messages are printed to stderr, and blocks are left unchanged.
availableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits available on this machine. The executables to look for are taken from the configuration.
unavailableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits not available on this machine. The executables to look for are taken from the configuration.