[skip ci] Documenting options

LaurentRDC · Jun 14, 2020 · 6a7a0b9 · 6a7a0b9
1 parent fd0e0cb
commit 6a7a0b9
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -22,8 +22,8 @@ Do not edit manually
         pandoc-crossref](#compatibility-with-pandoc-crossref)
   - [Detailed usage](#detailed-usage)
       - [As a filter](#as-a-filter)
-      - [Parameters and options](#parameters-and-options)
       - [Syntax](#syntax)
+      - [Parameters and options](#parameters-and-options)
       - [Configuration](#configuration)
       - [Other commands](#other-commands)
   - [Installation](#installation)
@@ -305,31 +305,67 @@ so:
 pandoc --filter pandoc-plot --filter pandoc-crossref -i input.md -o output.html
 ```
 
-### Parameters and options
+### Syntax
+
+The syntax for code blocks in documents is shown below. `pandoc-plot`
+looks for code blocks with a specific class, depending on the toolkit
+you want to use. `pandoc-plot` will run the code and capture the figure
+output. There can only be **one** figure per code block.
+
+The possible parameters and options are described in [further
+below](#parameters-and-options).
+
+#### Markdown
+
+```` markdown
+  ```{.cls param1=value1 param2=value2 ...}
+  # script content
+  ```
+````
+
+#### LaTeX
+
+Note that the `minted` LaTeX package need not be installed.
+
+``` latex
+\begin{minted}[param1=value1, param2=value2, ...]{cls}
+...
+\end{minted}
+```
 
-`pandoc-plot` looks for code blocks with a specific class, depending on
-the toolkit you want to use. `pandoc-plot` will run the code and capture
-the figure output. There can only be **one** figure per code block.
+### Parameters and options
 
 There are parameters that affect the figure that will be included in
 your document. Here are all the possible general parameters, in Markdown
 syntax:
 
 ```` markdown
-  ```{.cls directory=(path) caption=(text) format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) source=(true|false) preamble=(path) dpi=(integer) executable=(path) caption_format=(text)}
+  ```{.cls 
+      .language
+      directory=(path) 
+      caption=(text) 
+      format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) 
+      source=(true|false) 
+      preamble=(path) 
+      dpi=(integer) 
+      executable=(path) 
+      caption_format=(text)
+      }
   # script content
   ```
 ````
 
-See [Syntax](#syntax) for other input formats, such as Latex.
-
   - `cls` must be one of the following: `matplotlib`, `matlabplot`,
     `plotly_python`, `plotly_r`, `mathplot`, `octaveplot`, `ggplot2`,
     `gnuplot`, or `graphviz`.
 
 All following parameters are optional, with their default values
 controlled by the [configuration](#configuration)
 
+  - `language` specifies the programming language used in this block.
+    This parameter is ignored by `pandoc-plot`, but your text editor may
+    use it to highlight code. See [Code
+    highlighting](#code-highlighting) below.
   - `directory` is a path to the directory where the figure and source
     code will be saved. You cannot control the file name. This path is
     either absolute, or relative from the working directory where you
@@ -359,42 +395,6 @@ controlled by the [configuration](#configuration)
     `caption_format=markdown+raw_tex`. See Pandoc’s guide on [Specifying
     formats](https://pandoc.org/MANUAL.html#specifying-formats).
 
-### Syntax
-
-#### Markdown
-
-```` markdown
-  ```{.cls directory=(path) caption=(text) format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) source=(true|false) preamble=(path) dpi=(integer) executable=(path) caption_format=(text)}
-  # script content
-  ```
-````
-
-Simple example using the `matplotlib` toolkit:
-
-```` markdown
-  ```{.matplotlib caption="Figure" source=true}
-  # script content
-  ```
-````
-
-#### LaTeX
-
-Note that the `minted` LaTeX package need not be installed.
-
-``` latex
-\begin{minted}[directory=(path), caption=(text), format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP), source=(true|false), preamble=(path), dpi=(integer), executable=(path), caption_format=(text)]{cls}
-...
-\end{minted}
-```
-
-Simple example using the `ggplot2` toolkit:
-
-``` latex
-\begin{minted}[format=png, caption=This is a figure]{ggplot2}
-...
-\end{minted}
-```
-
 #### Code highlighting
 
 If your editor supports code highlighting in code blocks, you can also
@@ -406,22 +406,30 @@ include the programming language. In Markdown:
   ```
 ````
 
-For example, for Matplotlib plots:
+or Latex:
 
-```` markdown
-  ```{.python .matplotlib}
+``` latex
+  \begin{minted}[(options)]{language, cls}
   # script content
-  ```
-````
+  \end{minted}
+```
 
-or for GGPlot2 figures:
+For example, for GGPlot2 figures:
 
 ```` markdown
-  ```{.r .ggplot2}
+  ```{.r .ggplot2 caption=Highlighted code block}
   # script content
   ```
 ````
 
+or (Latex):
+
+``` latex
+  \begin{minted}[caption=Highlighted code block]{r, ggplot2}
+  # script content
+  \end{minted}
+```
+
 This way, you benefit from code highlighting *and* `pandoc-plot`.
 
 ### Configuration

diff --git a/readme/README.template b/readme/README.template
@@ -201,25 +201,55 @@ You can chain other filters with it (e.g., [`pandoc-crossref`](https://github.co
 pandoc --filter pandoc-plot --filter pandoc-crossref -i input.md -o output.html
 ```
 
-### Parameters and options
+### Syntax
 
-`pandoc-plot` looks for code blocks with a specific class, depending on the toolkit you want to use. `pandoc-plot` will run the code and capture the figure output. There can only be **one** figure per code block.
+The syntax for code blocks in documents is shown below. `pandoc-plot` looks for code blocks with a specific class, depending on the toolkit you want to use. `pandoc-plot` will run the code and capture the figure output. There can only be **one** figure per code block.
 
-There are parameters that affect the figure that will be included in your document. Here are all the possible general parameters, in Markdown syntax:
+The possible parameters and options are described in [further below](#parameters-and-options).
+
+#### Markdown
 
 ````markdown
-  ```{.cls directory=(path) caption=(text) format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) source=(true|false) preamble=(path) dpi=(integer) executable=(path) caption_format=(text)}
+  ```{.cls param1=value1 param2=value2 ...}
   # script content
   ```
+````
+
+#### LaTeX
 
+Note that the `minted` LaTeX package need not be installed.
+````latex
+\begin{minted}[param1=value1, param2=value2, ...]{cls}
+...
+\end{minted}
 ````
 
-See [Syntax](#syntax) for other input formats, such as Latex.
+### Parameters and options
+
+There are parameters that affect the figure that will be included in your document. Here are all the possible general parameters, in Markdown syntax:
+
+````markdown
+  ```{.cls 
+      .language
+      directory=(path) 
+      caption=(text) 
+      format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) 
+      source=(true|false) 
+      preamble=(path) 
+      dpi=(integer) 
+      executable=(path) 
+      caption_format=(text)
+      }
+  # script content
+  ```
+
+````
 
 * `cls` must be one of the following: `matplotlib`, `matlabplot`, `plotly_python`, `plotly_r`, `mathplot`, `octaveplot`, `ggplot2`, `gnuplot`, or `graphviz`.
 
 All following parameters are optional, with their default values controlled by the [configuration](#configuration)
 
+* `language` specifies the programming language used in this block. This parameter is ignored by `pandoc-plot`, but your text editor may use it to highlight code. See [Code highlighting](#code-highlighting) below.
 * `directory` is a path to the directory where the figure and source code will be saved. You cannot control the file name. This path is either absolute, or relative from the working directory where you call `pandoc-plot`.
 * `caption` is the caption text. The format of the caption is specified in the `caption_format` parameter, described below.
 * `format` is the desired filetype for the resulting figure. Possible values for `format` are [`PNG`, `PDF`, `SVG`, `JPG`, `EPS`, `GIF`, `TIF`, `WEBP`]. Not all toolkits support all formats. See `pandoc-plot toolkits` for toolkit-specific information regarding save formats.
@@ -229,65 +259,38 @@ All following parameters are optional, with their default values controlled by t
 * `executable` is a path to the executable to use (e.g. `C:\\python3.exe`) or the name of the executable (e.g. `python3`).
 * `caption_format` is the text format of the caption. Possible values are exactly the same as `pandoc`'s format specification, usually `FORMAT+EXTENSION-EXTENSION`. For example, captions in Markdown with raw LaTeX would be parsed correctly provided that `caption_format=markdown+raw_tex`. See Pandoc's guide on [Specifying formats](https://pandoc.org/MANUAL.html#specifying-formats).
 
-### Syntax
-
-#### Markdown
-
-````markdown
-  ```{.cls directory=(path) caption=(text) format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP) source=(true|false) preamble=(path) dpi=(integer) executable=(path) caption_format=(text)}
-  # script content
-  ```
-````
+#### Code highlighting
 
-Simple example using the `matplotlib` toolkit:
+If your editor supports code highlighting in code blocks, you can also include the programming language. In Markdown:
 
 ````markdown
-  ```{.matplotlib caption="Figure" source=true}
+  ```{.language .cls (options)}
   # script content
   ```
 ````
 
-#### LaTeX
-
-Note that the `minted` LaTeX package need not be installed.
-````latex
-\begin{minted}[directory=(path), caption=(text), format=(PNG|PDF|SVG|JPG|EPS|GIF|TIF|WEBP), source=(true|false), preamble=(path), dpi=(integer), executable=(path), caption_format=(text)]{cls}
-...
-\end{minted}
-````
-
-Simple example using the `ggplot2` toolkit:
+or Latex:
 
 ````latex
-\begin{minted}[format=png, caption=This is a figure]{ggplot2}
-...
-\end{minted}
-````
-
-#### Code highlighting
-
-If your editor supports code highlighting in code blocks, you can also include the programming language. In Markdown:
-
-````markdown
-  ```{.language .cls (options)}
+  \begin{minted}[(options)]{language, cls}
   # script content
-  ```
+  \end{minted}
 ````
 
-For example, for Matplotlib plots:
+For example, for GGPlot2 figures:
 
 ````markdown
-  ```{.python .matplotlib}
+  ```{.r .ggplot2 caption=Highlighted code block}
   # script content
   ```
 ````
 
-or for GGPlot2 figures:
+or (Latex):
 
-````markdown
-  ```{.r .ggplot2}
+````latex
+  \begin{minted}[caption=Highlighted code block]{r, ggplot2}
   # script content
-  ```
+  \end{minted}
 ````
 
 This way, you benefit from code highlighting *and* `pandoc-plot`.