doc_processer/docs/WORD_MATHML_GUIDE.md

# MathML 导入 Word 完整指南

## MathML 简化优化 ✨

我们的 MathML 输出已经过深度优化，相比标准 Pandoc 输出更加**简洁、高效、Word 兼容**。

### 自动移除的冗余元素

✅ **结构简化**
- 移除 `<semantics>` 包装器（Word 不需要）
- 移除 `<annotation>` 元素（仅用于调试）
- 移除冗余的单层 `<mrow>` 包装

✅ **属性简化**
- 移除 `form="prefix/infix/postfix"` 属性
- 移除 `stretchy="true/false"` 属性
- 移除 `fence="true/false"` 属性
- 移除 `separator="true/false"` 属性
- 移除 `columnalign`、`columnspacing`、`rowspacing` 等表格属性
- 移除 `class` 和 `style` 属性（Word 不支持）

✅ **内容优化**
- Unicode 实体 → 实际字符（如 `&#x03B3;` → `γ`）
- `display="inline"` → `display="block"`（更好的渲染效果）
- 清理额外的空白字符

### 简化效果对比

**简化前（标准 Pandoc 输出）：**
```xml
<math display="inline" xmlns="http://www.w3.org/1998/Math/MathML">
<semantics>
<mrow>
<mi>γ</mi>
<mo form="infix">=</mo>
<mn>22</mn>
<mo form="infix">.</mo>
<mn>2</mn>
</mrow>
<annotation encoding="application/x-tex">\gamma = 22.2</annotation>
</semantics>
</math>
```
长度：~280 字符

**简化后（我们的输出）：**
```xml
<math display="block" xmlns="http://www.w3.org/1998/Math/MathML">
<mi>γ</mi><mo>=</mo><mn>22</mn><mo>.</mo><mn>2</mn>
</math>
```
长度：~120 字符

**减少约 60% 的冗余！** 🎉

---

## 问题诊断

如果 MathML 无法在 Word 中渲染，通常是以下原因：

### 1. **MathML 格式问题**（已全部修复 ✅）
- ~~包含 `<semantics>` 和 `<annotation>` 包装器~~ ✅ 已移除
- ~~使用 `display="inline"` 而不是 `display="block"`~~ ✅ 已修复
- ~~缺少 `xmlns` 命名空间~~ ✅ 自动添加
- ~~使用 HTML 实体编码而不是实际字符~~ ✅ 已解码
- ~~包含冗余属性~~ ✅ 已清理

### 2. **Word 粘贴方法不正确**
- ❌ 直接粘贴到正文
- ❌ 使用"选择性粘贴"
- ❌ 粘贴位置不对

## Word 中正确的粘贴方法

### 方法 1：使用 MathType（推荐）✨

如果你安装了 MathType：

1. 复制 MathML 内容
2. 在 Word 中：**插入** → **对象** → **MathType 公式**
3. 在 MathType 中：**编辑** → **粘贴 MathML**
4. 点击"确定"

### 方法 2：使用 Word 内置公式编辑器

#### 选项 A：Alt 文本方法（最可靠）

1. 在 Word 中：**插入** → **公式**
2. 输入任意内容（如 `x`）
3. 选中公式，右键 → **公式选项** → **另存为新公式**
4. 取消，返回文档
5. 右键公式 → **编辑替换文本**
6. 将 MathML 粘贴到替换文本框
7. 按 Enter

#### 选项 B：XML 方法（需要开发者模式）

1. **文件** → **选项** → **自定义功能区**
2. 勾选"开发工具"
3. **开发工具** → **XML 映射**
4. 粘贴 MathML

#### 选项 C：宏方法（高级）

使用 VBA 宏：

```vba
Sub InsertMathML()
    Dim mathML As String
    mathML = "<math>...</math>" ' 粘贴你的 MathML
    
    Selection.Range.InsertXML mathML
End Sub
```

### 方法 3：使用在线工具转换

1. 访问 https://www.mathcha.io/
2. 粘贴 MathML
3. 导出为 Word 格式

## 测试你的 MathML

运行诊断工具：

```bash
python test_mathml_word_compatibility.py
```

这会检查：
- ✓ 命名空间是否正确
- ✓ Display 属性
- ✓ 是否有 semantics 包装器
- ✓ Unicode 实体

## 示例：正确的 MathML 格式

```xml
<math display="block" xmlns="http://www.w3.org/1998/Math/MathML">
  <mrow>
    <mi>γ</mi>
    <mo>=</mo>
    <mn>22.2</mn>
    <mo>,</mo>
    <mi>c</mi>
    <mo>=</mo>
    <mn>30.4</mn>
  </mrow>
</math>
```

**不要有：**
```xml
<math>
  <semantics>    ❌ Word 可能不识别
    <mrow>...</mrow>
    <annotation>...</annotation>    ❌ Word 不需要
  </semantics>
</math>
```

## API 使用

### 获取 Word 兼容的 MathML

```bash
curl -X POST "http://localhost:8000/api/v1/image/ocr" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "...",
    "model_name": "mineru"
  }'
```

响应中的 `mathml` 字段已经过优化，可以直接用于 Word。

### 如果还是不工作

1. **检查 Word 版本**
   - Word 2010+ 支持 MathML
   - Word Online 支持有限

2. **检查 MathML 内容**
   ```bash
   python test_mathml_word_compatibility.py
   ```

3. **尝试 OMML 格式（Word 原生）**
   ```bash
   curl -X POST "http://localhost:8000/api/v1/convert/latex-to-omml" \
     -H "Content-Type: application/json" \
     -d '{"latex": "\\gamma = 22.2"}'
   ```
   
   OMML 是 Word 的原生格式，兼容性最好。

## 为什么 OMML 更好？

| 格式 | 用途 | Word 兼容性 |
|------|------|------------|
| **MathML** | Web 标准、跨平台 | ⭐⭐⭐ 需要转换 |
| **OMML** | Word 原生格式 | ⭐⭐⭐⭐⭐ 完美 |

**建议**：
- 手动粘贴 → 使用 MathML
- 编程生成 Word 文档 → 使用 OMML

## 常见错误

### 错误 1：粘贴后显示为文本

**原因**：粘贴位置不对或格式不对

**解决**：
1. 确保 MathML 以 `<math` 开头
2. 使用 Alt 文本方法
3. 或使用 OMML 接口

### 错误 2：显示为方框

**原因**：Word 无法解析 MathML 结构

**解决**：
1. 检查是否有 `<semantics>` 包装器（我们已移除）
2. 使用 OMML 格式

### 错误 3：部分显示不正确

**原因**：某些 LaTeX 命令不支持

**解决**：
1. 检查 LaTeX 语法
2. 使用 Word 支持的标准命令

## 最终建议

**最简单的方法**：使用 OMML 格式

```bash
# 1. 获取 LaTeX
POST /api/v1/image/ocr
→ 获取 "latex" 字段

# 2. 转换为 OMML
POST /api/v1/convert/latex-to-omml
→ 获取 "omml" 字段

# 3. 使用 python-docx 或 Office.js 插入
```

这样可以避免所有 MathML 兼容性问题！