docs: revise thesis narrative, diagrams, and build layout

docs/thesis/generate.ps1

@@ -2,8 +2,16 @@
 # use pandoc -M to change the key: diagram:engine:mermaid:outputFormat to svg or pdf if output is html or pdf.
 # use the script at stuff/pandoc-diagram.ps1 to set the env vars and pass the filter to pandoc.
 param(
+    [Parameter(Mandatory = $true, HelpMessage = "The output type to generate. Must be either 'html' or 'pdf'.")]
     [string]$type,
-    [Parameter(ValueFromRemainingArguments = $true)]
+    [Parameter(Mandatory = $true, HelpMessage = "The input Markdown file to process.")]
+    [string]$InputFile = (Join-Path $PSScriptRoot "system-design-implementation.md"),
+    [string]$OutputFile = (Join-Path $PSScriptRoot "system-design-implementation.$type"),
+    [Parameter(ValueFromRemainingArguments = $true, HelpMessage = "Additional arguments to pass to pandoc.
+    
+    Notable use: 
+    - passing --resource-path to specify the directory where images and other resources are located,
+    - passing --pdf-engine=xelatex to specify the PDF engine for PDF output.")]
     [string[]]$RemainingArgs
 )
 function New-PandocDiagramMetadata([string] $outputFormat) {
@@ -100,24 +108,61 @@ if ($type -eq "pdf") {
     $title_pages_args = @("--include-in-header", $title_pages_header)
 }
 
+$tex_preamble_header = Join-Path $PSScriptRoot "header-includes.tex"
+if (-not (Test-Path $tex_preamble_header)) {
+    Write-Error "header-includes.tex is missing. Make sure the thesis preamble header exists."
+    exit 1
+}
+$html_preamble_header = Join-Path $PSScriptRoot "header-includes.html"
+if (-not (Test-Path $html_preamble_header)) {
+    Write-Error "header-includes.html is missing. Make sure the thesis preamble header exists."
+    exit 1
+}
+
+$preamble_args = @()
+if ($type -eq "pdf") {
+    $preamble_args += @("--include-in-header", $tex_preamble_header)
+}
+elseif ($type -eq "html") {
+    $preamble_args += @("--include-in-header", $html_preamble_header)
+}
+
+$info_md = Join-Path $PSScriptRoot "info.md"
+if (-not (Test-Path $info_md)) {
+    Write-Error "info.md is missing. Make sure the thesis info.md file exists."
+    exit 1
+}
+
+$input_files = @($info_md, $InputFile)
 
 $metatempfile = New-TemporaryFile
 $pandocExitCode = 0
 
+$pandoc_args = $(
+    @(
+        "--lua-filter", $include_markdown_filter,
+        "--lua-filter", $diagram_filter,
+        "--lua-filter", $figure_format_filter,
+        "--filter=pandoc-crossref",
+        "--pdf-engine=xelatex"
+    ) + 
+    $title_pages_args + 
+    $preamble_args + 
+    @(
+        "--metadata", "thesisFigureFormat=$outputFormat",
+        "--metadata", "thesisAgentResults=$agent_results",
+        "--metadata-file", $metatempfile,
+        "--embed-resources", "--standalone", "--citeproc"
+    ) +
+    $input_files + 
+    @("--output", $OutputFile) + 
+    $RemainingArgs
+).Where({ [string]::IsNullOrWhiteSpace($_) -eq $false })
+
 try {
     Set-Content -Path $metatempfile -Value $metadata
-    pandoc `
-        --lua-filter $include_markdown_filter `
-        --lua-filter $diagram_filter `
-        --lua-filter $figure_format_filter `
-        --filter=pandoc-crossref `
-        --pdf-engine=xelatex `
-        @title_pages_args `
-        --metadata thesisFigureFormat=$outputFormat `
-        --metadata thesisAgentResults=$agent_results `
-        --metadata-file=$metatempfile `
-        --embed-resources --standalone --citeproc `
-        @RemainingArgs
+    Write-Host "Running pandoc for file $($InputFile | Split-Path -Leaf) to generate $($OutputFile | Split-Path -Leaf)..."
+    pandoc @pandoc_args
     $pandocExitCode = $LASTEXITCODE
 }
 finally {