Compiling Documents¶

This guide covers compiling LaTeX documents to PDF using jettex.

Basic Compilation¶

Using pdflatex¶

The most common LaTeX engine:

import jettex

result = jettex.pdflatex("document.tex")

if result.success:
    print(f"PDF created: {result.output_file}")
else:
    print(f"Error: {result.stderr}")

Using xelatex¶

For Unicode and OpenType fonts:

result = jettex.xelatex("document.tex")

Using lualatex¶

For Lua scripting and modern features:

result = jettex.lualatex("document.tex")

Using latexmk¶

For complex documents with bibliography, index, etc.:

result = jettex.latexmk("document.tex")

CompileResult Object¶

All compilation functions return a CompileResult object:

from jettex import CompileResult

result = jettex.pdflatex("document.tex")

# Check success
print(result.success)        # True or False

# Output file path
print(result.output_file)    # Path to PDF if successful

# Log file path
print(result.log_file)       # Path to .log file

# Command output
print(result.stdout)         # Standard output
print(result.stderr)         # Standard error

# Return code
print(result.returncode)     # 0 for success

Compilation Options¶

Output Directory¶

Specify where to put output files:

result = jettex.pdflatex(
    "document.tex",
    output_dir="/path/to/output"
)

Interaction Mode¶

Control how LaTeX handles errors:

# Non-stop mode (default) - don't stop on errors
result = jettex.pdflatex("document.tex", interaction="nonstopmode")

# Batch mode - no output, no stops
result = jettex.pdflatex("document.tex", interaction="batchmode")

# Scroll mode - show output but don't stop
result = jettex.pdflatex("document.tex", interaction="scrollmode")

# Error stop mode - stop on every error
result = jettex.pdflatex("document.tex", interaction="errorstopmode")

SyncTeX¶

Enable SyncTeX for editor synchronization:

result = jettex.pdflatex("document.tex", synctex=True)

Shell Escape¶

Enable shell escape for packages like minted:

result = jettex.pdflatex("document.tex", shell_escape=True)

Security Note

Only use shell escape with trusted documents, as it allows arbitrary command execution.

Quiet Mode¶

Suppress output:

result = jettex.pdflatex("document.tex", quiet=True)

Timeout¶

Set a compilation timeout:

# Timeout after 60 seconds
result = jettex.pdflatex("document.tex", timeout=60)

Extra Arguments¶

Pass additional arguments to the engine:

result = jettex.pdflatex(
    "document.tex",
    extra_args=["-file-line-error", "-halt-on-error"]
)

Using latexmk¶

latexmk automatically handles multiple compilation passes:

# Basic usage
result = jettex.latexmk("document.tex")

# Specify engine
result = jettex.latexmk("document.tex", engine="xelatex")
result = jettex.latexmk("document.tex", engine="lualatex")

# Clean auxiliary files after compilation
result = jettex.latexmk("document.tex", clean=True)

Cleaning Auxiliary Files¶

Remove auxiliary files created during compilation:

# Clean auxiliary files for a document
count = jettex.clean_auxiliary("document.tex")
print(f"Removed {count} files")

# Clean from a specific directory
count = jettex.clean_auxiliary("document.tex", output_dir="/path/to/output")

Files removed include: .aux, .log, .out, .toc, .lof, .lot, .fls, .fdb_latexmk, .synctex.gz, .bbl, .blg, .bcf, .run.xml, .idx, .ilg, .ind, .nav, .snm, .vrb, .xdv

Error Handling¶

result = jettex.pdflatex("document.tex")

if not result.success:
    # Check the log file for details
    if result.log_file and result.log_file.exists():
        log_content = result.log_file.read_text()
        print("Compilation log:")
        print(log_content[-2000:])  # Last 2000 chars

    # Or check stderr
    if result.stderr:
        print("Error output:")
        print(result.stderr)

CLI Compilation¶

Compile from the command line:

# Basic compilation
jettex compile document.tex

# Specify engine
jettex compile document.tex --engine xelatex

# Specify output directory
jettex compile document.tex --output-dir ./build

# Disable auto-install
jettex compile document.tex --no-auto-install

# Quiet mode
jettex compile document.tex --quiet