texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/smart_dashes.py

@@ -0,0 +1,66 @@
+"""Markdown extension that converts ``--``/``---`` into proper dashes."""
+
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Extension, Markdown
+from markdown.treeprocessors import Treeprocessor
+
+
+_DASH_PATTERN = re.compile(r"---|--")
+
+
+def _replace_dashes(text: str) -> str:
+    """Replace ASCII dash sequences with typographic counterparts."""
+
+    def _swap(match: re.Match[str]) -> str:
+        payload = match.group(0)
+        return "\u2014" if payload == "---" else "\u2013"
+
+    return _DASH_PATTERN.sub(_swap, text)
+
+
+class _SmartDashesTreeprocessor(Treeprocessor):
+    """Replace double/triple hyphens outside code with typographic dashes."""
+
+    _SKIP_TAGS: ClassVar[set[str]] = {"code", "pre", "kbd", "script", "style"}
+
+    def run(self, root: ElementTree.Element) -> None:  # type: ignore[override]
+        self._process(root)
+
+    def _process(self, element: ElementTree.Element) -> None:
+        if self._is_skipped(element):
+            return
+
+        if element.text:
+            element.text = _replace_dashes(element.text)
+
+        for child in list(element):
+            self._process(child)
+            if child.tail:
+                child.tail = _replace_dashes(child.tail)
+
+    def _is_skipped(self, element: ElementTree.Element) -> bool:
+        tag = element.tag
+        if isinstance(tag, str):
+            tag = tag.lower()
+        return tag in self._SKIP_TAGS
+
+
+class TexsmithSmartDashesExtension(Extension):
+    """Register the smart dash tree-processor."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        md.treeprocessors.register(
+            _SmartDashesTreeprocessor(md), "texsmith_smart_dashes", priority=16
+        )
+
+
+def makeExtension(**kwargs: object) -> TexsmithSmartDashesExtension:  # noqa: N802
+    return TexsmithSmartDashesExtension(**kwargs)
+
+
+__all__ = ["TexsmithSmartDashesExtension", "makeExtension"]

texsmith/templates/__init__.py

@@ -0,0 +1,3 @@
+"""Built-in templates shipped with TeXSmith."""
+
+__all__ = []

texsmith/templates/article/README.md

@@ -0,0 +1,33 @@
+# TeXSmith Article Template
+
+This directory hosts the built-in `article` layout bundled with [TeXSmith](https://github.com/yves-chevallier/texsmith). The CLI exposes it via `--template article` (or `-tarticle`), so no extra installation is required.
+
+```bash
+texsmith intro.md --template article --output-dir build/article
+```
+
+To customise the template, copy this directory (or extract it via `importlib.resources`) and adjust the manifest, assets, or LaTeX entry point before packaging it as your own distribution.
+
+## Fonts
+
+Markdown is usually rendered on web broswers that supports a wide range of unicode characters. In LaTeX few fonts support such a wide range of characters. This template uses the most comprehensive font available: [Noto](https://notofonts.github.io/). However you need to install the font on your system first. You can download it from [Google Fonts](https://fonts.google.com/noto) or install it through your system package manager. For example on Ubuntu:
+
+```bash
+sudo apt update
+sudo apt install fonts-noto-core
+sudo apt install fonts-noto-cjk
+sudo apt install fonts-noto-extra
+```
+
+For black and white emojis, the `Symbola` font is used. For example on Ubuntu:
+
+```bash
+sudo apt update
+sudo apt install fonts-symbola
+```
+
+## Template Details
+
+- Engine: LuaLaTeX (shell escape required)
+- TeX Live year: 2023
+- tlmgr packages: `babel`, `geometry`, `hyperref`, `microtype`, `fontspec`

texsmith/templates/article/__init__.py

@@ -0,0 +1,281 @@
+"""Article template integration for texsmith."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any, ClassVar
+import unicodedata
+
+from texsmith.adapters.latex.utils import escape_latex_chars
+from texsmith.core.templates import TemplateError, WrappableTemplate
+
+
+_PACKAGE_ROOT = Path(__file__).parent.resolve()
+
+
+class Template(WrappableTemplate):
+    """Expose the article template as a wrappable template instance."""
+
+    _LATIN_RANGE_LIMIT: ClassVar[int] = 0x024F
+    _TEXTCOMP_CHARACTERS: ClassVar[set[str]] = {
+        "\N{EURO SIGN}",
+        "\N{POUND SIGN}",
+        "\N{YEN SIGN}",
+        "\N{SECTION SIGN}",
+        "\N{PILCROW SIGN}",
+        "\N{DEGREE SIGN}",
+        "\N{PLUS-MINUS SIGN}",
+        "\N{MICRO SIGN}",
+        "\N{MULTIPLICATION SIGN}",
+        "\N{DIVISION SIGN}",
+        "\N{COPYRIGHT SIGN}",
+        "\N{REGISTERED SIGN}",
+        "\N{TRADE MARK SIGN}",
+        "\N{VULGAR FRACTION ONE HALF}",
+        "\N{VULGAR FRACTION ONE QUARTER}",
+        "\N{VULGAR FRACTION THREE QUARTERS}",
+        "\N{PER MILLE SIGN}",
+    }
+    _ALLOWED_PUNCTUATION: ClassVar[set[str]] = {
+        "\N{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}",
+        "\N{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}",
+        "\N{SINGLE LEFT-POINTING ANGLE QUOTATION MARK}",
+        "\N{SINGLE RIGHT-POINTING ANGLE QUOTATION MARK}",
+        "\N{DOUBLE LOW-9 QUOTATION MARK}",
+        "\N{LEFT DOUBLE QUOTATION MARK}",
+        "\N{RIGHT DOUBLE QUOTATION MARK}",
+        "\N{RIGHT SINGLE QUOTATION MARK}",
+        "\N{SINGLE LOW-9 QUOTATION MARK}",
+        "\N{MIDDLE DOT}",
+        "\N{EN DASH}",
+        "\N{EM DASH}",
+        "\N{HORIZONTAL ELLIPSIS}",
+    }
+
+    def __init__(self) -> None:
+        try:
+            super().__init__(_PACKAGE_ROOT)
+        except TemplateError as exc:
+            raise TemplateError(f"Failed to initialise article template: {exc}") from exc
+        config_path = (self.root / "template" / "mermaid-config.json").resolve()
+        self.extras = {"mermaid_config": str(config_path)}
+
+    def prepare_context(
+        self,
+        latex_body: str,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        context = super().prepare_context(latex_body, overrides=overrides)
+        context["ts_extra_disable_hyperref"] = True
+
+        # Transform author metadata into a LaTeX-ready string while preserving defaults.
+        raw_authors = context.pop("authors", None)
+        author_value = self._format_authors(raw_authors)
+        if author_value:
+            context["author"] = author_value
+        else:
+            fallback_author = self._coerce_string(context.get("author"))
+            if fallback_author:
+                context["author"] = fallback_author
+            else:
+                context.pop("author", None)
+
+        context.pop("press", None)
+
+        engine_default = self.info.engine or "pdflatex"
+
+        context.setdefault("latex_engine", engine_default)
+        context.setdefault("requires_unicode_engine", False)
+        context.setdefault("unicode_chars", "")
+        context.setdefault("unicode_problematic_chars", "")
+        context.setdefault("pdflatex_extra_packages", [])
+
+        candidate_emoji = context.get("emoji")
+        if not candidate_emoji:
+            fonts_cfg = context.get("fonts")
+            if isinstance(fonts_cfg, Mapping):
+                candidate_emoji = fonts_cfg.get("emoji")
+        if not candidate_emoji:
+            press_cfg = context.get("press")
+            if isinstance(press_cfg, Mapping):
+                press_fonts = press_cfg.get("fonts")
+                if isinstance(press_fonts, Mapping):
+                    candidate_emoji = press_fonts.get("emoji")
+
+        emoji_mode = self._normalise_emoji_mode(candidate_emoji)
+        context["emoji"] = emoji_mode
+        if emoji_mode in {"symbola", "color"}:
+            context["latex_engine"] = "lualatex"
+            context["requires_unicode_engine"] = True
+
+        return context
+
+    def _coerce_string(self, value: Any) -> str | None:
+        if value is None:
+            return None
+        candidate = value.strip() if isinstance(value, str) else str(value).strip()
+        return candidate or None
+
+    def _format_authors(self, payload: Any) -> str | None:
+        if not payload:
+            return None
+        if not isinstance(payload, Iterable) or isinstance(payload, (str, bytes)):
+            return None
+
+        formatted: list[str] = []
+        for item in payload:
+            if not isinstance(item, Mapping):
+                continue
+            name_value = self._coerce_string(item.get("name"))
+            if not name_value:
+                continue
+            name_tex = escape_latex_chars(name_value)
+            affiliation_value = self._coerce_string(item.get("affiliation"))
+            if affiliation_value:
+                affiliation_tex = escape_latex_chars(affiliation_value)
+                formatted.append(f"{name_tex}\\thanks{{{affiliation_tex}}}")
+            else:
+                formatted.append(name_tex)
+
+        if not formatted:
+            return None
+        return " \\and ".join(formatted)
+
+    def _normalise_emoji_mode(self, value: Any) -> str:
+        candidate = self._coerce_string(value)
+        if candidate:
+            candidate_stripped = candidate.strip()
+        else:
+            default_value = self.info.get_attribute_default("emoji") or "black"
+            candidate = self._coerce_string(default_value)
+            candidate_stripped = candidate.strip() if candidate else "black"
+
+        if not candidate_stripped:
+            return "black"
+
+        lowered = candidate_stripped.lower()
+        if lowered in {"artifact", "symbola", "color", "black", "twemoji"}:
+            return lowered
+        return candidate_stripped
+
+    def wrap_document(
+        self,
+        latex_body: str,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+        context: Mapping[str, Any] | None = None,
+    ) -> str:
+        if context is None:
+            prepared = self.prepare_context(latex_body, overrides=overrides)
+            context_ref: dict[str, Any] | None = prepared
+        else:
+            prepared = dict(context)
+            context_ref = context if isinstance(context, dict) else None
+
+        preamble_override: str | None = None
+        if overrides:
+            press_section = overrides.get("press")
+            if isinstance(press_section, Mapping):
+                override_section = press_section.get("override")
+                if isinstance(override_section, Mapping):
+                    candidate = override_section.get("preamble")
+                    if isinstance(candidate, str) and candidate.strip():
+                        preamble_override = candidate.strip()
+            if preamble_override is None:
+                direct_override = overrides.get("preamble")
+                if isinstance(direct_override, str) and direct_override.strip():
+                    preamble_override = direct_override.strip()
+
+        if preamble_override:
+            existing_extra = prepared.get("extra_packages") or ""
+            package_parts = [existing_extra] if existing_extra else []
+            package_parts.append(preamble_override)
+            prepared["extra_packages"] = "\n".join(part for part in package_parts if part)
+
+        self._analyse_unicode_payload(prepared)
+
+        if context_ref is not prepared and context_ref is not None:
+            context_ref.clear()
+            context_ref.update(prepared)
+
+        return super().wrap_document(latex_body, overrides=overrides, context=prepared)
+
+    def _analyse_unicode_payload(self, context: dict[str, Any]) -> None:
+        unicode_chars = self._collect_unicode_characters(context)
+        problematic = []
+        extra_packages: set[str] = set()
+
+        base_engine = context.get("latex_engine") or "pdflatex"
+
+        for char in unicode_chars:
+            classification = self._classify_character(char)
+            if classification == "textcomp":
+                extra_packages.add("textcomp")
+            elif classification == "unsupported":
+                problematic.append(char)
+
+        context["unicode_chars"] = "".join(sorted(unicode_chars, key=ord))
+        context["unicode_problematic_chars"] = "".join(sorted(problematic, key=ord))
+        context["pdflatex_extra_packages"] = sorted(extra_packages)
+
+        requires_unicode_engine = bool(problematic)
+        context["requires_unicode_engine"] = requires_unicode_engine
+        context["latex_engine"] = "lualatex" if requires_unicode_engine else base_engine
+
+    def _collect_unicode_characters(self, payload: Any) -> set[str]:
+        collected: set[str] = set()
+        visited: set[int] = set()
+
+        def _walk(value: Any) -> None:
+            if isinstance(value, str):
+                for char in value:
+                    if ord(char) > 0x7F:
+                        collected.add(char)
+                return
+
+            if isinstance(value, Mapping):
+                identifier = id(value)
+                if identifier in visited:
+                    return
+                visited.add(identifier)
+                for key, item in value.items():
+                    if isinstance(key, str) and key == "callouts_definitions":
+                        continue
+                    _walk(item)
+                return
+
+            if isinstance(value, Iterable) and not isinstance(value, (bytes, bytearray)):
+                identifier = id(value)
+                if identifier in visited:
+                    return
+                visited.add(identifier)
+                for item in value:
+                    _walk(item)
+
+        _walk(payload)
+        return collected
+
+    def _classify_character(self, char: str) -> str:
+        codepoint = ord(char)
+        if codepoint <= self._LATIN_RANGE_LIMIT:
+            return "latin"
+        if char in self._ALLOWED_PUNCTUATION:
+            return "punctuation"
+        if char in self._TEXTCOMP_CHARACTERS:
+            return "textcomp"
+
+        name: str | None
+        try:
+            name = unicodedata.name(char)
+        except ValueError:
+            name = None
+
+        if name and "LATIN" in name:
+            return "latin"
+
+        return "unsupported"
+
+
+__all__ = ["Template"]

texsmith/templates/article/template/manifest.toml

@@ -0,0 +1,125 @@
+[compat]
+texsmith = ">=0.1,<1.0"
+
+[latex.template]
+name = "article"
+version = "0.1.0"
+entrypoint = "template/template.tex"
+engine = "lualatex"
+shell_escape = false
+texlive_year = 2023
+tlmgr_packages = [
+    "babel",
+    "geometry",
+    "hyperref",
+    "microtype",
+    "lmodern",
+    "textcomp",
+    "fontspec",
+    "biblatex",
+]
+fragments = [
+    "ts-geometry",
+    "ts-typesetting",
+    "ts-fonts",
+    "ts-extra",
+    "ts-keystrokes",
+    "ts-callouts",
+    "ts-code",
+    "ts-glossary",
+    "ts-index",
+    "ts-bibliography",
+    "ts-todolist",
+]
+
+[latex.template.attributes.title]
+default = ""
+type = "string"
+escape = "latex"
+allow_empty = true
+sources = ["title"]
+description = "The title of the document. If empty, first heading in document will be used."
+
+[latex.template.attributes.subtitle]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["subtitle"]
+description = "The subtitle of the document."
+
+[latex.template.attributes.toc]
+default = false
+type = "boolean"
+sources = ["toc"]
+description = "Whether to include a table of contents."
+
+[latex.template.attributes.authors]
+default = []
+type = "list"
+sources = ["authors"]
+description = "List of authors of the document. Use plain strings or objects with 'name', 'affiliation', and 'email' fields. You may include multiple authors."
+
+[latex.template.attributes.date]
+default = ""
+type = "string"
+escape = "latex"
+sources = ["date"]
+description = "The date of the document, use ISO format (YYYY-MM-DD) or any string. If empty, the current date will be used."
+
+[latex.template.attributes.language]
+default = "english"
+type = "string"
+allow_empty = false
+normaliser = "babel_language"
+description = "The language for hyphenation, typesettings and document terms (e.g., 'Table of Contents')."
+
+[latex.template.attributes.columns]
+default = 1
+type = "integer"
+description = "Number of columns for the document. When >1, uses the documentclass twocolumn option."
+
+[latex.template.attributes.page_numbers]
+default = true
+type = "boolean"
+sources = ["page_numbers"]
+description = "Whether to include page numbers in the document."
+
+[latex.template.attributes.numbering]
+default = true
+type = "boolean"
+sources = ["numbering"]
+description = "Whether to include section numbering in the document."
+
+[latex.template.attributes.glossary_style]
+default = "list"
+type = "string"
+allow_empty = false
+sources = ["glossary_style"]
+description = "The style used for the glossary section."
+
+[latex.template.attributes.bibliography_style]
+default = "numeric"
+type = "string"
+description = "The bibliography style to use. See BibLaTeX documentation for available styles."
+
+# Slots definition:
+# -----------------
+# Each slot represents a section of the document that can be filled with content.
+# The 'depth' parameter indicates the LaTeX sectioning command to use.
+[latex.template.slots.mainmatter]
+default = true
+depth = "section"
+description = "The main content of the document."
+
+[latex.template.slots.abstract]
+depth = "section"
+strip_heading = true
+description = "The abstract or summary of the document."
+
+[latex.template.slots.appendix]
+depth = "section"
+description = "Appendix content inserted before backmatter."
+
+[latex.template.slots.backmatter]
+depth = "section"
+strip_heading = true

texsmith/templates/article/template/mermaid-config.json

@@ -0,0 +1,18 @@
+{
+  "theme": "base",
+  "themeVariables": {
+    "primaryColor": "white",
+    "primaryTextColor": "black",
+    "primaryBorderColor": "black",
+    "secondaryColor": "transparent",
+    "secondaryTextColor": "black",
+    "tertiaryColor": "transparent",
+    "lineColor": "black",
+    "background": "red",
+    "clusterBkg": "white",
+    "clusterBorder": "black",
+    "fontFamily": "Latin Modern Roman, Computer Modern Serif, Times New Roman, serif",
+    "edgeLabelBackground": "#ffffff"
+  },
+  "themeCSS": ".node rect, .node circle, .node ellipse, .node polygon, .node path { stroke-width: 2px; }\n .edgePath .path { stroke-width: 2px !important; }\n.packetBlock { fill: #ffffff !important; stroke: #000000 !important; }\n.packet rect, .packet polygon { fill: #ffffff !important; stroke: #000000 !important; }\n.packet text, .packetLabel, .packetByte, .packetTitle { fill: #000000 !important; }\n.node rect, .node polygon, .node ellipse { fill: white !important; }"
+}

texsmith/templates/article/template/template.tex

@@ -0,0 +1,74 @@
+\BLOCK{ set base_docclass_options = documentclass_options|default('', true) }
+\BLOCK{ set combined_docclass_options = base_docclass_options[1:-1] if base_docclass_options else '' }
+\BLOCK{ set column_count = columns|default(1)|int }
+\BLOCK{ set option_parts = [] }
+\BLOCK{ if combined_docclass_options }\BLOCK{ set option_parts = option_parts + [combined_docclass_options] }\BLOCK{ endif }
+\BLOCK{ if column_count > 1 }\BLOCK{ set option_parts = option_parts + ['twocolumn'] }\BLOCK{ endif }
+\BLOCK{ set effective_documentclass_options = '[' ~ option_parts|join(',') ~ ']' if option_parts else '' }
+\documentclass\VAR{effective_documentclass_options}{article}
+
+\usepackage[svgnames,dvipsnames,x11names]{xcolor}
+\VAR{extra_packages}
+\usepackage{graphicx}
+\usepackage[\VAR{language|default('english')}]{babel}
+\usepackage[colorlinks=true, linkcolor=NavyBlue, urlcolor=NavyBlue, citecolor=NavyBlue]{hyperref}
+
+\usepackage{lastpage} % pour le label LastPage
+\usepackage{refcount} % pour \getpagerefnumber
+\makeatletter
+\def\ps@plain{%
+  \let\@oddhead\@empty
+  \let\@evenhead\@empty
+  \def\@oddfoot{%
+    \hfil
+    % Afficher le numéro seulement si le document a plus d’une page
+    \ifnum\getpagerefnumber{LastPage}>1\relax
+      \thepage
+    \fi
+    \hfil}%
+  \let\@evenfoot\@oddfoot
+}
+\makeatother
+
+\BLOCK{ set has_title_metadata = title|default('')|trim }
+\BLOCK{ set effective_date = date|default('')|trim }
+\BLOCK{ if has_title_metadata }
+\title{\VAR{title}\BLOCK{ if subtitle }\\\large \VAR{subtitle}\BLOCK{ endif }}
+\BLOCK{ if author }\author{\VAR{author}}\BLOCK{ else }\author{}\BLOCK{ endif }
+\BLOCK{ if effective_date }\date{\VAR{date}}\BLOCK{ else }\date{\today}\BLOCK{ endif }
+\BLOCK{ endif }
+
+\begin{document}
+
+\BLOCK{ if has_title_metadata }
+\maketitle
+\BLOCK{ endif }
+\BLOCK{ if not page_numbers }
+\pagenumbering{gobble}
+\thispagestyle{empty}
+\pagestyle{empty}
+\BLOCK{ endif }
+\BLOCK{ if numbering is defined and not numbering }
+\setcounter{secnumdepth}{-1}
+\BLOCK{ endif }
+
+\BLOCK{ if abstract }
+\begin{abstract}
+\VAR{abstract}
+\end{abstract}
+\BLOCK{ endif }
+\BLOCK{ if toc }
+\tableofcontents
+\BLOCK{ endif }
+
+\VAR{mainmatter}
+
+\BLOCK{ if appendix }
+\appendix
+\VAR{appendix}
+\BLOCK{ endif }
+
+\VAR{backmatter}
+\VAR{fragment_backmatter}
+
+\end{document}

texsmith/templates/book/README.md

@@ -0,0 +1,26 @@
+# TeXSmith Book Template
+
+The built-in `book` template targets long-form documents with front matter, chapters, appendices, and clean back matter. It wraps `memoir` defaults, modern callouts, keystroke helpers, todo lists, glossary/index hooks, and bibliography support.
+
+## Usage
+
+```bash
+texsmith manuscript.md --template book \
+  --slot frontmatter:intro.md \
+  --slot backmatter:appendix.md
+```
+
+Slots:
+- `frontmatter`, `preface`, `dedication`
+- `mainmatter` (default)
+- `appendix`
+- `backmatter`, `colophon`
+
+## Template Details
+
+- Engine: LuaLaTeX
+- TeX Live year: 2023
+- tlmgr packages: `babel`, `babel-french`, `csquotes`, `fontspec`, `fancyvrb`, `geometry`, `hyperref`, `longtable`, `microtype`, `titlesec`, `titletoc`, `xcolor`, `xunicode`
+- Built-in fragments: geometry, typesetting, fonts, extra, keystrokes, callouts, code, glossary, index, bibliography, todolist
+- Attributes: title/subtitle/authors/email/date/language/documentclass, hyperref options, edition/publisher/imprint*, glossary toggles, list-of figures/tables, `part` flag for part/chapter structure.
+- Assets: none (latexmkrc is injected by core).