mathfmt 0.1.0__tar.gz

mathfmt-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to MathFmt are documented here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-21
+
+- Added review-first `scan` and `apply` commands.
+- Added conservative `convert` and environment `doctor` commands.
+- Added native Word equation output for DOCX body text, tables, headers, and footers.
+- Added Codex Skill, tests, bilingual documentation, and release automation.

mathfmt-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+MathFmt welcomes contributors of every background and experience level.
+
+- Be respectful, constructive, and specific.
+- Critique ideas and code, never people.
+- Do not harass, threaten, discriminate, or publish private information.
+- Respect document privacy and intellectual property.
+
+Project maintainers may edit or remove unacceptable contributions and may temporarily or permanently
+restrict participation. Report conduct concerns privately to the repository owner through GitHub.

mathfmt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Thank you for helping improve MathFmt.
+
+1. Open an issue before large behavioral changes.
+2. Create a focused branch and keep source documents private.
+3. Install development dependencies with `python -m pip install -e ".[dev]"`.
+4. Run `ruff check .` and `pytest` before submitting a pull request.
+5. Add synthetic fixtures and tests for new notation or DOCX structures.
+
+Do not commit copyrighted, confidential, or personally identifying documents. Reproduce document
+problems with the smallest synthetic fixture possible.

mathfmt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mathfmt-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md LICENSE README.md SECURITY.md
+recursive-include skills *.md *.yaml

mathfmt-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: mathfmt
+Version: 0.1.0
+Summary: Typeset plain-text formulas in DOCX files as native Word equations.
+Author: Leo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gml853503962-creator/mathfmt
+Project-URL: Repository, https://github.com/gml853503962-creator/mathfmt
+Project-URL: Issues, https://github.com/gml853503962-creator/mathfmt/issues
+Keywords: docx,word,math,omml,equation,typesetting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=5.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# MathFmt
+
+[中文](#中文) | [English](#english)
+
+MathFmt turns awkward plain-text formulas in Word documents into native Word equations suitable for
+textbooks, exams, and technical reports. Processing stays on your computer.
+
+## 中文
+
+MathFmt 将 DOCX 文档中的普通文本公式转换为 Word 原生 OMML 公式，例如把 `ds(t)/dt`、
+`sqrt(x^2+1)` 和 `p1` 排版为纸质教材中常见的分式、根号与上下标。
+
+### 特点
+
+- 保留原始 DOCX，始终写入新文件。
+- 支持正文、表格、页眉、页脚和混合文本公式。
+- 自动跳过代码、图片公式和已有 Word 原生公式。
+- 提供可审核流程和保守的一键转换。
+- 完全本地运行，不上传文档。
+
+### 环境要求
+
+- Windows 10/11
+- Python 3.10 或更高版本
+- Microsoft Word/Office，并包含 `MML2OMML.XSL`
+
+MathFmt 不分发微软的 XSL 文件。它会自动检查常见 Office 安装目录，也可使用 `--xsl` 指定路径。
+
+### 安装
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+```
+
+从源码开发安装：
+
+```powershell
+git clone https://github.com/gml853503962-creator/mathfmt.git
+cd mathfmt
+python -m pip install -e ".[dev]"
+```
+
+### 使用
+
+```powershell
+# 保守的一键转换
+mathfmt convert input.docx
+
+# 审核后转换
+mathfmt scan input.docx --report candidates.json
+mathfmt apply input.docx --review candidates.json --output output.docx --report result.json
+```
+
+一键转换默认生成 `input.mathfmt.docx` 和 `input.mathfmt.report.json`，不会覆盖原文件。编辑
+`candidates.json` 中的 `selected`、`source` 或 `linear` 后再执行 `apply`。如果 Office 安装在
+非标准目录，为 `apply`、`convert` 或 `doctor` 添加 `--xsl C:\path\to\MML2OMML.XSL`。
+
+### Codex Skill
+
+仓库中的 `skills/mathfmt` 可复制到 Codex 技能目录。技能依赖已安装的 `mathfmt` 命令。
+
+## English
+
+MathFmt converts plain-text formulas in DOCX files into native Word OMML equations with stacked
+fractions, radicals, superscripts, subscripts, derivatives, and standard mathematical operators.
+
+### Highlights
+
+- Never overwrites the source DOCX.
+- Handles body text, tables, headers, footers, and formulas mixed with prose.
+- Skips likely code, image formulas, and existing Word equations.
+- Offers both a review-first workflow and conservative one-step conversion.
+- Processes documents locally without uploading them.
+
+### Requirements and installation
+
+MathFmt 0.1 supports Windows, Python 3.10+, and a Microsoft Office installation containing
+`MML2OMML.XSL`. The Microsoft stylesheet is detected locally and is not distributed with MathFmt.
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+mathfmt convert input.docx
+```
+
+For review-first conversion, run `scan`, edit the generated JSON, then run `apply` as shown above.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md),
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. Copyright (c) 2026 Leo.

