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.

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 sehen wir, dass die Datei das Paket „fancybox“ erfordert, das nicht „nativ“ unterstützt wird. Wir gehen außerdem davon aus, dass wir über die Quelldatei des Pakets „fancybox“ verfügen. Da es sich um ein einfaches Paket handelt, besteht es eigentlich nur aus einer Datei. Wir können diese Datei an einer beliebigen Stelle in unserem Dateisystem platzieren und den Verzeichnispfad einfach wie folgt angeben:

options.setRequiredInputDirectory(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.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();

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:

Und so legen wir den Zugriff auf diese Quelldateien fest:

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

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

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.

Nachfolgend stellen wir ein Beispiel für ein benutzerdefiniertes erforderliches Eingabeverzeichnis vor, das auch die Schnittstelle IFileCollector implementiert. Unser Hauptaugenmerk liegt auf der Erfassung von Dateinamen anhand ihrer Erweiterung, und wir lassen 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
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();
    }
}

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.