diff options
Diffstat (limited to 'paper/lua-filters/minted/README.md')
| -rw-r--r-- | paper/lua-filters/minted/README.md | 316 |
1 files changed, 0 insertions, 316 deletions
diff --git a/paper/lua-filters/minted/README.md b/paper/lua-filters/minted/README.md deleted file mode 100644 index b26491d..0000000 --- a/paper/lua-filters/minted/README.md +++ /dev/null @@ -1,316 +0,0 @@ -# minted - -This filter enables users to use the [`minted`][minted] package with the -`beamer` and `latex` writers. Users may attach any desired `minted` specific -styling / attributes to their code-blocks (or via document metadata). These -`minted` specific attributes will be _removed_ for any writers that are not -`beamer` or `latex`, since many of the `minted` options require using `latex` -specific syntax that can cause problems in other output formats. For example, -if the `fontsize=\footnotesize` attribute were applied to a code block, an -`html` export would include `data-fontsize="\footnotesize"`, which may produce -errors or more commonly be entirely meaningless for non-latex writers. - -The `minted` package will be used as a _replacement_ for the existing `pandoc` -inline code and code block elements. Behind the scenes, `minted` builds on top -of the `fancyvrb` latex package, using [pygments][pygments] to perform the -highlighting. The `minted` package contains _many_ options for customizing -output, users are encouraged to read / review section 5.3 of the -[minted documentation][minted_docs]. **This filter does not make any attempts -to validate arguments supplied to the `minted` package**. Invalid / conflicting -arguments are a usage error. - -**Contents** - -- [Setup](#setup) - - [LaTeX Preamble Configuration](#latex-preamble-configuration) - - [PDF Compilation](#pdf-compilation) -- [Minted Filter Settings](#minted-filter-settings) - - [Default Settings](#default-settings) - - [All Metadata Settings](#all-metadata-settings) - - [`no_default_autogobble`](#no_default_autogobble-boolean) - - [`no_mintinline`](#no_mintinline-boolean) - - [`default_block_language`](#default_block_language-string) - - [`default_inline_language`](#default_inline_language-string) - - [`block_attributes`](#block_attributes-list-of-strings) - - [`inline_attributes`](#inline_attributes-list-of-strings) -- [Important Usage Notes](#important-usage-notes) -- [Bonus](#bonus) - -# Setup - -## LaTeX Preamble Configuration - -Since this filter will emit `\mintline` commands for inline code, and -`\begin{minted} ... \end{minted}` environments for code blocks, you must ensure -that your document includes the `minted` package in the preamble of your -`beamer` or `latex` document. The filter cannot accomplish this for you. - -**Option 1** - -Use the `header-includes` feature of `pandoc` (`-H` / `--include-in-header`). -This will be injected into the preamble section of your `beamer` or `latex` -document. The bare minimum you need in this file is - -```latex -\usepackage{minted} -``` - -However, there are many other things you can set here (related or unrelated to -this filter), and this is a good opportunity to perform some global setup on the -`minted` package. Some examples: - -```latex -\usepackage{minted} - -% Set the `style=tango` attribute for all minted blocks. Can still be overriden -% per block (e.g., you want to change just one). Run `pygmentize -L` to see -% all available options. -\usemintedstyle{tango} - -% Depending on which pygments style you choose, comments and preprocessor -% directives may be italic. The `tango` style is one of these. This disables -% all italics in the `minted` environment. -\AtBeginEnvironment{minted}{\let\itshape\relax} - -% This disables italics for the `\mintinline` commands. -% Credit: https://tex.stackexchange.com/a/469702/113687 -\usepackage{xpatch} -\xpatchcmd{\mintinline}{\begingroup}{\begingroup\let\itshape\relax}{}{} -``` - -The `minted` package has many options, see the -[minted documentation][minted_docs] for more information. For example, see the -`bgcolor` option for the `minted` package. In this "header-include" file would -be an excellent location to `\definecolor`s that you want to use with `bgcolor`. - -**Option 1.5** - -You can also set `header-includes` in the metadata of your document. The above -example could be set as (noting the escaped backslashes): - -```yaml -colorlinks: true -header-includes: - # Include the minted package, set global style, define colors, etc. - - "\\usepackage{minted}" - - "\\usemintedstyle{tango}" - # Prevent italics in the `minted` environment. - - "\\AtBeginEnvironment{minted}{\\let\\itshape\\relax}" - # Prevent italics in the `\mintinline` command. - - "\\usepackage{xpatch}" - - "`\\xpatchcmd{\\mintinline}{\\begingroup}{\\begingroup\\let\\itshape\\relax}{}{}`{=latex}" -``` - -Note on the last line calling `\xpatchcmd`, we escape the backslashes and -additionally force `pandoc` to treat this as `latex` code by making it an inline -`latex` code element. See [pandoc issue 2139 (comment)][pandoc_issue_2139] for -more information. - -Formally, you may want to apply the ``-"`\\raw_tex`{=latex}"`` trick to all -metadata to indicate it is `latex` specific code. However, since `pandoc` -strips out any raw `latex` when converting to other writers, it isn't necessary. - -**Option 2** - -You can also create your own custom `beamer` or `latex` template to have much -finer control over what is / is not included in your document. You may obtain -a copy of the template that `pandoc` uses by default by running -`pandoc -D beamer` or `pandoc -D latex` depending on your document type. - -After you have modified the template to suit your needs (including at the very -least a `\usepackage{minted}`), specify your template file to `pandoc` using -the `--template <path/to/template/file>` command line argument. - -## PDF Compilation - -To compile a PDF, there are two things that the `minted` package requires be -available: an escaped shell to be able to run external commands (the -`-shell-escape` command line flag), and the ability to create and later read -auxiliary files (`minted` runs `pygmentize` for the highlighting). - -At the time of writing this, only one of these is accessible using `pandoc` -directly. One may pass `--pdf-engine-opt=-shell-escape` to forward the -`-shell-escape` flag to the latex engine being used. Unfortunately, though, -the second component (related to temporary files being created) is not supported -by `pandoc`. See [pandoc issue 4271][pandoc_issue_4271]. - -**However**, in reality this is an minor issue that can easily be worked around. -Instead of generating `md => pdf`, you just use `pandoc` to generate `md => tex` -and then compile `tex => pdf` yourself. See the [sample Makefile](Makefile) for -examples of how to execute both stages. **Furthermore**, you will notice a -significant advantage of managing the `pdf` compilation yourself: the generated -`minted` files are cached and unless you `make clean` (or remove them manually), -unchanged code listings will be reused. That is, you will have faster -compilation times :slightly_smiling_face: - -# Minted Filter Settings - -Direct control over the settings of this filter are performed by setting -sub-keys of a `minted` metadata key for your document. - -## Default Settings - -By default, this filter - -1. Transforms all inline `Code` elements to `\mintinline`. This can be disabled - globally by setting `no_mintinline: true`. - -2. Transforms all `CodeBlock` elements to `\begin{minted} ... \end{minted}` raw - latex code. This cannot be disabled. - -3. Both (1) and (2) default to the `"text"` pygments lexer, meaning that inline - code or code blocks without a specific code class applied will receive no - syntax highlighting. This can be changed globally by setting - `default_block_language: "lexer"` or `default_inline_language: "lexer"`. - -4. All `CodeBlock` elements have the `autogobble` attribute applied to them, - which informs `minted` to trim all common preceding whitespace. This can be - disabled globally by setting `no_default_autogobble: true`. However, doing - this is **strongly discouraged**. Consider a code block nested underneath - a list item. Pandoc will (correctly) generate indented code, meaning you - will need to manually inform `minted` to `gobble=indent` where `indent` is - the number of spaces to trim. Note that `pandoc` may not reproduce the same - indentation level of the original document. - -## All Metadata Settings - -Each of the following are nested under the `minted` metadata key. - -### `no_default_autogobble` (boolean) - -By default this filter will always use `autogobble` with minted, which will -automatically trim common preceding whitespace. This is important because -code blocks nested under a list or other block elements _will_ have common -preceding whitespace that you _will_ want trimmed. - -### `no_mintinline` (boolean) - -Globally prevent this filter from emitting `\mintinline` calls for inline -Code elements, emitting `\texttt` instead. Possibly useful in saving -compile time for large documents that do not seek to have syntax -highlighting on inline code elements. - -### `default_block_language` (string) - -The default pygments lexer class to use for code blocks. By default this -is `"text"`, meaning no syntax highlighting. This is a fallback value, code -blocks that explicitly specify a lexer will not use it. - -### `default_inline_language` (string) - -Same as `default_block_language`, only for inline code (typed in single -backticks). The default is also `"text"`, and changing is discouraged. - -### `block_attributes` (list of strings) - -Any default attributes to apply to _all_ code blocks. These may be -overriden on a per-code-block basis. See section 5.3 of the -[minted documentation][minted_docs] for available options. - -### `inline_attributes` (list of strings) - -Any default attributes to apply to _all_ inline code. These may be -overriden on a per-code basis. See section 5.3 of the -[minted documentation][minted_docs] for available options. - -[minted_docs]: http://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf -[minted]: https://ctan.org/pkg/minted?lang=en -[pygments]: http://pygments.org/ -[pandoc_issue_2139]: https://github.com/jgm/pandoc/issues/2139#issuecomment-310522113 -[pandoc_issue_4271]: https://github.com/jgm/pandoc/issues/4721 - -# Important Usage Notes - -Refer to the [`sample.md`](sample.md) file for some live examples of how to use -this filter. If you execute `make` in this directory, `sample_beamer.pdf`, -`sample_latex.pdf`, and `sample.html` will all be generated to demonstrate the -filter in action. - -`pandoc` allows you to specify additional attributes on either the closing -backtick of an inline code element, or after the third backtick of a fenced -code block. This is done using `{curly braces}`, an example: - -```md -`#include <type_traits>`{.cpp .showspaces style=bw} -``` - -or - - ```{.cpp .showspaces style=bw} - #include <type_traits> - ``` - -In order, these are - -- `.cpp`: specify the language lexer class. -- `.showspaces`: a `minted` boolean attribute. -- `style=bw`: a `minted` attribute that takes an argument (`bw` is a pygments - style, black-white, just an example). - -There are two rules that must not be violated: - -1. Any time you want to supply extra arguments to `minted` to a specific inline - code or code block element, **the lexer class must always be first, and - always be present**. - - This is a limitation of the implementation of this filter. - -2. Observe the difference between specifying boolean attributes vs attributes - that take an argument. Boolean `minted` attributes **must** have a leading - `.`, and `minted` attributes that take an argument **may not** have a leading - `.`. - - - **Yes**: `{.cpp .showspaces}`, **No**: `{.cpp showspaces}` - - **Yes**: `{.cpp style=bw}`, **No**: `{.cpp .style=bw}` - - If you violate this, then `pandoc` will likely not produce an actual inline - `Code` or `CodeBlock` element, but instead something else (undefined). - -Last, but not least, you will see that the `--no-highlight` flag is used in the -`Makefile` for the latex targets. This is added in the spirit of the filter -being a "full replacement" for `pandoc` highlighting with `minted`. This only -affects inline code elements that meet the following criteria: - -1. The inline code element has a lexer, e.g., `{.cpp}`. -2. The inline code element can actually be parsed for that language by `pandoc`. - -If these two conditions are met, and you do **not** specify `--no-highlight`, -the `pandoc` highlighting engine will take over. Users are encouraged to build -the samples (`make` in this directory) and look at the end of the -`Special Characters are Supported` section. If you remove `--no-highlight`, -`make realclean`, and then `make` again, you will see that the pandoc -highlighting engine will colorize the `auto foo = [](){};`. - -Simply put: if you do not want any pandoc highlighting in your LaTeX, **make -sure you add `--no-highlight`** and it will not happen. - -It is advantageous for this filter to rely on this behavior, because it means -that the filter does not need to worry about escaping special characters for -LaTeX -- `pandoc` will do that for us. Inspect the generated `sample_*.tex` -files (near the end) to see the difference. `--no-highlight` will produce -`\texttt` commands, but omitting this flag will result in some `\VERB` commands -from `pandoc`. - -# Bonus - -Included here is a simple python script to help you get the right color -definitions for `bgcolor` with minted. Just run -[`background_color.py`](background_color.py) with a single argument that is the -name of the pygments style you want the `latex` background color definition for: - -```console -$ ./background_color.py monokai -Options for monokai (choose *one*): - - (*) \definecolor{monokai_bg}{HTML}{272822} - (*) \definecolor{monokai_bg}{RGB}{39,40,34} - (*) \definecolor{monokai_bg}{rgb}{0.1529,0.1569,0.1333} - |--------/ - | - +--> You can rename this too :) -``` - -See the contents of [`sample.md`](sample.md) (click on "View Raw" to see the -comments in the metadata section). Notably, in order to use `\definecolor` you -should make sure that the `xcolor` package is actually included. Comments in -the file explain the options. |