Внешние пакеты LaTeX | Aspose.TeX для Java

Внешние пакеты LaTeX

Существует ряд общих пакетов LaTeX, включенных в библиотеку Aspose.TeX для Java. Таким образом, вам не нужно заботиться о том, как предоставить эти пакеты движку TeX библиотеки. Но иногда (возможно, часто) вашему файлу LaTeX может потребоваться пакет, выходящий за рамки «изначально» поддерживаемого «пакета» пакетов. В этом случае вы можете попытаться предоставить требуемые входные данные, то есть исходные файлы требуемого пакета, используя метод setRequiredInputDirectory() экземпляра класса TeXOptions. Мы увидим, как это работает, на двух примерах.

Распакованный требуемый ввод (пакет «fancybox»)

Допустим, у нас есть следующий простой файл LaTeX, который называется required-input-fs.tex из нашего примера решения:

\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}

В третьей строке мы видим, что для файла требуется пакет «fancybox», который «изначально» не поддерживается. Мы также предполагаем, что у нас есть исходный файл пакета «fancybox». Это простой пакет, поэтому он состоит всего из одного файла. Мы можем разместить этот файл в любом месте нашей файловой системы и указать путь к каталогу следующим образом:

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

После запуска задания TeX с этой опцией (не забудьте настроить другие параметры по мере необходимости) мы получим выходной документ (т. е. изображение PNG).

Вот полный исходный код примера:

// 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();

Заархивированные необходимые данные (пакет pgfplots)

Давайте теперь предположим, что у нас есть следующий также довольно простой файл LaTeX, который называется required-input-zip.tex из нашего примера решения:

\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}

В третьей строке мы видим, что для файла требуется пакет pgfplots, который также не поддерживается «изначально». Опять же, мы предполагаем, что у нас есть исходные файлы пакета pgfplots. Это довольно большой набор файлов, которые разделены между двумя местами, если вы найдете их в каталоге установки любого приложения для набора текста LaTeX. Вы можете найти папку pgfplots в папках \tex\generic и \tex\latex. И содержимое обеих этих папок должно быть предоставлено в качестве входных данных для библиотеки Aspose.TeX. Мы хотим, чтобы эти исходные файлы были упакованы в ZIP-архив, поэтому вот макет архива:

И вот как мы указываем доступ к этим исходным файлам:

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();
}

После запуска задания TeX с этой опцией мы получим выходной документ:

Вот полный исходный код примера:

// 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.

Использование внешних пакетов шрифтов

Обычно дистрибутивы LaTeX поставляются с набором шрифтов по умолчанию, которые можно использовать для набора текста. В дополнение к этим шрифтам Aspose.TeX предлагает несколько нестандартных пакетов шрифтов, таких как «amsfonts», «eurosym» и «wasysym». Как упоминалось ранее, Aspose.TeX также поддерживает использование внешних пакетов, хотя мы в основном фокусировались на пакетах, не включающих шрифты. Расширение движка Object TeX в Aspose.TeX требует карт шрифтов, которые представляют собой текстовые файлы с расширением .map, которые определяют физические шрифты, соответствующие внутреннему имени шрифта каждого TeX. Эти карты шрифтов необходимо загрузить в память TeX на этапе инициализации и включить в файлы пакета. Поскольку движку неизвестны названия всех карт шрифтов, он ищет любые файлы с расширением .map. Следовательно, реализация интерфейса IInputWorkingDirectory, используемого в качестве значения опции RequiredInputDirectory, должна предоставлять способ доступа к коллекциям имен файлов на основе их расширения. В частности, эта реализация также должна реализовывать интерфейс IFileCollector. Стандартные реализации InputFileSystemDirectory и InputZipDirectory уже удовлетворяют этому требованию.

Ниже мы представляем пример пользовательского обязательного входного каталога, который также реализует интерфейс IFileCollector. Наш основной акцент делается на сборе имен файлов на основе их расширения, и мы намеренно опускаем детали хранения и поиска файлов.

// 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();
    }
}

Ограничения

Пакет, необходимый для вашего файла LaTeX, может быть разработан под ядром LaTeX3e. Такой пакет, скорее всего, не будет работать с библиотекой Aspose.TeX, поскольку последняя основана на ядре LaTeX2e.

Кроме того, пакет, необходимый для вашего файла LaTeX, может напрямую вызывать зависящие от устройства примитивные команды, которые не поддерживаются механизмом Object TeX библиотеки Aspose.TeX. Такой пакет, к сожалению, точно не подойдет.