Add experimental support for redline PDFs

This adds experimental support for generating redline PDFs, using `latexdiff` as the driver.

As with many automated diff tools that don't record every individual edit, this struggles
with large section rewrites, hence "experimental", but hopefully provides a more visual form
of inspecting redlines.

In order to get latexdiff working effectively (e.g. using a more recent version), this also
requires updating the base Pandoc image to get the newer texlive repositories and tools,
which also necessitates updating the base template. In practice, however, there should be
no visual distinction.

As the tooling is largely written as a Bash entrypoint for Docker, the GitHub inputs are
renamed to be friendlier to accessing those in Bash, making this a breaking change from
previous versions. It also moves to explicitly provide output variables for the generated files,
rather than implicitly assuming a particular `GITHUB_WORKSPACE` layout/output. This
should make it more robust going forward and further isolate downstream projects of future
changes.

Dockerfile

@@ -1,12 +1,15 @@
-FROM pandoc/latex:2.9.2.1
+FROM pandoc/latex:2.11.2
 
 # Install the necessary LaTeX packages
 RUN tlmgr install \
   crimsonpro \
+  # Work around https://bugs.archlinux.org/task/67856 - needed by xecjk
+  ctex \
   draftwatermark \
   enumitem \
   everypage \
   fancyhdr \
+  latexdiff \
   parskip \
   sourcecodepro \
   sourcesanspro \

README.md

@@ -6,7 +6,7 @@ Groups to automatically produce Draft and Final Guidelines.
 
 ## Inputs
 
