Text.Pandoc.Filter.Plot

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;
• matlabplot for MATLAB plots;
• mathplot for Mathematica plots;
• octaveplot for GNU Octave plots;
• ggplot2 for ggplot2-based R plots;
• gnuplot for gnuplot 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 the Configuration 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"
    ```

Operating on single Pandoc blocks

makePlot

Arguments

:: 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

plotTransform

Arguments

:: 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]

Clean all output related to pandoc-plot. This includes output directories specified in the configuration and in the document/block. Note that *all* files in pandoc-plot output directories will be removed.

The cleaned directories are returned.

Runtime configuration

configuration :: FilePath -> IO Configuration

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

Default configuration values.

Since: 0.5.0.0

data Configuration

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: pathto/file.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.

Constructors

Configuration

Fields

• defaultDirectory :: !FilePath

  The default directory where figures will be saved.

• defaultWithSource :: !Bool

  The default behavior of whether or not to include links to source code and high-res

• defaultDPI :: !Int

  The default dots-per-inch value for generated figures. Renderers might ignore this.

• defaultSaveFormat :: !SaveFormat

  The default save format of generated figures.

• captionFormat :: !Format

  Caption format, in the same notation as Pandoc format, e.g. "markdown+tex_math_dollars"

• matplotlibPreamble :: !Script

  The default preamble script for the matplotlib toolkit.

• plotlyPythonPreamble :: !Script

  The default preamble script for the Plotly/Python toolkit.

• plotlyRPreamble :: !Script

  The default preamble script for the Plotly/R toolkit.

• matlabPreamble :: !Script

  The default preamble script for the MATLAB toolkit.

• mathematicaPreamble :: !Script

  The default preamble script for the Mathematica toolkit.

• octavePreamble :: !Script

  The default preamble script for the GNU Octave toolkit.

• 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.

• 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.

• plotlyPythonExe :: !FilePath

  The executable to use to generate figures using the Plotly/Python toolkit.

• plotlyRExe :: !FilePath

  The executable to use to generate figures using the Plotly/R toolkit.

• mathematicaExe :: !FilePath

  The executable to use to generate figures using the Mathematica toolkit.

• octaveExe :: !FilePath

  The executable to use to generate figures using the GNU Octave toolkit.

• 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.

• matplotlibTightBBox :: !Bool

  Whether or not to make Matplotlib figures tight by default.

• matplotlibTransparent :: !Bool

  Whether or not to make Matplotlib figures transparent by default.

Instances

Eq Configuration

Defined in Text.Pandoc.Filter.Plot.Types

Methods

(==) :: Configuration -> Configuration -> Bool

(/=) :: Configuration -> Configuration -> Bool

Show Configuration

Defined in Text.Pandoc.Filter.Plot.Types

Methods

showsPrec :: Int -> Configuration -> ShowS

show :: Configuration -> String

showList :: [Configuration] -> ShowS

Default Configuration

Defined in Text.Pandoc.Filter.Plot.Types

Methods

def :: Configuration

data SaveFormat

Generated figure file format supported by pandoc-plot. Note that not all formats are supported by all toolkits.

Constructors

PNG

PDF

SVG

JPG

EPS

GIF

TIF

WEBP

Instances

Bounded SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

minBound :: SaveFormat

maxBound :: SaveFormat

Enum SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

succ :: SaveFormat -> SaveFormat

pred :: SaveFormat -> SaveFormat

toEnum :: Int -> SaveFormat

fromEnum :: SaveFormat -> Int

enumFrom :: SaveFormat -> [SaveFormat]

enumFromThen :: SaveFormat -> SaveFormat -> [SaveFormat]

enumFromTo :: SaveFormat -> SaveFormat -> [SaveFormat]

enumFromThenTo :: SaveFormat -> SaveFormat -> SaveFormat -> [SaveFormat]

Eq SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

(==) :: SaveFormat -> SaveFormat -> Bool

(/=) :: SaveFormat -> SaveFormat -> Bool

Show SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

showsPrec :: Int -> SaveFormat -> ShowS

show :: SaveFormat -> String

showList :: [SaveFormat] -> ShowS

IsString SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

fromString :: String -> SaveFormat

Generic SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Associated Types

type Rep SaveFormat :: Type -> Type

Methods

from :: SaveFormat -> Rep SaveFormat x

to :: Rep SaveFormat x -> SaveFormat

ToJSON SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

toJSON :: SaveFormat -> Value

toEncoding :: SaveFormat -> Encoding

toJSONList :: [SaveFormat] -> Value

toEncodingList :: [SaveFormat] -> Encoding

FromJSON SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

Methods

parseJSON :: Value -> Parser SaveFormat

parseJSONList :: Value -> Parser [SaveFormat]

type Rep SaveFormat

Defined in Text.Pandoc.Filter.Plot.Types

type Rep SaveFormat = D1 (MetaData "SaveFormat" "Text.Pandoc.Filter.Plot.Types" "pandoc-plot-0.6.0.0-8E8gm0do5Mp1YT6dYBbPxl" False) (((C1 (MetaCons "PNG" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "PDF" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "SVG" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "JPG" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "EPS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "GIF" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "TIF" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "WEBP" PrefixI False) (U1 :: Type -> Type))))

type Script = Text

For testing and internal purposes ONLY

make

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.

make' :: Toolkit -> Configuration -> Block -> IO (Either PandocPlotError Block)

data PandocPlotError

Constructors

ScriptRuntimeError String Int

ScriptChecksFailedError String

ToolkitNotInstalledError Toolkit

Instances

Show PandocPlotError

Defined in Text.Pandoc.Filter.Plot

Methods

showsPrec :: Int -> PandocPlotError -> ShowS

show :: PandocPlotError -> String

showList :: [PandocPlotError] -> ShowS

readDoc :: FilePath -> IO Pandoc

Read document, guessing what extensions and reader options are appropriate. If the file cannot be read for any reason, an error is thrown.

availableToolkits :: Configuration -> IO [Toolkit]

List of toolkits available on this machine. The executables to look for are taken from the configuration.

unavailableToolkits :: Configuration -> IO [Toolkit]

List of toolkits not available on this machine. The executables to look for are taken from the configuration.