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

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

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

У 3-му рядку ми бачимо, що для файлу потрібен пакет 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. Такий пакет, на жаль, працювати точно не буде.