DOCSEARCHbyAlgolia
Submit Docs

Tylax Documentation

repository·main·Indexed 19 days ago

https://github.com/scipenai/tylax

A high-performance, AST-based bidirectional converter between LaTeX and Typst. Tylax supports mathematical formulas, tables, full documents, and experimental TikZ ↔ CeTZ graphics conversion. It features a macro engine for LaTeX (newcommand, def) and a built-in evaluator for Typst (#let, #for). Available as a Rust library (v0.3.7), a Python package, a CLI tool (t2l), and can be compiled to WebAssembly (WASM).

Tokens
18.3K
Snippets
75
Records
99
Agent score
64%

What's inside tylax

  1. Core Features of Tylax

    main

    Tylax is a high-performance, AST-based bidirectional converter between LaTeX and Typst. Key features include:

    • Macro Engine:
      • LaTeX: Full expansion of \newcommand, \def, \ifmmode, and complex nested macros.
      • Typst: Built-in evaluator to handle #let bindings, #for loops, and conditional logic.
    • Bidirectional Conversion: Supports math formulas, text, tables, and full documents.
    • Table Support: Handles multicolumn, multirow, and booktabs.
    • Graphics Support: Experimental TikZ $\leftrightarrow$ CeTZ conversion.
    • Document Structure: Preserves chapters, lists, and references.

  3. Compile Tylax to WebAssembly (WASM)

    main

    Tylax can be compiled to WASM for use in web browsers. Use wasm-pack with the wasm feature enabled and no default features.

    wasm-pack build --target web --out-dir web/src/pkg --features wasm --no-default-features

  5. Install Tylax

    main

    You can install the Tylax CLI tool via cargo or build it from the source code.

    From crates.io

    Use the following command to install the binary globally:

    cargo install tylax

    From Source

    Clone the repository and build the release version:

    git clone https://github.com/scipenai/tylax.git
cd tylax
cargo build --release

  6. How MacroSignature works

    main

    A MacroSignature describes how a macro's arguments are structured. It supports two modes:

    1. Simple(u8): An optimized path for standard LaTeX macros where arguments are strictly positional (e.g., #1, #2, ..., #n).
    2. Pattern(Vec<PatternPart>): A TeX primitive style that allows complex matching using a sequence of PatternParts:
      • Argument(u8): A parameter placeholder like #1.
      • Literal(Vec<TexToken>): Exact tokens that must appear in the input stream between arguments.

    You can retrieve the total number of arguments from any signature using the .num_args() method.

    // If a signature is Pattern([Arg(1), Literal(['=']), Arg(2)])
let sig = MacroSignature::Pattern(vec![...]);
assert_eq!(sig.num_args(), 2);

  7. How MiniEval handles Typst assignments and compound assignments

    main

    In the MiniEval engine, assignments follow Typst's behavior where they return none rather than the assigned value.

    • Simple Assignment (variable = value): The target must be an identifier. It assigns the evaluated value to the identifier in the current scope.
    • Compound Assignment (variable += value, variable -= value, etc.): These operations update the existing value of an identifier using the specified operator (AddAssign, SubAssign, MulAssign, or DivAssign).

  8. How Typst macro expansion works

    main

    The MacroExpander performs AST-based expansion of Typst code. Unlike regex-based substitution, it respects the syntactic structure of the document.

    Expansion Logic

    1. Scope Lookup: It searches for identifiers in a scope_stack (innermost first) and then in the global TypstDefDb.
    2. Variable Expansion: Identifiers found in the database are replaced by their stored text.
    3. Function/Macro Expansion: When a FuncCall matches a defined function in the TypstDefDb, the expander:
      • Parses the actual arguments provided in the call.
      • Performs text-based substitution of parameters within the function body.
      • Recursively expands the resulting text to handle nested macros.
    4. Recursion Limit: To prevent infinite loops from recursive macros, the expander has a max_depth (defaulting to 50). If this limit is reached, it stops expanding and returns the original node text.

  9. Handle Citations and Cross-References between LaTeX and Typst

    main
    The refs module provides tools to parse, convert, and manage citations, labels, and cross-references when converting documents between LaTeX and Typst. It supports different citation modes (e.g., Author in Text vs. Normal), various reference types (e.g., Equation, Page, Named), and bibliography configurations.

  10. How closures and function calls work in MiniEval

    main

    MiniEval implements Typst's functional capabilities:

    • Closures: Defined via #let f(params) = body. Closures capture the current scope at definition time. They support positional parameters, named parameters with lazy defaults (evaluated in the call scope), and spread arguments (sinks).
    • Function Calls: Supports calling user-defined closures, built-in functions, and method calls (e.g., array.map()).
    • Method Calls: Supports the calc.xxx pattern for mathematical operations and specialized higher-order methods for arrays.
    • Argument Spreading: Supports spreading Array, Dict, or Arguments types into positional and named arguments.

  11. Configure the Typst preamble mode

    main

    When building a document, the PreambleMode (part of L2TOptions) determines how the Typst preamble is handled:

    • PreambleMode::Default: Uses a default style preamble based on the detected LaTeX document class.
    • PreambleMode::None: No preamble is added.
    • PreambleMode::Custom(text): Injects the provided text as the preamble. Ensure custom text ends with \n\n for proper formatting.

  12. Understand the ExpandResult structure

    main

    When using expand_macros_with_warnings, the returned ExpandResult provides access to the internal state of the expansion process:

    FieldTypeDescription
    outputStringThe final expanded Typst source code string.
    nodesVec<ContentNode>The sequence of content nodes produced after expansion and show-rule application.
    warningsVec<EvalWarning>Any warnings encountered during the MiniEval process.