Metadata-Version: 2.4
Name: mathfmt
Version: 0.2.2
Summary: Typeset plain-text formulas in DOCX files as native Word equations — cross-platform, no Office required.
Author-email: Leo <gml853503962@gmail.com>
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,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
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: pytest-cov>=7.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# MathFmt

[![CI](https://github.com/gml853503962-creator/mathfmt/actions/workflows/ci.yml/badge.svg)](https://github.com/gml853503962-creator/mathfmt/actions/workflows/ci.yml)

[中文](#中文) | [English](#english)

MathFmt turns plain-text formulas in Word documents into native Word OMML equations —
stacked fractions, radicals, superscripts, subscripts, derivatives, and standard
mathematical operators — suitable for textbooks, exams, and technical reports.

---

## Status

**Beta (v0.2.2).** Cross-platform OMML, confidence scoring, expanded formula support, self-update, and bug fixes.

---

## 中文

MathFmt 将 DOCX 中的普通文本公式排版为 Word 原生 OMML 公式。

### 快速示例

| 输入（纯文本） | 输出（Word 原生公式） |
|---|---|
| `ds(t)/dt` | 堆叠分式 d s(t) / d t |
| `s'(t) = -s''(t)` | 导数分数形式 |
| `sqrt(x^2 + 1)` | 根号 √(x²+1) |
| `x^3 + p1` | 上标 x³ + 下标 p₁ |
| `x != 0` | x ≠ 0 |
| `sin(x) + cos(x)` | sin(x) + cos(x) |
| `lim(p->0)` | lim 带下置 p→0 |
| `a/(b+c)` | 堆叠分式 |
| `e^(p1*t)` | e 的 p₁t 次幂 |
| `1(t)` | u(t)（单位阶跃） |
| `Delta + pi` | Δ + π |
| `x, y, z` | 逗号分隔序列 |

### 兼容性

| | Windows 10/11 | macOS | Linux |
|---|---|---|---|
| Python 3.10–3.13 | ✔ | ✔ | ✔ |
| 公式扫描 | ✔ | ✔ | ✔ |
| OMML 公式输出（内置 Python 后端） | ✔ | ✔ | ✔ |
| OMML 公式输出（Office XSL 后端） | ✔ | ✔¹ | ✔¹ |
| Word 渲染 | ✔ | ✔² | — |

¹ 需手动指定 `MML2OMML.XSL` 路径（`--xsl`）。  
² macOS 版 Microsoft Word。

### 命令

```powershell
mathfmt scan    input.docx --report candidates.json   # 扫描公式候选
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json  # 审核后转换
mathfmt convert input.docx                           # 保守一键转换
mathfmt validate input.docx                           # 离线结构验证
mathfmt doctor                                        # 环境诊断
mathfmt update                                        # 检查 GitHub 更新
```

### 更新

```powershell
mathfmt update              # 检查更新并显示安装命令
mathfmt update --check      # CI 模式：有更新时退出码 1，最新时退出码 0
mathfmt update --pre        # 包含预发布版本
mathfmt update --force      # 跳过缓存，立即检查 GitHub
```

检测结果缓存 1 小时。也可直接运行：

```powershell
pip install --upgrade mathfmt
```

### 版本路线

| 版本 | 内容 |
|---|---|
| **0.1.0** (2026-06-21) | 基础扫描、审核、转换；原生 Word 公式输出；Windows + Office |
| **0.2.0** (2026-06-21) | 跨平台内置 OMML；置信度评分；独立验证；积分/求和/矩阵/向量/分段 |
| **0.2.1** (2026-06-21) | GitHub 自更新；缓存隔离；SemVer 预发布支持 |
| **0.2.2** (2026-06-21) | CI/Ruff 修复；缓存崩溃修复；退出码修正；验证报告版本 |
| **0.3.0** (2026-Q4) | 正式语法引擎；LaTeX 输入；性能优化 |
| **1.0.0** (2027) | 稳定 API；长期支持 |

### 更多文档

- [公式语法参考](docs/formula-syntax.md) — 完整预处理规则、语法、MathML 映射和限制
- [工作流指南](docs/workflow.md) — 安装、审核流程、错误处理、CI 使用

### 维护

单人维护（Leo），尽力响应。欢迎提交 Issue 和 PR，也可通过
[gml853503962@gmail.com](mailto:gml853503962@gmail.com) 联系。安全漏洞请参阅
[SECURITY.md](SECURITY.md)。

---

## English

MathFmt converts plain-text formulas in DOCX files into native Word OMML equations.

### Quick Examples

| Input (plain text in DOCX) | Output (native Word equation) |
|---|---|
| `ds(t)/dt` | Stacked fraction d s(t) / d t |
| `s'(t) = -s''(t)` | Leibniz fraction derivatives |
| `sqrt(x^2 + 1)` | Radical √(x²+1) |
| `x^3 + p1` | Superscript x³ + subscript p₁ |
| `x != 0` | x ≠ 0 |
| `sin(x) + cos(x)` | sin(x) + cos(x) |
| `lim(p->0)` | lim with under-script p→0 |
| `a/(b+c)` | Stacked fraction |
| `e^(p1*t)` | e raised to p₁t |
| `1(t)` | u(t) (unit step) |
| `Delta + pi` | Δ + π |
| `x, y, z` | Comma-separated sequence |

### Compatibility

| | Windows 10/11 | macOS | Linux |
|---|---|---|---|
| Python 3.10–3.13 | ✔ | ✔ | ✔ |
| Formula scanning | ✔ | ✔ | ✔ |
| OMML output (built-in Python backend) | ✔ | ✔ | ✔ |
| OMML output (Office XSL backend) | ✔ | ✔¹ | ✔¹ |
| Word rendering | ✔ | ✔² | — |

¹ Manual `--xsl` path required for Office XSL backend.  
² Microsoft Word for Mac.

### Commands

```powershell
mathfmt scan    input.docx --report candidates.json   # Scan formula candidates
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json  # Apply reviewed candidates
mathfmt convert input.docx                           # Conservative one-step conversion
mathfmt validate input.docx                           # Offline structure validation
mathfmt doctor                                        # Environment check
mathfmt update                                        # Check GitHub for updates
```

### Updating

```powershell
mathfmt update              # Check for updates and show install commands
mathfmt update --check      # CI mode: exit 1 when update available, 0 when current
mathfmt update --pre        # Include pre-release versions
mathfmt update --force      # Skip cache, re-check GitHub immediately
```

Check results are cached for 1 hour. You can also upgrade directly:

```powershell
pip install --upgrade mathfmt
```

### Version Roadmap

| Version | Scope |
|---|---|
| **0.1.0** (2026-06-21) | Scan, review, convert; native Word OMML; Windows + Office |
| **0.2.0** (2026-06-21) | Cross-platform built-in OMML; confidence scoring; validate; integrals, sums, matrices |
| **0.2.1** (2026-06-21) | GitHub self-update; cache isolation; SemVer pre-release support |
| **0.2.2** (2026-06-21) | CI/Ruff fixes; cache crash fix; exit code correction; validate version |
| **0.3.0** (2026-Q4) | Formal grammar engine; LaTeX input; performance |
| **1.0.0** (2027) | Stable API; long-term support |

### Further Reading

- [Formula Syntax Reference](docs/formula-syntax.md) — every preprocessing rule, the full grammar, MathML output mapping, and known limitations
- [Workflow Guide](docs/workflow.md) — step-by-step install, review flow, troubleshooting, CI usage

### Maintenance

Single-maintainer project (Leo), best-effort response. Issues and pull requests are
welcome. You can also contact the maintainer at
[gml853503962@gmail.com](mailto:gml853503962@gmail.com). See
[CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and
[SECURITY.md](SECURITY.md).

---

## Contributing

Issues and pull requests are welcome.

## License

MIT License. Copyright (c) 2026 Leo.
