',
f'',
f'
")
correct_image = media.image_html(correct.get("picture"))
back_parts = [
'{text_html(question.get("question", ""))}
',
]
q_image = media.image_html(question.get("picture_question"))
if q_image:
front_parts.append(
f'{q_image}
'
)
front_parts.append('- ')
for choice in choices:
choice_image = media.image_html(choice.get("picture"))
image_html_part = (
f'
- "
f'{text_html(choice["text"])}' f"{image_html_part}" " "
)
front_parts.append("
{choice_image}
' if choice_image else ""
)
front_parts.append(
"',
f'
")
return "".join(front_parts), "".join(back_parts), correct_label
def display_path(path):
"""Return the user-facing section path with the top prefix stripped.
Used for both the visible card breadcrumb and the stored `Path`
note field so the two never drift.
"""
if not path:
return ""
return " / ".join([_short_category_title(path[0]), *path[1:]])
# ============================================================================
# LaTeX and HTML escaping
# ============================================================================
def text_html(value):
"""Escape text for HTML, preserve line breaks, and enable MathJax.
The catalog uses bare `$...$` for inline LaTeX (DESIGN.md §3
quotes the upstream README on this). Anki 2.1+ ships built-in
MathJax that recognizes `\\(...\\)` but not `$...$`, so we
tokenize the input into alternating math / non-math runs, escape
each run for HTML, and wrap math runs in `\\(...\\)` afterwards.
Non-math newlines become `Richtige Antwort: {correct_label}
',
f'{text_html(correct["text"])}
',
]
if correct_image:
back_parts.append(
f'{correct_image}
'
)
back_parts.append("` and the catalog's safe inline markup (`...`) survives escaping. """ parts = [] for is_math, chunk in tokenize_dollar_math(str(value)): if is_math: escaped = html.escape(chunk) parts.append(r"\(" + escaped + r"\)") else: escaped = escape_text_preserving_safe_tags(chunk) parts.append("
".join(escaped.splitlines())) return "".join(parts) def escape_text_preserving_safe_tags(text): """HTML-escape `text` while preserving exact `` / `` tags. The live catalog uses `...` to emphasize negation in question stems (e.g. "Welche der folgenden Aussagen ist nicht korrekt"). Preserving those tags keeps that emphasis visible on the rendered card. Anything else — including ordinary mathematical comparisons like `2 < 3` — still goes through `html.escape`. """ escaped_parts = [] for part in SAFE_INLINE_TAG_RE.split(text): if SAFE_INLINE_TAG_RE.fullmatch(part): escaped_parts.append(part.lower()) else: escaped_parts.append(html.escape(part)) return "".join(escaped_parts) def tokenize_dollar_math(text): """Yield `(is_math, chunk)` pairs, splitting on unescaped `$...$`. A backslash-escaped `\\$` is treated as a literal dollar and does not open or close a math span. Unmatched dollars (an opening `$` with no closing partner) are treated as ordinary text. """ index = 0 while index < len(text): start = find_unescaped_dollar(text, index) if start is None: yield False, text[index:] return end = find_unescaped_dollar(text, start + 1) if end is None: yield False, text[index:] return if start > index: yield False, text[index:start] yield True, text[start + 1:end] index = end + 1 def find_unescaped_dollar(text, start): """Return the index of the next `$` not preceded by an odd run of `\\`.""" while True: pos = text.find("$", start) if pos == -1: return None backslashes = 0 cursor = pos - 1 while cursor >= 0 and text[cursor] == "\\": backslashes += 1 cursor -= 1 if backslashes % 2 == 0: return pos start = pos + 1 # ============================================================================ # Media registry # ============================================================================ class MediaRegistry: """Resolve catalog image stems and collect media files for one `.apkg`. Indexes every file in `media_dir` by filename. Each call to `resolve(reference)` accepts the catalog's bare stem (e.g. `"AB109_q"`) or a filename with extension; on a hit, the `Path` is recorded in `used_paths` so the packager can include only the files we actually referenced. """ def __init__(self, media_dir): self.media_dir = media_dir # filename → Path for every file under `media_dir` self.by_filename = {} # files referenced by at least one resolved reference self.used_paths = set() # references that didn't resolve (recorded for diagnostics) self.missing = [] self._index_media_dir() def _index_media_dir(self): """Populate `by_filename` from a single pass over `media_dir`.""" if not self.media_dir.exists(): return for path in self.media_dir.iterdir(): if path.is_file(): self.by_filename[path.name] = path def resolve(self, reference): """Return the resolved `Path`, or `None` if the reference is missing. Picture references in the catalog are stems without extensions (e.g. `"AB109_q"`); we try the stem with `.svg` first, then `.png`. A reference that already carries an extension is tried as-is. References containing path separators are rejected outright — the catalog only ever names a bare basename. """ if not reference: return None ref = str(reference) if "/" in ref or "\\" in ref: self.missing.append(ref) return None if Path(ref).suffix: candidates = [ref] else: candidates = [f"{ref}.svg", f"{ref}.png"] for candidate in candidates: path = self.by_filename.get(candidate) if path is not None: self.used_paths.add(path) return path self.missing.append(ref) return None def image_html(self, reference): """Return an `