Community hub
0 subscribers7 pages, 0 posts
Recent from talks
All channels
Be the first to start a discussion here.
Be the first to start a discussion here.
Be the first to start a discussion here.
Be the first to start a discussion here.
Contribute something
Welcome to the community hub built to collect knowledge and have discussions related to LuaTeX.
Nothing was collected or created yet.
LuaTeX
View on Wikipediafrom Wikipedia
| LuaTeX | |
|---|---|
 | |
| Original authors | Taco Hoekwater, Hartmut Henkel, Hans Hagen |
| Developers | Taco Hoekwater, Hartmut Henkel, Hans Hagen, etc. (7 active developers) |
| Initial release | 2007 |
| Stable release | 1.21.0[1]
/ February 13, 2025 |
| Repository | |
| Written in | Lua, C |
| Operating system | Multiplatform |
| Type | Typesetting |
| License | GNU General Public License |
| Website | www |
LuaTeX, sometimes typeset as LuaTeX, is a TeX-based computer typesetting system which started as a version of pdfTeX with a Lua scripting engine embedded. After some experiments it was adopted by the TeX Live distribution as a successor to pdfTeX (itself an extension of ε-TeX, which generates PDFs).[2][3][4] Later in the project some functionality of Aleph was included (esp. multi-directional typesetting). The project was originally sponsored by the Oriental TeX project, founded by Idris Samawi Hamid, Hans Hagen, and Taco Hoekwater.
In November 2024, LuaLaTeX was declared the recommended format for LaTeX.[5]
Objective of the project
[edit]The main objective of the project is to provide a version of TeX where all internals are accessible from Lua. In the process of opening up TeX much of the internal code is rewritten. Instead of hard coding new features in TeX itself, users (or macro package writers) can write their own extensions. LuaTeX offers support for OpenType fonts with external modules. One of them, written in Lua, is provided by the LuaTeX team, but support for complex scripts is limited. Since 2020 LuaTeX includes the HarfBuzz engine for correct rendering of complex scripts using OpenType.[6] An alternate approach can be found on GitHub.[7]
A related project is MPLib (an extended MetaPost library module), which brings a graphics engine into TeX.[8]
The LuaTeX team consists of Luigi Scarso, Taco Hoekwater, Hartmut Henkel and Hans Hagen.
Versions
[edit]The first public beta was launched at TUG 2007 in San Diego. The first formal release was planned for the end of 2009, and the first stable production version was released in 2010. Version 1.00 was released in September 2016 during ConTeXt 2016. Version 1.12 was released for TeXLive 2020.[9]
As of October 2010[update], both ConTeXt mark IV and LaTeX with extra packages (e.g. luaotfload, luamplib, luatexbase, luatextra) make use of new LuaTeX features. (When LuaTeX is used with the LaTeX format, it is sometimes called "LuaLaTeX".) Both are supported in TeX Live 2010 with LuaTeX 0.60, and in LyX.[10] Special support in plain TeX is still under development.
Further development takes place as LuaMetaTeX in connection with the ConTeXt project.[9][11]
See also
[edit]
Further reading
[edit]- CTAN: LuaTeX Manual
- Manuel Pégourié-Gonnard: A guide to LuaLaTeX. 5 May 2013. [Outdated.]
- LuaTeX development team: Documentation. October 2021.
- Official LuaTeX wiki
- ConTeXt wiki
External links
[edit]References
[edit]- ^ "LuaTeX NEWS file". Retrieved 2025-03-09.
- ^ TeX Frequently Asked Questions Archived 2014-10-27 at the Wayback Machine - What is PDFTeX?
- ^ TeX Frequently Asked Questions Archived 2014-10-27 at the Wayback Machine - PDFTeX and LuaTeX
- ^ PDFTeX's NEWS file Archived 2009-07-09 at the Portuguese Web Archive - news for 3.141592-1.40.0 version.
- ^ Engine news from the LaTeX Project
- ^ Khaled Hosny. "Bringing world scripts to LuaTEX: The HarfBuzz experiment" (PDF). Retrieved 2023-07-14.
- ^ tatzetwerk (August 2020). "luatex-harfbuzz". GitHub. Retrieved 16 October 2021.
- ^ Hagen, Hans. "The MetaPost library and LuaTEX" (PDF). TUGboat - TUG 2008 Conference Proceedings. 29 (3): 446–453. Retrieved 16 October 2021.
- ^ a b "LuaTeX Roadmap". luatex.org. Retrieved 2023-07-14.
- ^ "LyX wiki | LyX / LuaTeX". wiki.lyx.org. Retrieved 2017-08-31.
- ^ "luametatex". GitHub. Retrieved 2023-07-14.
LuaTeX
View on Grokipediafrom Grokipedia
LuaTeX is an extended typesetting system derived from pdfTeX, integrating the Lua scripting language to provide a flexible, programmable interface for document processing while maintaining compatibility with traditional TeX syntax and outputs.[1]
Developed primarily by Hans Hagen, Taco Hoekwater, Hartmut Henkel, and Luigi Scarso, LuaTeX emphasizes an open-source approach with a lean core engine, delegating extensibility to Lua scripts for tasks such as font loading, node manipulation, and backend customization.[2] Its first public beta was presented at the TUG 2007 conference in San Diego, with stable version 1.00 released in September 2016 as part of TeX Live 2017, and subsequent updates including version 1.22 integrated into TeX Live 2025 for enhanced stability and features like improved PDF handling.[1][3]
Key aspects of LuaTeX include native Unicode support, advanced OpenType font processing via Lua modules like luaotfload, and the ability to embed Lua code directly in documents for dynamic behaviors, making it particularly suited for complex multilingual typesetting and integration with markup systems such as ConTeXt or LuaLaTeX.[4] The engine's design allows it to function as both a TeX interpreter and a Lua runtime, enabling developers to access low-level typesetting primitives through Lua for custom extensions without altering the core C and Pascal codebase.[5] As of 2025, LuaTeX remains actively maintained through community contributions and is distributed via major TeX implementations like TeX Live.[6]
Introduction
Overview
LuaTeX is an extended version of the pdfTeX engine that embeds Lua as a scripting language to enable programmable typesetting.[1] This integration allows users to extend and customize typesetting behaviors directly within the engine, making it a flexible tool for complex document processing while preserving compatibility with existing pdfTeX workflows.[7] The primary purpose of LuaTeX is to develop an open, configurable variant of the TeX typesetting system, leveraging Lua's scripting capabilities to support advanced automation and extensions without disrupting traditional TeX macros.[1] In November 2024, the LaTeX Project recommended LuaTeX as the preferred engine for new LuaLaTeX documents, marking its adoption as the successor to pdfTeX in TeX Live distributions.[8] This milestone underscores LuaTeX's maturity and its role in modern LaTeX workflows, particularly for users requiring Lua scripting for custom extensions or enhanced Unicode and OpenType font handling.[7] LuaTeX also incorporates capabilities from Aleph for multi-directional typesetting, facilitating the handling of right-to-left and bidirectional text in diverse linguistic contexts.[9]History
LuaTeX originated around 2005 as an experimental extension of pdfTeX, initiated by developers Taco Hoekwater and Hans Hagen to incorporate Lua scripting for enhanced extensibility.[10][11] The project aimed to modernize TeX's capabilities while maintaining backward compatibility, with early work focusing on embedding Lua into the pdfTeX engine.[12] The first public beta release of LuaTeX was presented at the TeX Users Group (TUG) 2007 conference in San Diego, marking a significant milestone after approximately one year of development.[12][1] This beta introduced core features like improved font handling and initial support for complex scripts, demonstrating LuaTeX's potential as a flexible typesetting engine.[13] LuaTeX achieved its initial stable release in 2010 with version 0.60, transitioning from beta to production-ready status and being included in TeX Live 2010.[13][14] This version emphasized stability and feature completeness, allowing broader adoption for document processing tasks.[10] Development received key sponsorship from the Oriental TeX project at Colorado State University, which funded core enhancements to handle complex scripts such as Arabic.[15][10] This support, led by Idris Samawi Hamid, advanced LuaTeX's capabilities for scholarly typesetting in non-Latin languages.[16] A pivotal milestone occurred in September 2016 with the release of version 1.00, which was integrated into TeX Live 2017 and solidified LuaTeX as a standard TeX engine.[1][17] In 2020, LuaTeX incorporated the HarfBuzz library, introducing the LuaHBTeX engine variant for superior complex script shaping and OpenType support.[18] This integration, bundled in TeX Live 2020, significantly improved handling of multilingual typography.[19]Development and Objectives
Project Goals
The LuaTeX project was initiated to create an extended version of pdfTeX that embeds Lua as a scripting language, enabling users to access and manipulate TeX's internal mechanisms directly through Lua code without requiring engine recompilation.[20] This core goal emphasizes exposing TeX primitives, variables, and hooks to Lua, allowing for customizable scripting at the user level to handle tasks such as token processing and output generation.[12] By providing stable interfaces for these interactions, LuaTeX aims to maintain compatibility with existing TeX workflows while fostering innovation in document processing.[20] A key design principle is the development of a "lean core" engine, where non-essential functionalities like font loading, file handling, and advanced typography are offloaded to modular Lua scripts rather than embedding them rigidly in the C-based TeX codebase.[20] This approach reduces the engine's complexity and bloat, replacing experimental features from predecessors like pdfTeX and Aleph with flexible Lua-based solutions.[12] LuaTeX thus preserves TeX's renowned precision in typesetting calculations while introducing programmable extensibility for automation and document engineering.[20] To address limitations in traditional TeX, LuaTeX incorporates native Unicode support via an internal UTF-8 data path, enabling seamless handling of complex scripts and international typography without legacy reencoding mechanisms.[12] This modernity extends to a configurable font subsystem that supports OpenType and TrueType formats through Lua-driven interfaces, allowing users to adapt font loading and shaping programmatically.[20] In the long term, the project envisions LuaTeX evolving as a comprehensive toolkit for document construction, including direct integration with the MetaPost library for graphics and vector output.[20]Key Contributors
LuaTeX's development was primarily led by Taco Hoekwater as the lead architect, responsible for Pascal and C coding as well as code base management, alongside Hans Hagen, who handled Lua coding, general oversight, and integration with the ConTeXt typesetting system.[2] These efforts began in the mid-2000s, with initial programming work starting around 2006 under the guidance of Hoekwater, Hagen, and Hartmut Henkel.[10] The ConTeXt community has played a vital role in LuaTeX's evolution, providing ongoing maintenance, testing, and enhancements through collaborative platforms like the Context Garden project, which hosts documentation, binaries, and resources for Lua scripting within ConTeXt.[21] This community-driven support ensures LuaTeX's stability and adaptability for advanced typesetting needs.[22] Funding for LuaTeX's early development came from the Oriental TeX project, initiated by Idris Samawi Hamid, Hans Hagen, and Taco Hoekwater, which sponsored core enhancements for complex scripts including Arabic right-to-left typesetting and CJK font handling via node list processing.[15][23] LuaTeX is distributed through the TeX Live system, maintained by the TeX Users Group, where it serves as the primary modern engine, effectively replacing pdfTeX for new projects due to its superior extensibility.[6] In 2024, the LaTeX Project officially recommended LuaLaTeX—LuaTeX's LaTeX interface—as the preferred engine for new documents, citing its advantages in Unicode support and scripting; this push was driven by the project team, including key contributor David Carlisle.[8]Technical Architecture
Core Engine
LuaTeX's core engine is an extension of the pdfTeX typesetting system, specifically derived from pdfTeX version 1.40.9, which itself builds upon the original TeX engine by Donald Knuth.[5] The architecture retains pdfTeX's foundational structure, including the classic TeX82 algorithms for paragraph breaking, line breaking, and hyphenation, while introducing modular components rewritten in C for better maintainability and removing experimental features from pdfTeX.[5] This design preserves the deterministic behavior of traditional TeX processing, ensuring reliable glyph placement and layout calculations central to typesetting.[1] Enhancements to these algorithms, such as Unicode-aware hyphenation using a finite-state hash table, build upon the core without altering its fundamental flow.[5] The engine generates PDF output directly, embedding fonts and supporting hyperlinks in a manner fully compatible with pdfTeX-produced files, allowing seamless integration into existing workflows.[5] Primitives like\pdfextension and options for multi-line hyperlink handling enable advanced PDF features while decoupling the backend from the core processing logic.[5] This direct PDF production eliminates the need for intermediate DVI files in most cases, streamlining compilation for modern document preparation.
Memory management follows TeX's traditional pools for nodes, glyphs, and boxes but incorporates a Lua interface for dynamic allocation, utilizing sparse arrays and shared attribute lists to handle up to 65,535 registers without predefined limits.[5] This hybrid approach allows the core engine to remain efficient for static allocations while permitting Lua scripts to manage expandable resources, such as custom node manipulation, though users must heed allocation caveats to avoid overflows.[5]
LuaTeX operates in compatibility mode to support plain TeX, LaTeX, and ConTeXt formats with minimal modifications to input files, inheriting pdfTeX's handling of macro packages and ensuring backward compatibility for legacy documents.[1] The engine is compiled using the Web2C framework in C for high performance, with Lua code compiled to bytecode (using Lua 5.3) to optimize execution speed during typesetting.[5] While generally slower than pdfTeX for simple plain TeX tasks, it excels in efficiency for complex documents involving scripting, as seen in ConTeXt applications.[13]
Lua Integration
LuaTeX embeds a Lua 5.3 interpreter directly into its TeX engine, enabling the execution of Lua scripts during the typesetting process to extend and customize document processing.[24] This integration allows Lua code to interact seamlessly with TeX's internal state, providing a programmable layer over the traditional TeX primitives without requiring external processes.[25] The primary mechanisms for invoking Lua include the\directlua primitive, which executes code immediately upon encounter, and \latelua, which defers execution until page shipout, ensuring timing flexibility in document workflows.[24]
Access to TeX's operations occurs through Lua callbacks, which serve as hooks at critical points in the typesetting pipeline, such as the pre_linebreak_filter before line breaking or the hyphenate callback after hyphenation decisions.[24] These callbacks enable Lua functions to intercept, inspect, and modify TeX behavior dynamically; for instance, a script can alter paragraph breaking logic or adjust hyphenation patterns on the fly.[25] Registration of these callbacks is handled via Lua's callback.register function, allowing users to override or augment default TeX actions while maintaining compatibility with existing formats.[24]
The LuaTeX API exposes TeX internals through dedicated Lua libraries, including tex for accessing parameters and registers, node for manipulating the node-based representation of document content, and font for handling font loading and properties.[24] These libraries provide programmatic interfaces to core TeX elements, such as querying current typesetting state via tex or defining custom font metrics with font.read_tfm.[24] This API design facilitates fine-grained control, bridging Lua's general-purpose scripting with TeX's specialized typesetting engine.[1]
LuaTeX supports precompilation of Lua code into bytecode for improved performance, using primitives like \luabytecode to load and \luabytecodecall to execute it, which reduces parsing overhead in large documents.[24] Bytecode can be embedded directly in format files or managed via Lua tables like lua.bytecode, allowing efficient reuse across compilations.[24] The --luaconly command-line option further enables standalone bytecode compilation, akin to the luac tool.[24]
Error handling in LuaTeX ensures that Lua runtime issues propagate to the TeX layer with informative diagnostics, preventing silent failures and aiding debugging in scripted documents.[24] Callbacks such as show_error_hook and show_error_message allow customization of error reporting, while the --safer option restricts potentially hazardous Lua functions to enhance security in shared environments.[24] This mechanism supports robust scripting by integrating Lua's exception handling with TeX's error reporting system.[24]
Node System
LuaTeX employs a node-based data model to represent document elements during the typesetting process, where nodes form a doubly-linked list structure. Each node encapsulates atomic components such as glyphs (individual characters with positioning and font attributes), boxes (hlist for horizontal arrangements and vlist for vertical ones), glue (flexible spacing elements that adjust during line breaking or page layout), and penalties (values influencing break decisions like line or page divisions). This linked list design allows for efficient traversal and modification of the document's internal representation, building upon TeX's traditional node concepts while extending them for Lua integration.[5] Access to these nodes is provided through LuaTeX's node library, which offers a comprehensive read/write API for creating, inspecting, and altering node lists directly from Lua scripts. For instance, developers can generate a new glyph node usingnode.new("glyph", {char=65, font=0}) to represent the character 'A' in a specified font, or traverse lists with functions like node.tail(n) to reach the end of a node chain for appending operations. The library supports operations on node properties, such as adjusting widths, heights, or depths in box nodes, enabling programmatic intervention in the typesetting flow. This API is fully documented in the LuaTeX reference manual, emphasizing its role in extending TeX's capabilities beyond static rules.[5]
In the processing pipeline, nodes are primarily generated during TeX's shipout phase, where the engine assembles the horizontal and vertical lists that form pages, converting input tokens into this structured format. Lua scripts can then modify these node lists via callbacks—such as buildpage_filter—before the final PDF output, allowing dynamic adjustments to the document structure without altering the core TeX algorithms. For example, glyph nodes carry detailed attributes like character codes, font identifiers, and language-specific metrics, while math nodes handle equation components derived from math mode processing. Hlist and vlist nodes aggregate these elements into boxes with computed dimensions, facilitating hierarchical layout construction.[5]
The node system's advantages lie in its provision of fine-grained control over layout details, surpassing traditional TeX extensions by permitting Lua-driven customizations. Users can implement precise kerning adjustments between glyph nodes using functions like node.kerning, or suppress ligatures by manipulating glyph sequences—such as converting character nodes to explicit glyphs via Lua interventions. This enables advanced typographic features, like context-aware spacing or experimental layouts, while maintaining compatibility with TeX's proven breaking and placement logic.[5]
Features
Font and Unicode Support
LuaTeX provides native support for Unicode input by processing source files encoded in UTF-8, allowing direct handling of a wide range of characters without requiring additional encoding declarations.[5] This UTF-8 input is converted into the engine's internal 32-bit Unicode codepoint representation, which extends the original TeX's 8-bit character model to accommodate full Unicode coverage.[12] As a result, multilingual documents can be authored seamlessly in UTF-8, with the engine managing character normalization and collation internally during typesetting.[26] The font system in LuaTeX relies on a flexible, Lua-based font loader that enables the use of contemporary font formats such as OpenType, TrueType, and Type 1. This loader, primarily implemented through the luaotfload library, reads font files directly and extracts metrics, glyphs, and features into Lua tables for processing by the engine.[27] Unlike traditional TeX engines, LuaTeX does not embed font handling in C code but delegates it to Lua modules, permitting customization of font loading workflows while maintaining compatibility with legacy formats.[28] A HarfBuzz-enabled variant of LuaTeX, known as luahbtex, incorporates the HarfBuzz text shaping library starting in 2019, which handles advanced glyph substitution, positioning, and reordering for bidirectional and contextual requirements.[29] This integration supports features like ligature formation, mark attachment, and script-specific behaviors in languages such as Arabic (right-to-left with mirroring) and Devanagari (conjunct forms and vowel signs), significantly improving typesetting accuracy for non-Latin scripts over earlier TeX engines.[30] HarfBuzz processes OpenType layout tables during font loading, ensuring that complex text runs are shaped before insertion into the TeX node stream. OpenType font features in LuaTeX, such as kerning (via the 'kern' feature) and ligatures (via the 'liga' feature), are accessible and modifiable through Lua scripting, allowing users to selectively enable or override them at runtime.[31] For instance, a Lua handler can inspect and adjust feature states in the font data table before the engine applies them, providing granular control over typographic variations. If no custom Lua handler is defined, the system falls back to traditional TeX metrics and ligature building mechanisms for compatibility.[32] LuaTeX inherits its multi-directional typesetting capabilities from the Aleph engine, enabling support for left-to-right, right-to-left, and top-to-bottom layouts through directional commands and node manipulations.[5] This framework allows mixing directions within paragraphs, such as embedding RTL text in LTR documents, with automatic reversal of paragraph flow and glyph mirroring as needed for scripts like Hebrew or Mongolian vertical writing.[13] The implementation builds on Aleph's Omega-derived model but has been refined in LuaTeX to integrate with its Unicode and node-based architecture.[21]Scripting Capabilities
LuaTeX's scripting capabilities leverage the embedded Lua interpreter to enable dynamic automation and customization of document processing, allowing users to generate content programmatically during compilation. This integration supports tasks such as reading external data sources and inserting processed results into the TeX stream, facilitating applications like report generation from structured inputs. For instance, Lua scripts can parse CSV files using theluafilesystem library to create database-driven tables, where data is loaded into Lua tables and formatted into LaTeX tabular environments via tex.sprint.[5] Similarly, conditional formatting can be implemented by evaluating Lua conditions on node lists, such as altering glyph colors based on content thresholds before line breaking.[5]
Extension modules enhance LuaTeX's scripting by providing libraries for specialized tasks, including file I/O, XML parsing, and network interactions. The luafilesystem module allows scripts to read and write files during compilation, enabling automation like loading configuration data or appending log entries without external tools.[5] For XML processing, the luaxml library parses structured documents into Lua tables, which can then be traversed to extract elements and output formatted TeX content, such as converting XML metadata into bibliographies. Network requests are possible via the luasocket module, though this requires explicit enabling and is typically used for fetching remote resources like font files or data feeds in controlled environments.[5] These modules are dynamically loadable via Lua's require mechanism, extending TeX's capabilities beyond static markup.[5]
Callbacks provide a mechanism to intercept and modify TeX's internal processes using Lua functions, registered with callback.register. This allows overriding primitives, such as custom hyphenation patterns loaded from external files via the hyphenate callback, where a Lua function analyzes word nodes and inserts discretionary breaks based on user-defined rules.[5][33] Another example is the process_input_buffer callback, which filters input lines to apply transformations like automatic quoting or locale-specific substitutions before tokenization.[5] Multiple callbacks can be chained using metafunctions to compose behaviors without overwriting defaults.[33] The Lua API for node and font manipulation further supports these overrides in formats like ConTeXt.[5]
Efficient scripting practices are essential for maintaining performance in LuaTeX, as excessive Lua calls can introduce overhead compared to native TeX operations. To optimize repeated executions, define functions with \luafunction and store bytecode in format files using \luabytecode, reducing interpretation time for loops or filters.[5] Avoid unnecessary node traversals by using direct access methods, such as local next = node.next instead of metatable lookups, which is particularly beneficial in high-volume processing like paragraph filtering.[5] Disabling unused callbacks with callback.register(name, false) yields minor speed gains, though it should be used judiciously to preserve functionality.[33]
Security considerations arise from Lua's access to system resources, necessitating safeguards in shared or untrusted environments. LuaTeX lacks a built-in sandbox, so scripts can execute arbitrary code via functions like os.execute, potentially leading to vulnerabilities such as arbitrary command injection if shell escape is enabled.[5] To mitigate risks, invoke LuaTeX with the --safer option, which disables dangerous modules like os execution primitives and restricts file I/O to read-only.[5] Additionally, --nosocket prevents network access through luasocket, and configuration files like texmf.cnf can limit shell commands to predefined patterns.[5] Users should validate inputs and avoid loading untrusted Lua files to prevent exploits like those involving malformed node manipulations.[5]
Graphics and MetaPost
LuaTeX incorporates the MPLib library, an embedded MetaPost interpreter that enables the generation of vector graphics directly during the typesetting process. This integration allows MetaPost code to be executed inline within LuaTeX documents, producing scalable illustrations without requiring separate compilation steps or external file handling. The library processes MetaPost's descriptive language for creating paths, fills, and transformations, seamlessly inserting the resulting graphic nodes into the document's output stream.[5] MPLib features a C-based implementation of MetaPost, which significantly improves execution speed compared to traditional standalone MetaPost workflows. This enhancement stems from the library's tight embedding within LuaTeX's engine, allowing for rapid processing—capable of handling approximately 2000 simple graphics per second on mid-2000s hardware—while supporting output directly to PDF as the primary format. Additionally, SVG output is available through dedicated methods in the library, facilitating vector graphics export for web or further editing purposes.[34][5] The Lua interface to MPLib provides programmatic access via functions such asmplib.new for instance creation, mplib.execute for running code, and mplib.finish for finalization, enabling dynamic generation of parametric diagrams based on document data like variables or loops. This allows scripting complex, data-driven visuals where graphic elements adapt to textual content or calculations performed in Lua.[5]
Common use cases include scientific illustrations, such as chemical structures or geometric proofs; flowcharts representing algorithms; and custom ornaments like intricate borders or icons that integrate fluidly with surrounding text. These applications leverage MetaPost's strengths in precise Bézier curve handling and color management for professional-quality results.[34][35]
A key limitation of LuaTeX's MetaPost support is the absence of direct raster image handling, as MPLib focuses exclusively on vector output; bitmap graphics must be incorporated using external tools and included via standard TeX mechanisms.[5]
Usage and Implementation
Basic Compilation
LuaTeX is invoked from the command line using theluatex binary, which processes TeX input files and generates output, typically in PDF format. The basic command is luatex filename.tex, where filename.tex is the source file; this defaults to PDF output but can be explicitly set with the -output-format=pdf option, while -output-format=dvi produces DVI files. Other common options include --jobname=STRING to specify the base name for output files, --interaction=STRING to control user prompts (e.g., batchmode for non-interactive runs), and --halt-on-error to stop execution upon encountering the first error. For initialization tasks, such as defining custom primitives, the -ini or --ini flag starts LuaTeX in initialization mode.[5]
Format files, with the .fmt extension, accelerate compilation by precompiling and storing macro definitions, primitives, and Lua modules for reuse. To build a format file, run luatex -ini [plain](/page/The_Plain) for a plain TeX format or luatex -ini luatex for a Lua-enabled variant, which saves the result as plain.fmt or luatex.fmt in the system's format directory. Once created, load a format with --fmt=FORMAT (e.g., luatex --fmt=[plain](/page/The_Plain) filename.tex), or specify it via the \formatname primitive in the input file. This approach is particularly useful for Lua-integrated formats, as it preserves \directlua primitives and other extensions without reloading them each time.[5]
Input files for LuaTeX must be encoded in UTF-8 to leverage its native Unicode support, allowing seamless handling of international characters without additional setup. Lua code is embedded directly in the TeX source using the \directlua{code} primitive, which executes the enclosed Lua statements immediately during processing—for instance, \directlua{tex.print("Hello from Lua")} inserts dynamic text. Source files can reference font specifications as detailed in font handling sections, but basic compilation assumes standard TeX syntax unless Lua extensions are invoked.[5]
Error diagnostics in LuaTeX blend TeX-style messages with Lua traces, often displaying stack information for mixed errors; for example, a Lua syntax error might show the line in the \directlua block alongside TeX context. Enable detailed reporting with --file-line-error for file and line numbers in messages, or use \tracingonline=1 to output errors to the terminal in real time. Basic debugging involves primitives like \show_context to inspect the current processing state or \errmessage{description} to trigger custom warnings; for Lua-specific issues, the --luadebug option loads Lua's debug library to step through code. Interpreting these requires familiarity with both TeX expansion errors and Lua runtime faults, such as nil value accesses.[5]
LuaTeX binaries are widely available through major TeX distributions: TeX Live includes it as a core engine in its annual releases for Unix, macOS, and Windows platforms; MiKTeX provides it via its package manager for on-demand installation on Windows; and standalone binaries, often experimental, can be downloaded from the ConTeXt build farm for various architectures, compatible with the ConTeXt MkIV suite. These installations typically place the luatex executable in the system's PATH, enabling direct command-line use without additional configuration.[36][37][38]
With LaTeX and ConTeXt
LuaLaTeX serves as the LuaTeX-based engine for LaTeX documents, enabling a straightforward transition from pdfLaTeX by simply invokinglualatex instead of pdflatex during compilation.[39] This mode integrates seamlessly with LaTeX's macro system while leveraging LuaTeX's capabilities, particularly through packages like fontspec, which allows direct access to system-installed OpenType fonts and advanced font features such as ligatures and kerning without requiring font conversion. For instance, users can load an OpenType font using \setmainfont{Latin Modern Roman} to enable Unicode-aware typesetting in LaTeX documents.
In ConTeXt Mark IV, LuaTeX has been the native engine since its introduction in 2007, with Lua code deeply embedded in the macro layer to handle document setup, styling, and dynamic content generation.[40] Commands like \setupbodyfont and \definecolor often invoke underlying Lua functions for flexible configuration, allowing users to script custom layouts directly within the document source.[41] This integration eliminates the need for separate preprocessing steps, streamlining the creation of complex documents such as books or presentations.
LuaTeX maintains strong compatibility with legacy LaTeX code, supporting most standard packages with minimal adjustments. When using system or OpenType fonts in LaTeX for microtypographic features, LuaLaTeX is recommended over pdfLaTeX due to its benefits including Unicode support, direct access to system fonts, and future-proofing.[42] The microtype package enables character protrusion, font expansion, letterspacing, and interword spacing adjustments in LuaTeX, with protrusion providing the most significant visual refinement when fully enabled.[43] However, for cases requiring critical font expansion in tight justified text with classic styles and TeX fonts, pdfLaTeX may be preferable due to specific engine optimizations.[44] Similarly, hyperref works reliably with LuaTeX via its pdfTeX-compatible driver (hpdftex.def), producing hyperlinks and PDF metadata, but users may need to load it after other font-related packages to avoid conflicts. In practice, documents using classic LaTeX classes like article or book compile under LuaLaTeX with only occasional tweaks, such as disabling certain pdfTeX-specific options.[45]
One key advantage in ConTeXt workflows is the ability to prototype documents rapidly, as Lua's scripting role in the macro layer allows inline code for tasks like data-driven styling or conditional formatting, reducing iteration time compared to traditional TeX-based setups.[41] This facilitates experimental designs, such as generating tables from Lua arrays, directly within the typesetting process.
In 2024, the LaTeX Project endorsed LuaLaTeX as the preferred engine for new projects, citing its modernity, Unicode support, and extensibility via Lua as superior to pdfLaTeX and XeLaTeX for future-proof document production.[46]
Advanced Customization
LuaTeX's programmability enables users to develop custom modules by creating reusable Lua files that extend typesetting functionality. These modules are typically stored as.lua files and can be loaded using the require statement within \directlua blocks, allowing seamless integration into TeX documents; for instance, \directlua{require("mymodule")} imports a module named mymodule.lua from the TeX search path managed by kpathsea.[5] Alternatively, functions defined in external Lua files can be registered and invoked via \luafunction or \luafunctioncall, where the Lua code populates a functions table accessible through lua.get_functions_table() for efficient repeated calls.[5] This approach promotes modularity by separating Lua logic from the main TeX document, facilitating reuse across projects.[47]
Workflow automation in LuaTeX leverages Lua scripts to streamline repetitive tasks, such as batch processing multiple documents or generating dynamic PDF metadata. For batch processing, users can employ Lua initialization scripts loaded via the --lua command-line option, which execute before TeX processing and can iterate over input files to automate compilation sequences.[5] Dynamic PDF metadata, including titles, authors, and keywords, can be set programmatically using the pdf table in Lua, such as pdf.set_info("Title", "Document Title"), allowing metadata to be derived from document content or external data sources during runtime.[5] Integration with version control systems, like Git, can be achieved through wrapper scripts that invoke LuaTeX and handle commits or diffs based on compilation outputs, though this requires external shell automation.[48]
Debugging Lua code in LuaTeX involves combining Lua's built-in facilities with TeX's logging mechanisms for effective troubleshooting. Lua's print function outputs messages to the TeX log via texio.write_nl(string.format(...)), enabling real-time monitoring of variable states or execution flow during document processing.[5] The --luadebug switch activates Lua's debug library, allowing breakpoints and stack inspection, while TeX primitives like \tracingonline > 2 reveal node-level details for tracing interactions between Lua and the TeX engine.[5] Errors in Lua code trigger contextual messages in the log, and functions like tex.error() provide formatted error reporting with category support to categorize issues without halting compilation.[5]
Best practices for Lua programming in LuaTeX emphasize modular code organization, performance optimization, and clear documentation to ensure maintainable extensions. Code should be organized into modules returning tables of functions, loaded via require to avoid global namespace pollution, with local variables preferred in \directlua chunks to minimize conflicts.[47][5] For performance, avoid frequent node manipulations by batching operations and reusing tables instead of creating new ones, as LuaTeX's node library can be memory-intensive; additionally, register callbacks judiciously to prevent overhead in hot paths like line breaking.[5] Documentation standards include embedding LuaDoc-style comments in modules and using TeX comments for integration points, facilitating collaboration and version tracking in TDS-compliant directories.[47]
A practical case study of advanced customization is the implementation of a custom bibliography system using Lua-driven sorting and formatting, as exemplified by the citeproc-lua engine. This module processes bibliographic data in Citation Style Language (CSL) format, applying locale-specific sorting algorithms—such as alphabetical by author or chronological by date—and formatting rules for citations and references directly in LuaTeX. Users load the module via require("citeproc") and invoke it through callbacks like pre_mlist_to_hlist_filter to manipulate node lists for bibliography entries, enabling dynamic adjustments based on document context without relying on external tools like BibTeX. This approach demonstrates LuaTeX's flexibility for domain-specific extensions, supporting over 10,000 CSL styles for consistent output across publications.