introduce a new default beamer template

3 files changed, 594 insertions, 0 deletions

diff --git a/pandoc/filters/center-img.lua b/pandoc/filters/center-img.lua
new file mode 100644
index 00000000..18782725
--- /dev/null
+++ b/pandoc/filters/center-img.lua
@@ -0,0 +1,20 @@
+-- Based on:
+-- https://pandoc.org/lua-filters.html#center-images-in-latex-and-html-output
+-- Licensed under MIT License found at:
+-- https://github.com/TomBener/pandoc-templates/blob/05aba224519d8a2b037108948bde0d820860b786/LICENSE
+
+-- Filter images with this function if the target format is LaTeX.
+if FORMAT:match('beamer') then
+  function Image(elem)
+    -- Surround all images with the 'center' class with image-centering raw LaTeX.
+    if elem.classes[1] == "center" then
+      return {
+        pandoc.RawInline('latex', '\\hfill\\break{\\centering'),
+        elem,
+        pandoc.RawInline('latex', '\\par}')
+      }
+    else
+      return elem
+    end
+  end
+end
diff --git a/pandoc/filters/include-files.lua b/pandoc/filters/include-files.lua
new file mode 100644
index 00000000..f9f208e9
--- /dev/null
+++ b/pandoc/filters/include-files.lua
@@ -0,0 +1,120 @@
+--- include-files.lua – filter to include Markdown files
+---
+--- Copyright: © 2019–2021 Albert Krewinkel
+--- License:   MIT – see LICENSE file for details
+
+-- Module pandoc.path is required and was added in version 2.12
+PANDOC_VERSION:must_be_at_least '2.12'
+
+local List = require 'pandoc.List'
+local path = require 'pandoc.path'
+local system = require 'pandoc.system'
+
+--- Get include auto mode
+local include_auto = false
+function get_vars (meta)
+  if meta['include-auto'] then
+    include_auto = true
+  end
+end
+
+--- Keep last heading level found
+local last_heading_level = 0
+function update_last_level(header)
+  last_heading_level = header.level
+end
+
+--- Update contents of included file
+local function update_contents(blocks, shift_by, include_path)
+  local update_contents_filter = {
+    -- Shift headings in block list by given number
+    Header = function (header)
+      if shift_by then
+        header.level = header.level + shift_by
+      end
+      return header
+    end,
+    -- If image paths are relative then prepend include file path
+    Image = function (image)
+      if path.is_relative(image.src) then
+        image.src = path.normalize(path.join({include_path, image.src}))
+      end
+      return image
+    end,
+    -- Update path for include-code-files.lua filter style CodeBlocks
+    CodeBlock = function (cb)
+      if cb.attributes.include and path.is_relative(cb.attributes.include) then
+        cb.attributes.include =
+          path.normalize(path.join({include_path, cb.attributes.include}))
+        end
+      return cb
+    end
+  }
+
+  return pandoc.walk_block(pandoc.Div(blocks), update_contents_filter).content
+end
+
+--- Filter function for code blocks
+local transclude
+function transclude (cb)
+  -- ignore code blocks which are not of class "include".
+  if not cb.classes:includes 'include' then
+    return
+  end
+
+  -- Markdown is used if this is nil.
+  local format = cb.attributes['format']
+
+  -- Attributes shift headings
+  local shift_heading_level_by = 0
+  local shift_input = cb.attributes['shift-heading-level-by']
+  if shift_input then
+    shift_heading_level_by = tonumber(shift_input)
+  else
+    if include_auto then
+      -- Auto shift headings
+      shift_heading_level_by = last_heading_level
+    end
+  end
+
+  --- keep track of level before recusion
+  local buffer_last_heading_level = last_heading_level
+
+  local blocks = List:new()
+  for line in cb.text:gmatch('[^\n]+') do
+    if line:sub(1,2) ~= '//' then
+      local fh = io.open(line)
+      if not fh then
+        io.stderr:write("Cannot open file " .. line .. " | Skipping includes\n")
+      else
+        -- read file as the given format with global reader options
+        local contents = pandoc.read(
+          fh:read '*a',
+          format,
+          PANDOC_READER_OPTIONS
+        ).blocks
+        last_heading_level = 0
+        -- recursive transclusion
+        contents = system.with_working_directory(
+            path.directory(line),
+            function ()
+              return pandoc.walk_block(
+                pandoc.Div(contents),
+                { Header = update_last_level, CodeBlock = transclude }
+              )
+            end).content
+        --- reset to level before recursion
+        last_heading_level = buffer_last_heading_level
+        blocks:extend(update_contents(contents, shift_heading_level_by,
+                                      path.directory(line)))
+        fh:close()
+      end
+    end
+  end
+  return blocks
+end
+
+return {
+  { Meta = get_vars },
+  { Header = update_last_level, CodeBlock = transclude }
+}
diff --git a/pandoc/filters/minted.lua b/pandoc/filters/minted.lua
new file mode 100644
index 00000000..68db5f0b
--- /dev/null
+++ b/pandoc/filters/minted.lua
@@ -0,0 +1,454 @@
+--[[
+minted -- enable the minted environment for code listings in beamer and latex.
+
+MIT License
+
+Copyright (c) 2019 Stephen McDowell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+]]
+
+--------------------------------------------------------------------------------
+-- Quick documentation.  See full documentation here:                         --
+-- https://github.com/pandoc/lua-filters/blob/master/minted                   --
+--------------------------------------------------------------------------------
+--[[
+Brief overview of metadata keys that you can use in your document:
+
+minted:
+  no_default_autogobble:   <boolean>, *DISCOURAGED*
+  no_mintinline:           <boolean>
+  default_block_language:  <string>
+  default_inline_language: <string>
+  block_attributes:        <list of strings>
+    - attr_1
+    - attr_2
+    - ...
+  inline_attributes:       <list of strings>
+    - attr_1
+    - attr_2
+    - ...
+
+In words, underneath the `minted` metadata key, you have the following options:
+
+### `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
+overridden 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
+overridden 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
+]]
+
+local List = require('pandoc.List')
+
+--------------------------------------------------------------------------------
+-- Potential metadata elements to override.                                   --
+--------------------------------------------------------------------------------
+local minted_no_mintinline           = false
+local minted_default_block_language  = "text"
+local minted_default_inline_language = "text"
+local minted_block_attributes        = {}
+local minted_inline_attributes       = {}
+
+--------------------------------------------------------------------------------
+-- Constants used to differentiate Code and CodeBlock elements.               --
+--------------------------------------------------------------------------------
+local MintedInline = 0
+local MintedBlock  = 1
+
+--------------------------------------------------------------------------------
+-- Utility functions.                                                         --
+--------------------------------------------------------------------------------
+-- Return the string lexer class to be used with minted.  `elem` should be
+-- either a Code or CodeBlock element (whose `classes` list will be inspected
+-- first).  `kind` is assumed to be either `MintedInline` or `MintedBlock` in
+-- order to choose the appropriate fallback lexer when unspecified.
+local function minted_language(elem, kind)
+  -- If the code [block] attached classes, we assume the first one is the
+  -- lexer class to use.
+  if #elem.classes > 0 then
+    return elem.classes[1]
+  end
+  -- Allow user-level metadata to override the inline language.
+  if kind == MintedInline then
+    return minted_default_inline_language
+  end
+  -- Allow user-level metadata to override the block language.
+  if kind == MintedBlock then
+    return minted_default_block_language
+  end
+
+  -- Failsafe, should not hit here unless function called incorrectly.
+  return "text"
+end
+
+-- Returns a boolean specifying whether or not the specified string `cls` is an
+-- option that is supported by the minted package.
+local function is_minted_class(cls)
+  -- Section 5.3 Available Options of Minted documentation.  Note that many of
+  -- these do not apply to \mintinline (inline Code).  Users are responsible
+  -- for supplying valid arguments to minted.  For example, specifying
+  -- `autogobble` and `gobble` at the same time is a usage error.
+  --
+  -- http://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf
+  local all_minted_options = List:new{
+    "autogobble", "baselinestretch", "beameroverlays", "breakafter",
+    "breakaftergroup", "breakaftersymbolpre", "breakaftersymbolpost",
+    "breakanywhere", "breakanywheresymbolpre", "breakanywheresymbolpost",
+    "breakautoindent", "breakbefore", "breakbeforegroup",
+    "breakbeforesymbolpre", "breakbeforesymbolpost", "breakbytoken",
+    "breakbytokenanywhere", "breakindent", "breakindentnchars", "breaklines",
+    "breaksymbol", "breaksymbolleft", "breaksymbolright", "breaksymbolindent",
+    "breaksymbolindentnchars", "breaksymbolindentleft",
+    "breaksymbolindentleftnchars", "breaksymbolindentright",
+    "breaksymbolindentrightnchars", "breaksymbolsep", "breaksymbolsepnchars",
+    "breaksymbolsepleft", "breaksymbolsepleftnchars", "breaksymbolsepright",
+    "breaksymbolseprightnchars", "bgcolor", "codetagify", "curlyquotes",
+    "encoding", "escapeinside", "firstline", "firstnumber", "fontfamily",
+    "fontseries", "fontsize", "fontshape", "formatcom", "frame", "framerule",
+    "framesep", "funcnamehighlighting", "gobble", "highlightcolor",
+    "highlightlines", "keywordcase", "label", "labelposition", "lastline",
+    "linenos", "numberfirstline", "numbers", "mathescape", "numberblanklines",
+    "numbersep", "obeytabs", "outencoding", "python3", "resetmargins",
+    "rulecolor", "samepage", "showspaces", "showtabs", "space", "spacecolor",
+    "startinline", "style", "stepnumber", "stepnumberfromfirst",
+    "stepnumberoffsetvalues", "stripall", "stripnl", "tab", "tabcolor",
+    "tabsize", "texcl", "texcomments", "xleftmargin", "xrightmargin"
+  }
+  return all_minted_options:includes(cls, 0)
+end
+
+-- Return a string for the minted attributes `\begin{minted}[attributes]` or
+-- `\mintinline[attributes]`.  Attributes are acquired by inspecting the
+-- specified element's `classes` and `attr` fields.  Any global attributes
+-- provided in the document metadata will be included _only_ if they do not
+-- override the element-level attributes.
+--
+-- `elem` should either be a Code or CodeBlock element, and `kind` is assumed to
+-- be either `MintedInline` or `MintedBlock`.  The `kind` determines which
+-- global default attribute list to use.
+local function minted_attributes(elem, kind)
+  -- The full listing of attributes that will be joined and returned.
+  local minted_attributes = {}
+
+  -- Book-keeping, track xxx=yyy keys `xxx` that have been added to
+  -- `minted_attributes` to make checking optional global defaults via the
+  -- `block_attributes` or `inline_attributes` easier.
+  local minted_keys = {}
+
+  -- Boolean style options for minted (e.g., ```{.bash .autogobble}) will appear
+  -- in the list of classes.
+  for _, cls in ipairs(elem.classes) do
+    if is_minted_class(cls) then
+      table.insert(minted_attributes, cls)
+      table.insert(minted_keys, cls)
+    end
+  end
+
+  -- Value options using key=value (e.g., ```{.bash fontsize=\scriptsize}) show
+  -- up in the list of attributes.
+  for cls, value in pairs(elem.attributes) do
+    if is_minted_class(cls) then
+      table.insert(minted_attributes, cls .. "=" .. value)
+      table.insert(minted_keys, cls)
+    end
+  end
+
+  -- Add any global defaults _only_ if they do not conflict.  Note that conflict
+  -- is only in the literal sense.  If a user has `autogobble` and `gobble=2`
+  -- specified, these do conflict in the minted sense, but this filter makes no
+  -- checks on validity ;)
+  local global_defaults = nil
+  if kind == MintedInline then
+    global_defaults = minted_inline_attributes
+  elseif kind == MintedBlock then
+    global_defaults = minted_block_attributes
+  end
+  for _, global_attr in ipairs(global_defaults) do
+    -- Either use the index of `=` minus one, or -1 if no `=` present.  Fallback
+    -- on -1 means that the substring is the original string.
+    local end_idx = (string.find(global_attr, "=") or 0) - 1
+    local global_key = string.sub(global_attr, 1, end_idx)
+    local can_insert_global = true
+    for _, existing_key in ipairs(minted_keys) do
+      if existing_key == global_key then
+        can_insert_global = false
+        break
+      end
+    end
+
+    if can_insert_global then
+      table.insert(minted_attributes, global_attr)
+    end
+  end
+
+  -- Return a comma delimited string for specifying the attributes to minted.
+  return table.concat(minted_attributes, ",")
+end
+
+-- Return the specified `elem` with any minted data removed from the `classes`
+-- and `attr`.  Otherwise writers such as the HTML writer might produce invalid
+-- code since latex makes heavy use of the \backslash.
+local function remove_minted_attibutes(elem)
+  -- Remove any minted items from the classes.
+  classes = {}
+  for _, cls in ipairs(elem.classes) do
+    if not is_minted_class(cls) and cls ~= "no_minted" then
+      table.insert(classes, cls)
+    end
+  end
+  elem.classes = classes
+
+  -- Remove any minted items from the attributes.
+  extra_attrs = {}
+  for cls, value in pairs(elem.attributes) do
+    if not is_minted_class(cls) then
+      table.insert(extra_attrs, {cls, value})
+    end
+  end
+  elem.attributes = extra_attrs
+
+  -- Return the (potentially modified) element for pandoc to take over.
+  return elem
+end
+
+-- Return a `start_delim` and `end_delim` that can safely wrap around the
+-- specified `text` when used inline. If no special characters occur in `text`,
+-- then a pair of braces are returned. Otherwise, if any character of
+-- `possible_delims` are not in `text`, then it is returned. If no delimiter
+-- could be found, an error is raised.
+local function minted_inline_delims(text)
+  local start_delim, end_delim
+  if text:find('[{}]') then
+    -- Try some other delimiter (the alphanumeric digits are in Python's
+    -- string.digits + string.ascii_letters order)
+    possible_delims = ('|!@#^&*-=+' .. '0123456789' ..
+                       'abcdefghijklmnopqrstuvwxyz' ..
+                       'ABCDEFGHIJKLMNOPQRSTUVWXYZ')
+    for char in possible_delims:gmatch('.') do
+      if not text:find(char, 1, true) then
+        start_delim = char
+        end_delim = char
+        break
+      end
+    end
+    if not start_delim then
+      local msg = 'Unable to determine delimiter to use around inline code %q'
+      error(msg:format(text))
+    end
+  else
+    start_delim = '{'
+    end_delim = '}'
+  end
+
+  return start_delim, end_delim
+end
+
+--------------------------------------------------------------------------------
+-- Pandoc overrides.                                                          --
+--------------------------------------------------------------------------------
+-- Override the pandoc Meta function so that we can parse the metadata for the
+-- document and store the necessary variables locally to use in other functions
+-- such as Code and CodeBlock (helper methods).
+function Meta(m)
+  -- Grab the `minted` metadata, quit early if not present.
+  local minted = m["minted"]
+  local found_autogobble = false
+  local always_autogobble = true
+  if minted ~= nil then
+    -- Parse and set the global bypass to turn off all \mintinline calls.
+    local no_mintinline = minted["no_mintinline"]
+    if no_mintinline ~= nil then
+      minted_no_mintinline = no_mintinline
+    end
+
+    -- Parse and set the default block language.
+    local default_block_language = minted.default_block_language
+      and pandoc.utils.stringify(minted.default_block_language)
+    if default_block_language ~= nil then
+      minted_default_block_language = default_block_language
+    end
+
+    -- Parse and set the default inline language.
+    local default_inline_language = minted.default_inline_language
+      and pandoc.utils.stringify(minted.default_inline_language)
+    if default_inline_language ~= nil then
+      minted_default_inline_language = default_inline_language
+    end
+
+    -- Parse the global default minted attributes to use on every block.
+    local block_attributes = minted["block_attributes"]
+    if block_attributes ~= nil then
+      for _, attr in ipairs(block_attributes) do
+        if attr == "autogobble" then
+          found_autogobble = true
+        end
+        table.insert(minted_block_attributes, attr[1].text)
+      end
+    end
+
+    -- Allow users to turn off autogobble for blocks, but really they should not
+    -- ever seek to do this (indented code blocks under list for example).
+    local no_default_autogobble = minted["no_default_autogobble"]
+    if no_default_autogobble ~= nil then
+      always_autogobble = not no_default_autogobble
+    end
+
+    -- Parse the global default minted attributes to use on ever inline.
+    local inline_attributes = minted["inline_attributes"]
+    if inline_attributes ~= nil then
+      for _, attr in ipairs(inline_attributes) do
+        table.insert(minted_inline_attributes, attr[1].text)
+      end
+    end
+  end
+
+  -- Make sure autogobble is turned on by default if no `minted` meta key is
+  -- provided for the document.
+  if always_autogobble and not found_autogobble then
+    table.insert(minted_block_attributes, "autogobble")
+  end
+
+  -- Return the metadata to pandoc (unchanged).
+  return m
+end
+
+-- Override inline code elements to use \mintinline for beamer / latex writers.
+-- Other writers have all minted attributes removed.
+function Code(elem)
+  if FORMAT == "beamer" or FORMAT == "latex" then
+    -- Allow a bypass to turn off \mintinline via adding .no_minted class.
+    local found_no_minted_class = false
+    for _, cls in ipairs(elem.classes) do
+      if cls == "no_minted" then
+        found_no_minted_class = true
+        break
+      end
+    end
+
+    -- Check for local or global bypass to turn off \mintinline
+    if minted_no_mintinline or found_no_minted_class then
+      return nil -- Return `nil` signals to `pandoc` that elem is not changed.
+    end
+
+    local start_delim, end_delim = minted_inline_delims(elem.text)
+    local language   = minted_language(elem, MintedInline)
+    local attributes = minted_attributes(elem, MintedInline)
+    local raw_minted = string.format(
+      "\\mintinline[%s]{%s}%s%s%s",
+      attributes,
+      language,
+      start_delim,
+      elem.text,
+      end_delim
+    )
+    -- NOTE: prior to pandoc commit 24a0d61, `beamer` cannot be used as the
+    -- RawBlock format.  Using `latex` should not cause any problems.
+    return pandoc.RawInline("latex", raw_minted)
+  else
+    return remove_minted_attibutes(elem)
+  end
+end
+
+-- Override code blocks to use \begin{minted}...\end{minted} for beamer / latex
+-- writers.  Other writers have all minted attributes removed.
+function CodeBlock(block)
+  if FORMAT == "beamer" or FORMAT == "latex" then
+    local language   = minted_language(block, MintedBlock)
+    local attributes = minted_attributes(block, MintedBlock)
+    local raw_minted = string.format(
+      "\\begin{minted}[%s]{%s}\n%s\n\\end{minted}",
+      attributes,
+      language,
+      block.text
+    )
+    -- NOTE: prior to pandoc commit 24a0d61, `beamer` cannot be used as the
+    -- RawBlock format.  Using `latex` should not cause any problems.
+    return pandoc.RawBlock("latex", raw_minted)
+  else
+    return remove_minted_attibutes(block)
+  end
+end
+
+-- Override headers to make all beamer frames fragile, since any minted
+-- environments or \mintinline invocations will halt compilation if the frame
+-- is not marked as fragile.
+function Header(elem)
+  if FORMAT == 'beamer' then
+    -- Check first that 'fragile' is not already present.
+    local has_fragile = false
+    for _, val in ipairs(elem.classes) do
+      if val == 'fragile' then
+        has_fragile = true
+        break
+      end
+    end
+
+    -- If not found, add fragile to the list of classes.
+    if not has_fragile then
+      table.insert(elem.classes, 'fragile')
+    end
+
+    -- NOTE: pass the remaining work to pandoc, noting that 2.5 and below
+    -- may duplicate the 'fragile' specifier.  Duplicated fragile does *not*
+    -- cause compile errors.
+    return elem
+  end
+end
+
+-- NOTE: order of return matters, Meta needs to be first otherwise the metadata
+-- from the document will not be loaded _first_.
+return {
+  {Meta = Meta},
+  {Code = Code},
+  {CodeBlock = CodeBlock},
+  {Header = Header}
+}