summaryrefslogtreecommitdiff
path: root/src/Text/Pandoc/Filter/Plot.hs
diff options
context:
space:
mode:
Diffstat (limited to 'src/Text/Pandoc/Filter/Plot.hs')
-rw-r--r--src/Text/Pandoc/Filter/Plot.hs62
1 files changed, 35 insertions, 27 deletions
diff --git a/src/Text/Pandoc/Filter/Plot.hs b/src/Text/Pandoc/Filter/Plot.hs
index 0a7e5a3..d2bd2a4 100644
--- a/src/Text/Pandoc/Filter/Plot.hs
+++ b/src/Text/Pandoc/Filter/Plot.hs
@@ -8,11 +8,11 @@ Maintainer : laurent.decotret@outlook.com
Stability : unstable
Portability : portable
-This module defines a Pandoc filter @makePlot@ and related functions
+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.
+code blocks, using a multitude of plotting toolkits.
-The syntax for code blocks is simple, Code blocks with the appropriate class
+The syntax for code blocks is simple. Code blocks with the appropriate class
attribute will trigger the filter:
* @matplotlib@ for matplotlib-based Python plots;
@@ -23,6 +23,17 @@ attribute will trigger the filter:
* @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.
@@ -31,7 +42,7 @@ 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.
+ * @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.
@@ -41,7 +52,7 @@ 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"}
+ ```{.gnuplot format=png caption="Sinusoidal function" source=true}
sin(x)
set xlabel "x"
@@ -54,13 +65,16 @@ module Text.Pandoc.Filter.Plot (
makePlot
-- * Operating on whole Pandoc documents
, plotTransform
+ -- * Cleaning output directories
+ , cleanOutputDirs
-- * Runtime configuration
, configuration
, Configuration(..)
, SaveFormat(..)
, Script
- -- * For testing purposes ONLY
+ -- * For testing and internal purposes ONLY
, make
+ , readDoc
, availableToolkits
, unavailableToolkits
) where
@@ -77,11 +91,12 @@ import Text.Pandoc.Filter.Plot.Internal
-- | Highest-level function that can be walked over a Pandoc tree.
--- All code blocks that have the @.plot@ / @.plotly@ class will be considered
--- figures.
+-- All code blocks that have the appropriate class names will be considered
+-- figures, e.g. @.matplotlib@.
--
--- 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 @$...$@,
+-- 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.
makePlot :: Configuration -- ^ Configuration for default values
-> Block
-> IO Block
@@ -89,7 +104,11 @@ makePlot conf block = maybe (return block) (\tk -> make tk conf block) (plotTool
-- | Walk over an entire Pandoc document, changing appropriate code blocks
--- into figures. Default configuration is used.
+-- into figures.
+--
+-- 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.
plotTransform :: Configuration -- ^ Configuration for default values
-> Pandoc -- ^ Input document
-> IO Pandoc
@@ -116,22 +135,11 @@ make tk conf block = runReaderT (makePlot' block) (PlotEnv tk conf)
where
handleResult spec ScriptSuccess = return $ toImage (captionFormat conf) spec
handleResult _ (ScriptChecksFailed msg) = do
- liftIO $ hPutStrLn stderr $ "pandoc-plot: The script check failed with message: " <> msg
+ liftIO $ hPutStrLn stderr $ " ERROR (pandoc-plot) The script check failed with message: " <> msg
return blk
handleResult _ (ScriptFailure _ code) = do
- liftIO $ hPutStrLn stderr $ "pandoc-plot: The script failed with exit code " <> show code
+ liftIO $ hPutStrLn stderr $ "ERROR (pandoc-plot) The script failed with exit code " <> show code
return blk
-
-
--- | Possible errors returned by the filter
-data PandocPlotError
- = ScriptError String Int -- ^ Running script has yielded an error
- | ScriptChecksFailedError String -- ^ Script did not pass all checks
- deriving (Eq)
-
-instance Show PandocPlotError where
- show (ScriptError cmd exitcode) = mconcat [ "Script error: plot could not be generated.\n"
- , " Command: ", cmd, "\n"
- , " Exit code " <> (show exitcode)
- ]
- show (ScriptChecksFailedError msg) = "Script did not pass all checks: " <> msg \ No newline at end of file
+ handleResult _ (ToolkitNotInstalled tk') = do
+ liftIO $ hPutStrLn stderr $ "ERROR (pandoc-plot) The " <> show tk' <> " toolkit is required but not installed."
+ return blk \ No newline at end of file