summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLaurentRDC <>2020-01-23 18:41:00 (GMT)
committerhdiff <hdiff@hdiff.luite.com>2020-01-23 18:41:00 (GMT)
commit601cd3ff6362b106496aa5196e7abd4502047bb6 (patch)
treeb3dab2b147af15ee72dcf2eb8fbc606e33abbd38
parent314ccbe9380ebd0d6eba8c3e9ad4aa936a3f63b9 (diff)
version 0.2.1.00.2.1.0
-rw-r--r--CHANGELOG.md6
-rw-r--r--README.md19
-rw-r--r--pandoc-plot.cabal2
-rw-r--r--src/Text/Pandoc/Filter/Plot.hs30
-rw-r--r--src/Text/Pandoc/Filter/Plot/Renderers/GNUPlot.hs16
-rw-r--r--src/Text/Pandoc/Filter/Plot/Types.hs39
6 files changed, 77 insertions, 35 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e03c37..a664963 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
pandoc-plot uses [Semantic Versioning](http://semver.org/spec/v2.0.0.html)
+
+Release 0.2.1.0
+---------------
+
+* Improved documentation.
+
Release 0.2.0.0
---------------
diff --git a/README.md b/README.md
index c9d15e8..50df0f1 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
## A Pandoc filter to generate figures from code blocks in documents
-[![Hackage version](https://img.shields.io/hackage/v/pandoc-plot.svg)](http://hackage.haskell.org/package/pandoc-plot) [![Build status](https://ci.appveyor.com/api/projects/status/mmgiuk52j356e6jp?svg=true)](https://ci.appveyor.com/project/LaurentRDC/pandoc-plot) [![Build Status](https://dev.azure.com/laurentdecotret/pandoc-plot/_apis/build/status/LaurentRDC.pandoc-plot?branchName=master)](https://dev.azure.com/laurentdecotret/pandoc-plot/_build/latest?definitionId=5&branchName=master) ![GitHub](https://img.shields.io/github/license/LaurentRDC/pandoc-plot)
+[![Hackage version](https://img.shields.io/hackage/v/pandoc-plot.svg)](http://hackage.haskell.org/package/pandoc-plot) [![Stackage version (nightly)](http://stackage.org/package/pandoc-plot/badge/nightly)](http://stackage.org/nightly/package/pandoc-plot) [![Build status](https://ci.appveyor.com/api/projects/status/mmgiuk52j356e6jp?svg=true)](https://ci.appveyor.com/project/LaurentRDC/pandoc-plot) [![Build Status](https://dev.azure.com/laurentdecotret/pandoc-plot/_apis/build/status/LaurentRDC.pandoc-plot?branchName=master)](https://dev.azure.com/laurentdecotret/pandoc-plot/_build/latest?definitionId=5&branchName=master) ![GitHub](https://img.shields.io/github/license/LaurentRDC/pandoc-plot)
`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.
@@ -237,6 +237,12 @@ octaveplot:
ggplot2:
preamble: ggplot2.r
executable: Rscript
+
+# The possible parameters for the gnuplot toolkit
+gnuplot:
+ preamble: gnuplot.gp
+ executable: gnuplot
+
```
A file like the above sets the **default** values; you can still override them in documents directly.
@@ -276,15 +282,22 @@ matlabplot:
*Coming soon*
-### From Hackage
+### From Hackage/Stackage
-`pandoc-plot` is available on [Hackage](http://hackage.haskell.org/package/pandoc-plot). Using the [`cabal-install`](https://www.haskell.org/cabal/) tool:
+`pandoc-plot` is available on [Hackage](http://hackage.haskell.org/package/pandoc-plot) and [Stackage](https://www.stackage.org/nightly/package/pandoc-plot). Using the [`cabal-install`](https://www.haskell.org/cabal/) tool:
```bash
cabal update
cabal install pandoc-plot
```
+or
+
+```bash
+stack update
+stack install pandoc-plot
+```
+
### From source
Building from source can be done using [`stack`](https://docs.haskellstack.org/en/stable/README/) or [`cabal`](https://www.haskell.org/cabal/):
diff --git a/pandoc-plot.cabal b/pandoc-plot.cabal
index e485882..bbbc5ea 100644
--- a/pandoc-plot.cabal
+++ b/pandoc-plot.cabal
@@ -1,5 +1,5 @@
name: pandoc-plot
-version: 0.2.0.0
+version: 0.2.1.0
cabal-version: >= 1.12
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.
diff --git a/src/Text/Pandoc/Filter/Plot.hs b/src/Text/Pandoc/Filter/Plot.hs
index 6446129..28679b2 100644
--- a/src/Text/Pandoc/Filter/Plot.hs
+++ b/src/Text/Pandoc/Filter/Plot.hs
@@ -15,14 +15,15 @@ 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. For example:
+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;
+* @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;
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,12 +32,23 @@ 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 support Markdown formatting and LaTeX math (@$...$@).
+ * @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 the same format as the document (e.g. Markdown captions in Markdown documents).
* @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"}
+ sin(x)
+
+ set xlabel "x"
+ set ylabel "y"
+ ```
+@
-}
module Text.Pandoc.Filter.Plot (
-- * Operating on single Pandoc blocks
diff --git a/src/Text/Pandoc/Filter/Plot/Renderers/GNUPlot.hs b/src/Text/Pandoc/Filter/Plot/Renderers/GNUPlot.hs
index 70beab7..033e04d 100644
--- a/src/Text/Pandoc/Filter/Plot/Renderers/GNUPlot.hs
+++ b/src/Text/Pandoc/Filter/Plot/Renderers/GNUPlot.hs
@@ -23,7 +23,7 @@ module Text.Pandoc.Filter.Plot.Renderers.GNUPlot (
import Text.Pandoc.Filter.Plot.Renderers.Prelude
gnuplotSupportedSaveFormats :: [SaveFormat]
-gnuplotSupportedSaveFormats = [PNG] -- TODO: support more save formats
+gnuplotSupportedSaveFormats = [PNG, SVG, EPS, GIF, JPG, PDF]
gnuplotCommand :: Configuration -> FigureSpec -> FilePath -> Text
@@ -31,11 +31,21 @@ gnuplotCommand Configuration{..} _ fp = [st|#{gnuplotExe} -c #{fp}|]
gnuplotAvailable :: Configuration -> IO Bool
-gnuplotAvailable Configuration{..} = commandSuccess [st|#{gnuplotExe} -h|] -- TODO: test this
+gnuplotAvailable Configuration{..} = commandSuccess [st|#{gnuplotExe} -h|]
gnuplotCapture :: FigureSpec -> FilePath -> Script
gnuplotCapture FigureSpec{..} fname = [st|
-set term png
+set terminal #{terminalString saveFormat}
set output '#{fname}'
|]
+
+-- | Terminal name for supported save formats
+terminalString :: SaveFormat -> Text
+terminalString PNG = "pngcairo"
+terminalString SVG = "svg"
+terminalString EPS = "postscript eps"
+terminalString GIF = "gif"
+terminalString JPG = "jpeg"
+terminalString PDF = "pdfcairo"
+terminalString fmt = error $ "gnuplot: unsupported save format" <> show fmt
diff --git a/src/Text/Pandoc/Filter/Plot/Types.hs b/src/Text/Pandoc/Filter/Plot/Types.hs
index faa1ccc..1f99528 100644
--- a/src/Text/Pandoc/Filter/Plot/Types.hs
+++ b/src/Text/Pandoc/Filter/Plot/Types.hs
@@ -89,30 +89,32 @@ data PlotEnv
, config :: !Configuration
}
+-- | The @Configuration@ type holds the default values to use
+-- when running pandoc-plot. These values can be overridden in code blocks.
data Configuration = Configuration
{ 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.
-- Default preambles
- , matplotlibPreamble :: !Script
- , plotlyPythonPreamble :: !Script
- , matlabPreamble :: !Script
- , mathematicaPreamble :: !Script
- , octavePreamble :: !Script
- , ggplot2Preamble :: !Script
- , gnuplotPreamble :: !Script
+ , matplotlibPreamble :: !Script -- ^ The default preamble script for the matplotlib toolkit.
+ , plotlyPythonPreamble :: !Script -- ^ The default preamble script for the Plotly/Python 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.
-- Toolkit executables
- , matplotlibExe :: !FilePath
- , matlabExe :: !FilePath
- , plotlyPythonExe :: !FilePath
- , mathematicaExe :: !FilePath
- , octaveExe :: !FilePath
- , ggplot2Exe :: !FilePath
- , gnuplotExe :: !FilePath
+ , 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.
+ , 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.
-- Toolkit-specific options
- , matplotlibTightBBox :: !Bool
- , matplotlibTransparent :: !Bool
+ , matplotlibTightBBox :: !Bool -- ^ Whether or not to make Matplotlib figures tight by default.
+ , matplotlibTransparent :: !Bool -- ^ Whether or not to make Matplotlib figures transparent by default.
} deriving (Eq, Show)
instance Default Configuration where
@@ -211,8 +213,7 @@ data FigureSpec = FigureSpec
instance Hashable FigureSpec -- From Generic
-- | Generated figure file format supported by pandoc-plot.
--- Note: all formats are supported by Matplotlib, but not all
--- formats are supported by Plotly
+-- Note that not all formats are supported by all toolkits.
data SaveFormat
= PNG
| PDF
@@ -227,7 +228,7 @@ data SaveFormat
instance Hashable SaveFormat -- From Generic
instance IsString SaveFormat where
- -- An error is thrown if the save format cannot be parsed. That's OK
+ -- | An error is thrown if the save format cannot be parsed. That's OK
-- since pandoc-plot is a command-line tool and isn't expected to run
-- long.
fromString s