Packages LaTeX externes | Java

Packages LaTeX externes

Il existe un certain nombre de packages LaTeX courants inclus dans la bibliothèque Aspose.TeX pour Java. Vous n’avez donc pas à vous soucier de la manière de fournir ces packages au moteur TeX de la bibliothèque. Mais parfois (peut-être souvent) votre fichier LaTeX peut nécessiter un package au-delà du « bundle » de packages pris en charge « nativement ». Dans ce cas, vous pouvez essayer de fournir l’entrée requise, c’est-à-dire les fichiers source du package requis, en utilisant la méthode setRequiredInputDirectory() de l’instance de classe TeXOptions. Nous verrons comment cela fonctionne avec deux exemples.

Entrée requise décompressée (package fancybox)

Disons que nous avons le fichier LaTeX simple suivant, qui est required-input-fs.tex de notre exemple de solution :

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

Sur la 3ème ligne, nous voyons que le fichier nécessite le package fancybox, qui n’est pas supporté “nativement”. Nous supposons également que nous disposons du fichier source du package fancybox. Il s’agit d’un package simple, il ne consiste donc en réalité que d’un seul fichier. Nous pouvons placer ce fichier n’importe où dans notre système de fichiers et spécifier le chemin du répertoire simplement comme suit :

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

Après avoir exécuté un travail TeX avec cette option (n’oubliez pas d’ajuster les autres options si nécessaire), nous obtenons le document de sortie (c’est-à-dire une image PNG).

Voici le code source complet de l’exemple :

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

Entrée requise archivée (package pgfplots)

Supposons maintenant que nous ayons le fichier LaTeX suivant, également assez simple, qui est « require-input-zip.tex » de notre exemple de solution :

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

Sur la 3ème ligne, nous voyons que le fichier nécessite le package pgfplots, qui n’est pas non plus supporté “nativement”. Encore une fois, nous supposons que nous avons les fichiers sources du paquet pgfplots. Il s’agit d’un ensemble assez important de fichiers répartis entre deux emplacements si vous les trouvez dans le répertoire d’installation de n’importe quelle application de composition LaTeX. Vous pouvez trouver le dossier pgfplots dans les dossiers \tex\generic et \tex\latex. Et le contenu de ces deux dossiers doit être fourni comme entrée requise dans la bibliothèque Aspose.TeX. Nous souhaitons que ces fichiers sources soient regroupés dans une archive ZIP, voici donc la présentation de l’archive :

Et voici comment nous spécifions l’accès à ces fichiers sources :

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

Après avoir exécuté un travail TeX avec cette option, nous obtenons le document de sortie :

Voici le code source complet de l’exemple :

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

REMARQUE : Le résultat a été vérifié à l’aide du package pgfplots version 1.18.1. La version du package pfg inclus dans la bibliothèque Aspose.TeX est la 3.1.9a.

Utilisation de packages de polices externes

En règle générale, les distributions LaTeX sont livrées avec une sélection de polices par défaut pouvant être utilisées pour la composition. En plus de ces polices, Aspose.TeX propose plusieurs packages de polices non standard, tels que amsfonts, eurosym et wasysym. Comme mentionné précédemment, Aspose.TeX prend également en charge l’utilisation de packages externes, même si nous nous sommes principalement concentrés sur les packages qui n’incluent pas de polices. L’extension du moteur Object TeX dans Aspose.TeX nécessite des cartes de polices, qui sont des fichiers texte avec l’extension .map qui spécifient les polices physiques correspondant au nom de police interne de chaque TeX. Ces cartes de polices doivent être chargées dans la mémoire de TeX pendant la phase d’initialisation et doivent être incluses dans les fichiers du package. Étant donné que le moteur ne connaît pas les noms de toutes les cartes de polices, il recherche tous les fichiers portant l’extension « .map ». Par conséquent, l’implémentation de l’interface IInputWorkingDirectory utilisée comme valeur de l’option RequiredInputDirectory doit fournir un moyen d’accéder à des collections de noms de fichiers en fonction de leur extension. Plus précisément, cette implémentation doit également implémenter l’interface IFileCollector. Les implémentations standards, InputFileSystemDirectory et InputZipDirectory, remplissent déjà cette exigence.

Ci-dessous, nous présentons un exemple de répertoire d’entrée requis personnalisé qui implémente également l’interface IFileCollector. Notre objectif principal est de rassembler les noms de fichiers en fonction de leur extension, et nous omettons intentionnellement les détails du stockage et de la récupération des fichiers.

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

Restrictions

Un package requis par votre fichier LaTeX peut être développé sous le noyau LaTeX3e. Un tel package ne fonctionnera probablement pas avec la bibliothèque Aspose.TeX puisque cette dernière est basée sur le noyau LaTeX2e.

De plus, un package requis par votre fichier LaTeX peut appeler directement des commandes primitives dépendantes du périphérique qui ne sont pas prises en charge par le moteur Object TeX de la bibliothèque Aspose.TeX. Malheureusement, un tel package ne fonctionnera pas à coup sûr.