mathfmt-0.1.0/README.md

@@ -0,0 +1,96 @@
+# MathFmt
+
+[中文](#中文) | [English](#english)
+
+MathFmt turns awkward plain-text formulas in Word documents into native Word equations suitable for
+textbooks, exams, and technical reports. Processing stays on your computer.
+
+## 中文
+
+MathFmt 将 DOCX 文档中的普通文本公式转换为 Word 原生 OMML 公式，例如把 `ds(t)/dt`、
+`sqrt(x^2+1)` 和 `p1` 排版为纸质教材中常见的分式、根号与上下标。
+
+### 特点
+
+- 保留原始 DOCX，始终写入新文件。
+- 支持正文、表格、页眉、页脚和混合文本公式。
+- 自动跳过代码、图片公式和已有 Word 原生公式。
+- 提供可审核流程和保守的一键转换。
+- 完全本地运行，不上传文档。
+
+### 环境要求
+
+- Windows 10/11
+- Python 3.10 或更高版本
+- Microsoft Word/Office，并包含 `MML2OMML.XSL`
+
+MathFmt 不分发微软的 XSL 文件。它会自动检查常见 Office 安装目录，也可使用 `--xsl` 指定路径。
+
+### 安装
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+```
+
+从源码开发安装：
+
+```powershell
+git clone https://github.com/gml853503962-creator/mathfmt.git
+cd mathfmt
+python -m pip install -e ".[dev]"
+```
+
+### 使用
+
+```powershell
+# 保守的一键转换
+mathfmt convert input.docx
+
+# 审核后转换
+mathfmt scan input.docx --report candidates.json
+mathfmt apply input.docx --review candidates.json --output output.docx --report result.json
+```
+
+一键转换默认生成 `input.mathfmt.docx` 和 `input.mathfmt.report.json`，不会覆盖原文件。编辑
+`candidates.json` 中的 `selected`、`source` 或 `linear` 后再执行 `apply`。如果 Office 安装在
+非标准目录，为 `apply`、`convert` 或 `doctor` 添加 `--xsl C:\path\to\MML2OMML.XSL`。
+
+### Codex Skill
+
+仓库中的 `skills/mathfmt` 可复制到 Codex 技能目录。技能依赖已安装的 `mathfmt` 命令。
+
+## English
+
+MathFmt converts plain-text formulas in DOCX files into native Word OMML equations with stacked
+fractions, radicals, superscripts, subscripts, derivatives, and standard mathematical operators.
+
+### Highlights
+
+- Never overwrites the source DOCX.
+- Handles body text, tables, headers, footers, and formulas mixed with prose.
+- Skips likely code, image formulas, and existing Word equations.
+- Offers both a review-first workflow and conservative one-step conversion.
+- Processes documents locally without uploading them.
+
+### Requirements and installation
+
+MathFmt 0.1 supports Windows, Python 3.10+, and a Microsoft Office installation containing
+`MML2OMML.XSL`. The Microsoft stylesheet is detected locally and is not distributed with MathFmt.
+
+```powershell
+pip install mathfmt
+mathfmt doctor
+mathfmt convert input.docx
+```
+
+For review-first conversion, run `scan`, edit the generated JSON, then run `apply` as shown above.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md),
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. Copyright (c) 2026 Leo.

mathfmt-0.1.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version.
+
+## Reporting a vulnerability
+
+Use GitHub private vulnerability reporting for the MathFmt repository. Do not include confidential
+DOCX files; provide a synthetic reproducer instead. Please allow the maintainer reasonable time to
+investigate before public disclosure.
+
+MathFmt processes files locally. Treat untrusted DOCX files as untrusted ZIP/XML input and run the
+tool with ordinary user privileges.

mathfmt-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mathfmt"
+version = "0.1.0"
+description = "Typeset plain-text formulas in DOCX files as native Word equations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Leo" }]
+keywords = ["docx", "word", "math", "omml", "equation", "typesetting"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Office Suites",
+  "Topic :: Text Processing :: Markup :: XML",
+]
+dependencies = ["lxml>=5.0"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+mathfmt = "mathfmt.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/gml853503962-creator/mathfmt"
+Repository = "https://github.com/gml853503962-creator/mathfmt"
+Issues = "https://github.com/gml853503962-creator/mathfmt/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["F", "I", "UP"]

mathfmt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mathfmt-0.1.0/skills/mathfmt/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: mathfmt
+description: Typeset plain-text formulas in Word DOCX documents as native paper-style Word equations. Use for requests to fix awkward formula symbols, convert typed math into textbook or exam formatting, normalize derivatives and control-system notation, or review formula candidates in DOCX files.
+---
+
+# MathFmt
+
+Convert plain-text formulas to native Word OMML equations with the installed `mathfmt` CLI. Preserve
+the source document and inspect the rendered result.
+
+## Workflow
+
+1. Run `mathfmt doctor` and resolve a missing `MML2OMML.XSL` with `--xsl PATH`.
+2. Use `mathfmt convert input.docx` only when conservative automatic selection is appropriate.
+3. For mixed technical prose, run `mathfmt scan input.docx --report candidates.json`, review the JSON,
+   then run `mathfmt apply input.docx --review candidates.json --output output.docx --report result.json`.
+4. Keep code, image formulas, and existing native Word equations unchanged.
+5. Inspect the result report and render every output page before delivery.
+
+Read `references/paper-notation.md` when reviewing notation or correcting a candidate's `linear` value.
+
+## Safety
+
+- Never use the input path as the output path.
+- Prefer the review-first flow when prose may resemble formulas.
+- Treat skipped candidates as unresolved work and report them.
+- Deliver only the final DOCX unless QA artifacts are requested.

mathfmt-0.1.0/skills/mathfmt/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MathFmt"
+  short_description: "Typeset DOCX formulas as native Word equations."
+  default_prompt: "Use $mathfmt to convert plain-text formulas in this DOCX into professional paper-style Word equations."

mathfmt-0.1.0/skills/mathfmt/references/paper-notation.md

@@ -0,0 +1,11 @@
+# Paper-Style Notation
+
+- Use stacked fractions for mathematical division.
+- Use radical bars for `sqrt(...)` or `√(...)`.
+- Render powers and indexes as true superscripts and subscripts.
+- Prefer fraction derivatives such as `ds(t)/dt` and `d²s(t)/dt²`.
+- Use `u(t)` for the unit-step function.
+- Preserve the source Laplace variable: commonly `p` in French material and `s` elsewhere.
+- Use standard symbols such as `±`, `≠`, `≤`, `≥`, `→`, `∞`, `Δ`, and `π`.
+- Prefer invisible multiplication for coefficient-variable products.
+- Split long table formulas at top-level addition or subtraction operators when necessary.

mathfmt-0.1.0/src/mathfmt/__init__.py

@@ -0,0 +1,6 @@
+"""MathFmt public API."""
+
+from .core import apply_docx, find_xsl, formula_to_mathml, scan_docx
+
+__all__ = ["apply_docx", "find_xsl", "formula_to_mathml", "scan_docx"]
+__version__ = "0.1.0"

mathfmt-0.1.0/src/mathfmt/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

mathfmt-0.1.0/src/mathfmt/cli.py

@@ -0,0 +1,136 @@
+"""Command-line interface for MathFmt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from lxml import etree
+
+from . import __version__
+from .core import apply_docx, find_xsl, scan_docx
+
+
+def default_output(input_path: Path) -> Path:
+    return input_path.with_name(f"{input_path.stem}.mathfmt.docx")
+
+
+def default_result_report(output_path: Path) -> Path:
+    return output_path.with_name(f"{output_path.stem}.report.json")
+
+
+def doctor_data(explicit_xsl: Path | None = None) -> dict[str, object]:
+    data: dict[str, object] = {
+        "mathfmt": __version__,
+        "python": platform.python_version(),
+        "platform": platform.platform(),
+        "windows": os.name == "nt",
+        "lxml": etree.LXML_VERSION,
+        "xsl": None,
+        "ready": False,
+    }
+    try:
+        data["xsl"] = str(find_xsl(explicit_xsl).resolve())
+        data["ready"] = True
+    except FileNotFoundError as exc:
+        data["error"] = str(exc)
+    return data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mathfmt",
+        description="Typeset plain-text DOCX formulas as native Word equations.",
+    )
+    parser.add_argument("--version", action="version", version=f"MathFmt {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="create a reviewable formula candidate report")
+    scan.add_argument("input", type=Path)
+    scan.add_argument("--report", type=Path, required=True)
+
+    apply = subparsers.add_parser("apply", help="apply a reviewed candidate report")
+    apply.add_argument("input", type=Path)
+    apply.add_argument("--review", type=Path, required=True)
+    apply.add_argument("--output", "--out", dest="output", type=Path, required=True)
+    apply.add_argument("--report", type=Path, required=True)
+    apply.add_argument("--xsl", type=Path)
+
+    convert = subparsers.add_parser("convert", help="conservatively convert detected formulas in one step")
+    convert.add_argument("input", type=Path)
+    convert.add_argument("--output", "--out", dest="output", type=Path)
+    convert.add_argument("--report", type=Path)
+    convert.add_argument("--xsl", type=Path)
+
+    doctor = subparsers.add_parser("doctor", help="check the local MathFmt environment")
+    doctor.add_argument("--xsl", type=Path)
+    doctor.add_argument("--json", action="store_true", dest="as_json")
+    return parser
+
+
+def run_convert(args: argparse.Namespace) -> int:
+    output = args.output or default_output(args.input)
+    report_path = args.report or default_result_report(output)
+    xsl = find_xsl(args.xsl)
+    with tempfile.TemporaryDirectory(prefix="mathfmt-") as temp_dir:
+        review_path = Path(temp_dir) / "candidates.json"
+        scan = scan_docx(args.input, review_path)
+        result = apply_docx(args.input, review_path, output, report_path, xsl)
+    print(f"Candidates: {scan['summary']['candidates']}")
+    print(f"Converted: {result['converted_count']}")
+    print(f"Skipped: {result['skipped_count']}")
+    print(f"Output: {output}")
+    print(f"Report: {report_path}")
+    return 0 if result["skipped_count"] == 0 else 2
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "scan":
+            report = scan_docx(args.input, args.report)
+            print(f"Candidates: {report['summary']['candidates']}")
+            print(f"Report: {args.report}")
+            return 0
+        if args.command == "apply":
+            result = apply_docx(
+                args.input,
+                args.review,
+                args.output,
+                args.report,
+                find_xsl(args.xsl),
+            )
+            print(f"Converted: {result['converted_count']}")
+            print(f"Skipped: {result['skipped_count']}")
+            print(f"Output: {args.output}")
+            print(f"Report: {args.report}")
+            return 0 if result["skipped_count"] == 0 else 2
+        if args.command == "convert":
+            return run_convert(args)
+        if args.command == "doctor":
+            data = doctor_data(args.xsl)
+            if args.as_json:
+                print(json.dumps(data, ensure_ascii=False, indent=2))
+            else:
+                print(f"MathFmt: {data['mathfmt']}")
+                print(f"Python: {data['python']}")
+                print(f"Platform: {data['platform']}")
+                print(f"MML2OMML.XSL: {data['xsl'] or 'not found'}")
+                print(f"Ready: {'yes' if data['ready'] else 'no'}")
+                if data.get("error"):
+                    print(f"Hint: {data['error']}")
+            return 0 if data["ready"] else 1
+    except (FileNotFoundError, ValueError, json.JSONDecodeError, etree.XMLSyntaxError) as exc:
+        print(f"mathfmt: error: {exc}", file=sys.stderr)
+        return 1
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())