TWBG_Materials/文档润色流和知识库构建流/claude-scholar/skills/publication-chart-skill/references/source-guides/pubtab-architecture.md

pubtab architecture (source-driven)

This guide explains pubtab from the actual package layout under pubtab/src/pubtab.

Core files:

• __init__.py
• cli.py
• models.py
• reader.py
• renderer.py
• config.py
• _preview.py
• tex_reader.py
• backends/
• themes/

1. Start at pubtab.__init__

The public contract is defined in __init__.py.

Public exports are intentionally small:

• xlsx2tex
• preview
• compile_pdf
• tex_to_excel
• SpacingConfig

This is the key architectural signal: pubtab exposes a compact API, while the real complexity is pushed into reader/renderer/preview internals.

2. Core data model layer

models.py defines the structured table representation.

Important dataclasses:

• CellStyle
• Cell
• TableData
• SpacingConfig
• ThemeConfig
• BackendConfig

Source fact:

• the shared structured representation is TableData, not raw Excel cells or raw LaTeX text.

Forward and reverse conversions both pass through this structured table model.

3. Forward pipeline: Excel to LaTeX

The main forward path is:

1. xlsx2tex(...) in __init__.py
2. read_excel(...) in reader.py
3. render(...) in renderer.py
4. optional preview through _preview.py

This gives a clean source-driven decomposition:

• reader.py = file ingestion and structure recovery
• renderer.py = LaTeX generation
• _preview.py = compile and raster preview

4. Reverse pipeline: LaTeX to Excel

The reverse path is:

1. tex_to_excel(...) in __init__.py
2. read_tex_multi(...) from tex_reader.py
3. writer functions to .xlsx

So roundtrip support is not an afterthought. It is a real architecture branch.

5. reader.py is richer than a plain spreadsheet loader

From the source, reader.py does much more than “read cells”:

• supports .xlsx and .xls
• extracts rich text segments
• reconstructs merged cells and spans
• reads styling information
• trims only trailing globally empty columns
• reads pubtab metadata sheets
• restores group separators, multicolumn alignment hints, and math-script hints

Interpretation from source:

• pubtab is optimized for publication table semantics, rather than for plain tabular text dumping.

6. renderer.py is the central logic hub

renderer.py turns TableData into backend-specific LaTeX.

From the source, it handles:

• style/theme loading
• backend template loading
• spacing resolution
• column spec construction or projection
• tabular vs tabularray differences
• merged cells, row/column spans, header rules, vertical rules
• background colors and grouped separators
• final template rendering

This file is where most of the difficult publication logic lives.

For skill design, that means:

• backend choice is not a cosmetic toggle
• column spec and rule behavior are structural concerns
• preview/render bugs usually require reading renderer.py

7. Theme vs backend is a real split

The codebase separates:

• themes in themes/
• LaTeX backends in backends/

That is reflected in two dataclasses:

• ThemeConfig
• BackendConfig

And in two loaders:

• load_theme(...)
• load_backend(...)

This is a major architectural point for the skill:

• theme decides stylistic defaults,
• backend decides LaTeX environment/template behavior.

Do not explain them as if they were the same thing.

8. Config precedence is explicit

In xlsx2tex(...), the source implements a clear precedence order:

1. hardcoded defaults
2. YAML config loaded by config.py
3. explicit function kwargs
4. in some roundtrip cases, values recovered from TableData

This is why user-facing guidance should say “CLI flags or function kwargs override YAML config.”

9. Multi-file and multi-sheet support are first-class

From __init__.py:

• directory input is supported for both forward and reverse paths
• sheet enumeration is supported when sheet=None
• multi-sheet export produces *_sheetNN.tex

The default skill guidance can therefore recommend batch/file-driven workflows, not only one-table-at-a-time usage.

10. Preview is a real compilation layer

preview(...) and compile_pdf(...) in __init__.py delegate into _preview.py.

That layer:

• finds or installs pdflatex
• builds a standalone document
• compiles the output
• retries missing packages through tlmgr
• converts PDF to PNG when requested

Preview is not a fake HTML-like snapshot. It is a real LaTeX compile pipeline.

11. tex_reader.py closes the roundtrip loop

tex_reader.py is substantial, not decorative.

From the source it supports parsing of:

• tabular
• tblr
• longtblr
• talltblr

It also handles:

• color parsing
• rule parsing
• multirow/multicolumn reconstruction
• metadata extraction
• grouped rows and placeholder cleanup

This makes pubtab suitable for source-aware roundtrip and migration tasks, rather than only one-way Excel export.

12. Reading order for source debugging

When you need source-level certainty, use this order:

1. pubtab/src/pubtab/__init__.py
2. pubtab/src/pubtab/models.py
3. pubtab/src/pubtab/reader.py
4. pubtab/src/pubtab/renderer.py
5. pubtab/src/pubtab/_preview.py
6. pubtab/src/pubtab/tex_reader.py
7. pubtab/src/pubtab/backends/ and themes/
8. pubtab/src/pubtab/cli.py for flag-to-API mapping only

13. Implications for this skill

The source says the most faithful default workflow is:

• use xlsx2tex(...) or CLI xlsx2tex for forward generation,
• use preview(...) to verify actual compile output,
• use tex_to_excel(...) for roundtrip or migration tasks,
• explain theme/backend separately,
• escalate into renderer/source debugging only when table structure or LaTeX behavior is the real problem.