Зовнішні пакети LaTeX | Aspose.TeX для Java

Зовнішні пакети LaTeX

До бібліотеки Aspose.TeX для Java включено кілька поширених пакетів LaTeX. Тому вам не потрібно піклуватися про те, як надати ці Пакети механізму 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. Такий пакет, на жаль, працювати точно не буде.