Expanding Latex’S Capabilities: Package Development And Contributions
Customizing LaTeX with Packages
LaTeX packages are extensions that provide additional functionality and customization options not available in the LaTeX core. Packages are implemented using the TeX/LaTeX programming language and can modify or enhance everything from document styling to mathematical typesetting capabilities.
There are over 4000 packages available in the Comprehensive TeX Archive Network (CTAN), covering almost every conceivable publishing need. While LaTeX offers excellent core typesetting tools, its true power lies in the extensive package ecosystem.
Packages must be loaded in the preamble of a LaTeX document using the \usepackage command and package name, like \usepackage{fancyhdr}. This makes all of the macros, commands, configuration options and other code in the package available to the document.
CTAN and LaTeX distributions offer package repositories and managers for browsing and automatically installing packages. However, with so much choice discovering the right packages can be challenging. Online LaTeX forums and sites like Stack Exchange provide recommendations for common use cases.
Understanding LaTeX Packages and Extension Mechanisms
LaTeX packages provide self-contained extensions focused on specific sets of related functionality, from simple tweaks like custom headers and footers, to major features like tables, diagrams and international language support.
At a technical level, packages contain macro definitions, internal variables settings, configuration options, and other LaTeX commands. When loaded these components integrate into the internal LaTeX system to offer new document-level macros. For example, graphicx provides the \includegraphics macro for inserting images.
While some packages like Babel modify LaTeX internals directly, most rely on LaTeX's extension and hook mechanisms. These let packages build on existing macros and environments without having to alter core code. For example, adjustbox overlays LaTeX box commands to enable image scaling options.
Loading and Installing Packages
The \usepackage command specifies packages to load from TeX's search path. After standard directories, it checks the paths in TEXMFHOME allowing users to install new packages. LaTeX distributions like MiKTeX feature integrated utilities to automatically fetch and set up packages from repositories like CTAN.
When loading packages, order can be important especially where inter-package dependencies exist. Packages should also be loaded before the \begin{document} point, as LaTeX cannot find new commands mid-document. Required or recommended packages are normally specified in package documentation.
Finding Packages on CTAN and Online Repositories
The Comprehensive TeX Archive Network (CTAN) provides a centralized set of TeX package repositories, with over 4000 packages. CTAN's search features and category structure help locate suitable packages. LaTeX distributions offer CTAN mirrors enabling direct installations of archived packages.
Platforms like Stack Exchange provide recommendations on packages for specific use cases.latexpackages.org offers a searchable snapshot of CTAN package capabilities. GitHub also hosts TeX packages, especially works-in-progress seeking wider testing and contribution.
Creating Your Own Packages
Developing custom LaTeX packages enables encapsulating and reusing document logic like custom styling or data transforms. Packages help separate concerns, improve maintainability and distribute useful capabilities to the community. They also offer a pathway to deeper TeX understanding and contribution.
Package development involves creation of supporting files like documentation and configuration standards compliance. Code comments explaining logic aids long-term maintenance. Rigorous testing across TeX distributions catches issues prior to release. Version control further enables tracking changes and enhancements.
Benefits of Building and Releasing Packages
Key motivations driving package development include:
- Extracting and reusing document constructs in other projects
- Adding missing functionality not provided by other packages
- Encapsulating complex formatting rules or data transforms
- Distributing useful capabilities to benefit the wider LaTeX community
- Establishing yourself as an expert within a package domain
- Participating more actively in advancing LaTeX capabilities
Anatomy of a LaTeX Package
A LaTeX package consists of a .ins installer file, .dtx code documentation along with:
- .sty containing LaTeX macro code
- .tex driver file that enables testing .dtx docs
- .pdf documentation generated from .dtx
- Example .tex files demonstrating usage
- README installation notes and usage guidance
Consistent style, structure and components help align to community package standards. This also aids long-term maintainability and distribution.
Coding and Documenting Packages
Internally packages utilize LaTeX or TeX programming syntax to process data and expose macros. Code comments document logic flow and usage constraints. By convention, percent signs (%) indicate developer notes vs documentation aimed at package users.
The DocStrip tool enables embedding macro documentation within .dtx source files via commented blocks. This ensures code and explanations remain synchronized during maintenance.
Code readability principles like modularity help future developers interpret and amend complex packages. Consistent macro naming conventions aid discoverability and interoperability between packages.
Modifying and Extending LaTeX Internals
While risky for portability, certain packages directly patch LaTeX internals to insert new behavior. Methods include:
- Redefining core macros using \renewcommand
- Altering macro argument parsing and preamble definitions
- Setting global flags and internal variables changed by other functions
- Overriding error, log and output routines
Low-level techniques should follow strict compatibility guidelines to avoid issues. Safer options exist in hook management packages like etoolbox for extending macros and executing code trigger points.
Contributing Improvements to LaTeX
The open-source nature of LaTeX allows developers to contribute packages, fixes and enhancements directly benefiting the community. Participation opportunities include:
- Submitting new packages to CTAN covering specialized use cases
- Adding features, options and fixes to existing packages
- Correcting bugs or inconsistencies in LaTeX core functionality
- Improving documentation like package manuals and tip sheets
Changes should adhere to the documented LaTeX3 project standards or base their additions on compatible packages. The arXiv preprint repository enables sharing WIP packages early before formal release.
Identifying Issues in LaTeX Packages
Analyzing package documentation and implementations highlights areas for improvement. Common issues include:
- Incorrect or inconsistent output rendering
- Non-standard options incompatible with other packages
- Undefined behavior for parameter combinations
- Restrictive constraints limiting usage
- Cryptic internal variable names harming readability
- Out-of-date docs not reflecting bug fixes
TeX's exception logging helps diagnose some problems. Tracing command execution order also clarifies inconsistencies vs expected behavior.
Contributing Code Updates to Packages
The decentralized nature of package distribution allows submitting fixes and updates directly to maintainers rather than just LaTeX core. Package authors generally invite improvements to code, tests or documentation via email, GitHub pull requests or patching systems.
Ensure any compatibility breaking changes or new defaults adhere to configured policies for the package. Backwards compatibility helps ensure stability across the extensive LaTeX distribution landscape.
Significant updates warrant incrementing the major version number per semantic versioning conventions. Trivial fixes to documentation or spacing only require increments to the patch version.
Releasing Packages to CTAN and Community
The Comprehensive TeX Archive Network facilitates distribution and discovery of contributed packages. Authors can upload manually via web from or integrate CTAN updates in their GitHub-CI pipelines to enable one-click releases.
CTAN referees will review packages to verify licenses, consistency against standards for naming, documentation etc. This governance upholds stability and interoperability across the ecosystem.
Beyond CTAN, personal and project websites provide alternate package hosting locations referenced in documentation. This grants flexibility to iteratively update separate from formal CTAN release cycles.
Case Study: Developing the Fancy Header Package
The Fancyhdr package sought to expand LaTeX's limited default header and footer options enabling page-wide customization of elements like:
- Targeting first page only vs even pages
- Multi-line headers and footers
- Mixing page numbers, logos and custom text
- Header styling and horizontal rules
Initial development occurred on GitHub to facilitate easier testing across different LaTeX engines like pdfLaTeX vs XeLaTeX. Later CTAN adoption increased discoverability.
Identifying the Need for Flexible Header Control
LaTeX sectioning and running header capabilities provide little configuration outside page numbers and titles. Complex branding, metadata or formatting requires painful manual overrides.
Use cases like scientific publishing have extensive demands such as two line headers, custom footer content, and selective overrides by page or chapter. No single package addressed these together in a simple way.
Implementing Key Header Modification Macros
Fancyhdr's core contribution involved set of macros to redefine header content regions. For example, \lhead sets the left header field globally or for special targets like chapters. Similarly \chead covers the center header.
Saving and clearing header definitions gave full control over content. Adding rules and styling parameters enabled visible demarcations between regions. This offered comparable functionality to word processing tools.
Configuration Through Package Options
To simplify application across different use cases, Fancyhdr allowed passing options like chapterprefix to auto-include the current chapter number in headers. Other flags determine behaviors like clearing all headers.
Grouping options into semantic categories like sectionmark formatting helped break down the extensive configuration possibilities.
Community Release and Enhancement
After exposure in LaTeX forums and conferences, CTAN inclusion increased discoverability. Feedback accelerated fixes like improved interactions with titlesec package for custom titles.
Continued maintenance work expanded support for edge cases like index headers, while introducing conventions assisting novice users. These community interactions continue improving Fancyhdr's capabilities.
Next Steps for LaTeX Package Developers
LaTeX offers unique opportunities to share specialized extensions benefitting publishers, academics, businesses and others relying on Tex's renowned high-quality typesetting.
Realizing this open source potential as an author involves:
- Actively participating in online LaTeX forums and question sites
- Attending local TeX meetups and international conferences like TUG
- Carefully following recommended practices for release preparation
- Supporting and maintaining packages by incorporating community feedback
Releasing well-documented packages adhering to naming, style and compatibility standards maximizes reusability. However, this also enables others to expand capabilities in ways not always possible working alone.
The LaTeX3 project offers information on current best practices for ambitious package authors aiming to influence wider ecosystem development. For new contributors, smaller fixes to existing works offer simpler ways to hone skills.
Through ongoing involvement, developers gain deep TeX expertise while advancing a platform empowering the vast document authoring needs across research and industry.