Fix Docker container dependencies and improve LaTeX error reporting

Docker improvements:
- Add pkg-config, libcairo2-dev, libgirepository1.0-dev to system dependencies
- Add pycairo to Python dependencies in Docker image
- Replace runtime dependency installation with verification step

Build script improvements:
- Enhanced LaTeX error reporting with categorized error analysis
- Show critical errors, undefined control sequences, and missing files
- Provide clearer debugging information for LaTeX compilation failures

These changes should resolve:
- pycairo installation failures in CI
- Bikeshed warnings about missing pycairo
- Better debugging for LaTeX compilation issues

Author: pwt-cd

.github/workflows/build-deploy.yml

@@ -131,11 +131,14 @@ jobs:
           echo "🔍 Running comprehensive schema validation..."
           python3 ../../../.github/scripts/validate-schemas.py
 
-      - name: Fix container dependencies
+      - name: Verify container dependencies
         run: |
-          echo "🔧 Installing missing container dependencies..."
-          pip3 install -r /usr/local/lib/python3.10/dist-packages/requirements.txt || echo "⚠️ Requirements file not found, continuing..."
-          pip3 install pycairo || echo "⚠️ pycairo installation failed, attempting build anyway..."
+          echo "🔍 Verifying container dependencies..."
+          echo "Python packages:"
+          pip3 list | grep -E "(pycairo|bikeshed|jsonschema|pydantic)"
+          echo "System packages:"
+          dpkg -l | grep -E "(pkg-config|libcairo2-dev|libgirepository)"
+          echo "✅ Container dependencies verified"
 
       - name: Build documentation (HTML and PDF)
         working-directory: drafts/current/specifications

drafts/current/specifications/build.sh

@@ -347,8 +347,35 @@ build_pdf() {
             echo "   PDF was generated successfully despite warnings"
         else
             print_error "❌ LaTeX compilation failed on pass $pass (exit code: $LATEX_EXIT_CODE)"
+            echo ""
+            echo "🔍 LaTeX Error Analysis:"
+            echo "========================"
+            
+            # Show critical errors first
+            if grep -q "^! \|Emergency stop\|Fatal error" "build/latex-pass$pass.log" 2>/dev/null; then
+                echo "Critical LaTeX errors:"
+                grep -A3 -B1 "^! \|Emergency stop\|Fatal error" "build/latex-pass$pass.log" | head -20
+                echo ""
+            fi
+            
+            # Show undefined control sequence errors
+            if grep -q "Undefined control sequence" "build/latex-pass$pass.log" 2>/dev/null; then
+                echo "Undefined control sequence errors:"
+                grep -A2 -B1 "Undefined control sequence" "build/latex-pass$pass.log" | head -10
+                echo ""
+            fi
+            
+            # Show missing file errors
+            if grep -q "File.*not found\|No file" "build/latex-pass$pass.log" 2>/dev/null; then
+                echo "Missing file errors:"
+                grep -A1 -B1 "File.*not found\|No file" "build/latex-pass$pass.log" | head -10
+                echo ""
+            fi
+            
             echo "Last 20 lines of log:"
             tail -20 "build/latex-pass$pass.log"
+            echo ""
+            echo "💡 Full log available at: build/latex-pass$pass.log"
             exit 1
         fi
 

tools/Dockerfile

@@ -17,11 +17,14 @@ RUN apt-get update && apt-get install -y \
     pandoc \
     git \
     curl \
+    pkg-config \
+    libcairo2-dev \
+    libgirepository1.0-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Upgrade pip and install Python dependencies
 RUN pip install --upgrade pip && \
-    pip install bikeshed jsonschema pydantic[email] requests
+    pip install bikeshed jsonschema pydantic[email] requests pycairo
 
 # Initialize Bikeshed spec database (this takes time, so cache it in image)
 RUN bikeshed update