texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/adapters/latex/partials/glossary.tex

@@ -0,0 +1 @@
+\gls{\VAR{key}}

texsmith/adapters/latex/partials/heading.tex

@@ -0,0 +1,14 @@
+\BLOCK{- set number_to_words = {
+            -1: 'part',
+            0: 'chapter',
+            1: 'section',
+            2: 'subsection',
+            3: 'subsubsection',
+            4: 'paragraph',
+            5: 'subparagraph'
+        } -}
+\BLOCK{- if level in number_to_words -}
+\\VAR{number_to_words[level]}\BLOCK{if not numbered and level <= 5}*\BLOCK{endif}{\VAR{text}}\BLOCK{if ref}\label{\VAR{ref}}\BLOCK{endif}\BLOCK{if level >= 4}\mbox{}\\\BLOCK{endif}
+\BLOCK{else -}
+\textbf{\VAR{text}}\BLOCK{if ref}\label{\VAR{ref}}\BLOCK{endif}
+\BLOCK{endif}

texsmith/adapters/latex/partials/highlight.tex

@@ -0,0 +1,25 @@
+\ifXeTeX
+  % soul breaks with ucharclasses on XeTeX: fall back to simple colored text.
+  \providecommand{\texsmithHighlight}[1]{\textcolor{yellow}{#1}}
+  \providecommand{\hl}[1]{\textcolor{yellow}{#1}}
+\else
+  \ifLuaTeX
+    \RequirePackage{lua-ul}
+    \providecommand{\texsmithHighlight}[1]{%
+      \begingroup
+      \setulcolor{yellow}%
+      \ul{#1}%
+      \endgroup
+    }
+    \providecommand{\hl}[1]{\texsmithHighlight{#1}}
+  \else
+    \providecommand{\texsmithHighlight}[1]{%
+      \begingroup
+      \setlength{\fboxsep}{0.8pt}%
+      \colorbox{yellow}{#1}%
+      \endgroup
+    }
+  \fi
+\fi
+
+\texsmithHighlight{\VAR{text}}

texsmith/adapters/latex/partials/horizontal_rule.tex

@@ -0,0 +1 @@
+\par\noindent\rule{\linewidth}{0.4pt}

texsmith/adapters/latex/partials/href.tex

@@ -0,0 +1 @@
+\href{\VAR{url}}{\VAR{text}}

texsmith/adapters/latex/partials/icon.tex

@@ -0,0 +1 @@
+\includegraphics[width=1em]{\VAR{text}}

texsmith/adapters/latex/partials/include.tex

@@ -0,0 +1 @@
+\input{\VAR{text}} % \VAR{title}

texsmith/adapters/latex/partials/index.tex

@@ -0,0 +1 @@
+\VAR{text}\index{\BLOCK{ if style == 'b' }\textbf{\VAR{entry}}\BLOCK{ elif style == 'i' }\textit{\VAR{entry}}\BLOCK{ elif style in ('bi', 'ib') }\textbf{\textit{\VAR{entry}}}\BLOCK{ else }\VAR{entry}\BLOCK{ endif }}

texsmith/adapters/latex/partials/italic.tex

@@ -0,0 +1 @@
+\emph{\VAR{text}}

texsmith/adapters/latex/partials/keystroke.tex

@@ -0,0 +1,46 @@
+\BLOCK{set ks = {
+    'control': 'Ctrl',
+    'alt': 'Alt',
+    'delete': 'Del',
+    'enter': '⏎ Enter',
+    'shift': '⇧ Shift',
+    'slash': '/',
+    'comma': ',',
+    'period': '.',
+    'arrow-up': '\\(\\uparrow\\)',
+    'arrow-down': '\\(\\downarrow\\)',
+    'arrow-left': '\\(\\leftarrow\\)',
+    'arrow-right': '\\(\\rightarrow\\)',
+    'backslash': '\\textbackslash',
+    'double-quote': '"',
+    'backspace': '⌫ Delete',
+    'command': '⌘',
+    'tab': 'Tab',
+    'esc': 'Esc',
+    'insert': 'Ins',
+    'home': 'Home',
+    'end': 'End',
+    'page-up': 'PgUp',
+    'page-down': 'PgDn',
+    'space': 'Space',
+    'f1': 'F1',
+    'f2': 'F2',
+    'f3': 'F3',
+    'f4': 'F4',
+    'f5': 'F5',
+    'f6': 'F6',
+    'f7': 'F7',
+    'f8': 'F8',
+    'f9': 'F9',
+    'f10': 'F10',
+    'f11': 'F11',
+    'f12': 'F12',
+}}
+\BLOCK{- for key in text -}
+\BLOCK{- if key in ks -}
+\keystroke{\VAR{ks[key]}}
+\BLOCK{- else -}
+\keystroke{\VAR{key|upper}}
+\BLOCK{- endif -}
+\BLOCK{- if not loop.last -} + \BLOCK{- endif -}
+\BLOCK{- endfor -}

texsmith/adapters/latex/partials/label.tex

@@ -0,0 +1 @@
+\label{\VAR{text}}

texsmith/adapters/latex/partials/list_acronyms.tex

@@ -0,0 +1,5 @@
+% Acronyms
+\BLOCK{for key, entry in text -}
+\BLOCK{ set pair = entry if (entry is sequence and not entry is string) else [key, entry] }
+\newacronym{\VAR{key}}{\VAR{pair[0]|latex_escape}}{\VAR{pair[1]|latex_escape}}
+\BLOCK{endfor}

texsmith/adapters/latex/partials/list_glossary.tex

@@ -0,0 +1,8 @@
+% Glossary entries
+\BLOCK{for key, item in text.items() -}
+\newglossaryentry{\VAR{key}}
+{
+    name={\VAR{item['name']}},
+    description={\VAR{item['description']}}
+}
+\BLOCK{endfor}

texsmith/adapters/latex/partials/multicolumn.tex

@@ -0,0 +1,3 @@
+\begin{multicols}{\VAR{columns}}
+\VAR{text}
+\end{multicols}

texsmith/adapters/latex/partials/ordered_list.tex

@@ -0,0 +1,5 @@
+\begin{enumerate}
+\BLOCK{for item in items -}
+    \item \VAR{item}
+\BLOCK{endfor}
+\end{enumerate}

texsmith/adapters/latex/partials/pagestyle.tex

@@ -0,0 +1 @@
+\thispagestyle{\VAR{text}}

texsmith/adapters/latex/partials/ref.tex

@@ -0,0 +1 @@
+\VAR{text} \ref{\VAR{ref}}

texsmith/adapters/latex/partials/regex.tex

@@ -0,0 +1 @@
+\href{\VAR{url}}{\mintinline{text}{\VAR{text}}}

texsmith/adapters/latex/partials/smallcaps.tex

@@ -0,0 +1 @@
+\textsc{\VAR{text}}

texsmith/adapters/latex/partials/strikethrough.tex

@@ -0,0 +1 @@
+\sout{\VAR{text}}

texsmith/adapters/latex/partials/strong.tex

@@ -0,0 +1 @@
+\textbf{\VAR{text}}

texsmith/adapters/latex/partials/subscript.tex

@@ -0,0 +1 @@
+\textsubscript{\VAR{text}}

texsmith/adapters/latex/partials/substitution.tex

@@ -0,0 +1 @@
+\xout{\VAR{original}}\ \uline{\VAR{replacement}}

texsmith/adapters/latex/partials/superscript.tex

@@ -0,0 +1 @@
+\textsuperscript{\VAR{text}}

texsmith/adapters/latex/partials/tabbed.tex

@@ -0,0 +1,3 @@
+\textbf{\VAR{title}}
+
+\VAR{text}

texsmith/adapters/latex/partials/table.tex

@@ -0,0 +1,48 @@
+\BLOCK{- set first_style = {
+    'left': 'l',
+    'right': 'r',
+    'center': 'c'
+} -}
+\BLOCK{- set rest_style = {
+    'left': 'X',
+    'right': 'Z',
+    'center': 'Y',
+    'justify': 'X'
+} -}
+\BLOCK{- if caption -}
+\begin{table}[H]
+\centering
+\BLOCK{if label -}
+\label{\VAR{label}}
+\BLOCK{- endif}
+\caption{\VAR{caption}}
+\BLOCK{else}
+\begin{center}
+\BLOCK{- endif}
+\BLOCK{- if is_large -}
+\BLOCK{- endif}
+\begin{tabularx}{\textwidth}{\BLOCK{- for column in columns}\BLOCK{- if loop.first }\VAR{first_style.get(column, 'l')}\BLOCK{- else }\VAR{rest_style.get(column, 'X')}\BLOCK{- endif }\BLOCK{- endfor}}
+\toprule
+\BLOCK{for row in rows -}
+\BLOCK{- if loop.first -}
+\BLOCK{- for col in row -}
+   \textbf{\VAR{col}}\BLOCK{- if not loop.last} & \BLOCK{else} \\
+\BLOCK{endif}
+\BLOCK{- endfor}
+\midrule
+\BLOCK{else -}
+\BLOCK{- for col in row -}
+   \VAR{col}\BLOCK{- if not loop.last} & \BLOCK{else} \\
+\BLOCK{endif}
+\BLOCK{- endfor -}
+\BLOCK{- endif -}
+\BLOCK{- endfor}
+\bottomrule
+\end{tabularx}
+\BLOCK{- if is_large -}
+\BLOCK{- endif}
+\BLOCK{- if caption -}
+\end{table}
+\BLOCK{- else}
+\end{center}
+\BLOCK{- endif}

texsmith/adapters/latex/partials/underline.tex

@@ -0,0 +1 @@
+\uline{\VAR{text}}

texsmith/adapters/latex/partials/unordered_list.tex

@@ -0,0 +1,5 @@
+\begin{itemize}
+\BLOCK{for item in items -}
+    \item{} \VAR{item}
+\BLOCK{endfor}
+\end{itemize}

texsmith/adapters/latex/partials/url.tex

@@ -0,0 +1 @@
+\href{\VAR{url}}{\VAR{text}}

texsmith/adapters/latex/pygments.py

@@ -0,0 +1,98 @@
+"""Pygments integration helpers for LaTeX rendering."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from pygments import highlight
+from pygments.formatters import LatexFormatter
+from pygments.lexers import ClassNotFound, TextLexer, get_lexer_by_name
+
+
+class PygmentsLatexHighlighter:
+    """Convert source code to LaTeX using Pygments."""
+
+    def __init__(
+        self,
+        *,
+        commandprefix: str = "PY",
+        style: str = "bw",
+        verboptions: str | None = None,
+    ) -> None:
+        self.commandprefix = commandprefix
+        self.style = style
+        self.verboptions = verboptions or r"breaklines, breakanywhere, commandchars=\\\{\}"
+
+    @property
+    def style_key(self) -> str:
+        """Identifier that groups style definitions."""
+        return f"{self.style}:{self.commandprefix}"
+
+    def render(
+        self,
+        code: str,
+        language: str,
+        *,
+        linenos: bool,
+        highlight_lines: Iterable[int] | None = None,
+    ) -> tuple[str, str]:
+        """Return the LaTeX code and style definitions for a payload."""
+        try:
+            lexer = get_lexer_by_name(language or "text")
+        except ClassNotFound:
+            lexer = TextLexer()
+
+        def _format_ranges(values: Iterable[int]) -> str:
+            sorted_vals = sorted(set(values))
+            if not sorted_vals:
+                return ""
+            ranges: list[str] = []
+            start = end = sorted_vals[0]
+            for num in sorted_vals[1:]:
+                if num == end + 1:
+                    end = num
+                else:
+                    ranges.append(f"{start}-{end}" if start != end else str(start))
+                    start = end = num
+            ranges.append(f"{start}-{end}" if start != end else str(start))
+            return ",".join(ranges)
+
+        verb_options = self.verboptions
+        formatted_highlight = _format_ranges(highlight_lines or [])
+        if formatted_highlight:
+            verb_options = f"{verb_options},highlightlines={{{formatted_highlight}}}"
+
+        formatter = LatexFormatter(
+            full=False,
+            linenos=linenos,
+            style=self.style,
+            commandprefix=self.commandprefix,
+            linenostart=1,
+            linenostep=1,
+            verboptions=verb_options,
+            hl_lines=list(highlight_lines or []),
+        )
+        latex_code = highlight(code, lexer, formatter)
+        style_defs = formatter.get_style_defs()
+        return latex_code, style_defs
+
+    def render_inline(self, code: str, language: str) -> tuple[str, str]:
+        """Return inline LaTeX macros for a code snippet (no Verbatim env)."""
+        try:
+            lexer = get_lexer_by_name(language or "text")
+        except ClassNotFound:
+            lexer = TextLexer()
+
+        formatter = LatexFormatter(
+            full=False,
+            linenos=False,
+            style=self.style,
+            commandprefix=self.commandprefix,
+            nowrap=True,
+        )
+        latex_code = highlight(code, lexer, formatter)
+        style_defs = formatter.get_style_defs()
+        return latex_code, style_defs
+
+
+__all__ = ["PygmentsLatexHighlighter"]

texsmith/adapters/latex/pyxindy.py

@@ -0,0 +1,64 @@
+"""Helpers to integrate the PyXindy toolchain (Python port of xindy)."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import shlex
+import shutil
+import sys
+
+
+def _python_module_available() -> bool:
+    """Return True when the PyXindy modules are importable."""
+    return importlib.util.find_spec("xindy") is not None
+
+
+def is_available() -> bool:
+    """Check whether PyXindy can be invoked (entry points or module)."""
+    return _python_module_available() or shutil.which("makeindex-py") is not None
+
+
+def _script_path(name: str) -> Path | None:
+    """Resolve a script living alongside the current interpreter."""
+    candidate = Path(sys.executable).with_name(name)
+    return candidate if candidate.exists() else None
+
+
+def index_command_tokens() -> list[str]:
+    """Return the argv tokens to invoke the makeindex-compatible wrapper."""
+    for candidate in ("makeindex-py", "makeindex4"):
+        resolved = shutil.which(candidate) or _script_path(candidate)
+        if resolved:
+            return [str(resolved)]
+    return [sys.executable, "-m", "xindy.tex.makeindex4"]
+
+
+def glossary_command_tokens() -> list[str]:
+    """Return the argv tokens to invoke the makeglossaries helper."""
+    for candidate in ("makeglossaries-py",):
+        resolved = shutil.which(candidate) or _script_path(candidate)
+        if resolved:
+            return [str(resolved)]
+    return [sys.executable, "-m", "xindy.tex.makeglossaries"]
+
+
+def latexmk_makeindex_command() -> str:
+    """Return a makeindex command string suitable for latexmkrc."""
+    tokens = [shlex.quote(token) for token in index_command_tokens()]
+    return " ".join([*tokens, "%O", "-o", "%D", "%S"])
+
+
+def latexmk_makeglossaries_command() -> str:
+    """Return a makeglossaries command string suitable for latexmkrc."""
+    tokens = [shlex.quote(token) for token in glossary_command_tokens()]
+    return " ".join([*tokens, '"$base"'])
+
+
+__all__ = [
+    "glossary_command_tokens",
+    "index_command_tokens",
+    "is_available",
+    "latexmk_makeglossaries_command",
+    "latexmk_makeindex_command",
+]

texsmith/adapters/latex/renderer.py

@@ -0,0 +1,220 @@
+"""High-level HTML to LaTeX renderer based on the modular pipeline."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from importlib import metadata
+import inspect
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from bs4 import BeautifulSoup, FeatureNotFound
+
+from texsmith.core.config import BookConfig
+from texsmith.core.context import AssetRegistry, DocumentState, RenderContext
+from texsmith.core.diagnostics import DiagnosticEmitter, NullEmitter
+from texsmith.core.exceptions import LatexRenderingError
+from texsmith.core.rules import RenderEngine, RenderPhase
+from texsmith.extensions import register_all_renderers
+
+from .formatter import LaTeXFormatter
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    pass
+
+
+class LaTeXRenderer:
+    _ENTRY_POINT_GROUP = "texsmith.renderers"
+    _ENTRY_POINT_PAYLOADS: list[Any] | None = None
+
+    """Convert HTML fragments to LaTeX using a modular pipeline."""
+
+    def __init__(
+        self,
+        config: BookConfig | None = None,
+        formatter: LaTeXFormatter | None = None,
+        output_root: Path | str = Path("build"),
+        parser: str = "lxml",
+        copy_assets: bool = True,
+        convert_assets: bool = False,
+        hash_assets: bool = False,
+    ) -> None:
+        self.config = config or BookConfig()
+        self.formatter = formatter or LaTeXFormatter()
+        self.parser_backend = parser
+        self.copy_assets = copy_assets
+        self.convert_assets = convert_assets
+        self.hash_assets = hash_assets
+
+        self.output_root = Path(output_root)
+        self.assets_root = (self.output_root / "assets").resolve()
+
+        self.assets = AssetRegistry(self.assets_root, copy_assets=self.copy_assets)
+
+        # Keep formatter in sync with runtime environment
+        self.formatter.config = self.config  # type: ignore[assignment]
+        self.formatter.output_path = self.assets_root  # type: ignore[assignment]
+        self.formatter.legacy_latex_accents = self.config.legacy_latex_accents
+
+        self.engine = RenderEngine()
+        self._register_builtin_handlers()
+        self._register_entry_point_handlers()
+        register_all_renderers(self)
+
+    def _register_builtin_handlers(self) -> None:
+        """Register the initial set of handlers for the renderer."""
+        from ..handlers import (
+            admonitions as admonition_handlers,
+            basic as basic_handlers,
+            blocks as block_handlers,
+            code as code_handlers,
+            inline as inline_handlers,
+            links as link_handlers,
+            media as media_handlers,
+        )
+        from ..plugins import material as material_plugins, snippet as snippet_plugin
+
+        self.engine.collect_from(basic_handlers)
+        self.engine.collect_from(inline_handlers)
+        self.engine.collect_from(code_handlers)
+        self.engine.collect_from(link_handlers)
+        self.engine.collect_from(block_handlers)
+        self.engine.collect_from(admonition_handlers)
+        self.engine.collect_from(media_handlers)
+        self.register(snippet_plugin)
+        self.register(material_plugins)
+
+    def register(self, handler: Any) -> None:
+        """Register additional handlers on demand.
+
+        Arguments can be callables decorated with :func:`renders` or modules/classes
+        exposing decorated attributes.
+        """
+        definition = getattr(handler, "__render_rule__", None)
+        if definition is not None:
+            self.engine.register(handler)
+            return
+
+        self.engine.collect_from(handler)
+
+    @classmethod
+    def _iter_entry_point_payloads(cls) -> Iterable[Any]:
+        if cls._ENTRY_POINT_PAYLOADS is None:
+            payloads: list[Any] = []
+            try:
+                entry_points = metadata.entry_points()
+                group = entry_points.select(group=cls._ENTRY_POINT_GROUP)
+            except Exception:  # pragma: no cover - defensive
+                cls._ENTRY_POINT_PAYLOADS = []
+                return ()
+
+            for entry_point in sorted(
+                group,
+                key=lambda ep: (getattr(ep, "priority", 0), getattr(ep, "name", "")),
+            ):
+                try:
+                    payloads.append(entry_point.load())
+                except Exception:  # pragma: no cover - defensive
+                    continue
+            cls._ENTRY_POINT_PAYLOADS = payloads
+        return cls._ENTRY_POINT_PAYLOADS
+
+    def _register_entry_point_handlers(self) -> None:
+        for payload in self._iter_entry_point_payloads():
+            self._apply_entry_point(payload)
+
+    def _apply_entry_point(self, payload: Any) -> None:
+        def _accepts_renderer(target: Callable[..., Any]) -> bool:
+            try:
+                signature = inspect.signature(target)
+            except (TypeError, ValueError):
+                return False
+            for parameter in signature.parameters.values():
+                if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD):
+                    return True
+                if parameter.kind in (parameter.POSITIONAL_ONLY, parameter.POSITIONAL_OR_KEYWORD):
+                    return True
+            return False
+
+        if callable(payload):
+            if _accepts_renderer(payload):
+                payload(self)
+                return
+            self.register(payload)
+            return
+
+        register = getattr(payload, "register", None)
+        if callable(register):
+            register(self)
+            return
+
+        self.register(payload)
+
+    def render(
+        self,
+        html: str,
+        *,
+        runtime: Mapping[str, Any] | None = None,
+        state: DocumentState | None = None,
+        emitter: DiagnosticEmitter | None = None,
+    ) -> str:
+        """Render an HTML fragment into LaTeX."""
+        active_emitter = emitter or NullEmitter()
+        try:
+            soup = BeautifulSoup(html, self.parser_backend)
+        except FeatureNotFound:
+            if self.parser_backend == "html.parser":
+                raise
+            # Fall back to the built-in parser when the preferred backend is missing.
+            from texsmith.core.conversion.debug import record_event
+
+            record_event(
+                active_emitter,
+                "parser_fallback",
+                {"preferred": self.parser_backend, "fallback": "html.parser"},
+            )
+            soup = BeautifulSoup(html, "html.parser")
+            self.parser_backend = "html.parser"
+        document_state = state or DocumentState()
+
+        context = RenderContext(
+            config=self.config,
+            formatter=self.formatter,
+            document=soup,
+            assets=self.assets,
+            state=document_state,
+        )
+
+        context.attach_runtime(
+            copy_assets=self.copy_assets,
+            convert_assets=self.convert_assets,
+            hash_assets=self.hash_assets,
+            emitter=active_emitter,
+        )
+        if runtime:
+            context.attach_runtime(**runtime)
+
+        try:
+            self.engine.run(soup, context)
+        except Exception as exc:  # pragma: no cover - defensive
+            raise LatexRenderingError("LaTeX rendering failed") from exc
+
+        return self._collect_output(soup)
+
+    def _collect_output(self, soup: BeautifulSoup) -> str:
+        """Extract the LaTeX output from the transformed soup."""
+        return soup.get_text()
+
+    def iter_registered_rules(self) -> Iterable[tuple[RenderPhase, str]]:
+        """Expose currently registered rules for debugging/reporting."""
+        for phase in RenderPhase:
+            for rule in self.engine.registry.iter_phase(phase):
+                yield phase, rule.name
+
+    def describe_registered_rules(self) -> list[dict[str, object]]:
+        """Return detailed metadata about registered rules."""
+        return self.engine.registry.describe()
+
+
+__all__ = ["LaTeXRenderer"]