External LaTeX packages | Python

External LaTeX packages

The Aspose.TeX library comes with a variety of common LaTeX packages, so there is no need to manually provide these packages to the TeX engine. However, there may be situations where your LaTeX file requires a package that is not included in the library’s “bundle” of packages. In such cases, you can try providing the necessary input, such as the source files of the required package, through the required_input_directory option of the TeXOptions class instance. We will explore how this works with two examples.

Required input provided in an unpacked form (the fancybox package).

Suppose we have the following basic LaTeX file named required-input-fs.tex, which is part of 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}

The 3rd line of the file indicates that it requires the fancybox package, which is not included in the “native” support. Let’s assume we have the source file for the fancybox package. Since it is a simple package consisting of a single file, we can place this file anywhere in our file system and specify the directory path as follows:

options.required_input_directory = InputFileSystemDirectory('path-to-directory-where-fancybox.sty-located')

Once we run a TeX job with this option (remember to adjust the other options as necessary), we will obtain the output document, which in this case is a PNG image.

Here is the complete source code for the example:

# Create conversion options for Object LaTeX format upon Object TeX engine extension.
options = TeXOptions.console_app_options(TeXConfig.object_latex)
# Specify a file system working directory for the output.
options.output_working_directory = OutputFileSystemDirectory(Util.output_directory)
# Specify a file system working directory for the required input.
# The directory containing packages may be located anywhere.
options.required_input_directory = InputFileSystemDirectory(path.join(Util.input_directory, "packages"))
# Initialize the options for saving in PNG format.
options.save_options = PngSaveOptions()
# Run LaTeX to PNG conversion.
TeXJob(path.join(Util.input_directory, "required-input-fs.tex"), ImageDevice(True), options).run()

Providing required input in an archived form (the pgfplots package)

Now, suppose we have the following LaTeX file named required-input-zip.tex, which is also a simple file 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 third line, it can be observed that the file necessitates the pgfplots package, which is not “natively” supported. Once again, assuming that we possess the source files for the pgfplots package, these files are quite numerous and are located in two different directories within the installation directory of any LaTeX typesetting application. The pgfplots folder can be found in both the \tex\generic and \tex\latex directories. For the Aspose.TeX library to function correctly, it is necessary to provide the contents of both these folders as input. To achieve this, we desire to package these source files into a ZIP archive. Below is the desired layout of the archive:

And here is the method by which we define the accessibility to these source files:

with open("path-to-zip-with-pgfplots-sources") as zipStream:
    ...
    options.required_input_directory = 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.
options = TeXOptions.console_app_options(TeXConfig.object_latex)
# Specify a file system working directory for the output.
options.output_working_directory = OutputFileSystemDirectory(Util.output_directory)
# Initialize the options for saving in PNG format.
options.save_options = PngSaveOptions()
# Create a file stream for the ZIP archive containing the required package.
# The ZIP archive may be located anywhere.
with open(path.join(Util.input_directory, "packages\\pgfplots.zip"), "rb") as zip_stream:
    # Specify a ZIP working directory for the required input.
    options.required_input_directory = InputZipDirectory(zip_stream, "")

    # Run LaTeX to PNG conversion.
    TeXJob(path.join(Util.input_directory, "required-input-zip.tex"), ImageDevice(True), 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.

Restrictions

If you come across a package that is developed under the LaTeX3e kernel anв is required by your LaTeX file, it is unlikely to work with the Aspose.TeX library. This is because the library is based on the LaTeX2e kernel.

In addition, there may be cases where a package required by your LaTeX file directly uses device-dependent primitive commands that are not supported by the Aspose.TeX library’s Object TeX engine. In such cases, the package will not work with the library.