External LaTeX packages | Aspose.TeX for Java

External LaTeX packages

There is a number of common LaTeX packages included in the Aspose.TeX library for Java. So you don’t have to take care about how to provide these packages to the library’s TeX engine. But sometimes (maybe often) your LaTeX file may require a package beyond the “natively” supported “bundle” of packages. In this case, you can try to provide the required input, i.e. required package’s source files, using the setRequiredInputDirectory() method of the TeXOptions class instance. We will see how this works with two examples.

Set inputFile to the full path of the corresponding LaTeX document and outputDirectory to an existing output folder. Both conversion examples produce PNG at 150 DPI. Import the Aspose.TeX classes used in the selected snippet, com.aspose.tex.rendering.ImageDevice, com.aspose.tex.rendering.PngSaveOptions and, for ZIP input, java.io.InputStream and java.nio.file.Files. Handle or declare exceptions in the calling method. Apply a license as described in the licensing guide.

Unpacked required input (fancybox package)

Let’s say we have the following simple LaTeX file, which is required-input-fs.tex from our example solution:

\documentclass{article}
\usepackage[a6paper,landscape]{geometry}
\usepackage{fancybox}
\begin{document}
Test: \fbox{
  \begin{Bitemize}[b]
  \item First item
  \item A second one\\ on two lines
  \item(2pt) A third with extra space
  \end{Bitemize}
}
\par\bigskip
Test: \fbox{
  \begin{Beqnarray}
  y & = & x^2 \\
  a^2 + 2ab + b^2 & = & (a + b)^2 \\
  \int_0^\infty e^{-ax} dx & = & \frac{1}{a}
  \end{Beqnarray}
}
\end{document}

The third line requires the external fancybox package. Set packagesDirectory to a local folder containing fancybox.sty and its dependencies. The complete example below assigns this folder to RequiredInputDirectory and produces a PNG image. The device and working directories remain open until the job finishes and are then disposed or closed.

Here is the complete source code for the example:

// Render the fancybox document using external package sources from a local folder.
// inputFile is the full TeX input path; packagesDirectory contains fancybox.sty.
// outputDirectory is an existing output folder.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());
OutputFileSystemDirectory output = new OutputFileSystemDirectory(outputDirectory);
InputFileSystemDirectory packages = new InputFileSystemDirectory(packagesDirectory);
options.setOutputWorkingDirectory(output);
options.setRequiredInputDirectory(packages);
PngSaveOptions saving = new PngSaveOptions();
saving.setResolution(150);
options.setSaveOptions(saving);
options.setInteraction(Interaction.NonstopMode);
options.setTerminalOut(new OutputMemoryTerminal());
ImageDevice device = new ImageDevice();
TeXJobResult result;
int pages;
try {
    result = new TeXJob(inputFile, device, options).run();
    pages = device.getPageCount();
} finally {
    device.dispose();
    output.close();
    packages.close();
}

Archived required input (pgfplots package)

Let’s now assume that we have the following also quite simple LaTeX file, which is required-input-zip.tex from our example solution:

\documentclass{article}
\usepackage[margin=0.25in]{geometry}
\usepackage{pgfplots}
\pgfplotsset{width=10cm,compat=1.18}
\begin{document}

First example is 2D and 3D math expressions plotted side-by-side.

%Here begins the 2D plot
\begin{tikzpicture}
\begin{axis}
\addplot[color=red]{exp(x)};
\end{axis}
\end{tikzpicture}
%Here ends the 2D plot
\hskip 5pt
%Here begins the 3D plot
\begin{tikzpicture}
\begin{axis}
\addplot3[
    surf,
]
{exp(-x^2-y^2)*x};
\end{axis}
\end{tikzpicture}
%Here ends the 3D plot

\end{document}

On the 3rd line, we see that the file requires the pgfplots package, which is also not “natively” supported. Again, we assume that we have the pgfplots package source files. It’s quite a large set of files that are divided between two locations if you find them in the installation directory of any LaTeX typesetting application. You can find pgfplots folder at both \tex\generic and \tex\latex folders. And the contents of both these folders must be provided as required input to the Aspose.TeX library. We want these source file to be packaged in a ZIP archive, so here is the archive’s layout:

Set packagesZip to a java.nio.file.Path pointing to the archive containing both the generic and LaTeX package sources. The complete Java example below opens it with Files.newInputStream(...) and assigns an InputZipDirectory to RequiredInputDirectory. The empty base-path argument selects the whole archive. Keep the ZIP stream and directory open until the TeX job finishes, then close them. The result is a PNG image with the two plots.

Here is the complete source code for the example:

