figgydeck 1.0.0__py3-none-any.whl

figgydeck/__init__.py

@@ -0,0 +1,22 @@
+"""figgydeck: turn textbooks into study decks (PowerPoint slides or Anki decks)."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from figgydeck.anki import build_apkg, build_combined_apkg
+from figgydeck.extract import extract_chapter
+from figgydeck.models import Chapter
+
+# The PowerPoint builders (build_pptx, build_combined_pptx) are equal
+# first-class outputs, but they live in figgydeck.pptx and are imported from
+# there so that the top-level package never hard-imports the optional
+# python-pptx dependency. Use `from figgydeck.pptx import build_pptx`.
+
+# Version is defined once in pyproject.toml; read it back from the installed
+# distribution metadata so the two can never drift.
+try:
+    __version__ = _pkg_version("figgydeck")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["extract_chapter", "build_apkg", "build_combined_apkg", "Chapter"]

figgydeck/anki.py

@@ -0,0 +1,331 @@
+"""Anki deck builder: turn a manifest + images into a .apkg file."""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+import shutil
+import tempfile
+from pathlib import Path
+
+import genanki
+
+from figgydeck.models import Chapter, load_manifest
+
+# Stable model ID — must not change between runs, or Anki will fail to
+# update existing notes when users re-import.
+_MODEL_ID = 1607392319
+_DECK_ID_BASE = 2059400110
+
+
+CARD_CSS = """
+/* ---------- Light mode (default) ---------- */
+.card {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-size: 17px; color: #2A1B23; background: #F8F4EC;
+  text-align: left; padding: 18px; line-height: 1.5;
+}
+.card-img {
+  display: block; max-width: 100%; max-height: 60vh;
+  margin: 0 auto 12px; border-radius: 6px;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.15);
+  background: #ffffff; padding: 6px;
+}
+.tag-row {
+  text-align: center; font-size: 12px; letter-spacing: 2px;
+  text-transform: uppercase; color: #A26769;
+  font-weight: 600; margin-top: 8px;
+}
+.divider {
+  border: 0; border-top: 2px solid #C9A86A;
+  width: 60px; margin: 16px auto;
+}
+.label {
+  font-size: 11px; letter-spacing: 1.5px; text-transform: uppercase;
+  color: #A26769; font-weight: 600; margin-bottom: 4px;
+}
+.title {
+  font-family: Georgia, serif; font-size: 22px; font-weight: 700;
+  color: #6D2E46; margin: 0 0 14px 0; line-height: 1.3;
+}
+.caption { font-size: 15px; color: #2A1B23; margin: 0 0 16px 0; }
+.meta {
+  font-size: 12px; color: #8A7079; font-style: italic;
+  border-top: 1px solid #D8C9B5; padding-top: 10px; margin-top: 12px;
+}
+.meta-line { margin: 2px 0; }
+.meta b { color: #6D2E46; font-style: normal; }
+
+/* ---------- Dark mode (.nightMode / .night_mode) ---------- */
+.nightMode .card, .night_mode .card,
+.card.nightMode, .card.night_mode {
+  color: #ECE2D0; background: #1F1419;
+}
+.nightMode .card-img, .night_mode .card-img,
+.card.nightMode .card-img, .card.night_mode .card-img {
+  background: #ffffff; box-shadow: 0 2px 16px rgba(0,0,0,0.6);
+}
+.nightMode .tag-row, .night_mode .tag-row,
+.card.nightMode .tag-row, .card.night_mode .tag-row { color: #E8B86F; }
+.nightMode .divider, .night_mode .divider,
+.card.nightMode .divider, .card.night_mode .divider { border-top-color: #E8B86F; }
+.nightMode .label, .night_mode .label,
+.card.nightMode .label, .card.night_mode .label { color: #E8B86F; }
+.nightMode .title, .night_mode .title,
+.card.nightMode .title, .card.night_mode .title { color: #F2C9A0; }
+.nightMode .caption, .night_mode .caption,
+.card.nightMode .caption, .card.night_mode .caption { color: #ECE2D0; }
+.nightMode .meta, .night_mode .meta,
+.card.nightMode .meta, .card.night_mode .meta {
+  color: #B5A39A; border-top-color: #4A2D38;
+}
+.nightMode .meta b, .night_mode .meta b,
+.card.nightMode .meta b, .card.night_mode .meta b { color: #F2C9A0; }
+"""
+
+
+def _build_model() -> genanki.Model:
+    return genanki.Model(
+        _MODEL_ID,
+        "figgydeck Card",
+        fields=[
+            {"name": "Number"},   # "Fig X.Y" or "Tab X.Y"
+            {"name": "Image"},    # <img src="...">
+            {"name": "Title"},    # tables have one; figures may be empty
+            {"name": "Caption"},  # cleaned caption body
+            {"name": "Book"},
+            {"name": "Chapter"},
+            {"name": "Page"},
+            {"name": "Type"},     # "Figure" | "Table"
+        ],
+        templates=[{
+            "name": "Image -> Details",
+            "qfmt": '{{Image}}<div class="tag-row">{{Number}}</div>',
+            "afmt": (
+                '{{Image}}<div class="tag-row">{{Number}}</div>'
+                '<hr class="divider">'
+                '<div class="label">{{Type}}</div>'
+                '{{#Title}}<div class="title">{{Title}}</div>{{/Title}}'
+                '{{#Caption}}<div class="caption">{{Caption}}</div>{{/Caption}}'
+                '<div class="meta">'
+                '<div class="meta-line"><b>Book:</b> {{Book}}</div>'
+                '<div class="meta-line"><b>Chapter:</b> {{Chapter}}</div>'
+                '<div class="meta-line"><b>Page:</b> {{Page}}</div>'
+                '</div>'
+            ),
+        }],
+        css=CARD_CSS,
+    )
+
+
+def _slugify(s: str) -> str:
+    s = s.lower()
+    s = re.sub(r"[^\w\s-]", "", s)
+    s = re.sub(r"[-\s]+", "-", s).strip("-")
+    return s
+
+
+def _add_notes(
+    deck: genanki.Deck,
+    model: genanki.Model,
+    manifest: list[dict],
+    images_dir: Path,
+    book_title: str,
+    chapter_title: str,
+    media_files: list[str],
+    *,
+    media_prefix: str = "",
+    stage_dir: Path | None = None,
+    log=lambda *a, **k: None,
+) -> int:
+    """Add one note per figure/table entry to `deck`; return the skipped count.
+
+    Appends each referenced image path to `media_files` (the caller writes them
+    into the genanki Package). genanki keys media by basename, so when merging
+    several chapters into one package `media_prefix` (the chapter slug) is set:
+    each image is copied into `stage_dir` as ``f"{media_prefix}__{name}"`` and
+    the note's ``<img src>`` references that unique basename. With an empty
+    prefix (single-chapter build) images are referenced in place, unchanged.
+    """
+    book_tag = _slugify(book_title)
+    chapter_tag = _slugify(chapter_title)
+    skipped = 0
+
+    for entry in manifest:
+        if not entry.get("image_filename"):
+            log(f"  skip {entry['type']} {entry['number']}: no image")
+            skipped += 1
+            continue
+        img_path = images_dir / entry["image_filename"]
+        if not img_path.exists():
+            log(f"  skip {entry['type']} {entry['number']}: missing {img_path}")
+            skipped += 1
+            continue
+
+        if media_prefix:
+            if stage_dir is None:
+                raise ValueError("media_prefix requires stage_dir")
+            media_name = f"{media_prefix}__{img_path.name}"
+            staged = stage_dir / media_name
+            shutil.copy(img_path, staged)
+            media_files.append(str(staged))
+        else:
+            media_name = img_path.name
+            media_files.append(str(img_path))
+
+        kind = entry["type"].capitalize()
+        number_label = f"Tab {entry['number']}" if kind == "Table" else f"Fig {entry['number']}"
+
+        note = genanki.Note(
+            model=model,
+            fields=[
+                number_label,
+                f'<img class="card-img" src="{html.escape(media_name)}">',
+                html.escape(entry.get("title") or ""),
+                html.escape(entry.get("caption") or ""),
+                html.escape(book_title),
+                html.escape(chapter_title),
+                f"p. {entry['page']}",
+                kind,
+            ],
+            tags=[
+                f"book::{book_tag}",
+                f"chapter::{chapter_tag}",
+                f"type::{kind.lower()}",
+            ],
+            # Stable GUID: re-running figgydeck and re-importing into Anki
+            # updates existing notes rather than creating duplicates.
+            guid=genanki.guid_for(book_tag, chapter_tag, kind, entry["number"]),
+        )
+        deck.add_note(note)
+
+    return skipped
+
+
+def _deck_for(book_title: str, chapter_title: str, deck_name: str) -> genanki.Deck:
+    """Create a genanki.Deck with a stable id derived from book + chapter.
+
+    Uses a SHA-256 digest (not builtin ``hash()``, which is salted per process
+    via ``PYTHONHASHSEED``) so the same book/chapter yields the same deck id on
+    every run. Anki keys decks by name on import, so the id is mostly cosmetic —
+    but a stable value keeps re-imports and diffs reproducible.
+    """
+    book_tag = _slugify(book_title)
+    chapter_tag = _slugify(chapter_title)
+    digest = hashlib.sha256(f"{book_tag}::{chapter_tag}".encode()).digest()
+    deck_id = _DECK_ID_BASE + int.from_bytes(digest[:4], "big") % 100000
+    return genanki.Deck(deck_id, deck_name)
+
+
+def build_apkg(
+    manifest: list[dict] | str | Path,
+    images_dir: str | Path,
+    book_title: str,
+    chapter_title: str,
+    output_path: str | Path,
+    *,
+    verbose: bool = True,
+) -> Path:
+    """Build an Anki .apkg from a chapter manifest.
+
+    Args:
+        manifest: Either the manifest list (from `extract_chapter()`) or a
+            path to a `manifest.json` file.
+        images_dir: Folder containing the extracted images referenced in
+            the manifest.
+        book_title: Display title for the book — appears on every card back.
+        chapter_title: Display title for the chapter.
+        output_path: Where to write the `.apkg` file.
+
+    Returns:
+        Path to the written .apkg file.
+    """
+    manifest = load_manifest(manifest)
+
+    images_dir = Path(images_dir)
+    output_path = Path(output_path)
+    log = print if verbose else (lambda *a, **k: None)
+
+    deck = _deck_for(book_title, chapter_title, f"{book_title} :: {chapter_title}")
+    model = _build_model()
+    media_files: list[str] = []
+
+    skipped = _add_notes(
+        deck, model, manifest, images_dir, book_title, chapter_title,
+        media_files, log=log,
+    )
+
+    pkg = genanki.Package(deck)
+    pkg.media_files = media_files
+    pkg.write_to_file(str(output_path))
+
+    log(f"\nWrote: {output_path}")
+    log(f"  notes added: {len(deck.notes)}")
+    log(f"  skipped: {skipped}")
+
+    return output_path
+
+
+def build_combined_apkg(
+    chapters: list[Chapter],
+    book_title: str,
+    output_path: str | Path,
+    *,
+    verbose: bool = True,
+) -> Path:
+    """Build one `.apkg` merging every chapter into its own Anki subdeck.
+
+    Args:
+        chapters: list of `Chapter` records. Each chapter's `manifest` may be
+            the list from `extract_chapter()` or a path to a `manifest.json`.
+        book_title: Book title — the parent deck; each chapter becomes a
+            subdeck named ``"{book_title}::{chapter_title}"`` ("::" with no
+            spaces is Anki's subdeck separator, so they nest under the book).
+        output_path: Where to write the combined `.apkg`.
+
+    Images from different chapters can share a basename (e.g. ``img-000.png``);
+    since genanki keys media by basename, each chapter's images are staged with
+    a chapter-prefixed basename so they don't collide inside the package.
+    """
+    output_path = Path(output_path)
+    log = print if verbose else (lambda *a, **k: None)
+
+    model = _build_model()
+    decks: list[genanki.Deck] = []
+    media_files: list[str] = []
+
+    # Keep the staging dir alive until after the package is written.
+    with tempfile.TemporaryDirectory(prefix="figgydeck-apkg-") as tmp:
+        stage_dir = Path(tmp)
+        total_notes = 0
+        total_skipped = 0
+
+        for i, chapter in enumerate(chapters):
+            manifest = load_manifest(chapter.manifest)
+            images_dir = chapter.images_dir
+            chapter_title = chapter.title
+            deck = _deck_for(
+                book_title, chapter_title, f"{book_title}::{chapter_title}"
+            )
+            # Index-prefixed so media basenames stay unique even if two
+            # chapters share a title (and thus a slug).
+            skipped = _add_notes(
+                deck, model, manifest, Path(images_dir), book_title, chapter_title,
+                media_files, media_prefix=f"ch{i}-{_slugify(chapter_title)}",
+                stage_dir=stage_dir, log=log,
+            )
+            decks.append(deck)
+            total_notes += len(deck.notes)
+            total_skipped += skipped
+
+        pkg = genanki.Package(decks)
+        pkg.media_files = media_files
+        pkg.write_to_file(str(output_path))
+
+    log(f"\nWrote: {output_path}")
+    log(f"  chapters: {len(chapters)}")
+    log(f"  notes added: {total_notes}")
+    log(f"  skipped: {total_skipped}")
+
+    return output_path

figgydeck/clean.py

@@ -0,0 +1,83 @@
+"""Caption cleanup: strip running headers, decode ligatures, normalize whitespace."""
+
+from __future__ import annotations
+
+import re
+
+# Common PDF font ligatures
+LIGATURES = {
+    "fi": "fi", "fl": "fl", "ff": "ff", "ffi": "ffi", "ffl": "ffl",
+    "ſt": "ft", "st": "st",
+}
+
+# A running header/footer is a banner of consecutive ALL-CAPS words (the book or
+# chapter title) that PDF extraction interleaves into the caption text. We treat
+# any run of >= 3 consecutive capitalized tokens -- with short lowercase
+# connectors like "of"/"the" allowed between them -- as such a banner and strip
+# it. This is a heuristic: ordinary captions rarely contain three consecutive
+# all-caps words with no intervening punctuation (acronym lists like "DNA, RNA"
+# are punctuated, so they don't match and are preserved).
+_CAPS_WORD = r"[A-Z][A-Z0-9&.'\-]*"
+_CONNECTOR = r"(?:of|the|and|in|for|to|a|an|&)"
+RUNNING_HEADER_RE = re.compile(
+    rf"{_CAPS_WORD}(?:(?:\s+{_CONNECTOR})*\s+{_CAPS_WORD}){{2,}}"
+)
+
+# Per-line footnote patterns are publisher-specific; none are enabled by default.
+# Add re.compile(...) entries here to drop footnote lines for a particular layout.
+FOOTNOTE_LINE_PATTERNS: list[re.Pattern[str]] = []
+
+
+def clean_caption(text: str) -> str:
+    """Clean a raw extracted caption into something readable.
+
+    Steps:
+        1. Decode font ligatures
+        2. Strip running headers (anywhere they appear)
+        3. Filter footnote-style lines
+        4. De-hyphenate line-wrapped words
+        5. Normalize the en-dash glyph
+        6. Collapse whitespace
+        7. Strip trailing partial words from running-header bleed
+    """
+    if not text:
+        return ""
+
+    # 1. Ligatures
+    for lig, repl in LIGATURES.items():
+        text = text.replace(lig, repl)
+
+    # 2. Running headers (mid-text occurrences)
+    text = RUNNING_HEADER_RE.sub(" ", text)
+
+    # 3. Per-line footnote filtering
+    lines = [ln.strip() for ln in text.split("\n") if ln.strip()]
+    lines = [ln for ln in lines if not any(p.match(ln) for p in FOOTNOTE_LINE_PATTERNS)]
+    text = " ".join(lines)
+
+    # 4. De-hyphenate line-wrapped words
+    text = re.sub(r"-\s+", "", text)
+
+    # 5. Elsevier renders en-dash as "e": "1968e1969" -> "1968–1969"
+    text = re.sub(r"(\d{4})e(\d{4})", r"\1–\2", text)
+
+    # 6. Collapse whitespace
+    text = re.sub(r"\s+", " ", text).strip()
+
+    # 7. Second running-header pass: catches banners that only became adjacent
+    #    once line breaks were collapsed (header bled onto the caption tail).
+    text = RUNNING_HEADER_RE.sub(" ", text)
+    text = re.sub(r"\s+", " ", text).strip()
+
+    return text
+
+
+def split_camel(s: str) -> str:
+    """Restore spaces in CamelCase strings extracted from PDF.
+
+    pdfplumber sometimes concatenates chars without inferring spaces, giving
+    us "RatStrainsandStocksOriginated...". This restores it to readable form.
+    """
+    s = re.sub(r"([a-z])([A-Z])", r"\1 \2", s)
+    s = re.sub(r"\s+", " ", s).strip()
+    return s

figgydeck/cli.py

@@ -0,0 +1,212 @@
+"""figgydeck command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from figgydeck.models import Chapter
+
+
+def _slug(s: str) -> str:
+    """Collapse whitespace and strip punctuation, keeping alphanumerics.
+
+    "Ch. 1: Historical Foundations" -> "Ch1HistoricalFoundations"
+    """
+    s = re.sub(r"[^\w\s]", "", s)
+    s = re.sub(r"\s+", "", s.title())
+    return s
+
+
+def _safe_filename(book: str, chapter: str) -> str:
+    """Build a clean filename from book + chapter titles.
+
+    Examples:
+        "Example Textbook (1st ed., 2020)", "Ch. 3: Cell Structure"
+        → "ExampleTextbook1StEd2020_Ch3CellStructure"
+    """
+    return f"{_slug(book)}_{_slug(chapter)}"
+
+
+def _chapter_title(pdf_path: Path, explicit: str | None) -> str:
+    """Resolve a chapter's display title.
+
+    Uses `explicit` when given; otherwise derives one from the PDF filename:
+    a ``ch01``-style stem becomes ``"Chapter 1"``; anything else is title-cased
+    with ``-``/``_`` turned into spaces.
+    """
+    if explicit:
+        return explicit
+    stem = pdf_path.stem
+    # Match a leading chapter marker and split off any descriptive remainder:
+    #   "ch01"                              -> "Chapter 1"
+    #   "Chapter-3-Biology-and-Diseases..." -> "Chapter 3: Biology and Diseases..."
+    #   "Chapter 11 - Microbiological..."   -> "Chapter 11: Microbiological..."
+    m = re.match(r"\s*ch(?:apter)?[\s._-]*0*(\d+)[\s._-]*(.*)$", stem, re.IGNORECASE)
+    if m:
+        num = int(m.group(1))
+        rest = re.sub(r"[\s_-]+", " ", m.group(2)).strip(" _-.")
+        return f"Chapter {num}: {rest}" if rest else f"Chapter {num}"
+    pretty = re.sub(r"[-_]+", " ", stem).strip()
+    return pretty.title() if pretty else stem
+
+
+_VALID_FORMATS = ("apkg", "pptx")
+
+
+def _format_list(s: str) -> list[str]:
+    """Parse a single --format value: comma-separated formats with validation."""
+    parts = [p.strip().lower() for p in s.split(",") if p.strip()]
+    if not parts:
+        raise argparse.ArgumentTypeError("--format value cannot be empty")
+    bad = [p for p in parts if p not in _VALID_FORMATS]
+    if bad:
+        raise argparse.ArgumentTypeError(
+            f"unknown format(s): {', '.join(bad)} "
+            f"(choose from: {', '.join(_VALID_FORMATS)})"
+        )
+    return parts
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="figgydeck",
+        description="Turn textbooks into study decks: extract figures (and "
+                    "optionally tables) and captions from chapter PDFs and "
+                    "package them as Anki decks or PowerPoint slides.",
+    )
+    p.add_argument("pdfs", nargs="+", metavar="PDF", help="One or more source chapter PDFs")
+    p.add_argument("--book", required=True, help="Book title (e.g. 'Example Textbook (1st ed., 2020)')")
+    p.add_argument(
+        "--chapter", action="append", default=None, metavar="TITLE",
+        help="Chapter title (e.g. 'Ch. 1: Historical Foundations'). Repeatable: "
+             "give one per PDF, in order. If omitted, titles are derived from "
+             "each PDF's filename.",
+    )
+    p.add_argument("--output", "-o", default="./out", help="Output directory (default: ./out)")
+    p.add_argument(
+        "--format", "-f", action="append", type=_format_list, default=None,
+        metavar="FMT[,FMT...]",
+        help="Output format(s) to build (required). Repeatable, or "
+             f"comma-separated. Choices: {', '.join(_VALID_FORMATS)}.",
+    )
+    p.add_argument("--combine", action="store_true",
+                   help="Merge all input PDFs into a single artifact per format.")
+    p.add_argument("--full-res", action="store_true",
+                   help="Embed full-resolution PNGs in .pptx (default: downscaled "
+                        "JPEGs, which keep the file small enough for Google Slides).")
+    p.add_argument("--tables", action="store_true",
+                   help="Also extract tables (default: figures only).")
+    p.add_argument("--save-manifest", action="store_true",
+                   help="Also write manifest.json (the structured extraction "
+                        "result) into the output directory.")
+    p.add_argument("--save-images", action="store_true",
+                   help="Also write the extracted figure/table images (an "
+                        "images/ folder) into the output directory.")
+    p.add_argument("--quiet", "-q", action="store_true", help="Suppress progress logging")
+    args = p.parse_args(argv)
+
+    # An explicit output format is required — the decks are the only
+    # deliverables, so we won't guess which one you want.
+    if not args.format:
+        print(
+            f"error: --format is required (choose from: {', '.join(_VALID_FORMATS)}); "
+            "e.g. --format apkg  or  --format apkg,pptx",
+            file=sys.stderr,
+        )
+        return 2
+
+    pdf_paths = [Path(p) for p in args.pdfs]
+    missing = [p for p in pdf_paths if not p.exists()]
+    if missing:
+        for p in missing:
+            print(f"error: {p} does not exist", file=sys.stderr)
+        return 2
+
+    # Resolve one chapter title per PDF: all-or-nothing on --chapter.
+    if args.chapter is None:
+        titles = [_chapter_title(p, None) for p in pdf_paths]
+    elif len(args.chapter) == len(pdf_paths):
+        titles = [_chapter_title(p, c) for p, c in zip(pdf_paths, args.chapter, strict=True)]
+    else:
+        print(
+            f"error: got {len(args.chapter)} --chapter value(s) for "
+            f"{len(pdf_paths)} PDF(s); supply either none or exactly one per PDF",
+            file=sys.stderr,
+        )
+        return 2
+
+    out_dir = Path(args.output)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    verbose = not args.quiet
+
+    # Flatten + dedupe requested formats while preserving order.
+    formats = list(dict.fromkeys(f for chunk in args.format for f in chunk))
+
+    # Bind builders up front so a missing optional dep (python-pptx) fails
+    # before the slow extraction step. Imported at call time so tests can
+    # patch the module-level functions.
+    apkg_single = apkg_combined = None
+    pptx_single = pptx_combined = None
+    if "apkg" in formats:
+        from figgydeck.anki import build_apkg as apkg_single
+        from figgydeck.anki import build_combined_apkg as apkg_combined
+    if "pptx" in formats:
+        from figgydeck.pptx import build_combined_pptx as pptx_combined
+        from figgydeck.pptx import build_pptx as pptx_single
+
+    from figgydeck.extract import extract_chapter
+
+    single_pdf = len(pdf_paths) == 1
+
+    # Extract into a temporary working dir. The built decks embed their own
+    # images, so the raw manifest.json / images/ are intermediates — surfaced
+    # into out_dir only when --save-manifest / --save-images ask for them. A
+    # single PDF extracts flat; multiple PDFs each get their own subdir so fixed
+    # image names (img-000.png, ...) don't collide.
+    with tempfile.TemporaryDirectory(prefix="figgydeck-extract-") as tmp:
+        work = Path(tmp)
+        chapters: list[Chapter] = []
+        for i, (pdf, title) in enumerate(zip(pdf_paths, titles, strict=True)):
+            sub = "" if single_pdf else f"{i:02d}_{_slug(title)}"
+            ex_dir = work / sub if sub else work
+            manifest = extract_chapter(pdf, ex_dir, include_tables=args.tables, verbose=verbose)
+            chapters.append(Chapter(manifest, ex_dir / "images", title))
+
+            if args.save_manifest or args.save_images:
+                dest = out_dir / sub if sub else out_dir
+                dest.mkdir(parents=True, exist_ok=True)
+                if args.save_manifest:
+                    shutil.copy(ex_dir / "manifest.json", dest / "manifest.json")
+                if args.save_images:
+                    shutil.copytree(ex_dir / "images", dest / "images", dirs_exist_ok=True)
+
+        # Write requested formats (inside the temp dir so extracted images exist).
+        optimize = not args.full_res
+        if args.combine:
+            base = f"{_slug(args.book)}_Combined"
+            if apkg_combined is not None:
+                apkg_combined(chapters, args.book, out_dir / f"{base}.apkg", verbose=verbose)
+            if pptx_combined is not None:
+                pptx_combined(chapters, args.book, out_dir / f"{base}.pptx",
+                              optimize_images=optimize, verbose=verbose)
+        else:
+            for chapter in chapters:
+                base = _safe_filename(args.book, chapter.title)
+                if apkg_single is not None:
+                    apkg_single(chapter.manifest, chapter.images_dir, args.book, chapter.title,
+                                out_dir / f"{base}.apkg", verbose=verbose)
+                if pptx_single is not None:
+                    pptx_single(chapter.manifest, chapter.images_dir, args.book, chapter.title,
+                                out_dir / f"{base}.pptx",
+                                optimize_images=optimize, verbose=verbose)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())