tabularray LaTeX3 Package

The tabularray package is a LaTeX3-based tool for typesetting tabulars and arrays. Unlike traditional LaTeX table implementations that rely on low-level TeX commands like \halign, \noalign, \span, and \omit, tabularray uses LaTeX3 functions to parse and typeset tables.

Key features include:

• Compatibility: It maintains compatibility with the basic syntax of standard LaTeX2 tables.
• Separation of Concerns: It completely separates table contents from table styles.
• Key-Value Configuration: Table styles can be configured entirely using a key-value interface, making it easier to manage complex layouts without modifying the table content itself.

The package includes several libraries to extend functionality:

• booktabs: Provides \toprule, \midrule, and \bottomrule.
• siunitx: For scientific notation, table alignment, and the s column type.
• amsmath: For math environments and the delimiter option.
• tikz: For drawing in normal, multispan, or corner nodes of cells.
• diagbox: For diagonal box cells.
• counter: For managing table counters.
• functional: For functional programming patterns within table specs.
• nameref and zref: For referencing.
• hyperlinks: For interactive tables.

Advanced styling is achieved through selectors and specialized commands:

• Selectors: Use odd, even, or every selectors, as well as U-Z indexes to target specific rows or columns.
• Child Selectors: Mix child selectors with child indexes or use indexers/selectors for child tuples.
• Identification: Use ids and classes within the \SetChild command.
• Expansion: Use the expand outer option for advanced layout control.

Manage the overall table environment with these options and commands:

• Global Settings: Use \SetTblrDefault for defaults and \SetTblrInner/\SetTblrOuter for scoped settings.
• Layout: Control stretch, rulesep, baseline (outer option), and mode (for math tables).
• Counters: Access rownum, colnum, rowcount, and colcount.
• Nesting: Support for nested tabularray tables.

Control the structure of your table using:

• Types: Use @, !, >, and < to define row and column types.
• Spacing: Adjust rowsep and colsep options.
• X Columns: Use X columns with positive or negative coefficients for flexible width allocation.
• Special Delimiters: Use \*[dimen], \ elax, or \hline\relax for specific formatting needs.

You can style table elements using several options:

• Cells: Use bg (background), fg (foreground), font, and measure options.
• Rows and Columns: Apply bg options to entire rows or columns.
• Spanning Cells: Apply bg with hspan (multicolumn) or vspan and valign (multirow) to ensure colors cover the spanned area correctly.

For tables that span multiple pages, use the longtblr environment with these capabilities:

• Page Control: Use \pagebreak, \nopagebreak, or the pagebreak option in hborder.
• Customization: Use \NewTblrTheme, \SetTblrStyle, and \TblrNote.
• Layout: Handle tall tables with \TblrOverlap and manage spacing with \parskip.
• Constraints: The package can forbid page breaks inside multirow cells to maintain visual integrity.

The tabularray package provides extensive control over cell properties. You can manage:

• Alignment: Vertical and horizontal alignment for single-line and multi-line cells, including support for stretch and parbox cells.
• Spanning: Multicolumn (hspan) and multirow (vspan) cells, including complex combinations of both.
• Line Breaking: Automatic line breaking using \ or within parbox cells.
• Custom Commands: The cmd option for cells.

For troubleshooting specific alignment or spanning behaviors, refer to test files cell-001 through cell-011.

Lines in tabularray can be customized via:

• Styles: Different styles and widths for both hlines and vlines.
• Positioning: Use leftpos, rightpos, abovepos, and belowpos to control line placement, alongside standard \hline and \cline commands.
• Defaults: Global control over default rule widths and colors.

If you wish to contribute improvements to tabularray support within the tex4ht ecosystem, follow these steps to develop and test a new tabularray.4ht driver:

1. Prepare source files: Download tex4ht-4ht.tex and tex4ht-html4.tex.
2. Consolidate code: Copy the existing tabularray code from those files into a new file named tabularray-4ht.tex.
3. Develop improvements: Modify tabularray-4ht.tex to enhance support.
4. Generate the driver: Run the following command to generate the tabularray.4ht file:

   texlua tex-to-4ht.lua

5. Verify changes: Compile test documents using your newly generated tabularray.4ht.
6. Submit: Submit your changes in tabularray-4ht.tex to the TeX4ht maintainers.

The benchmark.lua script is used to compare the running time of the tabularray package version currently in the repository against a specific TeX Live distribution version.

To run a benchmark, execute the script and provide the target TeX Live version as a command-line argument. The script will generate a benchmark data file named output-<tlver>.txt, where <tlver> is the version you provided.

# Example: Running benchmark for TeX Live 2024
lua benchmark.lua 2024