// Render the 2D/3D plots using pgfplots package sources from a ZIP archive.
// inputFile is the full TeX input path; packagesZip is a java.nio.file.Path.
// outputDirectory is an existing output folder; the ZIP includes generic and latex sources.
TeXJobResult result;
int pages;
try (InputStream zipStream = Files.newInputStream(packagesZip)) {
    TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());
    OutputFileSystemDirectory output = new OutputFileSystemDirectory(outputDirectory);
    InputZipDirectory packages = new InputZipDirectory(zipStream, "");
    options.setOutputWorkingDirectory(output);
    options.setRequiredInputDirectory(packages);
    PngSaveOptions saving = new PngSaveOptions();
    saving.setResolution(150);
    options.setSaveOptions(saving);
    options.setInteraction(Interaction.NonstopMode);
    options.setTerminalOut(new OutputMemoryTerminal());
    ImageDevice device = new ImageDevice();
    try {
        result = new TeXJob(inputFile, device, options).run();
        pages = device.getPageCount();
    } finally {
        device.dispose();
        output.close();
        packages.close();
    }
}

NOTE: The result was verified using the pgfplots package version 1.18.1. While the version of the pfg package included in the Aspose.TeX library is 3.1.9a.

Using external font packages

Typically, LaTeX distributions come with a selection of default fonts that can be used for typesetting. In addition to these fonts, Aspose.TeX offers several non-standard font packages, such as amsfonts, eurosym, and wasysym. As mentioned earlier, Aspose.TeX also supports the use of external packages, although our focus has mainly been on packages that do not include fonts.

The Object TeX engine extension in Aspose.TeX requires font maps, which are text files with the .map extension that specify the physical fonts corresponding to each TeX’s internal font name. These font maps need to be loaded into TeX’s memory during the initialization phase and must be included in the package files. Since the engine is not aware of the names of all font maps, it searches for any files with the .map extension. Therefore, the implementation of the IInputWorkingDirectory interface used as the value of the RequiredInputDirectory option must provide a way to access collections of file names based on their extension. Specifically, this implementation must also implement the IFileCollector interface. The standard implementations, InputFileSystemDirectory and InputZipDirectory, already fulfill this requirement.

The following custom RequiredInputDirectory implements both interfaces and reads explicitly registered local files. Save it as RequiredInputDirectory.java with its included imports. Register each file with storeFileName(...), then assign the instance using options.setRequiredInputDirectory(...) and close it after the job. It is a flat registry: filenames must be unique when requested without a full path. Extension matching is case-insensitive; the optional collection path selects a file-system directory. Register all required package, font-map, metric and physical font files. File collection makes maps discoverable; it does not supply missing font data.

import com.aspose.tex.IInputWorkingDirectory;
import com.aspose.tex.IFileCollector;
import com.aspose.tex.TeXInputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;

// Register local package files explicitly, including font maps and their dependencies.
// Save this class as RequiredInputDirectory.java and close it after the TeX job.
public class RequiredInputDirectory implements IInputWorkingDirectory, IFileCollector {
    private final Set<Path> files = new LinkedHashSet<Path>();
    private final List<TeXInputStream> streams = new ArrayList<TeXInputStream>();

    public void storeFileName(String fileName) {
        Path file = Paths.get(fileName).toAbsolutePath().normalize();
        if (!Files.isRegularFile(file)) {
            throw new IllegalArgumentException("Package file does not exist: " + file);
        }
        files.add(file);
    }

    @Override
    public TeXInputStream getFile(String fileName, boolean searchSubdirectories) {
        // This registry is a flat virtual directory; only registered files are accessible.
        for (Path file : files) {
            if (file.toString().equals(fileName) || file.getFileName().toString().equals(fileName)) {
                try {
                    TeXInputStream stream = new TeXInputStream(Files.newInputStream(file), file.toString());
                    streams.add(stream);
                    return stream;
                } catch (IOException exception) {
                    throw new UncheckedIOException(exception);
                }
            }
        }
        return new TeXInputStream(null, fileName);
    }

    @Override
    public String[] getFileNamesByExtension(String extension) {
        return getFileNamesByExtension(extension, null);
    }

    @Override
    public String[] getFileNamesByExtension(String extension, String path) {
        String requested = extension.toLowerCase(Locale.ROOT);
        if (!requested.isEmpty() && !requested.startsWith(".")) {
            requested = "." + requested;
        }
        Path directory = path == null ? null : Paths.get(path).toAbsolutePath().normalize();
        List<String> matches = new ArrayList<String>();
        for (Path file : files) {
            String name = file.getFileName().toString();
            int dot = name.lastIndexOf('.');
            String actual = dot < 0 ? "" : name.substring(dot).toLowerCase(Locale.ROOT);
            if (actual.equals(requested) && (directory == null || file.getParent().equals(directory))) {
                matches.add(file.toString());
            }
        }
        return matches.toArray(new String[0]);
    }

    @Override
    public void close() throws IOException {
        IOException failure = null;
        for (TeXInputStream stream : streams) {
            try {
                stream.close();
            } catch (IOException exception) {
                if (failure == null) { failure = exception; }
                else { failure.addSuppressed(exception); }
            }
        }
        streams.clear();
        files.clear();
        if (failure != null) { throw failure; }
    }
}

Restrictions

A package required by your LaTeX file may be developed under the LaTeX3e kernel. Such a package will most likely not work with the Aspose.TeX library since the latter is based on the LaTeX2e kernel.

Also, a package required by your LaTeX file may directly call device-dependent primitive commands that are not supported by the Aspose.TeX library’s Object TeX engine. Such a package, unfortunately, will not work for sure.