BUCKYVERSE

Fix EPUB Engine Command

This command resolves LaTeX engine compatibility issues when building EPUB files with Codexis, particularly addressing the fontspec package requirements for XeTeX or LuaLaTeX.

Problem

When building EPUB files using the build command with the epub format, you may encounter errors like:

[ERROR]   htlatex: Fatal Package fontspec Error: The fontspec package requires either XeTeX or
(fontspec)                      You must change your typesetting engine to,
(fontspec)                      e.g., "xelatex" or "lualatex" instead of
(fontspec)                      "latex" or "pdflatex".

This occurs because even though the -e lualatex flag is being passed to tex4ebook, the engine is not being properly set in all necessary places.

Solution

The fix-epub-engine command resolves this issue by:

  1. Creating or updating a tex4ebook configuration file to explicitly set the LaTeX engine
  2. Verifying that the necessary LaTeX engines are installed
  3. Ensuring proper environment configuration for EPUB building

Usage

# Default usage - sets up lualatex as the engine
codexis fix-epub-engine

# Specify a custom config file location
codexis fix-epub-engine --config /path/to/config.cfg

# Use xelatex instead of lualatex
codexis fix-epub-engine --engine xelatex

# Only validate the configuration without making changes
codexis fix-epub-engine --validate

# Enable verbose output for troubleshooting
codexis fix-epub-engine --verbose

Implementation Details

This command works by:

  1. Creating or updating a .tex4ebook.cfg file in your project or home directory
  2. Adding special configuration that forces tex4ebook to use the specified LaTeX engine
  3. Verifying that the required tools are installed and available in your PATH
  4. Providing debugging information to help diagnose any remaining issues

The EPUBBuilder module has also been updated to better handle LaTeX engine requirements, with additional environment variable settings and diagnostic information.

Additional Notes