Fix several minor issues with the tools. (#63)

Author: chrisfenner

Dockerfile

@@ -78,7 +78,7 @@ RUN pip install pandocfilters
 ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
     PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 
-RUN npm install --global --unsafe-perm [email protected] [email protected] [email protected] [email protected].6 [email protected]
+RUN npm install --global --unsafe-perm [email protected] [email protected] [email protected] [email protected].7 [email protected]
 
 # Install latest pandiff, which has not been released in a while
 # This pre-release build has --reference-doc support for docx output

build.sh

@@ -43,7 +43,7 @@ print_usage() {
 }
 
 
-if ! options=$(getopt --longoptions=help,puppeteer,notmp,gitversion,gitstatus,pdf:,latex:,docx:,resourcedir: --options="" -- "$@"); then
+if ! options=$(getopt --longoptions=help,puppeteer,notmp,gitversion,gitstatus,table_rules,pdf:,latex:,docx:,resourcedir: --options="" -- "$@"); then
 	echo "Incorrect options provided"
 	print_usage
 	exit 1
@@ -242,9 +242,11 @@ fi
 # Transform 1
 # GitHub Mermaid doesn't recognize the full ```{.mermaid ...} attributes-form
 # Pandoc doesn't recognized mixed ```mermaid {...} form
-# Hack: use sed to transform the former to the latter so everyone is happy
-sed 's/```mermaid *{/```{.mermaid /g' "${input_file}" > "${build_dir}/${input_file}.1"
-
+# Hack: use sed to transform the latter to the former so everyone is happy
+# Only transform if there is exactly one space after ```mermaid
+# Instructional documentation may use more than one space in the source code to suppress this.
+sed 's/```mermaid {/```{.mermaid /g' "${input_file}" > "${build_dir}/${input_file}.1"
+sed 's/```mermaid *{/```mermaid {/g' "${input_file}" > "${build_dir}/${input_file}.1"
 
 # Transform 2
 # \newpage is rendered as the string "\newpage" in GitHub markdown.
@@ -273,14 +275,15 @@ RESULT=0
 if [ -n "${pdf_output}" ]; then
 	echo "Generating PDF Output"
 	pandoc \
-		--dpi 300 \
 	    --pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--template=eisvogel.latex \
 		--filter=mermaid-filter \
+		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
+		--lua-filter=divide-code-blocks.lua \
 		--resource-path=.:/resources \
 		--data-dir=/resources \
 		--top-level-division=section \
@@ -312,14 +315,15 @@ fi
 if [ -n "${latex_output}" ]; then
 	echo "Generating LaTeX Output"
 	pandoc \
-		--dpi 300 \
 	    --pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--template=eisvogel.latex \
 		--filter=mermaid-filter \
+		--lua-filter=center-images \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
+		--lua-filter=divide-code-blocks.lua \
 		--resource-path=.:/resources \
 		--data-dir=/resources \
 		--top-level-division=section \
@@ -351,12 +355,12 @@ fi
 if [ -n "${docx_output}" ]; then
 	echo "Generating DOCX Output"
 	pandoc \
-		--dpi 150 \
 	    --pdf-engine=lualatex \
 		--embed-resources \
 		--standalone \
 		--filter=/resources/filters/info.py \
 		--filter=mermaid-filter \
+		--lua-filter=center-images.lua \
 		--lua-filter=parse-html.lua \
 		--filter=pandoc-crossref \
 		--resource-path=.:/resources \

filter/center-images.lua

@@ -0,0 +1,18 @@
+-- Center images (i.e., those produced by Mermaid): https://pandoc.org/lua-filters.html#center-images-in-latex-and-html-output
+
+function string:hassuffix(suffix)
+    return self:sub(-#suffix) == suffix
+end
+
+if FORMAT:match 'latex' then
+    function Image (elem)
+        return elem.src:hassuffix(".pdf")
+            -- Surround all pdf images with image-centering raw LaTeX.
+            and {
+                pandoc.RawInline('latex', '\\hfill\\break{\\centering'),
+                elem,
+                pandoc.RawInline('latex', '\\par}')
+            }
+            or elem
+    end
+end

filter/divide-code-blocks.lua

@@ -0,0 +1,9 @@
+-- draw horizontal rules above and below code blocks to separate them nicely
+
+function CodeBlock(block)
+    return {
+        pandoc.RawInline('latex', '\\noindent\\textcolor{gray}{\\rule{\\textwidth}{0.25pt}}'),
+        block,
+        pandoc.RawInline('latex', '\\noindent\\textcolor{gray}{\\rule{\\textwidth}{0.25pt}}'),
+    }
+end

guide.md

@@ -106,7 +106,7 @@ You can create a repository from scratch, or you can use
 to get started a little more quickly. There's a little green "Use this template" button in the top right
 (see @fig:use-template-button).
 
-![The "Use this template" button](use_template.jpg){#fig:use-template-button}
+![The "Use this template" button](use_template.jpg){#fig:use-template-button width=50%}
 
 ## GitHub Actions
 
@@ -183,7 +183,7 @@ The trickiest section is the YAML front matter at the very top of the Markdown f
 It looks like this:
 
 ```md
----
+--- 
 title: "TCG Markdown User's Guide"
 version: 0.1
 revision: 1
@@ -308,7 +308,7 @@ clicking on them.
 From this view, there is an "Edit" (pencil) button in the upper right-hand corner, pictured in
 @fig:edit-file-button:
 
-![GitHub Edit Button](edit_this_file.jpg){#fig:edit-file-button}
+![GitHub Edit Button](edit_this_file.jpg){#fig:edit-file-button width=30%}
 
 This will take you to a view where you can edit the file. There is a "Preview" button that you can use
 to see roughly how the changes will look when viewed from GitHub. Most everyday changes to TCG docs
@@ -317,7 +317,7 @@ can be previewed in high enough fidelity with this tool.
 When you're satisfied with your changes, use the green "Commit changes..." button. This will bring up
 the dialog box pictured in @fig:propose-changes:
 
-![Propose Changes Dialog](propose_changes.jpg){#fig:propose-changes}
+![Propose Changes Dialog](propose_changes.jpg){#fig:propose-changes width=60%}
 
 Include a descriptive commit message, extended description, and new branch name for your change,
 then click the green "Propose changes" button.
@@ -340,7 +340,7 @@ which looks like @fig:plus-button:
 After you've gone through all the changed files and provided your comments, you can click "Review changes"
 to finish the review. This dialog looks like @fig:finish-review:
 
-![Finish Review](finish_review.jpg){#fig:finish-review}
+![Finish Review](finish_review.jpg){#fig:finish-review width=60%}
 
 Here, you can provide summary comments and mark your review as one of:
 
@@ -359,13 +359,9 @@ The structure of the document is guided by lines that begin with `#`:
 
 ```md
 # Section Titles
-```
 
-```md
 ## Subsection Titles
-```
 
-```md
 ### Sub-subsection Titles
 ```
 
@@ -519,18 +515,20 @@ to the branch for the PR that reference the image, or you can do it in a subsequ
 Markdown syntax for including an image looks like `![Figure Title](filename)`. For example:
 
 ```md
-![Adding an Image](add_plus_button.jpg){#fig:add-plus-button}
+![Adding an Image](add_plus_button.jpg){#fig:add-plus-button width=60%}
 ```
 
 becomes:
 
-![Adding an Image](add_plus_button.jpg){#fig:add-plus-button}
+![Adding an Image](add_plus_button.jpg){#fig:add-plus-button width=60%}
 
 The `{#fig:add-plus-button}` attribute (note there are no spaces between the `)` and the `{`!) does two things:
 
 1. Includes the figure in the List of Figures (if you used `\listoffigures` as described in @sec:toc).
 2. Numbers the figure so you can reference it as @fig:add-plus-button by just typing `@fig:add-plus-button`.
 
+Including `width=60%` here specifies that the image should take up 60% of the page's width.
+
 ## Mermaid Charts
 
 [Mermaid](http://mermaid.js.org) is a language for text-based diagrams for inclusion in Markdown documents.
@@ -541,7 +539,7 @@ See the Mermaid website for a more exhaustive list of types of diagrams.
 Mermaid supports swim-lane digrams like the below with the following notation:
 
 ````md
-```mer​maid {caption="Startup Sequence"}
+```mermaid  {caption="Startup Sequence"}
 sequenceDiagram
 Host->>TPM: TPM2_Startup
 loop Measurements
@@ -569,7 +567,7 @@ Crossreferences to Mermaid diagrams are not currently supported.
 Mermaid supports flow-charts like the below with the following notation:
 
 ````md
-```mer​maid {caption="Flowchart"}
+```mermaid  {caption="Flowchart"}
 graph TD;
     A-->B;
     A-->C;

template/eisvogel.latex

@@ -60,7 +60,8 @@ $endif$
 \documentclass[
   paper=letter,
   captions=tableheading,
-  toc=sectionentrywithdots
+  toc=sectionentrywithdots,
+  numbers=noenddot
 ]{scrartcl}
 
 \usepackage{amsmath,amssymb}
@@ -363,17 +364,17 @@ $endif$
   \vskip 0.5em
   \begin{customblockquote}
   \list{}{\rightmargin=0em\leftmargin=0em}
-  \item\color{blockquote-text}\textbf{\textit{Start of informative comment}}
+  \item\color{blockquote-text}\textbf{\textit{\textcolor{gray}{\small Start of informative comment}}}
   \item\relax\color{blockquote-text}\ignorespaces
 }{
-  \item\color{blockquote-text}\textbf{\textit{End of informative comment}}
+  \item\color{blockquote-text}\textbf{\textit{\textcolor{gray}{\small End of informative comment}}}
   \unskip\unskip\endlist\end{customblockquote}
 }
 
 \usepackage{fontspec}
 \setmainfont{Arial}
 \setsansfont{Arial}
-\setmonofont{Source Code Pro}
+\setmonofont[Scale=0.9]{Source Code Pro}
 
 \usepackage{newunicodechar}
 % Use Arial Unicode to display various unicode symbols that might be present
@@ -698,6 +699,7 @@ $endif$
 % Allow TCG documents to use '\beginappendices' to easily mark the transition to appendices.
 \usepackage{appendix}
 \newcommand{\beginappendices}{
+  \newpage
   \appendix
   \appendixpage
   \addappheadtotoc