AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
fix(source-to-md): recover EPUB, ODT and RTF text the readers skipped
hugohe3f3660bfcd20b
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 89c877c2..f0e9fb7d 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -136,12 +136,26 @@ Hybrid converter: pure-Python for the common formats, pandoc fallback for the reNative path (no external binary required):- `.docx` — via `mammoth`; text-only tables (with footnotes) and chart data become pipe Markdown, and OMML / Office Math equations (Word-native or MathType "Convert to Office Math") are rewritten to inline LaTeX, including footnote and endnote math. Classic MathType OLE objects carry no OMML and are kept only as their preview image. Simple fields (`w:fldSimple`, e.g. caption numbers) keep their displayed result, and directly hidden runs (`w:vanish`) are omitted with a warning, matching what Word displays.- `.html` / `.htm` — via `markdownify` + `beautifulsoup4`-- `.epub` — via `ebooklib` + `markdownify`+- `.epub` — via `ebooklib` + `markdownify`; keep spine order, then append+ supplemental document items (not the EPUB 3 navigation document) with a+ warning. Resolve images relative to each+ chapter before basename fallbacks, so equal filenames in different chapter+ directories keep their own images. Non-rendered script/style/template content+ is omitted with a warning; interactive `hidden` / `display:none` text is kept.- `.ipynb` — via `nbconvert`; code-cell output images and Markdown attachmentsuse `<output-stem>_files/` with relative Markdown referencesPandoc fallback (only if you need these):- `.doc`, `.odt`, `.rtf`, `.tex`/`.latex`, `.rst`, `.org`, `.typ`+- `.odt` uses a temporary copy to expose table header rows, flatten text-box+ paragraphs while retaining inline links, and resolve conditional text from+ its stored `text:is-hidden` state. Diagnostics report these normalizations+ and excluded author-hidden fields; text-box geometry remains in the source.+- `.rtf` normalizes flat field instruction/result containers in a temporary+ copy so Pandoc retains their displayed text and links. Author-hidden text is+ omitted with a warning. Both preparations leave source files unchanged.+- `.doc` still requires a Pandoc build with a `doc` reader; a build without+ that reader reports an explicit conversion failure, not an empty success.- `.typ` evaluates under pandoc, so a real project file that imports its template,a package, or a custom function fails there; it then (or without pandoc) keeps thesource text with `=` headings mapped to Markdown and raw blocks, markup, math, and@@ -233,6 +247,7 @@ python3 scripts/source_to_md/ppt_to_md.py template.ppsx -o notes/template.mdBehavior:- extracts slide text in reading order+- excludes author-hidden shapes and groups (`cNvPr/@hidden`) with warnings; their text, pictures, tables, charts, and SmartArt descendants do not enter Markdown or the Beautify intake inventory- rewrites Office Math equations (`a14:m` OMML) as `$...$` inline or `$$...$$` display LaTeX, using the same converter as `.docx`- uses a chart's own visible title in its `> [Chart]` header, and a picture's alt text (`descr`) as its Markdown alt text- reads the `mc:Fallback` of other shape-tree `mc:AlternateContent` it cannot interpret (3D models, ink, zoom), so their preview pictures and text are kept; ChartEx stays reported as unsupported@@ -247,7 +262,6 @@ Behavior:Dependency:-- excludes author-hidden shapes and groups (`cNvPr/@hidden`) with warnings; their text, pictures, tables, charts, and SmartArt descendants do not enter Markdown or the Beautify intake inventory```bashpip install python-pptx```diff --git a/skills/ppt-master/scripts/source_to_md/doc_to_md.py b/skills/ppt-master/scripts/source_to_md/doc_to_md.pyindex 045380cf..d1ef392f 100644--- a/skills/ppt-master/scripts/source_to_md/doc_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/doc_to_md.py@@ -1333,11 +1333,11 @@ def _epub_image_candidates(src: str, document_name: str) -> list[str]:).lstrip("/")candidates = [+ relative_path,src,raw_path,decoded_path,normalized_path,- relative_path,Path(decoded_path).name,Path(normalized_path).name,]@@ -1378,15 +1378,36 @@ def _convert_epub(input_file: Path, out_file: Path) -> str:img_map[item.file_name] = filenameimg_map[Path(item.file_name).name] = filename- # Iterate document items in spine order+ # Keep the reading order, then retain supplemental documents (e.g. linked+ # footnotes) that an EPUB reader can open outside the linear spine.html_parts: list[str] = []spine_ids = [sid for sid, _ in book.spine]id_to_item = {it.get_id(): it for it in book.get_items_of_type(ebooklib.ITEM_DOCUMENT)}- for sid in spine_ids:+ # The EPUB 3 navigation document is the book's table of contents, not text.+ extra_ids = [+ sid for sid, item in id_to_item.items()+ if sid not in spine_ids and not isinstance(item, epub.EpubNav)+ ]+ if extra_ids:+ print(+ f"[WARN] EPUB: retaining {len(extra_ids)} document(s) outside the reading spine "+ "after the main text.",+ file=sys.stderr,+ )+ for sid in spine_ids + extra_ids:item = id_to_item.get(sid)if item is None:continuesoup = BeautifulSoup(item.get_content(), "html.parser")+ inert = soup.find_all(["script", "style", "template"])+ if inert:+ print(+ f"[WARN] EPUB {item.file_name}: omitted {len(inert)} non-rendered "+ "script/style/template element(s).",+ file=sys.stderr,+ )+ for element in inert:+ element.decompose()for img in soup.find_all("img"):src = img.get("src", "")if not src:@@ -1492,6 +1513,95 @@ def _check_pandoc() -> bool:return shutil.which("pandoc") is not None+def _prepare_odt_for_pandoc(input_file: Path) -> Path:+ """Expose text containers skipped by Pandoc's ODT reader in a temporary copy."""+ text_ns = "urn:oasis:names:tc:opendocument:xmlns:text:1.0"+ table_ns = "urn:oasis:names:tc:opendocument:xmlns:table:1.0"+ draw_ns = "urn:oasis:names:tc:opendocument:xmlns:drawing:1.0"+ try:+ with zipfile.ZipFile(input_file) as source:+ root = ET.fromstring(source.read("content.xml"))+ headers = textboxes = conditional = hidden = 0+ for parent in list(root.iter()):+ for child in list(parent):+ if child.tag == f"{{{table_ns}}}table-header-rows":+ index = list(parent).index(child)+ parent.remove(child)+ for row in reversed(list(child)):+ parent.insert(index, row)+ headers += 1+ elif child.tag == f"{{{draw_ns}}}frame":+ textbox = child.find(f"{{{draw_ns}}}text-box")+ if textbox is None:+ continue+ # Keep inline runs, links and line boundaries; geometry+ # has no Markdown representation. Other frame children+ # (for example images) remain available to Pandoc.+ span = ET.Element(f"{{{text_ns}}}span")+ span.text = textbox.text+ span.tail = child.tail+ child.tail = None+ for index, paragraph in enumerate(list(textbox)):+ if index:+ ET.SubElement(span, f"{{{text_ns}}}line-break")+ if paragraph.tag in {f"{{{text_ns}}}p", f"{{{text_ns}}}h"}:+ paragraph.tag = f"{{{text_ns}}}span"+ span.append(paragraph)+ parent.insert(list(parent).index(child) + 1, span)+ child.remove(textbox)+ textboxes += 1+ elif child.tag == f"{{{text_ns}}}hidden-text":+ if child.get(f"{{{text_ns}}}is-hidden") in {"true", "1"}:+ child.text = None+ child[:] = []+ hidden += 1+ child.tag = f"{{{text_ns}}}span"+ conditional += 1+ if not (headers or textboxes or conditional):+ return input_file+ print(+ f"[WARN] ODT: exposed {headers} table header container(s), flattened "+ f"{textboxes} text box(es), and resolved {conditional} conditional-text "+ f"field(s) for Pandoc; {hidden} author-hidden field(s) omitted. "+ "Text-box geometry is retained only in the source ODT.",+ file=sys.stderr,+ )+ with tempfile.NamedTemporaryFile(suffix=".odt", delete=False) as temporary:+ prepared = Path(temporary.name)+ with zipfile.ZipFile(prepared, "w") as destination:+ for item in source.infolist():+ content = (+ ET.tostring(root, encoding="utf-8", xml_declaration=True)+ if item.filename == "content.xml" else source.read(item.filename)+ )+ destination.writestr(item, content)+ return prepared+ except (OSError, KeyError, zipfile.BadZipFile, ET.ParseError) as exc:+ print(f"[WARN] ODT text preparation skipped: {exc}; using original file.", file=sys.stderr)+ return input_file+++def _prepare_rtf_for_pandoc(input_file: Path) -> Path:+ """Keep flat fields that Pandoc otherwise silently skips."""+ content = input_file.read_text(encoding="latin-1")+ if any(+ re.fullmatch(r"\\v(?:-?[1-9]\d*)? ?", token.group())+ for token in re.finditer(r"\\(?:[a-zA-Z]+-?\d* ?|[^a-zA-Z])", content)+ ):+ print("[WARN] RTF: author-hidden text is omitted by Pandoc.", file=sys.stderr)+ normalized, count = re.subn(+ r"(?<!\\)(\{(?:\\\*)?\\(?:fldrslt|fldinst)\s+)((?:\\[{}\\]|[^{}])+)(\})",+ lambda match: match[1] + "{" + match[2] + "}" + match[3],+ content,+ )+ if not count:+ return input_file+ print(f"[WARN] RTF: normalized {count} flat field container(s) for Pandoc.", file=sys.stderr)+ with tempfile.NamedTemporaryFile(suffix=".rtf", delete=False) as temporary:+ temporary.write(normalized.encode("latin-1"))+ return Path(temporary.name)++def _convert_with_pandoc(input_file: Path, out_file: Path, suffix: str) -> str:if not _check_pandoc():print(f"[ERROR] Format '{suffix}' requires pandoc. Install it:")@@ -1504,11 +1614,16 @@ def _convert_with_pandoc(input_file: Path, out_file: Path, suffix: str) -> str:rel_media_dir = f"{out_file.stem}_files"media_dir = out_file.parent / rel_media_dir+ prepared = input_file+ if suffix == ".odt":+ prepared = _prepare_odt_for_pandoc(input_file)+ elif suffix == ".rtf":+ prepared = _prepare_rtf_for_pandoc(input_file)cmd = ["pandoc","-f", input_format,"-t", "gfm",- str(input_file.resolve()),+ str(prepared.resolve()),"-o", str(out_file.resolve()),"--wrap", "none","--strip-comments",@@ -1516,9 +1631,13 @@ def _convert_with_pandoc(input_file: Path, out_file: Path, suffix: str) -> str:if suffix in PANDOC_MEDIA_FORMATS:cmd.extend(["--extract-media", rel_media_dir])- result = subprocess.run(cmd, capture_output=True, text=True,- encoding="utf-8", errors="replace",- cwd=str(out_file.parent))+ try:+ result = subprocess.run(cmd, capture_output=True, text=True,+ encoding="utf-8", errors="replace",+ cwd=str(out_file.parent))+ finally:+ if prepared != input_file:+ prepared.unlink()if result.returncode != 0:print(f"[ERROR] Pandoc conversion failed:\n{result.stderr}")return ""diff --git a/skills/ppt-master/scripts/tests/test_source_to_md_epub_survival.py b/skills/ppt-master/scripts/tests/test_source_to_md_epub_survival.pynew file mode 100644index 00000000..896f3fdf--- /dev/null+++ b/skills/ppt-master/scripts/tests/test_source_to_md_epub_survival.py@@ -0,0 +1,115 @@+#!/usr/bin/env python3+"""Regression tests for document conversion content survival."""++from __future__ import annotations++import contextlib+import io+import re+import shutil+import subprocess+import sys+import tempfile+import unittest+import zipfile+from pathlib import Path+++BACKEND = Path(__file__).resolve().parents[1] / "source_to_md"+if str(BACKEND) not in sys.path:+ sys.path.insert(0, str(BACKEND))++import doc_to_md # noqa: E402+++class EpubSurvivalTests(unittest.TestCase):+ def _book(self, path: Path) -> None:+ with zipfile.ZipFile(path, "w") as archive:+ archive.writestr("mimetype", "application/epub+zip")+ archive.writestr("META-INF/container.xml", (+ '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'+ '<rootfiles><rootfile full-path="content.opf" '+ 'media-type="application/oebps-package+xml"/></rootfiles></container>'+ ))+ archive.writestr("content.opf", (+ '<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="id">'+ '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'+ '<dc:identifier id="id">book</dc:identifier><dc:title>Book</dc:title>'+ '<dc:language>en</dc:language></metadata><manifest>'+ '<item id="a" href="a/ch.xhtml" media-type="application/xhtml+xml"/>'+ '<item id="b" href="b/ch.xhtml" media-type="application/xhtml+xml"/>'+ '<item id="note" href="note.xhtml" media-type="application/xhtml+xml"/>'+ '<item id="ia" href="a/pic.svg" media-type="image/svg+xml"/>'+ '<item id="ib" href="b/pic.svg" media-type="image/svg+xml"/>'+ '</manifest><spine><itemref idref="b"/><itemref idref="a"/></spine></package>'+ ))+ for chapter in ("a", "b"):+ archive.writestr(f"{chapter}/ch.xhtml", (+ '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter</title></head>'+ f'<body><p>CHAPTER{chapter}</p><img src="pic.svg" alt="IMAGE{chapter}"/>'+ '<p hidden="hidden">INTERACTIVEHIDDEN</p>'+ '<p style="display:none">INTERACTIVECSS</p>'+ '<template>INERTTEMPLATE</template><script>INERTSCRIPT</script>'+ '<style>INERTSTYLE</style><a href="../note.xhtml">NOTELINK</a></body></html>'+ ))+ archive.writestr(f"{chapter}/pic.svg", (+ '<svg xmlns="http://www.w3.org/2000/svg">'+ f'<text>PIXELS{chapter}</text></svg>'+ ))+ archive.writestr("note.xhtml", (+ '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Note</title></head>'+ '<body><p>LINKEDNOTE</p></body></html>'+ ))++ def test_spine_supplemental_text_and_inert_content(self) -> None:+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ source = root / "book.epub"+ self._book(source)+ diagnostics = io.StringIO()+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(diagnostics):+ text = doc_to_md.convert_to_markdown(str(source), str(root / "book.md"))+ for marker in ("CHAPTERa", "CHAPTERb", "LINKEDNOTE", "INTERACTIVEHIDDEN", "INTERACTIVECSS"):+ self.assertIn(marker, text)+ for marker in ("INERTTEMPLATE", "INERTSCRIPT", "INERTSTYLE"):+ self.assertNotIn(marker, text)+ self.assertLess(text.index("CHAPTERb"), text.index("CHAPTERa"))+ self.assertLess(text.index("CHAPTERa"), text.index("LINKEDNOTE"))+ self.assertIn("outside the reading spine", diagnostics.getvalue())+ self.assertIn("non-rendered", diagnostics.getvalue())++ def test_navigation_document_is_not_appended_as_text(self) -> None:+ from ebooklib import epub++ book = epub.EpubBook()+ book.set_identifier("nav-test")+ book.set_title("Book")+ book.set_language("en")+ chapter = epub.EpubHtml(title="Chapter", file_name="c1.xhtml")+ chapter.content = "<h1>Chapter</h1><p>CHAPTERBODY</p>"+ book.add_item(chapter)+ book.toc = (chapter,)+ book.add_item(epub.EpubNcx())+ book.add_item(epub.EpubNav())+ book.spine = [chapter]+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ epub.write_epub(root / "book.epub", book)+ diagnostics = io.StringIO()+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(diagnostics):+ text = doc_to_md.convert_to_markdown(str(root / "book.epub"), str(root / "book.md"))+ self.assertIn("CHAPTERBODY", text)+ self.assertNotIn("](c1.xhtml)", text)+ self.assertNotIn("outside the reading spine", diagnostics.getvalue())++ def test_same_basename_images_resolve_relative_to_each_chapter(self) -> None:+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ source = root / "book.epub"+ self._book(source)+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):+ text = doc_to_md.convert_to_markdown(str(source), str(root / "book.md"))+ for chapter in ("a", "b"):+ match = re.search(rf"!\[IMAGE{chapter}\]\(([^)]+)\)", text)+ self.assertIsNotNone(match)+ self.assertIn(f"PIXELS{chapter}", (root / match[1]).read_text())diff --git a/skills/ppt-master/scripts/tests/test_source_to_md_odt_survival.py b/skills/ppt-master/scripts/tests/test_source_to_md_odt_survival.pynew file mode 100644index 00000000..6ab8cc0f--- /dev/null+++ b/skills/ppt-master/scripts/tests/test_source_to_md_odt_survival.py@@ -0,0 +1,62 @@+#!/usr/bin/env python3+"""Regression tests for document conversion content survival."""++from __future__ import annotations++import contextlib+import io+import re+import shutil+import subprocess+import sys+import tempfile+import unittest+import zipfile+from pathlib import Path+++BACKEND = Path(__file__).resolve().parents[1] / "source_to_md"+if str(BACKEND) not in sys.path:+ sys.path.insert(0, str(BACKEND))++import doc_to_md # noqa: E402++[email protected](shutil.which("pandoc"), "Pandoc fallback requires the optional system binary")+class OdtSurvivalTests(unittest.TestCase):+ def test_odt_table_header_textbox_and_conditional_text(self) -> None:+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ source = root / "document.odt"+ subprocess.run(+ ["pandoc", "-f", "markdown", "-o", str(source)],+ input="| HEADERMARK |\n|---|\n| BODYMARK |\n", text=True,+ capture_output=True, check=True,+ )+ with zipfile.ZipFile(source) as archive:+ parts = {name: archive.read(name) for name in archive.namelist()}+ parts["content.xml"] = parts["content.xml"].replace(b"</office:text>", (+ '<text:p>LEFTMARK <draw:frame text:anchor-type="as-char"><draw:text-box><text:p>BOXMARK '+ '<text:a xlink:href="https://example.invalid/BOXURL">BOXLINK</text:a>'+ '</text:p><text:p>BOXSECOND</text:p></draw:text-box></draw:frame> RIGHTMARK</text:p>'+ '<text:p><text:hidden-text text:is-hidden="false">CONDITIONVISIBLE</text:hidden-text>'+ '<text:hidden-text text:is-hidden="true">CONDITIONHIDDEN</text:hidden-text>'+ 'TAILMARK</text:p></office:text>'+ ).encode())+ with zipfile.ZipFile(source, "w") as archive:+ for name, data in parts.items():+ archive.writestr(name, data)+ original = source.read_bytes()+ diagnostics = io.StringIO()+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(diagnostics):+ text = doc_to_md.convert_to_markdown(str(source), str(root / "document.md"))+ for marker in (+ "HEADERMARK", "BODYMARK", "BOXMARK", "BOXSECOND", "BOXLINK", "BOXURL",+ "CONDITIONVISIBLE", "TAILMARK",+ ):+ self.assertIn(marker, text)+ self.assertNotIn("CONDITIONHIDDEN", text)+ self.assertLess(text.index("LEFTMARK"), text.index("BOXMARK"))+ self.assertLess(text.index("BOXSECOND"), text.index("RIGHTMARK"))+ self.assertIn("1 author-hidden field(s) omitted", diagnostics.getvalue())+ self.assertEqual(source.read_bytes(), original)diff --git a/skills/ppt-master/scripts/tests/test_source_to_md_rtf_survival.py b/skills/ppt-master/scripts/tests/test_source_to_md_rtf_survival.pynew file mode 100644index 00000000..41454c5b--- /dev/null+++ b/skills/ppt-master/scripts/tests/test_source_to_md_rtf_survival.py@@ -0,0 +1,61 @@+#!/usr/bin/env python3+"""Regression tests for document conversion content survival."""++from __future__ import annotations++import contextlib+import io+import re+import shutil+import subprocess+import sys+import tempfile+import unittest+import zipfile+from pathlib import Path+++BACKEND = Path(__file__).resolve().parents[1] / "source_to_md"+if str(BACKEND) not in sys.path:+ sys.path.insert(0, str(BACKEND))++import doc_to_md # noqa: E402++[email protected](shutil.which("pandoc"), "Pandoc fallback requires the optional system binary")+class RtfSurvivalTests(unittest.TestCase):+ def test_rtf_flat_hyperlink_fields_and_hidden_text(self) -> None:+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ source = root / "document.rtf"+ source.write_text(+ r'{\rtf1\ansi BEFORE {\v HIDDENMARK} '+ r'{\field{\*\fldinst HYPERLINK "https://example.invalid/LINKURL"}'+ r'{\fldrslt LINKTEXT}} AFTER}', encoding="ascii",+ )+ original = source.read_bytes()+ diagnostics = io.StringIO()+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(diagnostics):+ text = doc_to_md.convert_to_markdown(str(source), str(root / "document.md"))+ for marker in ("BEFORE", "LINKURL", "LINKTEXT", "AFTER"):+ self.assertIn(marker, text)+ self.assertNotIn("HIDDENMARK", text)+ self.assertIn("author-hidden", diagnostics.getvalue())+ self.assertEqual(source.read_bytes(), original)++ def test_rtf_nested_field_results_and_literal_backslashes_stay_visible(self) -> None:+ with tempfile.TemporaryDirectory() as temporary:+ root = Path(temporary)+ source = root / "nested.rtf"+ source.write_text(+ r'{\rtf1\ansi \\v VISIBLEMARK '+ r'{\field{\*\fldinst{HYPERLINK "https://example.invalid/NESTEDURL"}}'+ r'{\fldrslt{NESTEDTEXT}}}}', encoding="ascii",+ )+ diagnostics = io.StringIO()+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(diagnostics):+ text = doc_to_md.convert_to_markdown(str(source), str(root / "nested.md"))+ self.assertIn("VISIBLEMARK", text)+ self.assertIn("NESTEDTEXT", text)+ self.assertIn("NESTEDURL", text)+ self.assertNotIn("author-hidden", diagnostics.getvalue())