External LaTeX packages | 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.

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}[t]
  y & = & x^2 \\
  a^2 + 2ab + b^2 & = & (a + b)^2 \\
  \int_0^\infty e^{-ax} dx & = & \frac{1}{a}
  \end{Beqnarray}
}
\end{document}

On the 3rd line, we see that the file requires the fancybox package, which is not “natively” supported. We also assume that we have the fancybox package source file. It is a simple package, so it really consists of just one file. We can place this file anywhere in our file system and specify the directory path as simply as follows:

options.setRequiredInputDirectory(new InputFileSystemDirectory("path-to-directory-where-fancybox.sty-located"));

After running a TeX job with this option (don’t forget to adjust the other options as needed), we get the output document (i.e., a PNG image).

Here is the complete source code for the example:

// Create conversion options for Object LaTeX format upon Object TeX engine extension.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());
// Specify a file system working directory for the output.
options.setOutputWorkingDirectory(new OutputFileSystemDirectory(Utils.getOutputDirectory()));
// Specify a file system working directory for the required input.
// The directory containing packages may be located anywhere.
options.setRequiredInputDirectory(new InputFileSystemDirectory(Utils.getInputDirectory() + "packages"));
// Initialize the options for saving in PNG format.
options.setSaveOptions(new PngSaveOptions());
// Run LaTeX to PNG conversion.
new TeXJob(Utils.getInputDirectory() + "required-input-fs.tex", new ImageDevice(), options).run();

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:

And here is how we specify the access to these source files:

final Stream zipStream = File.Open("path-to-zip-with-pgfplots-sources"), FileMode.Open))
try {
    ...
    options.setRequiredInputDirectory(new InputZipDirectory(zipStream));
    ...
} finally {
    if (zipStream != null)
        zipStream.close();
}

After running a TeX job with this option, we get the output document:

Here is the complete source code for the example:

// Create conversion options for Object LaTeX format upon Object TeX engine extension.
TeXOptions options = TeXOptions.consoleAppOptions(TeXConfig.objectLaTeX());
// Specify a file system working directory for the output.
options.setOutputWorkingDirectory(new OutputFileSystemDirectory(Utils.getOutputDirectory()));
// Initialize the options for saving in PNG format.
options.setSaveOptions(new PngSaveOptions());
// Create a file stream for the ZIP archive containing the required package.
// The ZIP archive may be located anywhere.
final InputStream stream = new FileInputStream(Utils.getInputDirectory() + "packages\\pgfplots.zip");
try {
    // Specify a ZIP working directory for the required input.
    options.setRequiredInputDirectory(new InputZipDirectory(stream, ""));
    
    // Run LaTeX to PNG conversion.
    new TeXJob(Utils.getInputDirectory() + "required-input-zip.tex", new ImageDevice(), options).run();
} finally {
    if (stream != null)
        stream.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.

Below, we present an example of a custom required input directory that also implements the IFileCollector interface. Our main emphasis is on gathering file names based on their extension, and we intentionally omit the details of file storage and retrieval.

// This is an implementation of IInputWorkingDirectory that is suitable for the TeX job's RequiredInputDirectory option
// in case required input contains fonts provided by external packages.
// The class additionally implements IFileCollector, which provides access to file collections by extension.
// This is necessary to load external font maps, which are files (outside TeX syntax) that map TeX's
public class RequiredInputDirectory implements IInputWorkingDirectory, IFileCollector
{
    private Map<String, Map<String, String>> _fileNames = new HashMap<String, Map<String, String>>();

    public RequiredInputDirectory()
    { 
    }

    // This method should preliminarily be called for each file entry that is supposed to be located inside
    // the required input directory. Inside is an example of how the dictionary of file names could be organized
    // for easy collection of file names by extension.
    // Here fileName is a full file name. This can be a file path on a file system, a URL, or whatever else (theoretically).
    public void storeFileName(String fileName)
    {
        String extension = getExtension(fileName);
        String name = getFileNameWithoutExtension(fileName);

        Map<String, String> files = _fileNames.get(extension);
        if (files == null)
            _fileNames.put(extension, files = new HashMap<String, String>());

        files.put(name, fileName);
    }

    // The IInputWorkingDirectory implementation.
    public TeXInputStream getFile(String fileName, boolean searchSubdirectories)
    {
        return new TeXInputStream(null, fileName); // Here we actually return a stream for the file requested by its name.
    }
    
    // Here is how we gather file collections by extension.
    public String[] getFileNamesByExtension(String extension)
    {
    	return getFileNamesByExtension(extension, null);
    }

    // Here is how we gather file collections by extension.
    public String[] getFileNamesByExtension(String extension, String path)
    {
        Map<String, String> files = _fileNames.get(extension);
        if (files == null)
            return new String[0];
        
        return files.values().toArray(new String[0]);
    }
    
    private String getExtension(String fileName)
    {
    	int pos = fileName.indexOf('.');
    	if (pos < 0)
    		return "";
    	
    	return fileName.substring(pos);
    }
    
    private String getFileNameWithoutExtension(String fileName)
    {
    	int pos = fileName.lastIndexOf('/');
    	if (pos >= 0)
    		fileName = fileName.substring(pos + 1);
    	
    	pos = fileName.indexOf('.');
    	if (pos < 0)
    		return fileName;
    	
    	return fileName.substring(0, pos);
    }

    public void close()
    {
        _fileNames.clear();
    }
}

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.