-### `markdown-file`
+### `markdown_file`
 
 **Required** The name of the Markdown file to convert. This should be relative
 to [`GITHUB_WORKSPACE`](https://docs.github.com/en/free-pro-team@latest/actions/reference/environment-variables).
@@ -15,9 +15,24 @@ In general, running [`actions/checkout`](https://github.com/actions/checkout)
 for the CWG repository is a necessary step before invoking this action, and
 allows just passing the filename relative to the current repository.
 
+### `diff_file`
+
+Optional: The path, relative to
+[`GITHUB_WORKSPACE`](https://docs.github.com/en/free-pro-team@latest/actions/reference/environment-variables),
+that contains the previous "version" of `markdown_file`.
+
+For example, on a `push` event, this would be the
+[`before`](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads#push)
+SHA-1's file (e.g. using [`actions/checkout`](https://github.com/actions/checkout)
+with a `ref` of `${{ github.event.push.before }}` and a custom `path`).
+
+This is fairly experimental and prone to break. Redlines are only generated
+if `pdf` is `"true"`. Further, if this path does not exist, a redline is
+simply not generated.
+
 ### `pdf`
 
-Generate a PDF from `markdown-file`. Default: `"true"`.
+Generate a PDF from `markdown_file`. Default: `"true"`.
 
 The resulting PDF will be in the same directory of `GITHUB_WORKSPACE` as the
 input file, but with a `pdf` extension.
@@ -56,12 +71,29 @@ Add a "DRAFT" watermark to the resulting document. Default: `"false"`
 
 This is currently only supported for PDF outputs.
 
+## Outputs
+
+### `pdf_file`
+
+The path to the generated PDF file, if `pdf` was `"true"`, relative to
+`GITHUB_WORKSPACE`.
+
+### `docx_file`
+
+The path to the generated DOCX file, if `docx` was `"true"`, relative to
+`GITHUB_WORKSPACE`.
+
+### `pdf_redline_file`
+
+The path to the generated PDF redline, if `pdf` was `"true"` and `diff_file`
+provided a path to a valid Markdown file.
+
 ## Example usage
 
 ```
 uses: cabforum/build-guidelines-action@v1
 with:
-  markdown-file: docs/BR.md
+  markdown_file: docs/BR.md
   draft: true
   lint: true
 ```

action.yml

@@ -1,9 +1,13 @@
 name: 'Build CA/Browser Forum Guideline'
 description: 'Convert a Pandoc-flavored Markdown file to PDF and DOCX using the CA/B Forum Guideline template'
 inputs:
-  markdown-file:
+  markdown_file:
     description: 'Name of the file to convert'
     required: true
+  diff_file:
+    description: 'Previous version to diff against (EXPERIMENTAL)'
+    required: false
+    default: ''
   pdf:
     description: 'Generate a PDF file (true/false)'
     required: false
@@ -20,8 +24,15 @@ inputs:
     description: 'Include a draft watermark (PDF-only for now) (true/false)'
     required: false
     default: 'false'
+outputs:
+  pdf_file:
+    description: 'The generated PDF file (if pdf was true), relative to GITHUB_WORKSPACE'
+  docx_file:
+    description: 'The generated DOCX file (if docx was true), relative to GITHUB_WORKSPACE'
+  pdf_redline_file:
+    description: 'The generated PDF redline file (if pdf was true and diff_file was supplied), relative to GITHUB_WORKSPACE'
 runs:
   using: 'docker'
   image: 'Dockerfile'
   args:
-    - ${{ inputs.markdown-file }}
+    - ${{ inputs.markdown_file }}

entrypoint.sh

@@ -6,11 +6,12 @@ INPUT_DRAFT="${INPUT_DRAFT:-false}"
 INPUT_PDF="${INPUT_PDF:-true}"
 INPUT_DOCX="${INPUT_DOCX:-true}"
 INPUT_LINT="${INPUT_LINT:-false}"
+INPUT_DIFF_FILE="${INPUT_DIFF_FILE:-}"
 TEXINPUTS="${TEXINPUTS:-}"
 
 if [ "$#" -ne 1 ]; then
   echo "No markdown file specified"
-  echo "Usage: $0 <markdown-file.md>"
+  echo "Usage: $0 <markdown_file.md>"
   exit 1
 fi
 if [ ! -f "$1" ]; then
@@ -23,6 +24,15 @@ if [ "${1##*.}" != "md" ] ; then
 fi
 BASE_FILE="${1%.*}"
 
+DIFF_FILE=
+if [ -n "${INPUT_DIFF_FILE}" ]; then
+  if [ -f "${INPUT_DIFF_FILE}" ] && [[ "${INPUT_DIFF_FILE}" =~ .*\.md ]]; then
+    DIFF_FILE="${INPUT_DIFF_FILE}"
+  else
+    echo "Skipping redline; unable to find ${INPUT_DIFF_FILE} or the filename doesn't end in .md"
+  fi
+fi
+
 PANDOC_ARGS=( -f markdown --table-of-contents -s )
 
 if [ "$INPUT_DRAFT" = "true" ]; then
@@ -42,7 +52,29 @@ if [ "$INPUT_PDF" = "true" ]; then
   pandoc "${PANDOC_ARGS[@]}" -t latex --template=/cabforum/templates/guideline.latex -o "${BASE_FILE}.tex" "${1}"
   TEXINPUTS="${TEXINPUTS}:/cabforum/" pandoc "${PANDOC_PDF_ARGS[@]}"
   set +x
+  echo "::set-output name=pdf_file::${BASE_FILE}.pdf"
   echo "::endgroup::"
+
+  if [ -n "${DIFF_FILE}" ]; then
+    echo "::group::Generating diff"
+    TMP_DIR=$(mktemp -d)
+    OUT_DIFF_TEX=$(basename "${DIFF_FILE}" ".md")
+    OUT_DIFF_TEX="${TMP_DIR}/${OUT_DIFF_TEX}"
+    set -x
+    pandoc "${PANDOC_ARGS[@]}" -t latex --template=/cabforum/templates/guideline.latex -o "${OUT_DIFF_TEX}.tex" "${DIFF_FILE}"
+    latexdiff --packages=hyperref "${OUT_DIFF_TEX}.tex" "${BASE_FILE}.tex" > "${OUT_DIFF_TEX}-redline.tex"
+    # Three runs in total are required (and match what Pandoc does under the hood)
+    TEXINPUTS="${TEXINPUTS}:/cabforum/" xelatex -interaction=nonstopmode --output-directory="${TMP_DIR}" "${OUT_DIFF_TEX}-redline.tex" || true
+    TEXINPUTS="${TEXINPUTS}:/cabforum/" xelatex -interaction=nonstopmode --output-directory="${TMP_DIR}" "${OUT_DIFF_TEX}-redline.tex" || true
+    TEXINPUTS="${TEXINPUTS}:/cabforum/" xelatex -interaction=nonstopmode --output-directory="${TMP_DIR}" "${OUT_DIFF_TEX}-redline.tex" || true
+    set +x
+    if [ -f "${OUT_DIFF_TEX}-redline.pdf" ]; then
+      cp "${OUT_DIFF_TEX}-redline.pdf" "${BASE_FILE}-redline.pdf"
+      echo "::set-output name=pdf_redline_file::${BASE_FILE}-redline.pdf"
+    fi
+    echo "::endgroup::"
+  fi
+
 fi
 
 if [ "$INPUT_DOCX" = "true" ]; then
@@ -55,6 +87,7 @@ if [ "$INPUT_DOCX" = "true" ]; then
   set -x
   pandoc "${PANDOC_DOCX_ARGS[@]}"
   set +x
+  echo "::set-output name=docx_file::${BASE_FILE}.docx"
   echo "::endgroup::"
 fi
 

templates/guideline.latex

@@ -21,7 +21,8 @@
 \usepackage{graphicx}
 
 % Used by Pandoc tables
-\usepackage{longtable,booktabs}
+\usepackage{longtable,booktabs, array}
+\usepackage{calc}
 
 % Configure colors
 \usepackage{xcolor}