Add manual PDF index

Update the options passed to pandoc and run it twice with `makeindex` in
between.

Add a Lua filter that passes through `\index` within HTML comments so that we
can custom add our index entries.

It would be nice to be able to use these index entries in the lunr.js search
results as well, but that will have to wait.

Author: garfieldnate

.github/workflows/build_pdf.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - fix_index
   workflow_dispatch:
 
 jobs:

docs/soar_manual/build.sh

@@ -20,7 +20,35 @@ pandoc \
     --listings \
     --number-sections \
     --lua-filter=docs/soar_manual/path_filter.lua \
+    --lua-filter=docs/soar_manual/index_filter.lua \
     -V geometry:"left=3cm, top=2.5cm, right=3cm, bottom=3cm" \
+    -V has-index \
+    docs/soar_manual/01_Introduction.md \
+    docs/soar_manual/02_TheSoarArchitecture.md \
+    docs/soar_manual/03_SyntaxOfSoarPrograms.md \
+    docs/soar_manual/04_ProceduralKnowledgeLearning.md \
+    docs/soar_manual/05_ReinforcementLearning.md \
+    docs/soar_manual/06_SemanticMemory.md \
+    docs/soar_manual/07_EpisodicMemory.md \
+    docs/soar_manual/08_SpatialVisualSystem.md \
+    docs/soar_manual/09_SoarUserInterface.md \
+    output/cli.tex \
+    -o output/SoarManual.pdf
+
+# Run makeindex to generate the index file
+cd output && makeindex SoarManual.idx && cd ..
+
+# Run pandoc again to include the index in the final PDF
+pandoc \
+    --pdf-engine=lualatex \
+    --resource-path=docs/soar_manual/ \
+    --template=docs/soar_manual/template.tex \
+    --listings \
+    --number-sections \
+    --lua-filter=docs/soar_manual/path_filter.lua \
+    --lua-filter=docs/soar_manual/index_filter.lua \
+    -V geometry:"left=3cm, top=2.5cm, right=3cm, bottom=3cm" \
+    -V has-index \
     docs/soar_manual/01_Introduction.md \
     docs/soar_manual/02_TheSoarArchitecture.md \
     docs/soar_manual/03_SyntaxOfSoarPrograms.md \

docs/soar_manual/index_filter.lua

@@ -0,0 +1,26 @@
+-- Pandoc Lua filter to extract LaTeX index commands from HTML comments
+-- This allows index entries to be hidden from MkDocs while being processed for PDF output
+
+function extractIndexFromComments(elem)
+    if elem.tag == "RawInline" and elem.format == "html" then
+        local comment = elem.text
+        -- Match HTML comments containing \index commands
+        local index_cmd = comment:match("<!%-%-.-\\index{(.-)}.-->")
+        if index_cmd then
+            -- Return LaTeX raw inline instead of HTML comment
+            return pandoc.RawInline("latex", "\\index{" .. index_cmd .. "}")
+        end
+        -- Match full \index{...} commands in comments
+        local full_index = comment:match("<!%-%-.-(\\\index{.-}).--->")
+        if full_index then
+            return pandoc.RawInline("latex", full_index)
+        end
+    end
+    return elem
+end
+
+return {
+    {
+        RawInline = extractIndexFromComments
+    }
+}

docs/soar_manual/template.tex

@@ -23,7 +23,7 @@
 % soar version information
 \newcommand{\SoarVersionMajor}{9}
 \newcommand{\SoarVersionMinor}{6}
-\newcommand{\SoarVersionRevision}{1}
+\newcommand{\SoarVersionRevision}{4}
 
 $if(linestretch)$
 \usepackage{setspace}
@@ -435,6 +435,9 @@
 $endif$
 
 \begin{document}
+$if(has-index)$
+\makeindex
+$endif$
 \begin{titlepage}
   \vspace{1.5in}
 
@@ -558,4 +561,7 @@
 $include-after$
 
 $endfor$
+$if(has-index)$
+\printindex
+$endif$
 \end{document}