Use external LaTeX packages from file system, ZIP archives, custom directories with .NET

README.md

Aspose.TeX for .NET – External LaTeX Packages Examples

These snippets demonstrate how to use external LaTeX packages with Aspose.TeX for .NET. Learn how to provide packages from the file system, ZIP archives, and implement custom input directory handling for packages with fonts.

Key Use Cases

• Use external LaTeX packages from the file system
• Use external LaTeX packages from a ZIP archive
• Implement custom IInputWorkingDirectory for packages with fonts
• Handle external font maps from packages

How to Run Examples

1. Reference Aspose.TeX for .NET: Aspose.TeX on Windows; Aspose.TeX.Drawing on non‑Windows.
2. Copy a snippet into your project.
3. Apply a temporary license as described in the licensing guide.
4. Build and run.

Restrictions

In evaluation mode, the output may contain watermarks and limitations. Apply a valid license to unlock full features.

Related Documentation

More about external LaTeX packages:

• External LaTeX Packages – .NET

Related Resources

• Documentation – Aspose.TeX for .NET
• Product page – Aspose.TeX for .NET
• Free Support Forum – Aspose.TeX
• Blog – Aspose.TeX Product Family
• API Reference – Aspose.TeX for .NET
• NuGet (Windows) – Aspose.TeX
• NuGet (non‑Windows) – Aspose.TeX for .NET

Requirements

• .NET 6.0+, .NET Core, or .NET Framework
• Aspose.TeX for .NET library

Examples Overview

1. Required Input from File System

Provide external LaTeX packages from a file system directory. The directory containing packages may be located anywhere on your file system. Use InputFileSystemDirectory to specify the location.

Use Case: When you have packages installed locally or in a custom directory structure.

2. Required Input from ZIP Archive

Provide external LaTeX packages from a ZIP archive. This allows you to package all required dependencies together. Use InputZipDirectory to specify the ZIP archive and optional base path inside it.

Use Case: When distributing LaTeX documents with all dependencies packaged together, or when packages are downloaded as ZIP archives.

3. Custom Required Input Directory

Implement IInputWorkingDirectory and IFileCollector interfaces for advanced package handling. This is particularly useful when the required input contains fonts provided by external packages.

Key Features:

• IInputWorkingDirectory: Provides access to package files
• IFileCollector: Enables the collection of files by extension
• Font Maps: Handles external font maps that map TeX's internal font names to physical font files

Use Case: When working with packages that include custom fonts or when you need fine-grained control over package loading.

Common LaTeX Packages

Examples work with common LaTeX packages such as:

• fancybox - Fancy frames and boxes
• fancyhdr - Extensive control of page headers and footers
• pgfplots - Create normal/logarithmic plots in two and three dimensions
• And many others supported by Aspose.TeX

Implementation Notes

The RequiredInputDirectory class demonstrates:

1. File Name Storage: Pre-registering files that will be requested by the TeX engine
2. Extension-Based Collection: Organizing files by extension for efficient lookup
3. Stream Handling: Returning file streams when requested by the TeX engine
4. Disposal: Proper cleanup of resources

Aspose.TeX for .NET – External LaTeX Packages Examples

Aspose.TeX for .NET – External LaTeX Packages Examples

Example-RequiredInput-FileSystem.cs

// External LaTeX packages from file system
// Learn more: https://docs.aspose.com/tex/net/external-latex-packages/

// 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(OutputDir);
// Specify a file system working directory for the required input.
// The directory containing packages may be located anywhere.
options.RequiredInputDirectory = new InputFileSystemDirectory(Path.Combine(DataDir, "packages"));
// Initialize the options for saving in PNG format.
options.SaveOptions = new PngSaveOptions();
// Run LaTeX to PNG conversion.
new TeXJob(Path.Combine(DataDir, "required-input-fs.tex"), new ImageDevice(), options).Run();

Example-RequiredInput-Zip.cs

// External LaTeX packages from ZIP archive
// Learn more: https://docs.aspose.com/tex/net/external-latex-packages/

// 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(OutputDir);
// 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(DataDir, "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(DataDir, "required-input-zip.tex"), new ImageDevice(), options).Run();
}

Example-RequiredInputDirectory.cs

// Custom implementation of IInputWorkingDirectory for external packages with fonts
// Learn more: https://docs.aspose.com/tex/net/external-latex-packages/

// 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)
    {
        // Try to find the file in our stored files
        foreach (var extFiles in _fileNames.Values)
        {
            foreach (var file in extFiles.Values)
            {
                if (file.EndsWith(fileName) || Path.GetFileName(file) == fileName)
                {
                    return new NamedStream(File.OpenRead(file), fileName);
                }
            }
        }
        // If not found in stored files, return null (file not available)
        return new NamedStream(null, fileName);
    }

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