External LaTeX packages | .NET

External LaTeX packages

The Aspose.TeX library includes a number of common LaTeX packages. So you don’t have to worry about how to provide these packages to the library’s TeX engine. But sometimes (or quite often) your LaTeX file may require a package beyond the “natively” supported “bundle” of packages. If this is the case, you can try to provide the required input, i.e. required package’s source files, via the RequiredInputDirectory option 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 can see that the file requires the fancybox package, which is not “natively” supported. Let’s also assume that we have the fancybox package source file. It is a simple package, so it really consists of a single file. We can place this file anywhere in our file system and specify the directory path as simply as shown below:

options.RequiredInputDirectory = 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.OutputWorkingDirectory = new OutputFileSystemDirectory(RunExamples.OutputDirectory);
// Specify a file system working directory for the required input.
// The directory containing packages may be located anywhere.
options.RequiredInputDirectory = new InputFileSystemDirectory(Path.Combine(RunExamples.InputDirectory, "packages"));
// Initialize the options for saving in PNG format.
options.SaveOptions = new PngSaveOptions();
// Run LaTeX to PNG conversion.
new TeXJob(Path.Combine(RunExamples.InputDirectory, "required-input-fs.tex"), new ImageDevice(), options).Run();

Archived required input (pgfplots package)

Let’s now say 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 can 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 number 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 this is how we specify the access to these source files:

using (Stream zipStream = File.Open("path-to-zip-with-pgfplots-sources"), FileMode.Open))
{
    ...
    options.RequiredInputDirectory = new InputZipDirectory(zipStream);
    ...
}

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.OutputWorkingDirectory = new OutputFileSystemDirectory(RunExamples.OutputDirectory);
// Initialize the options for saving in PNG format.
options.SaveOptions = new PngSaveOptions();
// Create a file stream for the ZIP archive containing the required package.
// The ZIP archive may be located anywhere.
using (Stream zipStream = File.Open(Path.Combine(RunExamples.InputDirectory, "packages\\pgfplots.zip"), FileMode.Open))
{
    // Specify a ZIP working directory for the required input.
    options.RequiredInputDirectory = new InputZipDirectory(zipStream, "");
    
    // Run LaTeX to PNG conversion.
    new TeXJob(Path.Combine(RunExamples.InputDirectory, "required-input-zip.tex"), new ImageDevice(), options).Run();
}

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.

Employing external font packages

As a rule, LaTeX distributions provide a set of default fonts available for typesetting. Except these fonts, Aspose.TeX includes a number of non-standard font packages. For example, amsfonts, eurosym, and wasysym. As we saw above, Aspose.TeX also allows to employ external packages. But mostly we were talking about packages that don’t contain fonts.

The Aspose.TeX’s Object TeX engine extension needs font maps (which are text files in a certain format with the .map extension by convention) to determine which physical fonts correspond to each TeX’s internal font name. These font maps must be loaded into TeX’s memory during the initialization phase. And, of course, they must be present among the files of the package you are plugging in. Since the engine doesn’t know the names of all font maps, it looks for all files with the .map extension. Therefore, an implementation of the IInputWorkingDirectory interface that is used as a value of the RequiredInputDirectory option must provide a way to access collections of file names by extension. More specifically, this implementation must also implement the IFileCollector interface. The standard implementations - InputFileSystemDirectory and InputZipDirectory - already do it.

Below, we provide an illustrative example of a custom required input directory that also implements the IFileCollector interface. While focusing on collecting file names by extension, 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
// internal font names to file names of physical fonts.
public class RequiredInputDirectory : IInputWorkingDirectory, IFileCollector
{
    private Dictionary<string, Dictionary<string, string>> _fileNames =
        new Dictionary<string, Dictionary<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 = Path.GetExtension(fileName);
        string name = Path.GetFileNameWithoutExtension(fileName);
        
        Dictionary<string, string> files;
        if (!_fileNames.TryGetValue(extension, out files))
            _fileNames.Add(extension, files = new Dictionary<string, string>());

        files[name] = fileName;
    }

    // The IInputWorkingDirectory implementation.
    public NamedStream GetFile(string fileName, bool searchSubdirectories = false)
    {
        return new NamedStream(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, string path = null)
    {
        Dictionary<string, string> files;
        if (!_fileNames.TryGetValue(extension, out files))
            return new string[0];

        return new List<string>(files.Values).ToArray();
    }

    public void Dispose()
    {
        _fileNames.Clear();
    }
}

Restrictions

It may happen that a package required by your LaTeX file is 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.

It may also happen that a package required by your LaTeX file directly calls 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.