texsmith 0.2.1.dev0__tar.gz → 0.3.0__tar.gz

texsmith-0.3.0/.github/issues/plain-md-caption-inline-formatting.md

@@ -0,0 +1,134 @@
+# Plain Markdown table caption with inline formatting is silently dropped
+
+## Summary
+
+When a `Table: …` caption line above a plain Markdown table (i.e. not a
+` ```yaml table ` fence) contains inline Markdown markers — italics
+(`*x*`), inline code (`` `x` ``), links, etc. — the caption is **silently
+dropped**: it does not become a `<caption>` element on the table and
+instead remains as a plain paragraph in the output (so it renders as body
+text in front of the table, unrelated to it).
+
+This is the symmetric counterpart of the yaml-table caption bug fixed in
+`extensions/tables/html.py` (use of `_set_inline_content` for the caption
+text). The plain-Markdown path has its own preprocessor and treeprocessor
+and was not addressed by that fix.
+
+## Reproduction
+
+```markdown
+Table: Coverage of the old foundation (*Info1*, *Info2*)
+
+| Skill | Description |
+|-------|-------------|
+| Foo   | Bar         |
+```
+
+After `texsmith --build … article`, the rendered LaTeX contains:
+
+```latex
+Table: Coverage of the old foundation (\emph{Info1}, \emph{Info2})
+
+\begin{table}[H]
+\centering
+\begin{tabular}{ll}
+…
+\end{tabular}
+\end{table}
+```
+
+— the `Table: …` line is rendered as a regular paragraph; the caption is
+**not** attached to the table at all (no `\caption{…}` is emitted).
+
+The same source without italics works correctly:
+
+```markdown
+Table: Coverage of the old foundation
+
+| … |
+```
+
+→ produces a proper `\caption{Coverage of the old foundation}` inside the
+table environment.
+
+## Root cause
+
+[`_MarkdownTableCaptionTreeprocessor._caption_from_paragraph`](../../src/texsmith/extensions/tables/markdown.py)
+early-returns when the paragraph contains any child elements:
+
+```python
+@staticmethod
+def _caption_from_paragraph(
+    paragraph: ElementTree.Element,
+) -> _CaptionInfo | None:
+    if len(paragraph):
+        # Caption paragraphs are expected to be plain text.
+        return None
+    text = (paragraph.text or "").strip()
+    if not text.startswith("Table:"):
+        return None
+    return _parse_caption_line(text)
+```
+
+A paragraph containing `<em>`, `<code>`, `<a>` etc. has
+`len(paragraph) > 0`, so the treeprocessor returns `None` and the
+paragraph is left in the document. No fallback handles this case —
+`_attach_caption` is also written under the assumption that the caption
+is plain text (it does `caption.text = info.text`).
+
+## Suggested fix
+
+Two changes:
+
+1. In `_caption_from_paragraph`, do **not** short-circuit on
+   `len(paragraph) > 0`. Inspect `paragraph.text` (text before the first
+   child) for the `Table:` prefix; if present, return a richer
+   `_CaptionInfo` that preserves the paragraph's inline structure.
+
+2. In `_attach_caption`, instead of `caption.text = info.text`, build the
+   `<caption>` element by:
+   - Setting `caption.text` to the leading text after stripping
+     `"Table:"` (and trimming any leading whitespace).
+   - Moving the paragraph's children into the new `<caption>` element
+     (preserving order).
+   - If the existing `_CAPTION_LINE_RE` extracts a `{#label}` suffix,
+     that suffix lives in the *trailing tail* of the last child or in
+     the leading text when no children exist; we need to detect it on
+     whichever node carries it and strip it before moving children.
+
+A clean shape:
+
+```python
+@staticmethod
+def _caption_from_paragraph(paragraph):
+    leading = (paragraph.text or "").lstrip()
+    if not leading.startswith("Table:"):
+        return None
+    # Strip the Table: prefix from the leading text, leaving inline
+    # structure intact.
+    return _CaptionInfoRich(
+        leading=leading[len("Table:"):].lstrip(),
+        children=list(paragraph),
+        # tail of last child holds the optional {#label} suffix
+        trailing=…,
+    )
+```
+
+`_attach_caption` then becomes a transfer of (leading text, children,
+trailing text without `{#label}`) into a fresh `<caption>` element, with
+the label peeled off and assigned to `table.set("id", label)` as today.
+
+## Workaround
+
+Use a ` ```yaml table ` fence instead of a plain Markdown table — the
+yaml-table preprocessor handles caption italics correctly since the fix
+to `extensions/tables/html.py` that wraps caption text through
+`_set_inline_content`.
+
+## Out of scope but worth verifying
+
+- Inline code in captions (`` `foo` ``) likely fails the same way. Same
+  root cause.
+- Inline links (`[text](url)`) probably same.
+- Whether the source-line-level capture path used in some other table
+  flows has the same blind spot is worth a quick audit while at it.

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/.github/workflows/ci.yml

@@ -21,6 +21,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.18"
           enable-cache: true
           cache-python: false
         env:
@@ -55,6 +56,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.18"
           enable-cache: true
           cache-python: false
         env:
@@ -65,7 +67,7 @@ jobs:
 
       - name: Install Cairo (macOS)
         if: runner.os == 'macOS'
-        run: brew install cairo
+        run: brew list cairo >/dev/null 2>&1 || brew install cairo
 
       - name: Run pytest
         run: uv run pytest
@@ -92,6 +94,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.18"
           enable-cache: true
           cache-python: false
         env:
@@ -128,6 +131,7 @@ jobs:
       # Install system dependencies (Playwright, cairo, etc.)
       - name: Install system dependencies
         run: |
+          sudo apt-get update
           sudo apt-get install -y libglib2.0-0 libnspr4 libnss3 libatk1.0-0 \
           libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 \
           libxdamage1 libxfixes3 libxrandr2 libgbm1 libcairo2 libpango-1.0-0
@@ -136,6 +140,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.18"
           enable-cache: true
           cache-python: false
 
@@ -149,6 +154,21 @@ jobs:
           uv run playwright install-deps
           uv run playwright install chromium
 
+      # Build the main Python package distribution before docs/examples touch the repo
+      - name: Build distributions (texsmith)
+        run: uv build
+
+      # Build the MkDocs plugin distribution before docs/examples touch the repo
+      - name: Build distributions (mkdocs_texsmith)
+        working-directory: packages/mkdocs_texsmith
+        run: uv build
+
+      # Ensure no generated artifacts pollute the version calculation
+      - name: Verify clean git state
+        run: |
+          git status --porcelain
+          test -z "$(git status --porcelain)"
+
       # Build all examples (clean + all)
       - name: Build examples
         run: |
@@ -165,15 +185,6 @@ jobs:
         run: |
           make docs
 
-      # Build the main Python package distribution
-      - name: Build distributions (texsmith)
-        run: uv build
-
-      # Build the MkDocs plugin distribution
-      - name: Build distributions (mkdocs_texsmith)
-        working-directory: packages/mkdocs_texsmith
-        run: uv build
-
       # Upload all artifacts needed for the release job
       - name: Upload release artifacts
         uses: actions/upload-artifact@v4
@@ -242,6 +253,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.18"
           enable-cache: true
           cache-python: false
         env:

texsmith-0.3.0/.wiki/README.md

@@ -0,0 +1,20 @@
+# Cached Wikipedia images
+
+This folder contains locally cached copies of Wikipedia images used in the examples.
+
+Why this exists:
+
+- CI (especially Windows) occasionally hits HTTP 429 rate limits when fetching directly from `upload.wikimedia.org`.
+- Keeping a local copy makes the examples deterministic and prevents flaky builds.
+
+How it works:
+
+- The Markdown examples still reference HTTP URLs, but we point them to the repo via
+  `https://raw.githubusercontent.com/yves-chevallier/texsmith/refs/heads/master/.wiki/...`.
+- This preserves the HTTP fetch path in the renderer while avoiding third‑party rate limits.
+
+If you need to add new images:
+
+1. Download the file from Wikipedia (or another source with a compatible license).
+2. Place it in this folder using a stable filename.
+3. Update the example markdown to reference the raw GitHub URL.

texsmith-0.3.0/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
+and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Structured `glossary:` front-matter section, validated with pydantic, that complements the existing `*[KEY]: …` body syntax. Each entry carries an explicit `description` and an optional `group`; groups are declared at the top with their displayed title (`groups: {tech: Acronymes techniques, …}`), and entries with no group fall back to the standard acronym table. TeXSmith emits one localised `\printglossary[type=<group>, title=<title>]` per group in declaration order, plus `\printglossary[type=\acronymtype]` for ungrouped entries; the default acronym title now uses `\acronymname` so `babel` localises it (e.g. *Acronymes* under `language: french`). Front-matter entries that never appear in the body are still defined in the glossary; entries that do appear are auto-substituted with `\acrshort{KEY}` whenever the strict, case-sensitive form occurs in the text — `\Gls`/`\GLS` casing helpers are not synthesised (a documented limitation). The `article` template now loads `babel` before `extra_packages` so the `glossaries` package picks up the active language. New `examples/glossary/` tutorial.
+- `article` template now supports `listoffigures: true` and `listoftables: true` front-matter flags (mirroring the `book` template), plus a `lists_position: toc | backmatter` knob to choose whether the lists are inserted right after the table of contents (default) or just before the backmatter and references. Each list is wrapped in `\ifnum\value{figure|table}>0` so empty documents don't emit blank pages.
+- New `yaml table` Markdown fence describing complex tables in YAML and compiling to `tabular` / `tabularx` / `longtable` on demand. Supports multi-row and multi-column cells (in headers and body), nested grouped headers, width-groups, separators with optional labels, footers, captions via the standard `Table: …` syntax, and explicit width control. Validation errors surface as inline error admonitions with a clear, localised message. New `examples/tables/` tutorial pairs each YAML source with its rendered output and ships a Makefile to build the demo PDF.
+- `ts-extra` now auto-loads the `multirow` package when `\multirow` is detected in the rendered LaTeX.
+- `Table: <caption> {#label}` now also works on plain Markdown tables: a tree processor pairs the caption paragraph with the following `<table>` and injects a `<caption>` child carrying the caption text (and optional `id` from the `{#label}` part). Both the yaml-table renderer and the legacy table renderer consume `<caption>` directly, so the LaTeX output gets a proper `\caption{…}` with its `\label{…}`.
+- 0.5 em of vertical breathing room is inserted between the caption and the table body for both yaml-tables and plain Markdown tables when a caption is present.
+- New `yaml table-config` fence applied right below a plain Markdown table sends per-column attributes (`align`, `width`, `width-group`) and table-level settings to the yaml-table renderer. Marks the table with `data-ts-*` attributes so it goes through the same `tabular` / `tabularx` / `longtable` selection as full yaml-tables, including caption handling. A `BlockProcessor` parses the fence into a real ElementTree marker so a sibling tree processor can bind the config to the preceding `<table>`.
+- New explicit `width: X` value (case-insensitive, alias for `tabularx`'s `X` column) marks a single column as flexible without needing a `width-group` shim. When any column carries `width: X`, only that column expands; the others keep their natural width.
+- `align` accepts long forms (`left`, `right`, `center`, `centre`, `justify`, `justified`) in addition to the short single-letter forms; both are normalised to the short form internally.
+- New `{margin}[note]{side?}` inline shorthand for margin notes, joining the unified `{keyword}[content]` family (alongside `{index}[term]` and `{latex}[payload]`). The optional single-letter suffix picks a side — `l` / `i` force the left margin (scoped `\reversemarginpar`), `r` / `o` the right; without a suffix the note follows the document's default (right in `oneside`, outer in `twoside`). Inline markdown inside the note is preserved (bold, italic, code, links). Compiles to `\marginnote{…}` from the LaTeX `marginnote` package, which `ts-extra` now auto-loads on detection. Three defensive layers keep notes within the page on any geometry: (1) `\marginfont` is configured with `\footnotesize`, `\sloppy`, `\emergencystretch=1em` and lowered hyphenation penalties so long words break (or inter-word spacing stretches) rather than overflow; (2) an `\AtBeginDocument` hook clamps `\marginparwidth` to the horizontal space the document's geometry actually reserves on each side (recto and, in twoside, verso), minus `\marginparsep` and a 6 pt safety buffer; (3) a custom `geometry: {left: 3cm, right: 4cm}` yields notes that still fit on both pages with no manual `marginparwidth=…` tweak. New `examples/marginnote/` tutorial with a Makefile; extension documented in `docs/syntax/notes.md`.
+
+### Fixed
+
+- Two long-standing test assertions that had drifted away from the templates they exercise: `test_render_template_applies_markdown_metadata` expected the title/subtitle pair `\\\large` (pre-spacing format) but the article template now emits `\\[0.5em]\large` (commit `c9aff0f`); `test_article_template_supports_columns_option` expected the `twocolumn` documentclass option, but the article template intentionally omits it and uses `\twocolumn[…]` after `\maketitle` so `\@thanks` stays populated and affiliation footnotes survive (`\tsreplayfn` flushes them). Both assertions updated to match the current — correct — template behaviour.
+- Python 3.10 compatibility regression: `enum.StrEnum` is 3.11+, but `requires-python = ">=3.10"` and the CI matrix exercises 3.10. The `tables` extension imported `StrEnum` unconditionally, breaking 50 test files at collection time on 3.10 (every test that transitively touches the markdown processor). Added a tiny version-guarded shim that subclasses `str, Enum` on 3.10 and re-exports the stdlib class on 3.11+. Aligned `ruff target-version` with `requires-python` so the version guard isn't flagged as `UP036 outdated version block`.
+- Page-number prefix (`n1` / `n2`) leaking into grouped acronym tables produced by the `glossaries` package. Two-part fix: (1) bumped the `pyxindy` dependency to **0.0.7**, which routes every `markup-locref` slot (`:open` / `:close` / `:sep` / `:prefix`) through the existing `_normalize_markup_string` helper so the xindy `~n` newline escape no longer leaks into the rendered output (`_update_locfmt` previously copied the raw strings verbatim); (2) extended TeXSmith's defensive post-processor (`adapters/latex/engines/__init__.py`) to glob `*-gls` in addition to `*.gls` so files emitted by `\newglossary*{<type>}` (e.g. `glossary.technical-gls`) go through `sanitize_glossary_output` for users still on pyxindy <0.0.7.
+- Glossary page numbers were not clickable: the `glossaries` package only wraps numbers in `\hyperpage` when `hyperref` is loaded *before* it. Both the `article` and `book` templates now load `babel` and `hyperref` before `\VAR{extra_packages}` (which carries `glossaries` via `ts-glossary`), enabling both babel-localised acronym titles and hyperref-backed clickable backreferences. Same constraint that applies to babel localisation, made explicit in the preamble comments.
+- HTML comments (`<!-- ... -->`) are now stripped before rendering and no longer appear verbatim in the LaTeX output. A shared `core.html_utils.strip_html_comments` helper runs in `extract_slot_fragments` (before node serialisation, where `str(comment_node)` would otherwise silently drop the `<!--`/`-->` delimiters and expose the raw comment text) and from the `discard_unwanted` PRE-phase handler.
+- `tabularx` column specifications now use `>{\raggedright\arraybackslash}X`, `>{\raggedleft\arraybackslash}X`, and `>{\centering\arraybackslash}X` for all columns (including the first), replacing the previous `l`/`X` split. This prevents text overflow in two-column (`twocolumn`) document layouts and improves line-breaking throughout.
+- Inline formatting (bold, italic, etc.) inside quoted text (`"**bold**"`) is now correctly rendered — `AtomicString` was preventing further inline processing inside `<q>` elements.
+- Silent exception swallowing in post-render rule/asset collection now emits a diagnostic warning instead of discarding the error.
+- Nested list environments (`\begin{itemize}`) no longer appear glued to the parent item text on the same line; a newline is now inserted between the item content and any nested `\begin{itemize|enumerate|description}`.
+- Table caption numbering no longer skips numbers (e.g. 1, 2, 4, …). `ts-extra` previously auto-loaded `ltablex` under single-column layouts, which silently transformed every `tabularx` into a `longtable` internally and bumped the `table` counter twice per use. Replaced by a plain `tabularx` load; explicit `longtable` is still detected on demand.
+
+### Changed
+
+- Removed dead code after the early `return` in `_allow_hyphenation` (unreachable lines).
+- Dropped the unused `fragments` field from `ExecutionContext`; fragment resolution was already propagated through `template_overrides`.
+- Deduplicated `runtime_common.get("code")` lookups in `_render_slot_fragments` into a single local variable.
+- Reverted an uncommitted injection of `template_overrides` into the Jinja render context (`runtime_common`) — it had no consumer and exposed internal state unnecessarily.
+- **Tables extension refactor (SSOT).** Introduced `texsmith.extensions.tables.constants` housing `TableAttr` (StrEnum for every `data-ts-*` attribute), `PERCENT_RE`, `ALIGN_ALIASES` / `ALIGN_WRAPPERS`, and a `Priority` class that documents each pipeline position. Removed the duplicate `_PERCENT_RE` in `layout.py`. Collapsed the three identical align/width/width-group validator triplets (`LeafColumn`, `ColumnGroup`, `ColumnConfig`) into a shared `_ColumnAttrs` base. Extracted a single `_consume_fence` helper used by both preprocessors and the block processor; the two preprocessors now fail identically (admonition surfaced on parse error) instead of diverging between silent fall-through and block-level error emission. Caption handling no longer wraps the table in a throwaway `<figure>` / `<figcaption>` to be unwrapped by `render_figures`; the `<caption>` is injected directly into the `<table>`. `render_figures` keeps its figure-with-table path (still reached by `pymdownx.blocks.caption`) and routes via a new `is_texsmith_table()` helper instead of literal attribute comparison. The `build_error_element` helper in `tables.html` lets the preprocessor and the block processor share admonition construction.
+- **`slot_options` plumbing simplified.** The per-slot render flags (`SlotOptions`) now live only on `Document` and are read directly by the consumer (`extract_slot_fragments`) instead of being copied through `ExecutionContext` and `BinderContext`. The `parse_slot_mapping_with_options` and `extract_front_matter_slots_with_options` wrappers were removed; `parse_slot_mapping` and `extract_front_matter_slots` now always return a `(selectors, options)` tuple.
+- **Fragment resolution extracted.** New `core.fragments.resolution` module with a typed `FragmentModifiers(append, prepend, disable)` dataclass, `parse_modifiers(raw)` for front-matter shapes, and a pure `merge_fragments(defaults, override, *, cli_enable, cli_disable)` function. `_resolve_fragments_list` is now a 15-line orchestrator instead of a 65-line dispatcher with three nested helpers.
+- **Silent `except Exception` handlers documented or warned.** Font-fallback scans in `conversion/renderer.py` now emit a warning via the diagnostic emitter on failure; user-supplied `should_render` callbacks in `core/fragments` warn with the fragment name instead of silently swallowing the failure; the third-party template-distribution discovery in `templates/loader.py` keeps its broad catch but carries an explicit comment and `# noqa: BLE001` explaining why it is intentional.
+
+### Removed
+
+- **`ExecutionContext` and `BinderContext` merged into `ConversionContext`.** Both classes carried an almost identical set of fields resolved at two successive stages (pre- and post-template-binding); they were collapsed into a single `core.conversion_contexts.ConversionContext` with optional `config` / `template_binding` fields that become populated when `bind_template` runs. Dead fields dropped: `BinderContext.documents: list[Document]` (only ever appended, never read meaningfully), `BinderContext.bound_segments` (written in `_render_document`, never read). The file `core/execution.py` has been deleted.
+
+- **Function renames tracking the new context class:**
+  - `resolve_execution_context` → `resolve_conversion_context` (returns the partially-populated `ConversionContext`).
+  - `build_binder_context` → `bind_template` (mutates the context in place to populate `config`, `template_binding`, and the template-refined `slot_requests`; same object returned for chaining). Its keyword parameter `execution=` is renamed to `context=`.
+  - `ConversionResult.binder_context` field renamed to `ConversionResult.context`.
+
+## [0.2.2] - 2026-02-24
+
+### Added
+
+- CLI/API version reporting (`texsmith --version`, `get_version()`).
+- Configurable HTTP user agent for remote asset and emoji fetching (`--http-user-agent` / `TEXSMITH_HTTP_USER_AGENT`).
+- TLS download helper with cert guidance for network fetches.
+- Cached Wikipedia images for the book example under `.wiki/` with documentation.
+
+### Changed
+
+- Horizontal rules now force a page break in LaTeX output.
+- Asset summaries hide temporary build roots and `.converted` cache files.
+- Letter example no longer hard-codes the format, allowing snippet overrides; docs include local build steps.
+- Book example images now resolve via raw GitHub URLs to avoid third‑party rate limits.
+- CI now runs `apt-get update` before installing system dependencies.
+
+### Fixed
+
+- Playwright SVG conversion now handles `viewBox`-only SVGs to prevent blank PDFs.
+- Suppressed noisy Tectonic `lineno` UTF‑8 warnings and made console output encoding-safe.
+- XeTeX fallback transitions no longer leak across scripts; arrow glyphs prefer Noto Sans Symbols.
+- Convert common Unicode symbols to LaTeX math macros to avoid missing glyphs.
+
+## [0.1.0] - 2025-12-20
+
+### Added
+
+- Initial TeXSmith CLI for Markdown to LaTeX/PDF conversion, including multi-document rendering and slot-aware templates.
+- Template system with built-in article/book/letter/snippet variants plus user template discovery and overrides.
+- Fragment system for typography, geometry, fonts, glossary/index, code blocks, and callouts.
+- Extensions for bibliography/citations, acronyms, mermaid/drawio diagrams, and rich admonitions.
+- Asset pipeline for fonts/emoji, hashed assets, and download helpers for Tectonic/Biber/PyXindy.
+- Documentation and examples (`docs/`, `mkdocs.yml`, `examples/`) plus developer docs and scripts (`README.md`, `DEVEL.md`, `scripts/`).
+- Tooling and quality gates (`pyproject.toml`, `noxfile.py`, `Makefile`, tests, CI, coverage, ruff/pyright configs).
+
+### Changed
+
+- Renamed the project to TeXSmith and refactored the codebase into `src/texsmith` with a `texsmith.core` conversion pipeline.
+- Reworked bibliography handling, front matter parsing, slot injection, and template rendering orchestration.
+- Switched the default LaTeX engine to Tectonic and improved typography, headings, and smart punctuation defaults.
+
+### Fixed
+
+- Numerous issues across templates (article/book), MkDocs output, snippets, CI, and Windows compatibility.
+
+### History
+
+- 2025-10-18: Seeded the initial LaTeX renderer and template set under `latex/`.
+- 2025-10-19: Added performance instrumentation and the first `docs/` content.
+- 2025-10-20: CLI accepted Markdown input, introduced article templates, examples, and a `build` command.
+- 2025-10-21: Added render phases, acronyms/index extensions, and renamed the project to TeXSmith.
+- 2025-10-23: Added the EPFL thesis template, `LICENSE.md`, `DEVEL.md`, and multi-document CLI support.
+- 2025-10-27: Major refactor around `texsmith.core`, `ConversionService`, diagnostics, and regression tests.
+- 2025-11-16: Added the mermaid extension and expanded built-in templates and docs.
+- 2025-11-24: Introduced rule/slot validation diagnostics and refined fragment registry behavior.
+- 2025-11-27: Made Tectonic the default engine and added download helpers/Makefiles for fonts and tools.
+- 2025-12-01: Added diagram generation via Playwright and `ts-typesetting` fragments.
+- 2025-12-11: Polished CLI options, snippets, and CI pipelines leading up to the release tag.

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: texsmith
-Version: 0.2.1.dev0
+Version: 0.3.0
 Summary: A Markdown to LaTeX converter.
 Project-URL: Homepage, https://github.com/yves-chevallier/texsmith
 Author-email: Yves Chevallier <yves.chevalier@heig-vd.ch>
@@ -32,7 +32,7 @@ Requires-Dist: pymupdf>=1.24.3
 Requires-Dist: pypdf>=6.1.1
 Requires-Dist: python-markdown-math>=0.9
 Requires-Dist: python-slugify>=8.0.4
-Requires-Dist: pyxindy>=0.0.6
+Requires-Dist: pyxindy>=0.0.7
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: requests>=2.32.5
 Requires-Dist: rich>=13.9.0
@@ -57,7 +57,8 @@ Description-Content-Type: text/markdown
 TeXSmith is a [Python](https://www.python.org/) package and CLI tool to convert **Markdown** or **HTML** documents into LaTeX format. It is designed to be extensible via templates and integrates with [MkDocs](https://www.mkdocs.org/) for generating printable documents from documentation sites.
 
 <p align="center">
-<img src="docs/assets/ts-logo.svg" width="70%" />
+<!-- Absolute link for compatibility with PyPi -->
+<img src="https://raw.githubusercontent.com/yves-chevallier/texsmith/master/docs/assets/ts-logo.svg" width="70%" />
 </p>
 
 ## TL;DR
@@ -67,6 +68,8 @@ pip install texsmith
 texsmith input.md input.bib -o build/ --build
 ```
 
+Check the installed version with `texsmith --version` or in Python with `texsmith.get_version()`.
+
 ## Key features
 
 - **MkDocs-native Markdown** – Ships with the same Material + pymdown extension stack you use in MkDocs, so tabs, callouts, annotations, tooltips, and data tables survive the conversion.

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/README.md

@@ -14,7 +14,8 @@
 TeXSmith is a [Python](https://www.python.org/) package and CLI tool to convert **Markdown** or **HTML** documents into LaTeX format. It is designed to be extensible via templates and integrates with [MkDocs](https://www.mkdocs.org/) for generating printable documents from documentation sites.
 
 <p align="center">
-<img src="docs/assets/ts-logo.svg" width="70%" />
+<!-- Absolute link for compatibility with PyPi -->
+<img src="https://raw.githubusercontent.com/yves-chevallier/texsmith/master/docs/assets/ts-logo.svg" width="70%" />
 </p>
 
 ## TL;DR
@@ -24,6 +25,8 @@ pip install texsmith
 texsmith input.md input.bib -o build/ --build
 ```
 
+Check the installed version with `texsmith --version` or in Python with `texsmith.get_version()`.
+
 ## Key features
 
 - **MkDocs-native Markdown** – Ships with the same Material + pymdown extension stack you use in MkDocs, so tabs, callouts, annotations, tooltips, and data tables survive the conversion.

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/about/devel/index.md

@@ -31,7 +31,6 @@ Roadmap and development notes for TeXSmith. I keep this file as a running checkl
 - [ ] Support for `tocloft` package to customize list of figures/tables
 - [ ] Support for `enumitem` package to customize lists
 - [ ] Develop submodules as standalone plugins
-  - [ ] Marginalia (`marginpar` package with footnotes syntax)
   - [ ] Epigraph Plugin
   - [ ] Letterine
   - [ ] Custom variables to insert in a document using mustaches

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/cli/index.md

@@ -134,6 +134,9 @@ $ texsmith --help
 `--hash-assets`
 : Hash the filenames of stored assets instead of preserving their original names. This helps avoid filename collisions when multiple assets with the same name are used in different documents.
 
+`--http-user-agent`
+: Override the User-Agent header used when fetching remote assets (images, emoji). You can also set `TEXSMITH_HTTP_USER_AGENT` in the environment.
+
 `--manifest`, `-m`
 : Generate a `manifest.json` file alongside the LaTeX output, containing metadata about the rendered document, including input sources, template details, and rendering options.
 

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/examples/letters.md

@@ -98,3 +98,15 @@ The former French AFNOR standard **NF Z 11-001**, replaced by ISO 269 back in 19
 While our documentation already covers the underlying standards that govern letter layout, what actually matters in practice is finding a tool that can embody these rules with precision, consistency, and a healthy respect for typographic sanity. This is the point where LaTeX—and specifically KOMA-Script’s `scrlttr2`—quietly distinguishes itself from the rest. Designed in the German tradition of rigorous typesetting, `scrlttr2` follows the logic of formal letter standards with an almost pedantic accuracy, offering a layout engine that behaves predictably and stays faithful to the structural constraints imposed by modern correspondence norms. Yet it remains flexible enough to emulate the conventions of other national styles without falling apart or requiring awkward hacks.
 
 In short, choosing `scrlttr2` was less about tradition and more about engineering. It gives us a letter typesetting engine that is standards-aware, robust enough for large-scale automation, and structured enough to keep our layouts consistent across contexts. It is not the easiest tool, nor the most forgiving, but for anyone who values correctness, longevity, and the quiet satisfaction of seeing a letter snap perfectly into place, it is simply the right one.
+
+## Build the exemple locally
+
+To build the letter example locally, navigate to the `examples/letter` directory and run the following command:
+
+```bash
+git clone https://github.com/yves-chevallier/texsmith.git
+cd texsmith
+uv sync
+cd examples/letter
+make
+```

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/guide/plumbing/pipeline.md

@@ -15,7 +15,7 @@ Templates define the layout and expose slots that get filled with content from y
    `Document.from_markdown` runs Python-Markdown with the bundled extensions (smallcaps, texlogos, index, Mermaid, raw LaTeX fences, etc.), extracts front matter, and caches the resulting HTML. `Document.from_html` can either keep the whole file or extract a selector (`article.md-content__inner` by default). Heading strategies are decided here (keep, drop, or promote the first heading into `press.title`), numbering defaults are resolved, and slot directives declared in front matter (`press.slot.*`) are seeded into the document slot mapping.
 
 3. **Bind the template and attributes**
-   `build_binder_context` resolves which template runtime to use (`TemplateBinding`) and which slots exist. Template attributes declared in `manifest.toml` (`TemplateAttributeSpec`) are merged in a strict order: template defaults → fragment defaults → front matter (`press.*` or direct fields) → CLI/session overrides. Attribute ownership is enforced so two fragments or the template cannot claim the same attribute. Before anything renders, mustache placeholders in HTML, front matter, and template overrides are expanded against the merged context so later stages see concrete values.
+   `bind_template` resolves which template runtime to use (`TemplateBinding`) and which slots exist. Template attributes declared in `manifest.toml` (`TemplateAttributeSpec`) are merged in a strict order: template defaults → fragment defaults → front matter (`press.*` or direct fields) → CLI/session overrides. Attribute ownership is enforced so two fragments or the template cannot claim the same attribute. Before anything renders, mustache placeholders in HTML, front matter, and template overrides are expanded against the merged context so later stages see concrete values.
 
 4. **Split content into slots**
    Slot requests come from CLI `--slot`, front matter, or defaults. `extract_slot_fragments` walks the HTML to find the requested headings/IDs, pulls those sections out, and assigns them to template slots (abstract, mainmatter, appendix, etc.). Base heading levels and offsets are computed per slot so sectioning commands line up with the template’s depth configuration. Any missing selectors produce warnings and the remainder of the document flows into the default slot.

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/guide/templates/fragments.md

@@ -40,10 +40,14 @@ written into the build directory as `ts-*.sty` and loaded via
 
 ## Using fragments in documents
 
-Fragments are declared under the `press.fragments` list in front matter. Each
+Fragments are declared under the `press.fragments` key in front matter. Each
 entry is either the name of a built-in fragment or a path to a custom Jinja
 template (absolute or relative to the Markdown file).
 
+### Explicit list (replaces template defaults)
+
+Provide a plain list to replace the template's default fragment set entirely:
+
 ```yaml
 ---
 press:
@@ -58,6 +62,30 @@ press:
 ---
 ```
 
+### Modifier dict (extends template defaults)
+
+When you only need to add or remove a few fragments without restating the full
+list, use the dict form with any combination of `append`, `prepend`, and
+`disable`:
+
+```yaml
+---
+press:
+  template: article
+  fragments:
+    append:
+      - ./fragments/heiglogo   # add a custom fragment at the end
+    prepend:
+      - ./fragments/header     # add a fragment at the start
+    disable:
+      - ts-geometry            # remove a specific built-in fragment
+---
+```
+
+All three keys are optional. Omitted keys leave the corresponding part of the
+default list unchanged. `disable` is applied first (before `prepend`/`append`),
+so the same fragment cannot appear in both `disable` and `prepend`/`append`.
+
 TeXSmith renders each fragment into the output directory and injects the
 corresponding `\usepackage{…}` lines into `\VAR{extra_packages}`.
 

texsmith-0.3.0/docs/syntax/abbr.md

@@ -0,0 +1,93 @@
+# Abbreviations / Acronyms
+
+Enable the `texsmith.abbr` extension and you can sprinkle definitions directly into your Markdown. Drop the abbreviation between square brackets, follow it with the expanded form in parentheses, and the parser does the rest.
+
+```markdown
+The HTML specification is maintained by the W3C.
+
+*[HTML]: HyperText Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+TeXSmith renders that snippet as:
+
+```text
+$ uv run texsmith abbr.md
+The \acrshort{HTML} specification is maintained by the \acrshort{W3C}.
+```
+
+Which displays as:
+
+```md {.snippet width="65%"}
+---
+press:
+  template: article
+  paper:
+    width: 150mm
+    height: 90mm
+    orientation: landscape
+  frame: true
+fragments:
+  ts-frame
+---
+The HTML specification is maintained by the W3C.
+
+*[HTML]: HyperText Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+Of course, this also works on this HTML site. Try hovering over the abbreviations.
+
+Acronyms are collected automatically during the LaTeX pass:
+
+```text
+$ uv run texsmith test.md -tarticle 1>/dev/null
+$ rg newacronym build/test.tex
+92:\newacronym{HTML}{HTML}{HyperText Markup Language}
+93:\newacronym{W3C}{W3C}{World Wide Web Consortium}
+```
+
+## Front-matter glossary
+
+For longer documents you can declare acronyms in a structured `glossary:` section
+in the YAML front matter. Each entry carries an explicit description and may be
+attached to a group; TeXSmith renders one localised `\printglossary` table per
+group (in declaration order) followed by a default table for ungrouped entries.
+The legacy `*[KEY]: …` body syntax keeps working and merges with the
+front-matter entries.
+
+```yaml
+---
+glossary:
+  style: long           # default; any glossaries-package style works
+  groups:
+    technique: Acronymes techniques
+    institutionnel: Acronymes institutionnels
+  entries:
+    API:
+      group: technique
+      description: Application Programming Interface
+    ONU:
+      group: institutionnel
+      description: Organisation des Nations Unies
+    DOI: Digital Object Identifier   # short form: ungrouped, description only
+---
+```
+
+The section is validated with pydantic, so unknown keys, missing descriptions,
+or references to undeclared groups raise a clear error at conversion time. The
+default acronym-table title follows the document language (it expands to
+`\acronymname` from the `glossaries` package, which is localised by `babel`).
+
+### Automatic substitution and limitations
+
+Unlike LaTeX, TeXSmith does **not** require `\gls{…}` / `\Gls{…}` calls in the
+source: the converter scans the body and replaces every **strict, case-sensitive**
+match of an acronym key with `\acrshort{KEY}`. As a consequence, casing helpers
+such as `\Gls`, `\GLS`, `\acrlong`, etc. are not synthesised — the substitution
+is the same regardless of where the acronym appears in the text. If you need
+those forms, drop down to raw LaTeX (e.g. with an explicit `\Gls{KEY}` written
+as a raw-LaTeX inline).
+
+*[HTML]: HyperText Markup Language
+*[W3C]: World Wide Web Consortium

{texsmith-0.2.1.dev0 → texsmith-0.3.0}/docs/syntax/captions.md

@@ -142,9 +142,9 @@ Caption: This is the caption for the figure.
 Tables follow the same pattern:
 
 ```md
+Table: This is the caption for the table. {#my-table}
+
 | Header 1 | Header 2 |
 |----------|----------|
 | Cell 1   | Cell 2   |
-
-Table: This is the caption for the table. {#my-table, short="Short caption for list of tables"}
 ```