Enable (and fix) Pandoc syntax highlighting (#243)

This change removes the --no-highlight flag from the pandoc invocation.
It fixes the issue with the template that that revealed (which is that
the $highlighting-styles$ magic was missing). If you are using this
project with a custom LaTeX template and this change breaks with an
error like "Environment Shaded undefied", then it's because your
template needs this magic as well. See
jgm/pandoc#7923 for more information on that.

This change re-styles code blocks to use a white background instead of
the light blue one, so that the kate-styled syntax highlighting looks
good. Since the background is white, but the code block still needs to
be a block, this change adds a 1pt black line around the code.

Author: chrisfenner

Dockerfile

@@ -130,7 +130,7 @@ RUN wget -O /usr/share/plantuml.jar https://github.com/plantuml/plantuml/release
 ENV PATH="/usr/local/texlive/bin/aarch64-linux:/usr/local/texlive/bin/x86_64-linux:${PATH}"
 
 # Packages that are needed despite not being used explicitly by the template:
-# bigfoot, catchfile, fancyvrb, footmisc, hardwrap, lineno, ltablex, latexmk, needspace, pgf, zref
+# bigfoot, catchfile, fancyvrb, footmisc, framed, hardwrap, lineno, ltablex, latexmk, needspace, pgf, zref
 # Package dependencies introduced by latexdiff:
 # changebar, datetime2, latexdiff, listings, marginnote, pdfcomment, soulpos
 RUN tlmgr update --self && tlmgr install \
@@ -159,6 +159,7 @@ RUN tlmgr update --self && tlmgr install \
     footmisc \
     footnotebackref \
     footnotehyper \
+    framed \
     fvextra \
     geometry \
     hardwrap \

build.sh

@@ -749,6 +749,11 @@ cache_generated_files() {
 	cp_chown .cache "${SOURCE_DIR}"
 }
 
+# This theme was chosen because it is light (like the rest of the document) and
+# looks reasonably nice for both programming languages (e.g., C) as well as
+# diff markups.
+SYNTAX_HIGHLIGHT_STYLE=kate
+
 # Takes Markdown input and writes LaTeX output using pandoc.
 do_latex() {
 	local input=$1
@@ -764,7 +769,7 @@ do_latex() {
 	local start=$(date +%s)
 	local cmd=(pandoc
 		--standalone
-		--no-highlight
+		--highlight-style=${SYNTAX_HIGHLIGHT_STYLE}
 		--template=${TEMPLATE_PDF}
 		--lua-filter=convert-diagrams.lua
 		--lua-filter=convert-aasvg.lua

filter/divide-code-blocks.lua

@@ -14,11 +14,15 @@ code_classes =
 }
 
 function CodeBlock(block)
-    local class = block.classes[1]
-    local class_spec = code_classes[string.lower(class or "")]
-    if not class_spec then
-        class_spec = code_classes["normal"]
+    local class_spec = code_classes["normal"]
+    for _, class in ipairs(block.classes) do
+        local maybe_spec = code_classes[string.lower(class)]
+        if maybe_spec then
+            class_spec = maybe_spec
+            break
+        end
     end
+
     font = class_spec["font"]
     return {
         pandoc.RawInline('latex', string.format([[

guide.tcg

@@ -174,7 +174,7 @@ Usage:
 You can specify a particular version of the docker container using the
 `DOCKER_IMAGE` environment variable:
 
-```sh
+```sh {.small}
 DOCKER_IMAGE=ghcr.io/trustedcomputinggroup/pandoc:0.6.5 ./docker_run --pdf=output.pdf ./input.md
 ```
 
@@ -782,7 +782,7 @@ reimplementation, the code uses the original
 
 Here is an example aasvg diagram:
 
-````md
+````md {.small}
 ```aasvg {caption="(v)TPM Key Management" #fig:tpm-key-management}
  .---------------------.    .----.
 |  Virtual Environment  |  | vTPM +--------------.-----------------.----------------.
@@ -1216,25 +1216,25 @@ To typeset complex equations with multi-character identifiers (such as the funct
 we recommend using the functions `\mathbf` (for functions) and `\mathit` (for variables). For constants, we recommend `\mathrm`.
 This avoids strange kerning issues where a string is treated as a product of single-character symbols, like in @eq:hmac-iso-bad-kerning:
 
-```md
-$$ \mathbf{HMAC}(K, \mathit{someTEXT}) \coloneq \mathbf{H}((\bar{K} \oplus \mathrm{OPAD}) \parallel \mathbf{H}((\bar{K} \oplus \mathrm{IPAD}) \parallel \mathit{someTEXT})) $$ {#eq:hmac-iso}
+```md {.tiny}
+$$ \mathbf{HMAC}(K, \mathit{someTEXT}) \coloneq \mathbf{H}((\bar{K} \oplus \mathrm{OPAD}) \parallel ... \parallel \mathit{someTEXT})) $$ {#eq:hmac-iso}
 ```
 
-$$ \mathbf{HMAC}(K, \mathit{someTEXT}) \coloneq \mathbf{H}((\bar{K} \oplus \mathrm{OPAD}) \parallel \mathbf{H}((\bar{K} \oplus \mathrm{IPAD}) \parallel \mathit{someTEXT})) $$ {#eq:hmac-iso}
+$$ \mathbf{HMAC}(K, \mathit{someTEXT}) \coloneq \mathbf{H}((\bar{K} \oplus \mathrm{OPAD}) \parallel ... \parallel \mathit{someTEXT})) $$ {#eq:hmac-iso}
 
-```md
+```md {.tiny}
 $$ HMAC(K, someTEXT) \coloneq H((\bar{K} \oplus OPAD) \parallel H((\bar{K} \oplus IPAD) \parallel someTEXT)) $$ {#eq:hmac-iso-bad-kerning}
 ```
 
 $$ HMAC(K, someTEXT) \coloneq H((\bar{K} \oplus OPAD) \parallel H((\bar{K} \oplus IPAD) \parallel someTEXT)) $$ {#eq:hmac-iso-bad-kerning}
 
 You can use Unicode characters to make equations a little more readable in plain-text:
 
-```md
-$$ \mathbf{HMAC}(K, \mathit{someTEXT}) := H((\bar{K} ⊕ \mathrm{OPAD}) \parallel H((\bar{K} ⊕ \mathrm{IPAD}) \parallel \mathit{someTEXT})) $$ {#eq:hmac-unicode}
+```md {.tiny}
+$$ \mathbf{HMAC}(K, \mathit{someTEXT}) := H((\bar{K} ⊕ \mathrm{OPAD}) \parallel ... \parallel \mathit{someTEXT})) $$ {#eq:hmac-unicode}
 ```
 
-$$ \mathbf{HMAC}(K, \mathit{someTEXT}) := \mathbf{H}((\bar{K} ⊕ \mathrm{OPAD}) \parallel \mathbf{H}((\bar{K} ⊕ \mathrm{IPAD}) \parallel \mathit{someTEXT})) $$ {#eq:hmac-unicode}
+$$ \mathbf{HMAC}(K, \mathit{someTEXT}) := \mathbf{H}((\bar{K} ⊕ \mathrm{OPAD}) \parallel ... \parallel \mathit{someTEXT})) $$ {#eq:hmac-unicode}
 
 # Advanced Features
 
@@ -1423,7 +1423,7 @@ Figures can be placed on landscape pages as in @fig:pdf-diagram or
 ![Wide Diagram](bigdiagram.pdf){#fig:pdf-diagram .landscape}
 ```
 
-````md
+````md {.small}
 ```mermaid {caption="Complicated Swimlane" #fig:landscape-swimlane width=3000 .landscape}
 sequenceDiagram
 Alice->>Bob: Hello

template/tcg.tex

@@ -147,6 +147,14 @@
 \usepackage{rotating}
 $endif$
 
+%
+% This is where the Haskell library skylighting will inject its definitions for the Shaded and Highlighting environments.
+% See also: https://github.com/jgm/pandoc/issues/7923
+%
+$if(highlighting-macros)$
+$highlighting-macros$
+$endif$
+
 % https://github.com/Wandmalfarbe/pandoc-latex-template/issues/391
 % We don't care to scale images.
 \newcommand*\pandocbounded[1]{#1}
@@ -344,11 +352,13 @@
 %
 % code block style
 %
-\definecolor{codeblock-background}{RGB}{240,244,255}
+\definecolor{codeblock-line}{RGB}{0,0,0}
+\definecolor{codeblock-background}{RGB}{255,255,255}
 \definecolor{codeblock-header}{RGB}{35,61,130}
 \usepackage{mdframed}
 \newmdenv[
-  linewidth=0pt,
+  linewidth=1pt,
+  linecolor=codeblock-line,
   backgroundcolor=codeblock-background,
   skipabove=5pt,
   nobreak=true]{customcodeblock}