Packages LaTeX externes | .NET

Packages LaTeX externes

La bibliothèque Aspose.TeX comprend un certain nombre de packages LaTeX courants. Vous n’avez donc pas à vous soucier de la manière de fournir ces packages au moteur TeX de la bibliothèque. Mais parfois (ou assez souvent), votre fichier LaTeX peut nécessiter un package au-delà du « bundle » de packages pris en charge « nativement ». Si tel est le cas, vous pouvez essayer de fournir l’entrée requise, c’est-à-dire les fichiers sources du package requis, via l’option RequiredInputDirectory 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 pouvons voir que le fichier nécessite le package fancybox, qui n’est pas supporté “nativement”. Supposons également que nous ayons le fichier source du package fancybox. Il s’agit d’un package simple, il se compose donc en réalité 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 aussi simplement que indiqué ci-dessous :

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

Entrée requise archivée (package pgfplots)

Disons maintenant que nous avons le fichier LaTeX suivant, également assez simple, qui est required-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 pouvons voir 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 nombre 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 :

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

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

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 fournissent un ensemble de polices par défaut disponibles pour la composition. À l’exception de ces polices, Aspose.TeX inclut un certain nombre de packages de polices non standard. Par exemple, « amsfonts », « eurosym » et « wasysym ». Comme nous l’avons vu ci-dessus, Aspose.TeX permet également d’employer des packages externes. Mais nous parlions surtout de packages qui ne contiennent pas de polices. L’extension du moteur Object TeX de Aspose.TeX a besoin de cartes de polices (qui sont des fichiers texte dans un certain format avec l’extension .map par convention) pour déterminer quelles polices physiques correspondent au nom de police interne de chaque TeX. . Ces cartes de polices doivent être chargées dans la mémoire de TeX lors de la phase d’initialisation. Et, bien sûr, elles doivent être présentes parmi les fichiers du package que vous branchez. Comme le moteur ne connaît pas les noms de toutes les cartes de polices, il recherche tous les fichiers avec l’extension .map. Par conséquent, une implémentation de l’interface IInputWorkingDirectory utilisée comme valeur de l’option RequiredInputDirectory doit fournir un moyen d’accéder aux collections de noms de fichiers par extension. Plus précisément, cette implémentation doit également implémenter l’interface IFileCollector. Les implémentations standard - InputFileSystemDirectory et InputZipDirectory - le font déjà.

Ci-dessous, nous fournissons un exemple illustratif d’un répertoire d’entrée requis personnalisé qui implémente également l’interface IFileCollector. Tout en nous concentrant sur la collecte des noms de fichiers par extension, 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
// 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();
    }
}

Restrictions

Il peut arriver qu’un package requis par votre fichier LaTeX soit 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.

Il peut également arriver qu’un package requis par votre fichier LaTeX appelle 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.