Working with custom TeX formats in Java

Extend document compilation capabilities by creating, loading, and executing custom TeX format files (`.fmt`) using Aspose.TeX for Java. Beyond standard pre-configured configurations (like Plain TeX or ObjectLaTeX), Aspose.TeX allows developers to build custom format dumps with pre-loaded macro packages to significantly speed up repetitive typesetting jobs and support specialized TeX dialects.

In the TeX ecosystem, a format file (.fmt) is a binary dump of TeX’s memory state after loading a specific set of macro packages and command definitions (such as LaTeX or AMS-TeX). Using format files allows the TeX engine to skip parsing large macro libraries during every execution, drastically accelerating document compilation.

Aspose.TeX for Java supports both built-in formats and user-defined custom formats created programmatically. Supported output directory types:

The engine ObjectLaTeX is a standard LaTeX format based on the ObjectTeX engine extension used for the general LaTeX document compilation (articles, reports, books).
The engine ObjectTeX is a TeX format extended with ObjectTeX features used for the lightweight, macro-free TeX typesetting.
The engine Custom Format (.fmt) is a developer-created binary format containing pre-compiled macros/packages used for the high-performance batch compilation with pre-loaded custom macro sets.

Creating a Custom TeX Format File (.fmt)

Generate a custom format dump from a .tex initialization file (containing macro definitions like \font, \catcode, or \dump) using TeXFormatEngine.

import com.aspose.tex.*;
import java.io.IOException;

public class CreateCustomTeXFormat {
    public static void main(String[] args) throws IOException {
        // Set up options for creating a custom format using ObjectTeX
        TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectEngineOptions());

        // Define input and output working directories
        options.setInputWorkingDirectory(new InputFileSystemDirectory("C:/TeXProject/CustomMacros/"));
        options.setOutputWorkingDirectory(new OutputFileSystemDirectory("C:/TeXProject/Formats/"));

        // Run the format generation job on the custom macro source file (e.g., 'myformat.tex')
        // The source file must end with the \dump command
        TeXJob job = new TeXJob("myformat", new PdfDevice(), options);
        job.run();

        System.out.println("Custom TeX format created successfully.");
    }
}

Compiling documents with a custom TeX format

Load and execute an existing or newly generated .fmt file to process input TeX documents.

import com.aspose.tex.*;
import java.io.IOException;

public class RunWithCustomTeXFormat {
    public static void main(String[] args) throws IOException {
        // Define working directory where the custom format file resides
        IInputWorkingDirectory formatDir = new InputFileSystemDirectory("C:/TeXProject/Formats/");

        // Initialize options using the custom format name ('myformat') and location
        TeXOptions options = TeXOptions.consoleAppOptions(
            TeXConfig.customFormat("myformat", formatDir)
        );

        // Set input/output directories for the target TeX document
        options.setInputWorkingDirectory(new InputFileSystemDirectory("C:/TeXProject/Input/"));
        options.setOutputWorkingDirectory(new OutputFileSystemDirectory("C:/TeXProject/Output/"));

        // Compile the document using the pre-loaded custom format
        TeXJob job = new TeXJob("document", new PdfDevice(), options);
        job.run();

        System.out.println("Document compiled using custom TeX format successfully.");
    }
}

Using built-in engines and formats

For standard document processing, leverage built-in configurations provided by TeXConfig.

import com.aspose.tex.*;

public class BuiltInTeXFormats {
    public static void main(String[] args) throws Exception {
        // Option A: Standard ObjectLaTeX (LaTeX document class support)
        TeXOptions latexOptions = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());

        // Option B: Plain ObjectTeX (Plain TeX primitives)
        TeXOptions plainTexOptions = TeXOptions.consoleAppOptions(TeXConfig.objectTeX());

        System.out.println("Built-in TeX format options initialized.");
    }
}

Installation and Setup

Integrate Aspose.TeX for Java into your project using Maven:

Package Manager Console Command

<repository>
    <id>AsposeJavaAPI</id>
    <name>Aspose Java API</name>
    <url>https://repository.aspose.com/repo/</url>
</repository>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-tex</artifactId>
    <version>Latest</version>
</dependency>

Next Steps

FAQ

1. What is the advantage of using a custom format file (.fmt)?

Creating a custom format pre-loads macro packages into binary format. This eliminates the parsing overhead on every run, significantly speeding up high-volume document rendering pipelines.

2. What command must be included in the source file to create a .fmt file?

The source TeX file must end with the native \dump TeX command, which signals the engine to create the binary format snapshot.

3. Can I load format files stored inside a ZIP archive?

Yes. Pass an instance of InputZipDirectory as the format provider directory parameter in TeXConfig.customFormat().