Externe LaTeX-Pakete | API für .NET

Externe LaTeX-Pakete

Die Aspose.TeX-Bibliothek enthält eine Reihe gängiger LaTeX-Pakete. Sie müssen sich also keine Gedanken darüber machen, wie Sie diese Pakete der TeX-Engine der Bibliothek bereitstellen. Aber manchmal (oder ziemlich oft) erfordert Ihre LaTeX-Datei möglicherweise ein Paket, das über das „nativ“ unterstützte „Paketpaket“ hinausgeht. Wenn dies der Fall ist, können Sie versuchen, die erforderliche Eingabe, d. h. die Quelldateien des erforderlichen Pakets, über die Option RequiredInputDirectory der Klasseninstanz TeXOptions bereitzustellen. Wir werden anhand von zwei Beispielen sehen, wie das funktioniert.

Entpackte erforderliche Eingabe („fancybox“-Paket)

Nehmen wir an, wir haben die folgende einfache LaTeX-Datei, die „required-input-fs.tex“ aus unserer Beispiellösung ist:

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

In der dritten Zeile können wir sehen, dass die Datei das Paket „fancybox“ erfordert, das nicht „nativ“ unterstützt wird. Nehmen wir außerdem an, dass wir die Quelldatei des Pakets „fancybox“ haben. Da es sich um ein einfaches Paket handelt, besteht es eigentlich aus einer einzigen Datei. Wir können diese Datei an einer beliebigen Stelle in unserem Dateisystem platzieren und den Verzeichnispfad wie folgt angeben:

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

Nachdem wir einen TeX-Job mit dieser Option ausgeführt haben (vergessen Sie nicht, die anderen Optionen nach Bedarf anzupassen), erhalten wir das Ausgabedokument (d. h. ein PNG-Bild).

Hier ist der vollständige Quellcode für das Beispiel:

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

Archivierte erforderliche Eingabe (Paket „pgfplots“)

Nehmen wir nun an, dass wir die folgende ebenfalls recht einfache LaTeX-Datei haben, nämlich „required-input-zip.tex“ aus unserer Beispiellösung:

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

In der dritten Zeile sehen wir, dass die Datei das Paket „pgfplots“ erfordert, das ebenfalls nicht „nativ“ unterstützt wird. Auch hier gehen wir davon aus, dass wir über die Quelldateien des Pakets „pgfplots“ verfügen. Es handelt sich um eine ziemlich große Anzahl von Dateien, die auf zwei Speicherorte verteilt sind, wenn Sie sie im Installationsverzeichnis einer beliebigen LaTeX-Satzanwendung finden. Sie finden den Ordner „pgfplots“ sowohl im Ordner „\tex\generic“ als auch im Ordner „\tex\latex“. Und der Inhalt dieser beiden Ordner muss als erforderliche Eingabe für die Aspose.TeX-Bibliothek bereitgestellt werden. Wir möchten, dass diese Quelldateien in ein ZIP-Archiv gepackt werden. Hier ist das Layout des Archivs:

Und so legen wir den Zugriff auf diese Quelldateien fest:

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

Nachdem wir einen TeX-Job mit dieser Option ausgeführt haben, erhalten wir das Ausgabedokument:

Hier ist der vollständige Quellcode für das Beispiel:

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

HINWEIS: Das Ergebnis wurde mit dem Paket pgfplots, Version 1.18.1, überprüft. Die Version des pfg-Pakets, das in der Aspose.TeX-Bibliothek enthalten ist, ist 3.1.9a.

Verwendung externer Schriftartenpakete

In der Regel stellen LaTeX-Distributionen eine Reihe von Standardschriftarten für den Schriftsatz zur Verfügung. Außer diesen Schriftarten enthält Aspose.TeX eine Reihe nicht standardmäßiger Schriftartenpakete. Zum Beispiel „amsfonts“, Eurosym und „wasysym“. Wie wir oben gesehen haben, ermöglicht Aspose.TeX auch die Verwendung externer Pakete. Aber meistens haben wir über Pakete gesprochen, die keine Schriftarten enthalten.

Die Object TeX-Engine-Erweiterung von Aspose.TeX benötigt Schriftartenzuordnungen (bei denen es sich laut Konvention um Textdateien in einem bestimmten Format mit der Erweiterung „.map“ handelt), um zu bestimmen, welche physischen Schriftarten dem internen Schriftartennamen jedes TeX entsprechen . Diese Schriftartenzuordnungen müssen während der Initialisierungsphase in den Speicher von TeX geladen werden. Und natürlich müssen sie in den Dateien des Pakets vorhanden sein, das Sie einbinden. Da die Engine nicht die Namen aller Schriftartenzuordnungen kennt, sucht sie nach allen Dateien mit der Erweiterung „.map“. Daher muss eine Implementierung der Schnittstelle IInputWorkingDirectory, die als Wert der Option RequiredInputDirectory verwendet wird, eine Möglichkeit bieten, über die Erweiterung auf Sammlungen von Dateinamen zuzugreifen. Genauer gesagt muss diese Implementierung auch die Schnittstelle IFileCollector implementieren. Die Standardimplementierungen – InputFileSystemDirectory und InputZipDirectory – tun dies bereits.

Nachfolgend stellen wir ein anschauliches Beispiel für ein benutzerdefiniertes erforderliches Eingabeverzeichnis bereit, das auch die Schnittstelle IFileCollector implementiert. Während wir uns auf das Sammeln von Dateinamen nach Erweiterung konzentrieren, lassen wir die Details zum Speichern und Abrufen von Dateien bewusst weg.

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

Einschränkungen

Es kann vorkommen, dass ein für Ihre LaTeX-Datei erforderliches Paket unter dem LaTeX3e-Kernel entwickelt wird. Ein solches Paket wird höchstwahrscheinlich nicht mit der Aspose.TeX-Bibliothek funktionieren, da letztere auf dem LaTeX2e-Kernel basiert.

Es kann auch vorkommen, dass ein von Ihrer LaTeX-Datei benötigtes Paket direkt geräteabhängige primitive Befehle aufruft, die von der Object TeX-Engine der Aspose.TeX-Bibliothek nicht unterstützt werden. Ein solches Paket wird leider nicht mit Sicherheit funktionieren.