mdhtml2docx 0.1.4__tar.gz → 0.1.6__tar.gz

{mdhtml2docx-0.1.4 → mdhtml2docx-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdhtml2docx
-Version: 0.1.4
+Version: 0.1.6
 Summary: Convert MDHTML to Word docx files
 Author-email: Jeremy Howard <j@fast.ai>
 License-Expression: Apache-2.0
@@ -10,13 +10,10 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mdhtml>=0.1.39
-Requires-Dist: fast5ever>=0.1.5
-Requires-Dist: oxml>=0.1.1
-Provides-Extra: validation
-Requires-Dist: lxml; extra == "validation"
+Requires-Dist: mdhtml>=0.1.44
+Requires-Dist: oxml>=0.1.4
 Provides-Extra: dev
-Requires-Dist: mdhtml2docx[validation]; extra == "dev"
+Requires-Dist: lxml; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: fastship; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -25,35 +22,34 @@ Dynamic: license-file
 
 # mdhtml2docx
 
-Convert [MDHTML](https://github.com/AnswerDotAI/mdhtml) to Word docx files.
+Write [mdhtml](https://github.com/AnswerDotAI/mdhtml) documents as Word docx files.
 
-`mdhtml` renders Markdown to an HTML5 document format shared by format-specific exporters. `mdhtml2docx` converts its portable core to docx from scratch. It uses [fast5ever](https://github.com/AnswerDotAI/fast5ever)'s mutable WHATWG DOM for input and `oxml` for WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
+`mdhtml2docx` consumes mdhtml's semantic `Document` API. The shared importer handles HTML5 parsing, raw-data decoding, and document structure. The shared reference index validates and plans references. `oxml` provides WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
 
-MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. It returns a warning when an unsupported block must become a plain paragraph. HTML parsing and repair belong to `mdhtml`.
+MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. HTML parsing and repair belong to `mdhtml`.
 
 ## Usage
 
 ```python
-from mdhtml import md2mdhtml
+from mdhtml import parse_md
 from mdhtml2docx import mdhtml2docx
 
-html = md2mdhtml(markdown_text)
-warnings = mdhtml2docx(html, 'out.docx')
+document = parse_md(markdown_text)
+warnings = mdhtml2docx(document, 'out.docx')
 ```
 
-`mdhtml2docx` takes an MDHTML string, writes a docx, and returns a list of warning strings. It parses strings with `mdhtml.mdhtml2dom`. Normal HTML5 repair applies; the input need not be well-formed XML.
+`mdhtml2docx` accepts a semantic `Document` or symbolic MDHTML, writes a docx, and returns warning strings. Normal HTML5 repair applies when importing MDHTML; the input need not be well-formed XML.
 
-You can also pass an existing mutable fast5ever DOM:
+Import existing MDHTML through the same document API:
 
 ```python
-from mdhtml import mdhtml2dom
+from mdhtml import Document
 
-document = mdhtml2dom(html)
-document.children[0].attrs['custom-style'] = 'Contract Title'
+document = Document.from_mdhtml(html)
 warnings = mdhtml2docx(document, 'out.docx')
 ```
 
-Body-position text and phrasing content become implicit Word paragraphs. Whitespace between blocks does not produce content. HTML templates are not rendered.
+The importer groups body-position text and phrasing content into paragraphs. The exporter reads ordinary dictionary snapshots of the semantic blocks, inlines, and note definitions. Operation arguments remain inert unless an operation renderer selects them.
 
 ## Supported content
 
@@ -71,6 +67,8 @@ A `details` div becomes its label as a bold line above the body. It does not bec
 
 Math spans and blocks become native Word math zones (`m:oMath`). These contain the source text unchanged, whether TeX, UnicodeMath, or AsciiMath. Math build-up and rendering are left to downstream tools. Pandoc reads the zones back as math.
 
+An id-bearing display equation receives a live `Equation N` caption below its math zone. Unlabelled equations remain unnumbered.
+
 When [fastpylight](https://github.com/AnswerDotAI/fastpylight) is installed, code blocks with a language use syntax coloring. Tokens receive `Hl*` character styles such as `Hl Keyword`. Their colors come from the reference theme described below. You can restyle them in Word.
 
 ## Styling
@@ -114,13 +112,7 @@ The converter accepts MDHTML raw data with `data-format="docx"`:
 
 A ```` ```{=docx} ```` fenced block in Markdown, or inline code followed by `{=docx}`, produces this element. The payload is parsed as WordprocessingML and inserted verbatim. Block payloads contain elements such as `w:p` or `w:tbl`. Inline payloads contain elements such as `w:r`. The prefixes `w`, `r`, `wp`, `a`, `pic`, and `m` are predeclared.
 
-Payload encoding follows these rules:
-
-- No `data-encoding`: use the literal payload.
-- `data-encoding="html"`: perform one character-reference decoding pass.
-- `data-encoding="base64"`: decode a base64-encoded UTF-8 payload.
-
-Malformed payloads and unknown encodings are dropped with a warning. Raw data for other formats is skipped silently.
+The shared mdhtml importer decodes payloads according to its raw-data contract. This exporter parses decoded `docx` payloads as WordprocessingML. Invalid encodings and malformed XML produce warnings. Other formats are skipped.
 
 For example, insert a page break with:
 
@@ -130,6 +122,8 @@ For example, insert a page break with:
 
 ## Cross-references
 
+Bibliographies and citations use mdhtml's shared Rust preparation. `::: bibliography` entries contain citation-author terms with ids and optional `year` attributes, followed by their formatted definitions. Citations use `[@key]`, narrative `{ref=text}`, author-suppressing `-@`, and per-item prefix/suffix text. `cite_style='numeric'` selects numbers in bibliography order; `'author-year'` selects author-year text. None inherits frontmatter. Citations become static linked text and bibliography entries retain their bookmarks. Section, page, figure and table cross-references remain native Word fields. Re-export the original document to change citation style.
+
 Markdown references such as `[@sec-payment]` become live Word REF fields. MDHTML represents them as `a` elements with `data-ref`.
 
 The default field is `REF <bookmark> \w \h`. It displays the full-context paragraph number, such as "3.(c)(iii)", as a hyperlink. The converter sets `updateFields` in `settings.xml` so Word refreshes fields on open.
@@ -150,7 +144,7 @@ A missing target id raises a conversion error. A reference type with no defined
 
 Number fields require numbered headings. If your reference docx already numbers its heading styles, the converter leaves that numbering unchanged.
 
-Otherwise, select a scheme with `number_headings`:
+The shared reference index resolves `number_headings` against document metadata. Numeric heading references infer decimal numbering when no scheme is supplied. You can select a scheme explicitly:
 
 - `'legal'` uses 1. / (a) / (i) numbering.
 - `'decimal'` uses 1. / 1.1. / 1.1.1. numbering.
@@ -160,18 +154,22 @@ The named schemes come from mdhtml's `SCHEMES`. The custom dictionary uses the s
 
 A reference-list entry ending in `.xml` can also supply styles and numbering. It contains raw `w:style`, `w:abstractNum`, and `w:num` elements. Each contributor's ids and references are remapped before merging, so separate contributors can reuse the same original numbering ids; later styles still win.
 
-### Figures and tables
+### Figures, tables, and equations
+
+Figures, captioned tables, and id-bearing display equations use independent live SEQ fields. A figure's caption appears below its body as "Figure 1: caption". A table's caption appears above it as "Table 1: caption". Equations receive an "Equation 1" caption below the math zone. Labels come from `reftypes`; changing a label never merges the counters.
 
-Figures and captioned tables use live SEQ fields. A figure's caption appears below its image as "Figure 1: caption", using the caption style. A table's caption appears above it as "Table 1: caption".
+When the element has an id, the converter bookmarks its label, number, and authored caption separately. The shared reference planner supplies prefix words; each Word REF field supplies only the live number. Thus `[@fig-plot]` displays "Figure 1", while `[-@tbl-stages]` displays only the number.
 
-When the element has an id, the converter bookmarks its label and number. `[@fig-plot]` inserts "Figure 1" from that bookmark without adding another prefix. A second, number-only bookmark supplies the bare number for references such as `[-@tbl-stages]`.
+Figure and table `{ref=text}` references use a separate bookmark containing the authored caption text. Generated bookmark names are reserved through the same collision-safe allocator as authored targets, including forward references. Equation references support full labels, bare numbers, and pages. `{ref=text}` to equation source is not supported by the Word exporter.
 
-`fig` and `tbl` are built-in reference types alongside `sec`. Their labels come from the same `reftypes` table. Same-type groups pluralize once. Mixed-type groups use each item's singular prefix, as in "Figure 1 and Table 2".
+`fig`, `tbl`, and `eq` are built-in reference types alongside `sec`. Grouped references use the shared planner's plural prefixes and separators, such as "Figures 1 and 2".
 
-Reference targets must be headings, paragraphs, figures, or tables with ids. A reference to anything else raises a conversion error.
+Reference targets include headings, paragraphs, figures, tables, equations, spans, and definition terms with ids. Paragraphs support text and page references; spans and definition terms support text and page references. Target and variant validation belongs to mdhtml.
 
 ## Validation
 
 Independent schema validation is optional. Install `mdhtml2docx[validation]` to use `mdhtml2docx.validate.fast_checks(path)`; this extra requires lxml. Normal conversion does not import it.
 
 The test suite checks docx containers, CRCs, and XML, validates against the ECMA-376 schemas with lxml, and performs semantic round trips through Pandoc's independent docx reader. Periodic acceptance runs open documents in Microsoft Word through AppleScript.
+
+Live Word scripting is provided by [macscript](https://github.com/AnswerDotAI/macscript), not the converter. The development-only `tools/check_docx.py` combines `oxml` validation with a live Word acceptance check; see "Live Word checks" in [DEV.md](DEV.md). Normal installation and conversion do not require macscript or Office.

{mdhtml2docx-0.1.4 → mdhtml2docx-0.1.6}/README.md

@@ -1,34 +1,33 @@
 # mdhtml2docx
 
-Convert [MDHTML](https://github.com/AnswerDotAI/mdhtml) to Word docx files.
+Write [mdhtml](https://github.com/AnswerDotAI/mdhtml) documents as Word docx files.
 
-`mdhtml` renders Markdown to an HTML5 document format shared by format-specific exporters. `mdhtml2docx` converts its portable core to docx from scratch. It uses [fast5ever](https://github.com/AnswerDotAI/fast5ever)'s mutable WHATWG DOM for input and `oxml` for WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
+`mdhtml2docx` consumes mdhtml's semantic `Document` API. The shared importer handles HTML5 parsing, raw-data decoding, and document structure. The shared reference index validates and plans references. `oxml` provides WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
 
-MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. It returns a warning when an unsupported block must become a plain paragraph. HTML parsing and repair belong to `mdhtml`.
+MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. HTML parsing and repair belong to `mdhtml`.
 
 ## Usage
 
 ```python
-from mdhtml import md2mdhtml
+from mdhtml import parse_md
 from mdhtml2docx import mdhtml2docx
 
-html = md2mdhtml(markdown_text)
-warnings = mdhtml2docx(html, 'out.docx')
+document = parse_md(markdown_text)
+warnings = mdhtml2docx(document, 'out.docx')
 ```
 
-`mdhtml2docx` takes an MDHTML string, writes a docx, and returns a list of warning strings. It parses strings with `mdhtml.mdhtml2dom`. Normal HTML5 repair applies; the input need not be well-formed XML.
+`mdhtml2docx` accepts a semantic `Document` or symbolic MDHTML, writes a docx, and returns warning strings. Normal HTML5 repair applies when importing MDHTML; the input need not be well-formed XML.
 
-You can also pass an existing mutable fast5ever DOM:
+Import existing MDHTML through the same document API:
 
 ```python
-from mdhtml import mdhtml2dom
+from mdhtml import Document
 
-document = mdhtml2dom(html)
-document.children[0].attrs['custom-style'] = 'Contract Title'
+document = Document.from_mdhtml(html)
 warnings = mdhtml2docx(document, 'out.docx')
 ```
 
-Body-position text and phrasing content become implicit Word paragraphs. Whitespace between blocks does not produce content. HTML templates are not rendered.
+The importer groups body-position text and phrasing content into paragraphs. The exporter reads ordinary dictionary snapshots of the semantic blocks, inlines, and note definitions. Operation arguments remain inert unless an operation renderer selects them.
 
 ## Supported content
 
@@ -46,6 +45,8 @@ A `details` div becomes its label as a bold line above the body. It does not bec
 
 Math spans and blocks become native Word math zones (`m:oMath`). These contain the source text unchanged, whether TeX, UnicodeMath, or AsciiMath. Math build-up and rendering are left to downstream tools. Pandoc reads the zones back as math.
 
+An id-bearing display equation receives a live `Equation N` caption below its math zone. Unlabelled equations remain unnumbered.
+
 When [fastpylight](https://github.com/AnswerDotAI/fastpylight) is installed, code blocks with a language use syntax coloring. Tokens receive `Hl*` character styles such as `Hl Keyword`. Their colors come from the reference theme described below. You can restyle them in Word.
 
 ## Styling
@@ -89,13 +90,7 @@ The converter accepts MDHTML raw data with `data-format="docx"`:
 
 A ```` ```{=docx} ```` fenced block in Markdown, or inline code followed by `{=docx}`, produces this element. The payload is parsed as WordprocessingML and inserted verbatim. Block payloads contain elements such as `w:p` or `w:tbl`. Inline payloads contain elements such as `w:r`. The prefixes `w`, `r`, `wp`, `a`, `pic`, and `m` are predeclared.
 
-Payload encoding follows these rules:
-
-- No `data-encoding`: use the literal payload.
-- `data-encoding="html"`: perform one character-reference decoding pass.
-- `data-encoding="base64"`: decode a base64-encoded UTF-8 payload.
-
-Malformed payloads and unknown encodings are dropped with a warning. Raw data for other formats is skipped silently.
+The shared mdhtml importer decodes payloads according to its raw-data contract. This exporter parses decoded `docx` payloads as WordprocessingML. Invalid encodings and malformed XML produce warnings. Other formats are skipped.
 
 For example, insert a page break with:
 
@@ -105,6 +100,8 @@ For example, insert a page break with:
 
 ## Cross-references
 
+Bibliographies and citations use mdhtml's shared Rust preparation. `::: bibliography` entries contain citation-author terms with ids and optional `year` attributes, followed by their formatted definitions. Citations use `[@key]`, narrative `{ref=text}`, author-suppressing `-@`, and per-item prefix/suffix text. `cite_style='numeric'` selects numbers in bibliography order; `'author-year'` selects author-year text. None inherits frontmatter. Citations become static linked text and bibliography entries retain their bookmarks. Section, page, figure and table cross-references remain native Word fields. Re-export the original document to change citation style.
+
 Markdown references such as `[@sec-payment]` become live Word REF fields. MDHTML represents them as `a` elements with `data-ref`.
 
 The default field is `REF <bookmark> \w \h`. It displays the full-context paragraph number, such as "3.(c)(iii)", as a hyperlink. The converter sets `updateFields` in `settings.xml` so Word refreshes fields on open.
@@ -125,7 +122,7 @@ A missing target id raises a conversion error. A reference type with no defined
 
 Number fields require numbered headings. If your reference docx already numbers its heading styles, the converter leaves that numbering unchanged.
 
-Otherwise, select a scheme with `number_headings`:
+The shared reference index resolves `number_headings` against document metadata. Numeric heading references infer decimal numbering when no scheme is supplied. You can select a scheme explicitly:
 
 - `'legal'` uses 1. / (a) / (i) numbering.
 - `'decimal'` uses 1. / 1.1. / 1.1.1. numbering.
@@ -135,18 +132,22 @@ The named schemes come from mdhtml's `SCHEMES`. The custom dictionary uses the s
 
 A reference-list entry ending in `.xml` can also supply styles and numbering. It contains raw `w:style`, `w:abstractNum`, and `w:num` elements. Each contributor's ids and references are remapped before merging, so separate contributors can reuse the same original numbering ids; later styles still win.
 
-### Figures and tables
+### Figures, tables, and equations
+
+Figures, captioned tables, and id-bearing display equations use independent live SEQ fields. A figure's caption appears below its body as "Figure 1: caption". A table's caption appears above it as "Table 1: caption". Equations receive an "Equation 1" caption below the math zone. Labels come from `reftypes`; changing a label never merges the counters.
 
-Figures and captioned tables use live SEQ fields. A figure's caption appears below its image as "Figure 1: caption", using the caption style. A table's caption appears above it as "Table 1: caption".
+When the element has an id, the converter bookmarks its label, number, and authored caption separately. The shared reference planner supplies prefix words; each Word REF field supplies only the live number. Thus `[@fig-plot]` displays "Figure 1", while `[-@tbl-stages]` displays only the number.
 
-When the element has an id, the converter bookmarks its label and number. `[@fig-plot]` inserts "Figure 1" from that bookmark without adding another prefix. A second, number-only bookmark supplies the bare number for references such as `[-@tbl-stages]`.
+Figure and table `{ref=text}` references use a separate bookmark containing the authored caption text. Generated bookmark names are reserved through the same collision-safe allocator as authored targets, including forward references. Equation references support full labels, bare numbers, and pages. `{ref=text}` to equation source is not supported by the Word exporter.
 
-`fig` and `tbl` are built-in reference types alongside `sec`. Their labels come from the same `reftypes` table. Same-type groups pluralize once. Mixed-type groups use each item's singular prefix, as in "Figure 1 and Table 2".
+`fig`, `tbl`, and `eq` are built-in reference types alongside `sec`. Grouped references use the shared planner's plural prefixes and separators, such as "Figures 1 and 2".
 
-Reference targets must be headings, paragraphs, figures, or tables with ids. A reference to anything else raises a conversion error.
+Reference targets include headings, paragraphs, figures, tables, equations, spans, and definition terms with ids. Paragraphs support text and page references; spans and definition terms support text and page references. Target and variant validation belongs to mdhtml.
 
 ## Validation
 
 Independent schema validation is optional. Install `mdhtml2docx[validation]` to use `mdhtml2docx.validate.fast_checks(path)`; this extra requires lxml. Normal conversion does not import it.
 
 The test suite checks docx containers, CRCs, and XML, validates against the ECMA-376 schemas with lxml, and performs semantic round trips through Pandoc's independent docx reader. Periodic acceptance runs open documents in Microsoft Word through AppleScript.
+
+Live Word scripting is provided by [macscript](https://github.com/AnswerDotAI/macscript), not the converter. The development-only `tools/check_docx.py` combines `oxml` validation with a live Word acceptance check; see "Live Word checks" in [DEV.md](DEV.md). Normal installation and conversion do not require macscript or Office.

{mdhtml2docx-0.1.4 → mdhtml2docx-0.1.6}/mdhtml2docx/__init__.py

@@ -1,4 +1,6 @@
-__version__ = "0.1.4"
+__version__ = "0.1.6"
+
+
 
 
 

{mdhtml2docx-0.1.4 → mdhtml2docx-0.1.6}/mdhtml2docx/hilite.py

@@ -1,7 +1,4 @@
-"""Optional syntax scopes for code blocks, via fastpylight (Jeremy's tree-sitter highlighter).
-When fastpylight is absent or the language unknown, callers fall back to plain runs, so the
-package does not require fastpylight. Colors live in the reference doc's Hl* character
-styles (see styles.theme_styles); this module only tokenizes."""
+"Optional syntax scopes for code blocks, via fastpylight When fastpylight is absent or the language unknown, callers fall back to plain runs, so the package does not require fastpylight. Colors live in the reference doc's Hl* character styles (see styles.theme_styles); this module only tokenizes."
 
 # theme_colors is probed too: a pre-theme_colors fastpylight is treated as absent, not half-working
 try: from fastpylight import tokenize, theme_colors  # chkstyle: ignore