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

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

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

Укажите в inputFile полный путь к соответствующему документу LaTeX, а в outputDirectory — существующую папку вывода. Оба примера преобразования создают PNG с разрешением 150 DPI. Импортируйте классы Aspose.TeX из выбранного примера, com.aspose.tex.rendering.ImageDevice, com.aspose.tex.rendering.PngSaveOptions, а для ввода из ZIP — java.io.InputStream и java.nio.file.Files. Обрабатывайте или объявляйте исключения в вызывающем методе. Примените лицензию согласно руководству по лицензированию.

Распакованный требуемый ввод (пакет «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}
  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. Укажите в packagesDirectory локальную папку с fancybox.sty и его зависимостями. Полный пример ниже назначает эту папку параметру RequiredInputDirectory и создаёт изображение PNG. Устройство и рабочие папки остаются открытыми до завершения задания, затем освобождаются или закрываются.

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

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

Заархивированные необходимые данные (пакет 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-архив, поэтому вот макет архива:

Укажите в packagesZip значение java.nio.file.Path, указывающее на архив с generic- и LaTeX-исходниками пакета. Полный Java-пример ниже открывает его через Files.newInputStream(...) и назначает InputZipDirectory параметру RequiredInputDirectory. Пустой аргумент базового пути выбирает весь архив. Держите ZIP-поток и папку открытыми до завершения задания TeX, затем закройте их. Результат — изображение PNG с двумя графиками.

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

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

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

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

Следующий пользовательский RequiredInputDirectory реализует оба интерфейса и читает явно зарегистрированные локальные файлы. Сохраните его как RequiredInputDirectory.java вместе с включёнными импортами. Зарегистрируйте каждый файл через storeFileName(...), назначьте экземпляр через options.setRequiredInputDirectory(...) и закройте его после задания. Это плоский реестр: имена файлов должны быть уникальными при запросе без полного пути. Расширения сравниваются без учёта регистра; необязательный путь сбора выбирает папку файловой системы. Зарегистрируйте все необходимые файлы пакета, карты шрифтов, метрики и физические файлы шрифтов. Сбор файлов делает карты доступными для обнаружения, но не предоставляет недостающие данные шрифтов.

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

Ограничения

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

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