Externe LaTeX-Pakete | API für Java

Externe LaTeX-Pakete

In der Aspose.TeX-Bibliothek für Java sind eine Reihe gängiger LaTeX-Pakete enthalten. Sie müssen sich also nicht darum kümmern, wie Sie diese Pakete der TeX-Engine der Bibliothek bereitstellen. Aber manchmal (vielleicht oft) erfordert Ihre LaTeX-Datei möglicherweise ein Paket, das über das „nativ“ unterstützte „Paketpaket“ hinausgeht. In diesem Fall können Sie versuchen, die erforderliche Eingabe, d. h. die Quelldateien des erforderlichen Pakets, mithilfe der Methode setRequiredInputDirectory() der Klasseninstanz TeXOptions bereitzustellen. Wir werden anhand von zwei Beispielen sehen, wie das funktioniert.

Setzen Sie inputFile auf den vollständigen Pfad des entsprechenden LaTeX-Dokuments und outputDirectory auf einen vorhandenen Ausgabeordner. Beide Konvertierungsbeispiele erzeugen PNG mit 150 DPI. Importieren Sie die Aspose.TeX-Klassen aus dem gewählten Beispiel, com.aspose.tex.rendering.ImageDevice, com.aspose.tex.rendering.PngSaveOptions und für ZIP-Eingaben java.io.InputStream und java.nio.file.Files. Behandeln oder deklarieren Sie Ausnahmen in der aufrufenden Methode. Wenden Sie eine Lizenz gemäß dem Lizenzleitfaden an.

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}
  y & = & x^2 \\
  a^2 + 2ab + b^2 & = & (a + b)^2 \\
  \int_0^\infty e^{-ax} dx & = & \frac{1}{a}
  \end{Beqnarray}
}
\end{document}

Die dritte Zeile benötigt das externe Paket fancybox. Setzen Sie packagesDirectory auf einen lokalen Ordner mit fancybox.sty und dessen Abhängigkeiten. Das vollständige Beispiel unten weist diesen Ordner RequiredInputDirectory zu und erzeugt ein PNG-Bild. Gerät und Arbeitsverzeichnisse bleiben bis zum Ende des Auftrags offen und werden danach freigegeben oder geschlossen.

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

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

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 Menge an 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:

Setzen Sie packagesZip auf einen java.nio.file.Path zum Archiv mit den generischen und LaTeX-Paketquellen. Das vollständige Java-Beispiel unten öffnet es mit Files.newInputStream(...) und weist RequiredInputDirectory ein InputZipDirectory zu. Das leere Basispfadargument wählt das gesamte Archiv. Halten Sie ZIP-Stream und Verzeichnis bis zum Ende des TeX-Auftrags offen und schließen Sie sie danach. Das Ergebnis ist ein PNG-Bild mit beiden Diagrammen.

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

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

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 enthalten LaTeX-Distributionen eine Auswahl an Standardschriftarten, die für den Schriftsatz verwendet werden können. Zusätzlich zu diesen Schriftarten bietet Aspose.TeX mehrere nicht standardmäßige Schriftartenpakete wie „amsfonts“, Eurosym und „wasysym“. Wie bereits erwähnt, unterstützt Aspose.TeX auch die Verwendung externer Pakete, obwohl unser Fokus hauptsächlich auf Paketen lag, die keine Schriftarten enthalten. Die Object TeX-Engine-Erweiterung in Aspose.TeX erfordert Schriftartenzuordnungen, bei denen es sich um Textdateien mit der Erweiterung „.map“ handelt, die die physischen Schriftarten angeben, die dem internen Schriftartennamen jedes TeX entsprechen. Diese Schriftartenzuordnungen müssen während der Initialisierungsphase in den Speicher von TeX geladen und in den Paketdateien enthalten sein. Da die Engine nicht die Namen aller Schriftartenkarten kennt, sucht sie nach Dateien mit der Erweiterung „.map“. Daher muss die Implementierung der Schnittstelle IInputWorkingDirectory, die als Wert der Option RequiredInputDirectory verwendet wird, eine Möglichkeit bieten, auf Sammlungen von Dateinamen basierend auf ihrer Erweiterung zuzugreifen. Insbesondere muss diese Implementierung auch die Schnittstelle IFileCollector implementieren. Die Standardimplementierungen InputFileSystemDirectory und InputZipDirectory erfüllen diese Anforderung bereits.

Das folgende benutzerdefinierte RequiredInputDirectory implementiert beide Schnittstellen und liest ausdrücklich registrierte lokale Dateien. Speichern Sie es mit den enthaltenen Importen als RequiredInputDirectory.java. Registrieren Sie jede Datei mit storeFileName(...), weisen Sie die Instanz mit options.setRequiredInputDirectory(...) zu und schließen Sie sie nach dem Auftrag. Es ist ein flaches Register: Dateinamen müssen bei Anfragen ohne vollständigen Pfad eindeutig sein. Erweiterungen werden ohne Beachtung der Groß-/Kleinschreibung verglichen; der optionale Sammlungspfad wählt ein Dateisystemverzeichnis. Registrieren Sie alle erforderlichen Paket-, Fontmap-, Metrik- und physischen Schriftdateien. Die Dateisammlung macht Fontmaps auffindbar, stellt aber keine fehlenden Schriftdaten bereit.

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

Einschränkungen

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

Außerdem ruft ein von Ihrer LaTeX-Datei benötigtes Paket möglicherweise direkt geräteabhängige primitive Befehle auf, die von der Object TeX-Engine der Aspose.TeX-Bibliothek nicht unterstützt werden. Ein solches Paket wird leider nicht mit Sicherheit funktionieren.