Add more support for HTML. (#225)

* Add more support for HTML.

The support is currently marked "experimental" as some features do not
work correctly or are untested.

* Update README.md

Co-authored-by: Chris Fenner <cfenn@google.com>

---------

Co-authored-by: Chris Fenner <cfenn@google.com>

Author: bluegate010

README.md

@@ -80,10 +80,29 @@ You can then run the following:
 
 ```sh
 ./docker_run \
-  --extra_resource_dir path/to/resource_dir \
+  --extra_resource_dir path/to/my_resource_dir \
   --template extra/my_resource_dir/template.tex \
   --reference_doc extra/my_resource_dir/reference_doc.docx \
   --csl extra/my_resource_dir/reference_style.csl \
   --pdf output.pdf \
   input.tcg
 ```
+
+## Rendering HTML (experimental)
+
+HTML support is experimental. Known issues:
+
+- `\listoffigures` and `\listoftables` are not supported, as they render without clickable links.
+- Mermaid figures currently render as fixed-width.
+
+To render a document to HTML:
+
+```sh
+./docker_run \
+  --extra_resource_dir path/to/my_resource_dir \
+  --template_html extra/my_resource_dir/html.template \
+  --html_stylesheet extra/my_resource_dir/style1.css \
+  --html_stylesheet extra/my_resource_dir/style2.css \
+  --html output.html \
+  input.tcg
+```

build.sh

@@ -532,6 +532,9 @@ if [ "${BLOCK_QUOTES_ARE_INFORMATIVE_TEXT}" == "yes" ]; then
 fi
 
 # Use sed to perform some basic fixups on certain input files.
+#
+# If the second argument is provided and is "html", strip out `\listoffigures` and `\listoftables`,
+# as these don't render correctly in HTML.
 do_md_fixups() {
 	local input=$1
 	# \newpage is rendered as the string "\newpage" in GitHub markdown.
@@ -563,6 +566,15 @@ do_md_fixups() {
 			EOF
 		fi
 	fi
+
+	# These don't render correctly:
+	#  - The lists are raw text and not clickable entries.
+	#  - The "List of Figures" and "List of Tables" headers show up in the toc
+	#    as raw text and not clickable entries.
+	if test "$2" == "html"; then
+		sed -i.bak 's/^\\listoffigures$//g' "${input}"
+		sed -i.bak 's/^\\listoftables$//g' "${input}"
+	fi
 }
 
 # latexdiff is pretty great, but it has some incompatibilities with our template, so we
@@ -693,6 +705,22 @@ analyze_latex_logs() {
 	fi
 }
 
+# Copy generated files (if any) back to the source directory so they can be cached and speed up future runs.
+cache_generated_files() {
+	find . -type f \( \
+		-name "*.aux" -o \
+		-name "*.lof" -o \
+		-name "*.lot" -o \
+		-name "*.toc" -o \
+		-name "*.upa" -o \
+		-name "*.upb" -o \
+		-name "*.convert.pdf" -o \
+		-name "*.mermaid.pdf" -o \
+		-name "*.mermaid.svg" -o \
+		-name "*.aasvg.pdf" \
+	\) -exec cp --parents {} "${SOURCE_DIR}" \; 2>/dev/null
+}
+
 # Takes Markdown input and writes LaTeX output using pandoc.
 do_latex() {
 	local input=$1
@@ -777,18 +805,7 @@ do_pdf() {
 	# Write any LaTeX errors to stderr.
 	>&2 grep -A 5 "] ! " "${logfile}"
 
-	# Copy generated files (if any) back to the source directory so they can be cached and speed up future runs.
-	find . -type f \( \
-		-name "*.aux" -o \
-		-name "*.lof" -o \
-		-name "*.lot" -o \
-		-name "*.toc" -o \
-		-name "*.upa" -o \
-		-name "*.upb" -o \
-		-name "*.convert.pdf" -o \
-		-name "*.mermaid.pdf" -o \
-		-name "*.aasvg.pdf" \
-	\) -exec cp --parents {} "${SOURCE_DIR}" \; 2>/dev/null
+	cache_generated_files
 	echo "Elapsed time: $(($end-$start)) seconds"
 	# Write any LaTeX errors to stderr.
 	>&2 grep -A 5 "! " "${logfile}"
@@ -846,6 +863,8 @@ do_docx() {
 	else
 		echo "DOCX output generated to file: ${output}"
 	fi
+
+	cache_generated_files
 }
 
 # Takes Markdown input and writes HTML output using pandoc.
@@ -884,6 +903,10 @@ do_html() {
 		--metadata=logo:/resources/img/tcg.png
 		--metadata=titlepage-rule-height:0
 		--metadata=colorlinks:true
+		--metadata=link-bibliography
+		--metadata=link-citations
+		--metadata=link-references
+		--citeproc
 		--metadata=contact:admin@trustedcomputinggroup.org
 		--from=${FROM}
 		${EXTRA_PANDOC_OPTIONS}
@@ -895,6 +918,7 @@ do_html() {
 		FAILED=true
 		echo "HTML output failed"
 	else
+		cache_generated_files
 		echo "HTML output generated to file: ${output}"
 	fi
 }
@@ -924,6 +948,7 @@ fi
 
 # Generate the html output
 if [ -n "${HTML_OUTPUT}" ]; then
+	do_md_fixups "${BUILD_DIR}/${INPUT_FILE}" "html"
 	do_html "${BUILD_DIR}/${INPUT_FILE}" "${SOURCE_DIR}/${HTML_OUTPUT}" "${CROSSREF_TYPE}"
 fi
 

filter/mermaid-filter.lua

@@ -1,6 +1,22 @@
 -- Turn mermaid-classed code blocks into figures, retaining other classes on the
 -- code block as classes on the figure.
 
+output_classes =
+{
+    ["pdf"] = {
+        ["extension"] = ".mermaid.pdf",
+        ["image_attrs"] = {},
+    },
+    ["html"] = {
+        ["extension"] = ".mermaid.svg",
+        ["image_attrs"] = {
+            "", -- No identifier
+            {}, -- No classes
+            {width = "500px"}
+        },
+    }
+}
+
 function runCommandWithInput(command, input)
     local pipe = io.popen(command, "w")
     if not pipe then
@@ -26,7 +42,9 @@ function fileExists(file)
 end
 
 function mermaidFigure(code, caption, attrs)
-    local filename = getContentsHash('code=' .. code .. 'caption=' .. pandoc.utils.stringify(caption) .. 'attrs=' .. pandoc.utils.stringify(attrs)) .. '.mermaid.pdf'
+    output_class = output_classes[FORMAT] or output_classes["pdf"]
+
+    local filename = getContentsHash('code=' .. code .. 'caption=' .. pandoc.utils.stringify(caption) .. 'attrs=' .. pandoc.utils.stringify(attrs)) .. output_class["extension"]
     if fileExists(filename) then
         print(string.format('%s already exists; not re-rendering it', filename))
     else
@@ -38,7 +56,7 @@ function mermaidFigure(code, caption, attrs)
         end
     end
 
-    local img = pandoc.Image(caption, filename)
+    local img = pandoc.Image(caption, filename, "", output_class["image_attrs"])
     return pandoc.Figure(img, caption, attrs)
 end