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 |
This module defines a Pandoc filter plotTransform
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:
matplotlib
for matplotlib-based Python plots;plotly_python
for Plotly-based Python plots;plotly_r
for Plotly-based R plots;matlabplot
for MATLAB plots;mathplot
for Mathematica plots;octaveplot
for GNU Octave plots;ggplot2
for ggplot2-based R plots;gnuplot
for gnuplot plots;graphviz
for Graphviz graphs;bokeh
for Bokeh-based Python plots;plotsjl
for Plots.jl-based Julia plots;
For example, in Markdown:
This is a paragraph. ```{.matlabplot} figure() plot([1,2,3,4,5], [1,2,3,4,5], '-k') ```
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). Format for captions is specified in the documentation for theConfiguration
type.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.
Here is an example code block which will render a figure using gnuplot, in Markdown:
```{.gnuplot format=png caption="Sinusoidal function" source=true} sin(x) set xlabel "x" set ylabel "y" ```
Synopsis
- makePlot :: Walkable Block a => Configuration -> a -> IO a
- plotTransform :: Configuration -> Pandoc -> IO Pandoc
- cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath]
- configuration :: FilePath -> IO Configuration
- defaultConfiguration :: Configuration
- data Configuration = Configuration {
- defaultDirectory :: !FilePath
- defaultWithSource :: !Bool
- defaultDPI :: !Int
- defaultSaveFormat :: !SaveFormat
- captionFormat :: !Format
- logVerbosity :: !Verbosity
- logSink :: !LogSink
- matplotlibPreamble :: !Script
- plotlyPythonPreamble :: !Script
- plotlyRPreamble :: !Script
- matlabPreamble :: !Script
- mathematicaPreamble :: !Script
- octavePreamble :: !Script
- ggplot2Preamble :: !Script
- gnuplotPreamble :: !Script
- graphvizPreamble :: !Script
- bokehPreamble :: !Script
- plotsjlPreamble :: !Script
- matplotlibExe :: !FilePath
- matlabExe :: !FilePath
- plotlyPythonExe :: !FilePath
- plotlyRExe :: !FilePath
- mathematicaExe :: !FilePath
- octaveExe :: !FilePath
- ggplot2Exe :: !FilePath
- gnuplotExe :: !FilePath
- graphvizExe :: !FilePath
- bokehExe :: !FilePath
- plotsjlExe :: !FilePath
- matplotlibTightBBox :: !Bool
- matplotlibTransparent :: !Bool
- data Verbosity
- data LogSink
- data SaveFormat
- type Script = Text
- availableToolkits :: Configuration -> IO [Toolkit]
- unavailableToolkits :: Configuration -> IO [Toolkit]
- pandocPlotVersion :: Version
- make :: Block -> PlotM Block
- makeEither :: Block -> PlotM (Either PandocPlotError Block)
- data PandocPlotError
- readDoc :: FilePath -> IO Pandoc
Operating on single Pandoc blocks
:: Walkable Block a | |
=> Configuration | Configuration for default values |
-> a | Input block or document |
-> IO a |
Highest-level function that can be walked over a Pandoc tree.
All code blocks that have the appropriate class names will be considered
figures, e.g. .matplotlib
.
This function can be made to operation on whole Pandoc
documents. However,
you should prefer the plotTransform
function for whole documents, as it
is optimized for parallel operations.
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.
Operating on whole Pandoc documents
:: Configuration | Configuration for default values |
-> Pandoc | Input document |
-> IO Pandoc |
Walk over an entire Pandoc document, transforming appropriate code blocks into figures. This function will operate on blocks in parallel if possible.
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.
Cleaning output directories
cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath] Source #
Clean all output related to pandoc-plot. This includes output directories specified in the configuration and in the document/block, as well as log files. Note that *all* files in pandoc-plot output directories will be removed.
The cleaned directories are returned.
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 not present, its value will be set to the default value. Parsing errors result in thrown exceptions.
defaultConfiguration :: Configuration Source #
Default configuration values.
Since: 0.5.0.0
data Configuration Source #
The Configuration
type holds the default values to use
when running pandoc-plot. These values can be overridden in code blocks.
You can create an instance of the Configuration
type from file using the configuration
function.
You can store the path to a configuration file in metadata under the key plot-configuration
. For example, in Markdown:
--- title: My document author: John Doe plot-configuration: pathtofile.yml ---
The same can be specified via the command line using Pandoc's -M
flag:
pandoc --filter pandoc-plot -M plot-configuration="path/to/file.yml" ...
In this case, use configurationPathMeta
to extact the path from Pandoc
documents.
Configuration | |
|
Instances
Eq Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad (==) :: Configuration -> Configuration -> Bool # (/=) :: Configuration -> Configuration -> Bool # | |
Show Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad showsPrec :: Int -> Configuration -> ShowS # show :: Configuration -> String # showList :: [Configuration] -> ShowS # |
Verbosity of the logger.
Debug | Log all messages, including debug messages. |
Info | Log information, warning, and error messages. |
Warning | Log warning and error messages. |
Error | Only log errors. |
Silent | Don't log anything. |
Description of the possible ways to sink log messages.
data SaveFormat Source #
Generated figure file format supported by pandoc-plot. Note that not all formats are supported by all toolkits.
PNG | Portable network graphics |
Portable document format | |
SVG | Scalable vector graphics |
JPG | JPEG/JPG compressed image |
EPS | Encapsulated postscript |
GIF | GIF format |
TIF | Tagged image format |
WEBP | WebP image format |
HTML | HTML for interactive plots. |
Instances
Determining available plotting toolkits
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 configur
Version information
pandocPlotVersion :: Version Source #
The version of the pandoc-plot package.
Since: 0.8.0.0
For testing and internal purposes ONLY
make :: Block -> PlotM Block Source #
Try to process the block with `pandoc-plot`. If a failure happens (or the block) was not meant to become a figure, return the block as-is.
makeEither :: Block -> PlotM (Either PandocPlotError Block) Source #
Try to process the block with `pandoc-plot`, documenting the error.
data PandocPlotError Source #
Instances
Show PandocPlotError Source # | |
Defined in Text.Pandoc.Filter.Plot showsPrec :: Int -> PandocPlotError -> ShowS # show :: PandocPlotError -> String # showList :: [PandocPlotError] -> ShowS # |