Build System Glossary Handling Issue

Problem

The current build system automatically runs makeglossaries after the first LaTeX compilation pass, regardless of whether the document actually uses glossaries. This causes build failures when testing with minimal documents that don't include glossary packages or commands.

Root Cause

Current Build Process Flow

1. First LaTeX pass: lualatex -interaction=nonstopmode manuscript.tex
2. Automatic makeglossaries: makeglossaries manuscript (always runs)
3. Final LaTeX passes: latexmk -pdf -lualatex manuscript.tex

Issue Details

Files affected:

• lib/codexis/core/latex_compiler.ex:185-189 - compile_all/2 function
• lib/codexis/builders/pdf_builder.ex:445-452 - compile_to_pdf/4 function

Behavior with minimal documents:

• LaTeX compilation succeeds and generates PDF
• makeglossaries fails with exit status 255: "No \@istfilename found in 'manuscript.aux'"
• Build process stops with error despite successful PDF generation

Expected makeglossaries behavior:

• Documents need \\makeglossaries command in preamble
• Documents need actual glossary entries (\\newglossaryentry, etc.)
• LaTeX generates auxiliary files (.glo, .ist) during compilation
• makeglossaries processes these auxiliary files to generate glossary content

Impact on Testing

This issue prevents:

• Performance optimization tests using minimal manuscripts
• CI/CD testing with simplified test documents
• Unit tests that don't require complex glossary functionality
• Format validation tests that focus on basic document structure

Solutions

Option 1: Conditional makeglossaries Execution (Recommended)

Check for glossary-related content before running makeglossaries:

defp should_run_makeglossaries?(tex_file_path, aux_file_path) do
  # Check if the main .tex file contains \makeglossaries command
  tex_content = File.read!(tex_file_path)
  has_makeglossaries_command = String.contains?(tex_content, "\\makeglossaries")
  
  # Check if .aux file exists and contains glossary-related markers
  aux_exists = File.exists?(aux_file_path)
  has_glossary_aux = if aux_exists do
    aux_content = File.read!(aux_file_path)
    String.contains?(aux_content, "@istfilename") or
    String.contains?(aux_content, "\\@glossarystyle")
  else
    false
  end
  
  has_makeglossaries_command and (has_glossary_aux or aux_exists)
end

Option 2: Suppress makeglossaries Errors

Continue build process even if makeglossaries fails:

{mg_output, mg_status} = System.cmd("makeglossaries", [basename], cd: working_dir_str)
Logger.info("makeglossaries output: #{mg_output}")

if mg_status != 0 do
  Logger.warning("makeglossaries failed with status #{mg_status}, continuing build...")
  # Don't return error, continue with build
end

Option 3: Build Option to Skip makeglossaries

Add build option to disable makeglossaries:

# In build options
skip_glossaries = Keyword.get(options, :skip_glossaries, false)

if not skip_glossaries do
  # Run makeglossaries
end

Recommended Implementation

Phase 1: Implement Option 2 (suppress errors) for immediate fix
Phase 2: Implement Option 1 (conditional execution) for robust solution
Phase 3: Add Option 3 (build option) for fine-grained control

This approach ensures:

• ✅ Existing complex manuscripts with glossaries continue to work
• ✅ Minimal test documents work without glossaries
• ✅ Performance tests can execute successfully
• ✅ No breaking changes to current build system
• ✅ Maintains flexibility for different document types

Testing Strategy

Test Cases Needed

1. Complex manuscript with glossaries (current manuscript.tex)

   • Should run makeglossaries successfully
   • Should generate proper glossary content in final output

2. Minimal manuscript without glossaries

   • Should skip makeglossaries or handle failure gracefully
   • Should generate valid PDF output

3. Manuscript with glossary packages but no entries

   • Should handle makeglossaries appropriately
   • Should not fail build process

4. Error handling

   • Should continue build even if makeglossaries fails
   • Should log appropriate warnings vs errors

Test Implementation

Update test fixtures to include:

• test/fixtures/test_manuscripts/with_glossaries/ - Full glossary usage
• test/fixtures/test_manuscripts/minimal_test/ - No glossary usage
• test/fixtures/test_manuscripts/empty_glossaries/ - Glossary packages but no entries

Clean-up

Remove temporary test directory:

rm -rf /Volumes/Storage/belmendo/Projects/codexis/test_makeglossaries