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

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

Бібліотека Aspose.TeX включає кілька загальних пакетів LaTeX. Тож вам не доведеться турбуватися про те, як надати ці Пакети механізму TeX бібліотеки. Але іноді (або досить часто) для вашого файлу LaTeX може знадобитися пакет, окрім “нативно” підтримуваного “набору” пакетів. Якщо це так, ви можете спробувати надати необхідні вхідні дані, тобто вихідні файли необхідного пакета, за допомогою параметра RequiredInputDirectory екземпляра класу 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.RequiredInputDirectory = 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.OutputWorkingDirectory = new OutputFileSystemDirectory(RunExamples.OutputDirectory);
// Specify a file system working directory for the required input.
// The directory containing packages may be located anywhere.
options.RequiredInputDirectory = new InputFileSystemDirectory(Path.Combine(RunExamples.InputDirectory, "packages"));
// Initialize the options for saving in PNG format.
options.SaveOptions = new PngSaveOptions();
// Run LaTeX to PNG conversion.
new TeXJob(Path.Combine(RunExamples.InputDirectory, "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}

У 3-му рядку ми бачимо, що для файлу потрібен пакет pgfplots, який також не підтримується “нативно”. Знову ж таки, ми припускаємо, що у нас є вихідні файли пакета pgfplots. Це досить велика кількість файлів, які розділені між двома розташуваннями, якщо ви знайдете їх у каталозі інсталяції будь-якої програми верстки LaTeX. Ви можете знайти папку pgfplots у папках \tex\generic і \tex\latex. І вміст обох цих папок має бути надано як необхідні вхідні дані для бібліотеки Aspose.TeX. Ми хочемо, щоб ці вихідні файли були запаковані в ZIP-архів, тому ось макет архіву:

І ось як ми визначаємо доступ до цих вихідних файлів:

using (Stream zipStream = File.Open("path-to-zip-with-pgfplots-sources"), FileMode.Open))
{
    ...
    options.RequiredInputDirectory = new InputZipDirectory(zipStream);
    ...
}

Після виконання завдання 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.OutputWorkingDirectory = new OutputFileSystemDirectory(RunExamples.OutputDirectory);
// Initialize the options for saving in PNG format.
options.SaveOptions = new PngSaveOptions();
// Create a file stream for the ZIP archive containing the required package.
// The ZIP archive may be located anywhere.
using (Stream zipStream = File.Open(Path.Combine(RunExamples.InputDirectory, "packages\\pgfplots.zip"), FileMode.Open))
{
    // Specify a ZIP working directory for the required input.
    options.RequiredInputDirectory = new InputZipDirectory(zipStream, "");
    
    // Run LaTeX to PNG conversion.
    new TeXJob(Path.Combine(RunExamples.InputDirectory, "required-input-zip.tex"), new ImageDevice(), options).Run();
}

ПРИМІТКА: Результат було перевірено за допомогою пакета pgfplots версії 1.18.1. У той час як версія пакета pfg, включеного в бібліотеку Aspose.TeX, є 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
// internal font names to file names of physical fonts.
public class RequiredInputDirectory : IInputWorkingDirectory, IFileCollector
{
    private Dictionary<string, Dictionary<string, string>> _fileNames =
        new Dictionary<string, Dictionary<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 = Path.GetExtension(fileName);
        string name = Path.GetFileNameWithoutExtension(fileName);
        
        Dictionary<string, string> files;
        if (!_fileNames.TryGetValue(extension, out files))
            _fileNames.Add(extension, files = new Dictionary<string, string>());

        files[name] = fileName;
    }

    // The IInputWorkingDirectory implementation.
    public NamedStream GetFile(string fileName, bool searchSubdirectories = false)
    {
        return new NamedStream(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, string path = null)
    {
        Dictionary<string, string> files;
        if (!_fileNames.TryGetValue(extension, out files))
            return new string[0];

        return new List<string>(files.Values).ToArray();
    }

    public void Dispose()
    {
        _fileNames.Clear();
    }
}

Обмеження

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

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