pubtab

Language: English | 中文

Convert Excel tables to publication-ready LaTeX (and back) with stable roundtrip behavior.

Highlights

• Roundtrip Consistency — Designed for tex -> xlsx -> tex workflows with minimal structural drift.
• All-Sheets by Default — xlsx2tex exports every sheet as *_sheetNN.tex when --sheet is not set.
• Style Fidelity — Preserves merged cells, colors, rich text, rotation, and common table semantics.
• Publication Preview — Generate PNG/PDF directly from .tex via one CLI entry.
• Overleaf-Ready Output — Generated .tex starts with commented \usepackage{...} hints.

Examples

Showcase

Example A: Excel -> LaTeX (all sheets)

pubtab xlsx2tex ./tables/benchmark.xlsx -o ./out/benchmark.tex

Output files (when workbook has multiple sheets):

• ./out/benchmark_sheet01.tex
• ./out/benchmark_sheet02.tex
• ...

Example B: LaTeX -> Excel (multi-table to multi-sheet)

pubtab tex2xlsx ./paper/tables.tex -o ./out/tables.xlsx

Example C: LaTeX -> PNG / PDF preview

pubtab preview ./out/benchmark_sheet01.tex -o ./out/benchmark_sheet01.png --dpi 300
pubtab preview ./out/benchmark_sheet01.tex --format pdf -o ./out/benchmark_sheet01.pdf

Generated .tex header includes package hints (comments only):

% Theme package hints for this table (add in your preamble):
% \usepackage{booktabs}
% \usepackage{multirow}
% \usepackage[table]{xcolor}

Quick Start

pip install pubtab

Latest PyPI release: pubtab on PyPI

CLI Quick Start

# 1) Excel -> LaTeX
pubtab xlsx2tex table.xlsx -o table.tex

# 2) LaTeX -> Excel
pubtab tex2xlsx table.tex -o table.xlsx

# 3) Preview
pubtab preview table.tex -o table.png --dpi 300

# 4) Native batch pipeline (directory input)
pubtab tex2xlsx ./tables_tex -o ./out/xlsx
pubtab xlsx2tex ./out/xlsx -o ./out/tex
pubtab preview ./out/tex -o ./out/png --format png --dpi 300

Python Quick Start

import pubtab

# Excel -> LaTeX
pubtab.xlsx2tex("table.xlsx", output="table.tex", theme="three_line")

# LaTeX -> Excel
pubtab.tex_to_excel("table.tex", "table.xlsx")

# Preview (.png by default)
pubtab.preview("table.tex", dpi=300)

# Native batch pipeline (directory input)
pubtab.tex_to_excel("tables_tex", "out/xlsx")
pubtab.xlsx2tex("out/xlsx", output="out/tex")
pubtab.preview("out/tex", output="out/png", format="png", dpi=300)

Parameter Guide

pubtab xlsx2tex

pubtab tex2xlsx

pubtab preview

Common Command Recipes

# Export all sheets (default)
pubtab xlsx2tex report.xlsx -o out/report.tex

# Export a specific sheet only
pubtab xlsx2tex report.xlsx -o out/report.tex --sheet "Main"

# Two-column table + preview
pubtab xlsx2tex report.xlsx -o out/report.tex --span-columns --preview --dpi 300

Features by Workflow

1) Excel -> LaTeX

• Reads .xlsx (openpyxl) and .xls (xlrd), then renders via Jinja2 themes.
• Preserves rich formatting: merged cells, colors, bold/italic/underline, rotation, diagbox, and multi-line cells.
• Applies table-level logic: header rule generation, section/group separators, and trailing-empty-column trimming.
• Supports all-sheet export by default and deterministic *_sheetNN file naming.

2) LaTeX -> Excel

• Parses multiple tables from one .tex file and writes each table to separate worksheet(s).
• Handles commands including \multicolumn, \multirow, \textcolor, \cellcolor, \rowcolor, \diagbox, and \rotatebox.
• Expands macros (\newcommand/\renewcommand) and resolves \definecolor variants.
• Improves robustness for row/cell splitting around escaped separators and nested wrappers.

3) Preview Pipeline

• pubtab preview compiles .tex to PNG/PDF using available local LaTeX tooling.
• If system pdflatex is unavailable, TinyTeX auto-install can bootstrap compilation.
• On missing .sty errors, pubtab can parse the missing package, run tlmgr install <package>, and retry compile automatically.
• TinyTeX download uses cert-friendly SSL handling and now provides actionable hints for certificate failures.
• PNG conversion works out of the box after pip install pubtab (bundled pdf2image + PyMuPDF backends).

Configuration

Use a YAML file to define repeatable defaults. CLI arguments always take precedence over config values.

theme: three_line
caption: "Experimental Results"
label: "tab:results"
header_rows: 2
sheet: null
span_columns: false
position: htbp
font_size: footnotesize
resizebox: null
col_spec: null
header_sep: null
preview: false
dpi: 300
spacing:
  tabcolsep: "4pt"
  arraystretch: "1.2"
group_separators: [3, 6]

pubtab xlsx2tex table.xlsx -o output.tex -c config.yaml

Theme System

pubtab uses a Jinja2-based theme system. The built-in three_line theme targets academic booktabs-style tables.

Custom theme layout:

my_theme/
├── config.yaml    # packages, spacing, font_size, caption_position
└── template.tex   # Jinja2 template

List available themes:

pubtab themes

Project Structure

pubtab/
├── pyproject.toml
├── README.md
├── README.zh-CN.md
├── LICENSE
└── src/pubtab/
    ├── __init__.py        # Public API: xlsx2tex, preview, tex_to_excel
    ├── cli.py             # CLI (click)
    ├── models.py          # Data models
    ├── reader.py          # Excel reader (.xlsx/.xls)
    ├── renderer.py        # LaTeX renderer (Jinja2)
    ├── tex_reader.py      # LaTeX parser (tex -> TableData)
    ├── writer.py          # Excel writer
    ├── _preview.py        # PNG/PDF preview helpers
    ├── config.py          # YAML config loader
    ├── utils.py           # Escape and color helpers
    └── themes/
        └── three_line/
            ├── config.yaml
            └── template.tex

References

• Test data includes .tex files referenced from Azhizhi_akeyan.

Contributing

Issues and pull requests are welcome at GitHub.

License

MIT