feat: 导出 SproutClaw .sproutclaw 配置
包含 extensions、skills、prompts、settings、auth、models、mcp 等配置。 排除 node_modules、npm 缓存、sessions 等运行时数据。
This commit is contained in:
@@ -0,0 +1,502 @@
|
||||
---
|
||||
name: software-copyright-materials
|
||||
description: >
|
||||
Generate guided Chinese software copyright application materials from a real project.
|
||||
Use this skill when the user asks for 软件著作权, 软著申请资料, 软著代码材料,
|
||||
操作手册, 申请表信息, or wants Word/TXT materials for software copyright registration.
|
||||
The workflow analyzes the imported project, extracts real source code, creates Markdown
|
||||
drafts for user confirmation, then uses bundled DOCX tooling to produce final
|
||||
Word documents and TXT.
|
||||
user-invocable: true
|
||||
compatibility: >
|
||||
Requires Python 3.10+ with python-docx (pip install python-docx).
|
||||
Optional: .NET SDK 8.0+ for full OpenXML DOCX validation (run vendor/docx-toolkit/scripts/setup.sh).
|
||||
allowed-tools: >
|
||||
Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch
|
||||
metadata:
|
||||
short-description: 生成软著申请资料 Word/TXT
|
||||
author: Fokkyp
|
||||
version: "1.1"
|
||||
repository: https://github.com/Fokkyp/SoftwareCopyright-Skill
|
||||
---
|
||||
|
||||
# 软著申请资料生成
|
||||
|
||||
这个 skill 生成可审阅、可追溯的软著申请资料。核心原则：
|
||||
|
||||
- 固定输出目录：当前工作目录下的 `软件著作权申请资料/`。不要默认写到 `/tmp`、`/private/tmp` 或其他临时目录。
|
||||
- 只有测试 skill 自身时才允许显式指定临时目录；面向用户生成材料时必须写入当前目录。
|
||||
- 先生成 Markdown 草稿，用户确认后再生成正式 Word/TXT。
|
||||
- 正式 Word/TXT 只能写入 `软件著作权申请资料/正式资料/`，不要散落在输出目录根部。
|
||||
- 正式 Word/TXT 的文字一律使用默认黑色字体，不生成蓝色超链接、主题色标题或其他彩色文字；Markdown 链接写入 Word 时必须转成普通文本。
|
||||
- 正式资料中的软件名称必须与 `草稿/申请表信息.md` 的“软件全称”字段一致；正式生成时以已确认的申请表软件全称为准。
|
||||
- 正式代码 Word 页眉中的版本号必须与 `草稿/申请表信息.md` 的“版本号”字段一致；正式生成时以已确认的申请表版本号为准。
|
||||
- 代码材料必须来自真实项目源码，禁止 AI 编造代码。
|
||||
- 写申请表和操作手册前，必须先形成模型研判后的 `草稿/业务理解.md/json`，理解软件业务、行业、目标用户、核心价值和操作流程。
|
||||
- 脚本只能收集项目证据、校验字段和生成文件；行业判断、功能抽取、代码抽取选择、操作手册结构必须由模型阅读项目后决定，不得依赖脚本关键字表或固定范本。
|
||||
- 优先抽取前端代码：入口、路由、页面、核心组件、接口封装、状态管理、工具函数。
|
||||
- 生成代码材料前，必须先生成代码文件候选清单；模型理解项目后填写抽取文件和选择理由，再让用户确认或修改。
|
||||
- 代码优先抽取模型和用户确认的、最能体现软件真实功能和运行逻辑的源码；不足 60 页时，从其他相关源码文件补充到 60 页；候选源码仍不足 60 页时，才生成全部代码文档。
|
||||
- 操作手册成稿应像真实软件随附的操作说明，而不是研发说明、功能清单或 AI 生成的汇总文。
|
||||
- 操作手册草稿必须按传统软著操作手册骨架组织：相关文档、说明、功能特点、系统要求、按真实页面/流程逐章操作、常见问题解答、术语表。一级章节标题使用中文大写序号，例如 `一、相关文档`，不得使用 `(1)、相关文档`。相关文档必须用表格指向总体设计、详细设计、测试案例等配套文档。正文尽量使用连续段落，不使用项目符号列表或 `1. 2. 3.` 编号列表。
|
||||
- 每个核心页面都要用普通用户视角说明页面用途、进入位置、用户可见内容、用户动作、输入限制或异常提示、结果反馈和截图预留。不得把章节写成“进入方式：/页面内容：/操作步骤：/操作规则：/操作结果与反馈：”这种字段模板；这些信息要自然合并到段落里。避免代码、框架、接口、状态管理、异步任务等技术化表达；撰写过程中由 agent 自行循环检查、扩写和修正，完整草稿完成后只向用户发起一次整体确认。
|
||||
- 操作手册必须去除明显“AI 味”：避免空泛赞美、营销口号、万能句式、每章同一结构、头中尾固定结构、过度对称的排比、没有项目细节的正确废话、频繁使用“旨在、赋能、一站式、智能化、高效便捷、显著提升、强大能力、丰富功能”等套话。每段都应能回答“这个项目里这个功能具体做什么、用户看见什么、操作后有什么结果”。
|
||||
- 操作手册生成必须同步输出 `草稿/操作手册自检记录.md` 和 `草稿/操作手册自检记录.json`，记录初稿、按项目流程扩写、去制式表达等自检轮次；如果前 3 轮仍发现问题，必须继续补写修正，直到问题清零或记录无法自动修复的原因后再停止。
|
||||
- 截图方式必须先让用户选择：Chrome DevTools MCP、Codex Computer Use、用户自行截图。用户选完后，再检查当前 MCP / Computer Use 能力是否可用；如果用户说现在不截图、先跳过截图或截图失败，操作手册仍必须保留清晰可见的截图预留位置，正式 Word 中也要能看到。
|
||||
- 申请表信息中的硬件/系统环境必须让用户确认或填写，不能硬编码。
|
||||
- Word 生成能力必须使用本 skill 内置的 `vendor/docx-toolkit`；不得引用外部 DOCX 目录。
|
||||
|
||||
## 强制人工门禁
|
||||
|
||||
凡是涉及用户选择、确认或补充信息的阶段，必须先停止当前执行，不得继续调用下一步脚本。即使处于自动审核、自动继续或无人值守模式，也必须把 `STOP_FOR_USER` 和 `NEXT_ACTION` 原样告知用户，并等待用户输入后再继续。
|
||||
|
||||
禁止使用“用户未选择则默认继续”的逻辑。用户回复确认后，先用确认脚本记录对应门禁，再进入下一阶段：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py --workdir 软件著作权申请资料 --stage <阶段名> --note "<用户确认内容>"
|
||||
```
|
||||
|
||||
必须停住的门禁：
|
||||
|
||||
- `environment`：完整 DOCX 环境缺失时，用户必须选择“安装完整环境”或“使用基础 DOCX 兜底继续”。
|
||||
- `project`：存在多个项目候选目录时，用户必须指定项目目录。
|
||||
- `business`：`草稿/业务理解.md` 生成后，用户必须确认行业、目标用户、核心功能和申请口径。
|
||||
- `application-fields`：`草稿/申请表信息.md` 生成后，用户必须补全并确认硬件、系统环境、著作权人、日期等字段。
|
||||
- `code-selection`：`草稿/代码文件选择.json` 生成后，用户必须确认或修改抽取文件。
|
||||
- `screenshot-method`：操作手册截图前，用户必须在 Chrome DevTools MCP、Codex Computer Use、用户自行截图三种方式中选择一种；如果用户明确说“现在不截图/先跳过截图”，记录为 `skip`。
|
||||
- `markdown`：全部 Markdown 草稿完成后，用户必须确认可以进入 Word/TXT 生成。
|
||||
|
||||
## 工作流
|
||||
|
||||
### 1. 启动环境检查
|
||||
|
||||
一开始先在当前工作目录创建输出目录并检查运行能力：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/check_environment.py \
|
||||
--out-dir 软件著作权申请资料
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
- `软件著作权申请资料/环境检查.md`
|
||||
- `软件著作权申请资料/环境检查.json`
|
||||
|
||||
环境检查必须告诉用户：
|
||||
|
||||
- 当前会在“当前目录/软件著作权申请资料”下生成材料。
|
||||
- Markdown 草稿、TXT、基础 DOCX 是否可用。
|
||||
- 内置 `vendor/docx-toolkit` 的完整 OpenXML 环境是否可用。
|
||||
- 如 `.NET SDK` 缺失，询问用户是否安装完整环境。
|
||||
|
||||
用户选择：
|
||||
|
||||
- 如果用户愿意安装完整环境，按 `${CLAUDE_SKILL_DIR}/vendor/docx-toolkit/scripts/setup.sh` 的要求安装依赖，再继续。完整环境生成和校验更规范。
|
||||
- 如果用户不安装，继续使用兜底方案生成 Markdown、TXT 和基础 DOCX。
|
||||
- 如果完整 DOCX 环境缺失，必须停止并等待用户选择；不得自动继续。
|
||||
|
||||
用户回复后记录门禁：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage environment \
|
||||
--note "<用户选择>"
|
||||
```
|
||||
|
||||
不要等到最后验证阶段才发现完整 DOCX 环境不可用；这个信息必须在流程开始时给出。
|
||||
|
||||
### 2. 定位项目
|
||||
|
||||
用户通常会把项目放在当前文件夹下。先扫描当前目录，避开本 skill、自身输出目录、`node_modules`、构建产物和隐藏目录，找到最可能的项目根目录。
|
||||
|
||||
如果有多个候选项目，必须停止并询问用户选择；如果只有一个明显候选项目，可以直接使用。
|
||||
|
||||
### 3. 分析项目
|
||||
|
||||
运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/analyze_project.py \
|
||||
--project <项目目录> \
|
||||
--out 软件著作权申请资料/analysis/project.json
|
||||
```
|
||||
|
||||
分析内容包括：
|
||||
|
||||
- `package.json`、README、脚本命令、依赖
|
||||
- 前端框架和主要编程语言
|
||||
- 入口文件、路由、页面、组件、接口、状态管理
|
||||
- 源码文件数量和源程序行数
|
||||
- 软件名称候选、主要功能候选、运行命令候选
|
||||
|
||||
### 4. 形成业务理解
|
||||
|
||||
在写申请表和操作手册前，先让脚本收集项目证据：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_business_context.py \
|
||||
--project <项目目录> \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--software-name "<软件全称>" \
|
||||
--out-dir 软件著作权申请资料/草稿
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
- `草稿/业务理解证据.md`
|
||||
- `草稿/业务理解证据.json`
|
||||
- `草稿/业务理解模型稿模板.json`
|
||||
|
||||
这一步只收集证据，不决定最终业务口径。接下来必须由模型阅读 `业务理解证据.md/json`、README、PRD/BRD、页面文案、路由、接口、必要源码和用户补充资料，自行判断：
|
||||
|
||||
- 应该重点读取哪些文档和源码
|
||||
- 软件属于什么行业 / 领域
|
||||
- 目标用户是谁
|
||||
- 核心价值是什么
|
||||
- 哪些功能应写入软著申请资料
|
||||
- 典型操作流程如何组织
|
||||
- 操作手册适合采用什么章节结构
|
||||
- 申请表建议口径如何表达
|
||||
|
||||
模型不得用脚本关键字表决定行业、功能和结构；不得把用户给的范本文案、测试项目名称、测试项目流程写成通用规则。
|
||||
|
||||
模型完成研判后，生成一个业务理解模型稿 JSON，字段至少包含：
|
||||
|
||||
- `product_positioning`
|
||||
- `industry`
|
||||
- `target_users`
|
||||
- `core_value`
|
||||
- `business_features`
|
||||
- `business_feature_details`
|
||||
- `operation_flow`
|
||||
- `application_purpose`
|
||||
- `main_functions`
|
||||
- `technical_characteristics`
|
||||
- `manual_sections`
|
||||
- `manual_modules`
|
||||
- `system_requirements`
|
||||
- `faq`
|
||||
- `glossary`
|
||||
|
||||
其中 `manual_modules` 是操作手册的核心输入，必须按真实页面、导航入口或业务流程填写。脚本不得按 `auth/query/form` 等分类模板自动补入口、步骤或反馈；缺少 `manual_modules` 或关键字段时必须停止让模型回到项目证据中补写。每个模块必须包含：
|
||||
|
||||
- `title`：页面或流程名称。
|
||||
- `evidence`：对应页面、路由、组件、需求文档或 README 证据。
|
||||
- `purpose`：该页面在软件中的用途。
|
||||
- `usage` 或 `usage_scenario`：用户在什么业务场景下会使用该页面，正在处理什么具体事务。缺少时不得生成操作手册。
|
||||
- `entry`：用户从哪里进入该页面。
|
||||
- `visible_elements`：用户实际能看到的输入框、按钮、列表、标签、状态或结果区域。
|
||||
- `operation_steps`：按真实页面顺序写用户动作，不能写代码实现。
|
||||
- `validation_rules`：必填项、长度限制、权限、额度、状态、异常提示等规则；没有则留空数组。
|
||||
- `feedback`：操作完成后用户能看到的结果、提示或状态变化。
|
||||
- `screenshot`：截图预留说明。
|
||||
|
||||
`manual_sections` 只允许补充当前软件本身的用途、业务场景、页面组织或用户流程，不要写“本操作手册用于……”“面向软著审核……”“不描述代码实现……”这类解释文档写作方式的元话语。最终操作手册应像真实软件说明书，而不是生成过程说明。
|
||||
|
||||
然后运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_business_context.py \
|
||||
--project <项目目录> \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--software-name "<软件全称>" \
|
||||
--out-dir 软件著作权申请资料/草稿 \
|
||||
--model-context <模型生成的业务理解JSON>
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
- `草稿/业务理解.md`
|
||||
- `草稿/业务理解.json`
|
||||
|
||||
最终业务理解必须覆盖：
|
||||
|
||||
- 产品定位
|
||||
- 面向领域 / 行业
|
||||
- 目标用户
|
||||
- 核心价值
|
||||
- 主要业务功能
|
||||
- 典型操作流程
|
||||
- 申请表建议口径
|
||||
- 证据来源
|
||||
- 操作手册结构建议
|
||||
|
||||
如果项目材料不足、业务类型较新，或用户明确希望参考竞品，可联网搜索相近产品和行业资料；外部调研只用于理解行业表达，不能编造项目不存在的功能。调研摘要应写入业务理解草稿，并区分“项目证据”和“行业参考”。
|
||||
|
||||
生成 `业务理解.md/json` 后必须停止，等待用户确认或修改。业务理解确认前，不得生成申请表和操作手册。如果业务理解仍不充分，先请用户补充产品说明。用户确认后运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage business \
|
||||
--note "<用户确认内容>"
|
||||
```
|
||||
|
||||
### 5. 引导用户确认字段
|
||||
|
||||
根据分析结果，向用户确认以下字段（按官网实际表单顺序）：
|
||||
|
||||
- 软件全称
|
||||
- 软件简称（可选）
|
||||
- 版本号
|
||||
- 软件分类（应用软件/嵌入式软件/中间件/系统软件/其他）
|
||||
- 开发完成日期（YYYY-MM-DD 格式）
|
||||
- 开发方式（单独开发/合作开发/委托开发/下达任务开发）
|
||||
- 软件说明（原创 / 修改（含翻译软件、合成软件））
|
||||
- 发表状态（已发表/未发表）
|
||||
- 首次发表日期（已发表时填写，YYYY-MM-DD 格式；未发表则留空）
|
||||
- 著作权人（复合字段：国家/省市/类型[自然人/法人]/姓名/证件类型/证件号）
|
||||
- 权利范围（全部权利/部分权利）
|
||||
- 权利取得方式（原始取得/继受取得）
|
||||
- 开发的硬件环境（≤50字符）
|
||||
- 运行的硬件环境（≤50字符）
|
||||
- 开发该软件的操作系统（≤50字符）
|
||||
- 软件开发环境 / 开发工具（≤50字符，格式：开发环境: xxx/开发工具: xxx）
|
||||
- 该软件的运行平台 / 操作系统（≤50字符）
|
||||
- 软件运行支撑环境 / 支持软件（≤50字符）
|
||||
- 编程语言（预设按钮选择 + 自定义输入≤120字符）
|
||||
- 源程序量（纯数字，单位为行，指全部源程序总行数）
|
||||
- 开发目的（≤50字符）
|
||||
- 面向领域 / 行业（≤50字符）
|
||||
- 软件的主要功能（500~1300字符）
|
||||
- 软件的技术特点（多选标签 + 文本描述≤100字符；标签：APP/游戏软件/教育软件/金融软件/医疗软件/地理信息软件/云计算软件/信息安全软件/大数据软件/人工智能软件/VR软件/5G软件/小程序/物联网软件/智慧城市软件，都不符合时可不选）
|
||||
- 页数（代码鉴别材料实际页数）
|
||||
|
||||
项目可推断字段可以先给建议值；硬件/系统环境必须允许用户选择建议值或手动填写。字段口径必须区分清楚：
|
||||
|
||||
- 软件全称：必须由用户确认。最终正式资料文件名、代码 Word 页眉、操作手册标题和正文中的软件名称，都必须与 `申请表信息.md` 的"软件全称"字段一致。
|
||||
- 软件简称：可选字段，如有常用简称则填写。
|
||||
- 版本号：必须由用户确认。优先读取项目配置中的版本号作为证据；如果项目版本号小于 V1.0（例如 V0.1.0、V0.9.0），必须明确询问用户"软著首次提交通常写 V1.0，本次填写 V1.0 还是项目当前版本号"。最终 `申请表信息.md` 的"版本号"字段就是正式资料版本号。
|
||||
- 软件分类：应用软件/嵌入式软件/中间件/系统软件/其他，默认为应用软件。
|
||||
- 开发完成日期、首次发表日期：必须使用 YYYY-MM-DD 格式。
|
||||
- 开发方式：单独开发/合作开发/委托开发/下达任务开发，默认单独开发。
|
||||
- 软件说明：原创 / 修改（含翻译软件、合成软件），默认原创。
|
||||
- 发表状态：已发表或未发表；已发表需附首次发表日期，未发表则首次发表日期留空。
|
||||
- 软件开发环境 / 开发工具：≤50字符，格式为 `开发环境: <操作系统>/开发工具: <IDE名称>`，例如 `开发环境: Windows 11/开发工具: Visual Studio Code`；不要把 React、Next.js、Vite、TypeScript 等技术栈写到此字段。
|
||||
- 开发该软件的操作系统：≤50字符，填写实际开发电脑的操作系统版本，例如 Windows 10、Windows 11、macOS 14、macOS 15。
|
||||
- 该软件的运行平台 / 操作系统：≤50字符，填写软件运行所在的操作系统或浏览器环境。
|
||||
- 软件运行支撑环境 / 支持软件：≤50字符，直接列出运行依赖（如 Node.js、npm、浏览器），不加格式前缀。
|
||||
- 开发的硬件环境：≤50字符，优先读取当前电脑 CPU、内存、硬盘配置作为建议值；读取不到时让用户填写。
|
||||
- 运行的硬件环境：≤50字符，默认可沿用开发硬件环境建议值，也可以按实际部署或运行设备修改。
|
||||
- 源程序量：纯数字（不含"行"字），指登记软件全部源程序的总行数。
|
||||
- 开发目的：≤50字符，用一句话说明软件开发目的，不能只写软件名称。
|
||||
- 面向领域 / 行业：≤50字符。
|
||||
- 软件的主要功能：500~1300字符，详细描述软件核心功能。
|
||||
- 软件的技术特点：多选标签（APP/游戏软件/教育软件等）+ 文本描述≤100字符，简述技术架构和关键技术；标签都不符合时可不选。
|
||||
|
||||
此阶段需要先停止等待用户输入；收到用户回复后，可整理为 `answers` JSON 传入申请表草稿生成。申请表字段的最终门禁在 `草稿/申请表信息.md` 生成后记录。
|
||||
|
||||
### 6. 确认代码文件选择
|
||||
|
||||
生成代码材料前，先运行候选文件分析：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/propose_code_selection.py \
|
||||
--project <项目目录> \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--out-dir 软件著作权申请资料/草稿
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
- `草稿/代码文件候选清单.md`：给用户看的候选说明。
|
||||
- `草稿/代码文件选择.json`：可编辑的选择文件。
|
||||
|
||||
脚本生成的候选清单只列证据，不默认选择文件。模型必须先阅读业务理解、候选文件、入口文件、页面文件和必要源码，判断哪些源码最能体现软件真实功能和运行逻辑，然后修改 `代码文件选择.json`：
|
||||
|
||||
- `selected: true` 表示抽取该文件。
|
||||
- `selected: false` 表示不抽取该文件。
|
||||
- `model_reason` 必须说明为什么选择该文件。
|
||||
|
||||
模型选择通常优先考虑前端入口、页面、核心组件、业务交互、数据请求、状态处理等能给审核员看懂软件功能的代码；如果相关前端代码不足 60 页，再补充后端服务、业务处理等相关源码。补充文件同样必须写入 `代码文件选择.json` 并由用户确认。不要默认抽取全量代码库。代码材料按完整文件原样复制，不支持只抽取某个文件的中间行段。用户确认并记录 `code-selection` 门禁后，代码抽取只读取 `代码文件选择.json` 中选中的完整文件。用户确认后运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage code-selection \
|
||||
--note "<用户确认内容>"
|
||||
```
|
||||
|
||||
### 7. 生成 Markdown 草稿
|
||||
|
||||
运行代码材料抽取：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/extract_code_material.py \
|
||||
--project <项目目录> \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--selection 软件著作权申请资料/草稿/代码文件选择.json \
|
||||
--software-name "<软件全称>" \
|
||||
--version "<版本号>" \
|
||||
--out-dir 软件著作权申请资料/草稿
|
||||
```
|
||||
|
||||
代码分页规则：
|
||||
|
||||
- 每页默认 50 行，并在 Word 中使用紧凑固定行距，尽量减少长行折行造成的页面溢出。
|
||||
- 总页数 `>= 60`：生成 `代码-前30页.md` 和 `代码-后30页.md`。
|
||||
- 总页数 `< 60` 且候选源码已用尽：只生成 `代码-全部.md`。
|
||||
- 总页数 `< 60` 但候选清单还有可补充源码：停止并要求用户在 `代码文件选择.json` 中继续选择补充文件。
|
||||
- 不为大项目生成超大“全量备份 Word”。
|
||||
- 同时生成 `代码提取清单.md` 和 `代码提取清单.json`，用于追溯代码来源。
|
||||
|
||||
生成申请表信息草稿：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_application_info.py \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--code-manifest 软件著作权申请资料/草稿/代码提取清单.json \
|
||||
--business-context 软件著作权申请资料/草稿/业务理解.json \
|
||||
--software-name "<软件全称>" \
|
||||
--version "<版本号>" \
|
||||
--out-dir 软件著作权申请资料/草稿
|
||||
```
|
||||
|
||||
生成后必须停止，让用户检查并补全 `草稿/申请表信息.md`。字段补全并确认后运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage application-fields \
|
||||
--note "<用户确认内容>"
|
||||
```
|
||||
|
||||
生成操作手册草稿：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_manual_draft.py \
|
||||
--analysis 软件著作权申请资料/analysis/project.json \
|
||||
--business-context 软件著作权申请资料/草稿/业务理解.json \
|
||||
--software-name "<软件全称>" \
|
||||
--version "<版本号>" \
|
||||
--out-dir 软件著作权申请资料/草稿
|
||||
```
|
||||
|
||||
操作手册草稿不得照抄用户提供的范本文案或旧项目内容，但应吸收其结构特点：先写相关文档、说明、功能特点和系统要求，再按真实页面或核心流程逐章说明操作，最后写常见问题解答和术语表。一级章节标题使用中文大写序号；相关文档章节必须是表格；功能特点和页面操作章节必须以段落展开，不用项目符号和编号列表堆信息。必须基于模型写入 `草稿/业务理解.json` 的 `manual_modules` 组织章节；`manual_sections` 只用于补充说明性段落，不应用来反复插入同一批功能模块。各功能章节必须写清页面用途、进入位置、用户看到的控件和数据、实际操作、输入限制或异常提示、操作结果和截图预留。语言要面向普通用户，说明“这个页面是干嘛的、用户怎么进入、用户点什么/填什么、操作后看到什么”，不要写代码实现、框架名称、接口封装、状态管理、异步队列等技术细节。撰写时由 agent 自行检查章节是否完整、内容是否过薄、语言是否过于技术化，并在草稿内部完成必要补写；完整草稿完成后只让用户做一次整体确认，确认前不得进入正式 Word/TXT 生成。
|
||||
|
||||
生成脚本必须同时写出 `草稿/操作手册自检记录.md` 和 `草稿/操作手册自检记录.json`。自检记录至少包含：
|
||||
|
||||
- 第 1 轮：初稿生成，检查章节完整性、截图预留、模块内容厚度和技术化表达。
|
||||
- 第 2 轮：按项目真实运行流程扩写模块说明，补足上下游衔接关系。
|
||||
- 第 3 轮：去除制式表达和 AI 味，重点检查重复句式、统一套话、空泛赞美、营销口号、过度整齐的排比和没有项目细节的正确废话。
|
||||
- 后续轮次：如果仍有问题，继续补写、去重、改写，不能把未修正的问题直接交给用户。
|
||||
|
||||
操作手册的模块写作必须从 `草稿/业务理解.json` 的行业、目标用户、核心价值、业务功能、典型操作流程和 `manual_modules` 出发。不同模块要写出各自的业务作用、入口、控件、规则和反馈，不能统一套用“进入页面、填写内容、提交按钮、查看结果”的固定句式，也不能使用“进入方式：/页面内容：/操作步骤：/操作规则：/操作结果与反馈：”这类字段标题；相近模块也要结合项目真实业务区分各自的操作目的和结果。自检时必须检查是否把同一批模块在多个章节中重复展开；如发现重复，改为每个真实页面或流程独立成章。不得把测试项目的功能名称、业务流程或示例文案写成通用规则。
|
||||
|
||||
### 8. 选择并获取截图
|
||||
|
||||
操作手册草稿完成后，先停止并让用户选择截图方式，必须给出三种选项：
|
||||
|
||||
1. Chrome DevTools MCP：适合已在浏览器中打开的 Web 项目，优先用于网页全页截图。
|
||||
2. Codex Computer Use：适合需要通过桌面应用或浏览器界面点击、切换、查看状态后截图的场景。
|
||||
3. 用户自行截图：用户自己把 PNG/JPG/JPEG/WebP 图片放入 `软件著作权申请资料/用户截图/`，agent 只负责整理和引用。
|
||||
|
||||
如果用户明确说“现在不截图”“先跳过截图”“这次不截图”，也必须记录截图方式门禁，方法填 `skip`。跳过截图不阻塞正式资料生成，但操作手册中每个核心功能模块必须保留可见的截图预留文字，例如：`【截图预留：请在此处插入“项目管理”页面或操作结果截图。】`。不要使用 HTML 注释作为截图占位，因为正式 Word 中看不到。
|
||||
|
||||
用户选择后，先记录门禁：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage screenshot-method \
|
||||
--method <chrome-devtools|computer-use|user-supplied|skip> \
|
||||
--note "<用户选择>"
|
||||
```
|
||||
|
||||
然后按用户选择检查当前能力并执行：
|
||||
|
||||
- 选择 Chrome DevTools MCP：先用工具发现能力检查当前环境是否有 `mcp__chrome_devtools__` 的 `list_pages`、`take_snapshot`、`take_screenshot`。可用时，先 `list_pages` 确认当前浏览器页面，再按页面/路由截图保存到 `软件著作权申请资料/截图/`；不可用时停止，告知用户需要重新选择截图方式或手动提供截图。
|
||||
- 选择 Codex Computer Use：先用工具发现能力检查当前环境是否有 `mcp__computer_use__` 的 `get_app_state`、`click`、`press_key`。可用时，先 `get_app_state` 查看目标应用或浏览器当前状态，再按操作手册需要导航和截图；如果当前 Computer Use 只能返回会话内截图而不能直接保存图片文件，则说明限制，并让用户改选 Chrome DevTools MCP 或把截图放入 `用户截图/`。
|
||||
- 选择用户自行截图：创建 `软件著作权申请资料/用户截图/`，提示用户把截图文件放入该目录；用户放入后运行下面的整理命令，把图片复制到 `软件著作权申请资料/截图/` 并生成 `截图清单.json`。
|
||||
- 选择跳过截图：不运行截图工具，继续保留操作手册中的可见截图预留文字；在生成报告中说明用户选择暂不截图，正式操作手册已预留截图位置。
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/capture_screenshots.py \
|
||||
--manual-dir 软件著作权申请资料/用户截图 \
|
||||
--out-dir 软件著作权申请资料/截图
|
||||
```
|
||||
|
||||
截图成功后，把截图引用补入 `草稿/操作手册.md`；截图失败或用户选择暂不提供截图时，继续生成带截图预留位的文字版，并在报告中说明“操作手册截图未生成或未插入，已保留截图预留位置”。
|
||||
|
||||
### 9. 用户确认 Markdown
|
||||
|
||||
生成 Word 前，必须让用户确认 `软件著作权申请资料/草稿/` 下的 Markdown。
|
||||
|
||||
重点检查：
|
||||
|
||||
- 软件名称和版本号是否一致
|
||||
- 代码材料前30页、后30页页眉软件名称是否与 `申请表信息.md` 的“软件全称”一致
|
||||
- 代码材料前30页、后30页页眉版本号是否与 `申请表信息.md` 的“版本号”一致
|
||||
- 操作手册 Word 页眉是否与代码材料页眉一致，均使用 `申请表信息.md` 的“软件全称”和“版本号”
|
||||
- `业务理解.md` 是否准确反映软件真实业务、行业和目标用户
|
||||
- `申请表信息.md` 中“待用户确认”的字段是否已确认
|
||||
- 代码材料是否只来自用户确认的完整文件
|
||||
- 操作手册是否符合审核员阅读场景，普通读者是否能看懂模块用途和操作方式
|
||||
- 操作手册每个章节是否有段落内容，核心模块是否写清模块用途、操作过程和结果反馈，是否避免过度技术化语言
|
||||
- 截图是否正确；若用户跳过截图，正式操作手册是否保留可见截图预留位置
|
||||
|
||||
用户确认后，必须记录 `markdown` 门禁；未记录时不得生成正式 Word/TXT。
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/confirm_stage.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--stage markdown \
|
||||
--note "<用户确认内容>"
|
||||
```
|
||||
|
||||
### 10. 生成正式 Word/TXT
|
||||
|
||||
用户确认后运行：
|
||||
|
||||
```bash
|
||||
python3 ${CLAUDE_SKILL_DIR}/scripts/build_docx_from_md.py \
|
||||
--workdir 软件著作权申请资料 \
|
||||
--software-name "<软件全称>" \
|
||||
--version "<版本号>"
|
||||
```
|
||||
|
||||
正式生成脚本必须重新读取 `草稿/申请表信息.md` 中已确认的“软件全称”和“版本号”，并用它们生成正式资料文件名、代码 Word 页眉和操作手册 Word 页眉。操作手册页眉必须与代码材料页眉格式一致：左侧为“软件全称 版本号”，右侧为“第 <页码> 页”。若命令参数 `--software-name` / `--version` 与申请表字段不同，以申请表字段为准，并在 `正式资料/生成报告.md` 中记录提示。
|
||||
|
||||
输出：
|
||||
|
||||
- `正式资料/申请表信息.txt`
|
||||
- 代码达到或超过 60 页：
|
||||
- `正式资料/<软件全称>-代码(前30页).docx`
|
||||
- `正式资料/<软件全称>-代码(后30页).docx`
|
||||
- 代码不足 60 页：
|
||||
- `正式资料/<软件全称>-代码(全部).docx`
|
||||
- `正式资料/<软件全称>_操作手册.docx`
|
||||
- `正式资料/生成报告.md`
|
||||
|
||||
### 11. 三轮验证
|
||||
|
||||
至少执行三轮验证并修复发现的问题：
|
||||
|
||||
1. 文件完整性：目标 Word/TXT 是否存在且非空。
|
||||
2. 代码真实性：抽样检查代码片段能回溯到项目源码。
|
||||
3. 业务真实性：申请表和操作手册中的行业、目标用户、主要功能、操作流程能回溯到 `业务理解.md` 和项目文档。
|
||||
4. 一致性和格式：软件名称、版本号、页数规则、申请表字段、操作手册标题和截图引用是否一致。
|
||||
|
||||
可用命令：
|
||||
|
||||
```bash
|
||||
python3 -m py_compile ${CLAUDE_SKILL_DIR}/scripts/*.py
|
||||
bash ${CLAUDE_SKILL_DIR}/vendor/docx-toolkit/scripts/docx_preview.sh <生成的docx>
|
||||
```
|
||||
|
||||
完整 DOCX 环境检查和安装必须直接恢复/构建 `${CLAUDE_SKILL_DIR}/vendor/docx-toolkit/scripts/dotnet/DocxToolkit.Cli/DocxToolkit.Cli.csproj`，不要对 `vendor/docx-toolkit/scripts/dotnet` 目录或 `.slnx` 文件执行隐式 restore/build。
|
||||
|
||||
如果 `环境检查.md` 或 `${CLAUDE_SKILL_DIR}/vendor/docx-toolkit/scripts/env_check.sh` 显示 `.NET SDK` 缺失，说明完整 DOCX OpenXML 校验环境未就绪。用户明确选择不安装并记录 `environment` 门禁后，继续生成 Markdown、TXT 和基础 DOCX，并在报告中说明当前使用兜底路径。
|
||||
|
||||
## 何时询问用户
|
||||
|
||||
以下场景必须询问并停止，等待用户输入后再继续：
|
||||
|
||||
- 多个项目候选目录需要选择。
|
||||
- 启动环境检查发现完整 DOCX 环境缺失时，询问用户是否安装完整环境。
|
||||
- 业务理解草稿生成后，请用户确认软件用途、行业、目标用户、核心功能和申请口径。
|
||||
- 软件全称、著作权人、日期、硬件/系统环境等登记字段需要确认。
|
||||
- 代码文件候选清单生成后，需要用户确认或修改 `代码文件选择.json`。
|
||||
- 操作手册截图前，需要用户在 Chrome DevTools MCP、Codex Computer Use、用户自行截图三种方式中选择一种；选择后再检查对应工具是否可用。
|
||||
- 用户是否确认 Markdown 草稿并进入 Word 生成。
|
||||
@@ -0,0 +1,3 @@
|
||||
display_name: 软著申请资料生成
|
||||
short_description: 从真实项目生成软著申请 Word 和 TXT 材料
|
||||
default_prompt: 读取当前目录中的项目，生成软件著作权申请资料草稿，确认后输出 Word 和 TXT。
|
||||
@@ -0,0 +1,61 @@
|
||||
# 申请表信息字段
|
||||
|
||||
按官网实际表单顺序和字段名：
|
||||
|
||||
1. 软件全称
|
||||
2. 软件简称（可选）
|
||||
3. 版本号
|
||||
4. 软件分类（应用软件/嵌入式软件/中间件/系统软件/其他）
|
||||
5. 开发完成日期（YYYY-MM-DD）
|
||||
6. 开发方式（单独开发/合作开发/委托开发/下达任务开发）
|
||||
7. 软件说明（原创 / 修改（含翻译软件、合成软件））
|
||||
8. 发表状态（已发表/未发表）
|
||||
9. 首次发表日期（已发表时填写，YYYY-MM-DD）
|
||||
10. 著作权人（复合字段：国家/省市/类型[自然人/法人]/姓名/证件类型/证件号）
|
||||
11. 权利范围（全部权利/部分权利）
|
||||
12. 权利取得方式（原始取得/继受取得）
|
||||
13. 开发的硬件环境（≤50字符）
|
||||
14. 运行的硬件环境（≤50字符）
|
||||
15. 开发该软件的操作系统（≤50字符）
|
||||
16. 软件开发环境 / 开发工具（≤50字符，格式：开发环境: xxx/开发工具: xxx）
|
||||
17. 该软件的运行平台 / 操作系统（≤50字符）
|
||||
18. 软件运行支撑环境 / 支持软件（≤50字符）
|
||||
19. 编程语言（预设按钮选择 + 自定义输入≤120字符）
|
||||
20. 源程序量（纯数字，单位行，指全部源程序总行数）
|
||||
21. 开发目的（≤50字符，不能只写软件名称）
|
||||
22. 面向领域 / 行业（≤50字符）
|
||||
23. 软件的主要功能（500~1300字符）
|
||||
24. 软件的技术特点（多选标签 + 文本描述≤100字符；标签：APP/游戏软件/教育软件/金融软件/医疗软件/地理信息软件/云计算软件/信息安全软件/大数据软件/人工智能软件/VR软件/5G软件/小程序/物联网软件/智慧城市软件，都不符合时可不选）
|
||||
25. 页数（代码鉴别材料实际页数）
|
||||
|
||||
## 字段来源与填写口径
|
||||
|
||||
- 软件全称、版本号、著作权人、日期：由用户确认。
|
||||
- 软件全称必须显式确认；正式资料文件名、代码 Word 页眉、操作手册标题和正文中的软件名称均以申请表信息中的"软件全称"为准。
|
||||
- 软件简称：可选；如有常用简称则填写。
|
||||
- 版本号必须显式确认；如果项目配置中的版本号小于 V1.0，需提醒用户软著首次提交通常写 V1.0，并让用户确认填写 V1.0 还是项目当前版本号。
|
||||
- 软件分类：默认选"应用软件"。
|
||||
- 开发完成日期和首次发表日期：必须使用 YYYY-MM-DD 格式。
|
||||
- 开发方式：默认"单独开发"，多人合作项目选"合作开发"。
|
||||
- 软件说明：默认"原创"。
|
||||
- 发表状态：用户确认已发表或未发表；已发表需附首次发表日期。
|
||||
- 编程语言、源程序量、功能模块、技术特点：根据项目分析生成。编程语言官网为预设按钮选择 + 自定义输入（≤120字符），预设选项包括 Assembly language、C、C#、C++、Delphi/Object Pascal、Go、HTML、Java、JavaScript、MATLAB、Objective-C、PHP、PL/SQL、Perl、Python、R、Ruby、SQL、Swift、Visual Basic、Visual Basic .Net。
|
||||
- 源程序量：只填纯数字（不含"行"字），指登记软件全部源程序的总行数（非仅代码材料抽取行数）。
|
||||
- 软件开发环境 / 开发工具：≤50字符，格式 `开发环境: <OS>/开发工具: <IDE>`，例如 `开发环境: Windows 11/开发工具: Visual Studio Code`；不要填写 React、Next.js、Vite、TypeScript 等技术栈。
|
||||
- 开发该软件的操作系统：≤50字符，填写实际开发电脑的操作系统版本。
|
||||
- 该软件的运行平台 / 操作系统：≤50字符，填写软件运行所在的操作系统或浏览器环境。
|
||||
- 软件运行支撑环境 / 支持软件：≤50字符，直接列出运行依赖（如 Node.js、npm、浏览器），不加格式前缀。
|
||||
- 开发的硬件环境：≤50字符，优先读取当前电脑 CPU、内存、硬盘配置作为建议值。
|
||||
- 运行的硬件环境：≤50字符，默认可沿用开发硬件建议值，也可按实际运行设备填写。
|
||||
- 开发目的：≤50字符，用一句话说明软件开发目的，不能只写软件名称。
|
||||
- 面向领域 / 行业：≤50字符。
|
||||
- 软件的主要功能：500~1300字符，详细描述软件核心功能。
|
||||
- 软件的技术特点：多选标签（APP/游戏软件/教育软件等）+ 文本描述≤100字符；标签都不符合时可不选。
|
||||
|
||||
## 一致性要求
|
||||
|
||||
- 软件全称和版本号必须与代码材料、操作手册一致。
|
||||
- 正式代码 Word 页眉软件名称必须与申请表信息中的“软件全称”一致，生成 Word 时以申请表软件全称为准。
|
||||
- 正式代码 Word 页眉版本号必须与申请表信息中的“版本号”一致，生成 Word 时以申请表版本号为准。
|
||||
- 主要功能必须来自当前项目，不得沿用范本中的旧项目描述。
|
||||
- `待用户确认` 字段在正式输出前应尽量替换为确认值；如仍存在，必须写入生成报告。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 业务理解规则
|
||||
|
||||
申请表信息和操作手册不能只根据代码结构泛泛生成，必须先理解软件业务。
|
||||
|
||||
## 证据收集
|
||||
|
||||
先用脚本收集证据，输出 `草稿/业务理解证据.md/json` 和 `草稿/业务理解模型稿模板.json`。证据通常包括：
|
||||
|
||||
- `README.md`
|
||||
- `docs/*PRD*.md`
|
||||
- `docs/*BRD*.md`
|
||||
- `docs/*ARCHITECTURE*.md`
|
||||
- 产品说明、需求文档、设计文档
|
||||
- 前端页面标题、按钮文案、路由、核心组件名
|
||||
- 后端 API 路由和模型名称
|
||||
|
||||
这些只是候选证据，不代表最终行业、功能和手册结构。
|
||||
|
||||
## 输出业务理解草稿
|
||||
|
||||
模型必须阅读证据和必要源码，自行判断应该抽取哪些业务信息，再生成业务理解模型稿 JSON。不得用关键字表或固定模板决定行业、功能和结构。
|
||||
|
||||
模型稿经脚本校验后生成 `草稿/业务理解.md` 和 `草稿/业务理解.json`，至少包含：
|
||||
|
||||
- 产品定位
|
||||
- 面向领域 / 行业
|
||||
- 目标用户
|
||||
- 用户痛点和核心价值
|
||||
- 主要业务功能
|
||||
- 典型操作流程
|
||||
- 操作手册结构建议
|
||||
- 操作手册页面/流程模块，必须说明每个真实页面或核心流程的使用场景、进入位置、用户可见元素、用户动作、输入/状态规则、结果反馈和截图预留
|
||||
- 申请表建议口径
|
||||
- 证据来源
|
||||
- 待用户确认项
|
||||
|
||||
## 外部调研
|
||||
|
||||
如果项目材料不足、业务类型较新，或用户明确希望参考竞品，可联网搜索相近产品和行业资料。
|
||||
|
||||
外部调研只用于帮助理解行业表达，不能编造项目不存在的功能。需要把调研结论写入业务理解草稿，并区分“项目证据”和“行业参考”。
|
||||
|
||||
## 生成材料约束
|
||||
|
||||
- `申请表信息.md/txt` 的开发目的、行业、主要功能、技术特点必须优先来自业务理解。
|
||||
- `操作手册.md/docx` 的说明、功能特点、系统要求、核心页面/流程、常见问题、术语表和章节结构必须优先来自模型确认后的业务理解。
|
||||
- 操作手册不应只生成抽象“功能列表”。模型应把路由、页面、按钮、输入框、列表、弹窗、状态提示、额度或权限规则等用户可见证据整理到 `manual_modules`，供脚本按通用操作手册骨架排版。最终成稿应是段落化用户手册，不是“进入方式/页面内容/操作步骤/结果反馈”的字段列表。
|
||||
- 如果缺少 `manual_modules`、`system_requirements`、`faq` 或 `glossary`，应回到业务理解阶段补充真实内容；脚本不得用分类模板兜底生成。
|
||||
- 如果业务理解仍不充分，先提示用户补充产品说明，而不是直接生成泛泛描述。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 代码抽取规则
|
||||
|
||||
## 选择方式
|
||||
|
||||
脚本只生成候选源码清单，不默认决定抽取文件。模型需要先理解项目业务、页面入口和源码职责，再决定抽取哪些文件或行段，并在 `代码文件选择.json` 中填写：
|
||||
|
||||
- `selected`
|
||||
- `start_line`
|
||||
- `end_line`
|
||||
- `model_reason`
|
||||
|
||||
选择时通常优先考虑审核员能看懂软件功能和运行逻辑的源码，例如入口、页面、业务组件、数据交互、状态处理、业务服务等。具体选择由模型根据项目实际判断，不能用固定路径规则直接拍板。
|
||||
|
||||
## 排除项
|
||||
|
||||
排除以下内容：
|
||||
|
||||
- `node_modules`
|
||||
- `dist`、`build`、`.next`、`.nuxt`、`coverage`
|
||||
- lock 文件
|
||||
- 图片、字体、二进制文件
|
||||
- sourcemap、minified 文件
|
||||
- 自动生成文件
|
||||
- 过短且无业务意义的配置文件
|
||||
|
||||
## 真实性要求
|
||||
|
||||
- 保留原始代码文本。
|
||||
- 可添加文件路径标记用于追溯。
|
||||
- 不改写业务逻辑。
|
||||
- 不使用 AI 补齐代码。
|
||||
|
||||
## 用户确认要求
|
||||
|
||||
- 代码抽取前必须先生成 `代码文件候选清单.md` 和 `代码文件选择.json`。
|
||||
- 模型必须先填写抽取选择和 `model_reason`，再让用户确认或手动调整 `selected`。
|
||||
- 用户可以通过 `start_line` / `end_line` 只抽取某个文件的指定行段。
|
||||
- 抽取脚本必须以 `代码文件选择.json` 为准，不能绕过确认步骤直接抽全量代码库。
|
||||
- `代码提取清单.md` 必须记录每个文件的抽取行段，便于回溯。
|
||||
@@ -0,0 +1,22 @@
|
||||
# 软著材料规则
|
||||
|
||||
## 鉴别材料
|
||||
|
||||
根据《计算机软件著作权登记办法》第十条，软件鉴别材料包括程序和文档的鉴别材料。
|
||||
|
||||
执行规则：
|
||||
|
||||
- 源程序和文档一般由前、后各连续 30 页组成。
|
||||
- 整个程序或文档不足 60 页时，提交全部。
|
||||
- 除特定情况外，程序每页不少于 50 行。
|
||||
- 除特定情况外，文档每页不少于 30 行。
|
||||
|
||||
## 本 skill 的落地规则
|
||||
|
||||
- 代码分页默认每页 50 行。
|
||||
- 总页数 `>= 60` 时，只输出前 30 页和后 30 页代码材料。
|
||||
- 总页数 `< 60` 时，只输出全部代码材料。
|
||||
- 不为大项目输出全量代码 Word，避免文件过大且不符合常规提交需求。
|
||||
- 代码材料必须来自项目源文件，不能由 AI 生成。
|
||||
- 文件页眉或页首必须包含软件全称和版本号。
|
||||
- 页码必须连续且清晰。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 操作手册结构
|
||||
|
||||
操作手册应像真实软件随附的操作说明，目标是让读者知道软件用途、功能和基本操作。
|
||||
|
||||
推荐采用软著审核友好的通用骨架，类似传统操作手册：
|
||||
|
||||
1. 相关文档：用表格指向总体设计、详细设计、测试案例等配套资料。
|
||||
2. 说明：说明软件定位、目标用户、业务场景和整体流程。
|
||||
3. 功能特点：按当前项目真实功能概括 4-8 项特点，每项说明业务作用和用户可见结果。
|
||||
4. 系统要求：用表格说明最低配置和推荐配置；Web 项目可写浏览器、网络和服务访问要求，桌面项目可写操作系统、处理器、内存、存储和分辨率。
|
||||
5. 具体页面 / 功能操作：从第 5 章开始，按真实页面、导航入口或核心流程逐章说明，每章写使用场景、页面用途、进入位置、页面内容、用户动作、输入限制或异常提示、操作结果和截图预留。
|
||||
6. 典型使用流程：如项目存在清晰串联流程，可单独写一章串起从进入软件到完成核心任务的过程。
|
||||
7. 常见问题解答：写 3-5 个与当前软件真实使用相关的问题和解决方法。
|
||||
8. 术语表：解释软件名称、核心业务对象、页面模块和用户可能不熟悉的术语。
|
||||
|
||||
以上是通用骨架，不是旧项目内容。正式章节标题使用中文大写序号，例如 `一、相关文档`，不要使用 `(1)、相关文档`。生成时必须根据当前项目业务、页面入口、功能关系和用户可见控件填充内容，不要照抄用户提供的范本文案。
|
||||
具体页面和流程必须来自 `草稿/业务理解.json` 中模型写入的 `manual_modules`。如果该字段为空，不能根据 `business_features` 生成兜底模块，应停止并要求模型阅读真实页面和项目资料后补全。
|
||||
|
||||
## 写作口径
|
||||
|
||||
- 使用通用、客观、简洁的中文。
|
||||
- 不写面向终端用户的复杂教程。
|
||||
- 每个章节必须有段落化说明，不能只写项目符号列表；正文不要用 `-`、`*`、`1. 2. 3.` 堆信息。
|
||||
- 每个核心页面或功能模块必须覆盖“使用场景 + 页面用途 + 进入位置 + 页面内容 + 用户动作 + 输入/状态规则 + 系统反馈 + 截图预留”，但这些信息要合并成自然段落，不能直接输出成字段表单。
|
||||
- 优先写用户真实能看到和操作的内容，例如输入框、按钮、下拉框、标签页、列表、卡片、弹窗、错误提示、状态栏、导入导出入口、额度或权限提示。
|
||||
- 补充说明段落只能写当前软件的用途、业务场景、页面组织和用户流程，不写“本操作手册用于……”“面向软著审核……”“不描述代码实现……”这类解释文档写作方式的元话语。
|
||||
- 禁止在脚本中按 auth、query、form、workflow 等分类自动生成入口、步骤或结果反馈。入口和步骤必须来自模型对当前项目真实页面的阅读。
|
||||
- 功能特点不要写成“开头一句总述 + 编号列表 + 结论”的头中尾结构。每个特点用段落展开，说明该功能解决什么业务问题、用户在页面上看到什么、完成操作后得到什么结果。不同功能的说明要有差异，避免每条都使用相同句式。
|
||||
- 页面章节不要输出“进入方式：”“页面内容：”“操作步骤：”“操作规则：”“操作结果与反馈：”这类模板小标题。
|
||||
- 操作手册语言要让审核员和普通读者能看懂，重点说明模块是做什么的、怎么操作、操作后看到什么。避免代码、框架、接口、状态管理、异步任务等技术化表达。
|
||||
- “AI 味”主要表现为空泛、整齐、万能、没有项目现场感：例如每个模块都用同一种句式，反复写“提升效率、优化体验、提供支持”，使用“旨在、赋能、一站式、智能化、高效便捷、显著提升、强大能力、丰富功能”等口号，却没有说明当前项目的真实页面、真实对象、真实动作和真实反馈。发现这类内容时必须改写成朴素、具体、可回溯到项目证据的表达。
|
||||
- 截图前必须先让用户在 Chrome DevTools MCP、Codex Computer Use、用户自行截图三种方式中选择；选择后检查对应能力是否可用。用户说现在不截图或先跳过截图时，记录为 `skip`，并在每个需要截图的位置保留正式 Word 中可见的截图预留文字。
|
||||
- 不夸大不存在的功能。
|
||||
- 功能名称和章节组织由模型根据项目证据判断；路由、页面、README、接口和组件命名只是证据来源，不是固定抽取规则。
|
||||
- Markdown 草稿生成前由 agent 自行检查章节完整性、内容厚度、项目流程一致性和语言自然度，发现章节过薄、模块套话、AI 味、技术化表达或相邻模块含义混淆时先循环补写和修正；完整草稿生成后只向用户发起一次整体确认，再进入 Word 生成。
|
||||
- 操作手册生成时必须同步输出 `操作手册自检记录.md/json`。记录中至少包含初稿生成、按项目流程扩写、去除制式表达和 AI 味三轮；如果第三轮仍发现问题，要继续自动修正并追加轮次记录。
|
||||
- 操作手册必须基于已确认的业务理解写作。相近功能应结合项目真实业务分别说明各自的操作目的、用户动作和结果反馈，不能用同一段话替换不同模块。
|
||||
- 自检时必须检查是否生成了“功能操作说明”大章下反复套同一批模块的情况；如果出现同一模块重复多次，必须改为每个真实页面独立成章。
|
||||
- 禁止把测试项目中的行业、角色、流程、功能名称或示例文案写成通用规则；范本只能帮助理解软著手册需要“通顺、具体、能给审核员看懂”，不能作为固定内容来源。
|
||||
@@ -0,0 +1,363 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Analyze a project and produce facts used by the copyright material workflow."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import COPYRIGHT_CODE_EXTS, FRONTEND_EXTS, count_text_lines, is_known_config_file, iter_project_files, normalize_title, read_json, read_text, rel, write_json
|
||||
|
||||
|
||||
DEPENDENCY_FRAMEWORKS = {
|
||||
"vue": "Vue",
|
||||
"@vue/runtime-core": "Vue",
|
||||
"react": "React",
|
||||
"next": "Next.js",
|
||||
"nuxt": "Nuxt",
|
||||
"svelte": "Svelte",
|
||||
"astro": "Astro",
|
||||
"@angular/core": "Angular",
|
||||
"vite": "Vite",
|
||||
"uni-app": "UniApp",
|
||||
"@dcloudio/uni-app": "UniApp",
|
||||
"electron": "Electron",
|
||||
"@tauri-apps/api": "Tauri",
|
||||
}
|
||||
|
||||
ENTRY_NAMES = {
|
||||
"main.ts",
|
||||
"main.js",
|
||||
"main.tsx",
|
||||
"main.jsx",
|
||||
"index.tsx",
|
||||
"index.jsx",
|
||||
"app.vue",
|
||||
"App.vue",
|
||||
"app.tsx",
|
||||
}
|
||||
|
||||
|
||||
def load_package(project: Path) -> tuple[dict[str, Any] | None, Path | None]:
|
||||
candidates = [
|
||||
project / "package.json",
|
||||
project / "frontend/package.json",
|
||||
project / "client/package.json",
|
||||
project / "web/package.json",
|
||||
project / "app/package.json",
|
||||
]
|
||||
for package_path in candidates:
|
||||
if not package_path.exists():
|
||||
continue
|
||||
try:
|
||||
return read_json(package_path), package_path
|
||||
except Exception:
|
||||
continue
|
||||
return None, None
|
||||
|
||||
|
||||
def detect_frameworks(package: dict[str, Any] | None, files: list[Path], project: Path) -> list[str]:
|
||||
found: set[str] = set()
|
||||
deps: dict[str, Any] = {}
|
||||
if package:
|
||||
for key in ("dependencies", "devDependencies", "peerDependencies"):
|
||||
deps.update(package.get(key) or {})
|
||||
for dep in deps:
|
||||
if dep in DEPENDENCY_FRAMEWORKS:
|
||||
found.add(DEPENDENCY_FRAMEWORKS[dep])
|
||||
suffixes = {p.suffix.lower() for p in files}
|
||||
if ".vue" in suffixes:
|
||||
found.add("Vue")
|
||||
if ".tsx" in suffixes or ".jsx" in suffixes:
|
||||
if "Vue" not in found:
|
||||
found.add("React")
|
||||
if (project / "vite.config.ts").exists() or (project / "vite.config.js").exists():
|
||||
found.add("Vite")
|
||||
if (project / "next.config.js").exists() or (project / "next.config.ts").exists() or any(p.name in {"next.config.js", "next.config.ts"} for p in files):
|
||||
found.add("Next.js")
|
||||
return sorted(found)
|
||||
|
||||
|
||||
def classify(path: Path, project: Path) -> str:
|
||||
r = rel(path, project).lower()
|
||||
name = path.name
|
||||
if name in ENTRY_NAMES or r in {"src/app/page.tsx", "src/app/layout.tsx", "app/page.tsx", "app/layout.tsx"} or r.endswith("/src/app/page.tsx") or r.endswith("/src/app/layout.tsx"):
|
||||
return "entry"
|
||||
if path.suffix.lower() in {".css", ".scss", ".sass", ".less"}:
|
||||
return "style"
|
||||
if any(part in r for part in ("/router/", "/routes/", "router.", "routes.")):
|
||||
return "route"
|
||||
if any(part in r for part in ("/pages/", "/views/", "/app/", "/screens/")):
|
||||
return "page"
|
||||
if "/components/" in r:
|
||||
return "component"
|
||||
if any(part in r for part in ("/api/", "/apis/", "/services/", "request.", "/request/", "/controllers/", "/handlers/", "/views.py")):
|
||||
return "api"
|
||||
if any(part in r for part in ("/models/", "/schemas/", "/entities/", "/repositories/", "/dao/")):
|
||||
return "model"
|
||||
if any(part in r for part in ("/store/", "/stores/", "/pinia/", "/redux/", "/zustand/")):
|
||||
return "state"
|
||||
if any(part in r for part in ("/utils/", "/lib/", "/hooks/", "/composables/", "/helpers/")):
|
||||
return "utility"
|
||||
return "source"
|
||||
|
||||
|
||||
def extract_route_paths(path: Path) -> list[str]:
|
||||
try:
|
||||
text = read_text(path, limit=200_000)
|
||||
except Exception:
|
||||
return []
|
||||
patterns = [
|
||||
r"path\s*:\s*['\"]([^'\"]+)['\"]",
|
||||
r"<Route[^>]+path=['\"]([^'\"]+)['\"]",
|
||||
r"href=['\"](/[^'\"]*)['\"]",
|
||||
]
|
||||
routes: list[str] = []
|
||||
for pattern in patterns:
|
||||
for match in re.findall(pattern, text):
|
||||
if match.startswith("/") and len(match) < 120 and "*" not in match:
|
||||
routes.append(match)
|
||||
return routes
|
||||
|
||||
|
||||
def summarize_readme(project: Path) -> str:
|
||||
for name in ("README.md", "README.zh.md", "readme.md", "Readme.md"):
|
||||
path = project / name
|
||||
if path.exists():
|
||||
text = read_text(path, limit=4000)
|
||||
return "\n".join(line.strip() for line in text.splitlines()[:60] if line.strip())
|
||||
return ""
|
||||
|
||||
|
||||
def analyze(project: Path) -> dict[str, Any]:
|
||||
project = project.resolve()
|
||||
package, package_path = load_package(project)
|
||||
source_files = [p for p in iter_project_files(project, COPYRIGHT_CODE_EXTS) if not is_known_config_file(p)]
|
||||
frontend_files = [p for p in source_files if p.suffix.lower() in FRONTEND_EXTS]
|
||||
class_counts: Counter[str] = Counter()
|
||||
extension_counts: Counter[str] = Counter()
|
||||
source_lines = 0
|
||||
total_source_lines = 0
|
||||
categorized: dict[str, list[str]] = {
|
||||
"entry": [],
|
||||
"route": [],
|
||||
"page": [],
|
||||
"component": [],
|
||||
"api": [],
|
||||
"model": [],
|
||||
"state": [],
|
||||
"utility": [],
|
||||
"style": [],
|
||||
"source": [],
|
||||
}
|
||||
route_paths: list[str] = ["/"]
|
||||
|
||||
for path in source_files:
|
||||
category = classify(path, project)
|
||||
class_counts[category] += 1
|
||||
extension_counts[path.suffix.lower()] += 1
|
||||
categorized[category].append(rel(path, project))
|
||||
source_lines += count_text_lines(path, skip_blank=False)
|
||||
if path.suffix.lower() in FRONTEND_EXTS and category in {"route", "page", "entry"}:
|
||||
route_paths.extend(extract_route_paths(path))
|
||||
|
||||
total_source_lines = source_lines
|
||||
|
||||
package_name = ""
|
||||
scripts: dict[str, str] = {}
|
||||
dependencies: dict[str, str] = {}
|
||||
if package:
|
||||
package_name = str(package.get("name") or "")
|
||||
scripts = {k: str(v) for k, v in (package.get("scripts") or {}).items()}
|
||||
for key in ("dependencies", "devDependencies"):
|
||||
dependencies.update({k: str(v) for k, v in (package.get(key) or {}).items()})
|
||||
|
||||
frameworks = detect_frameworks(package, frontend_files, project)
|
||||
language = infer_language(extension_counts, frameworks)
|
||||
route_paths = sorted(set(route_paths), key=lambda x: (x.count("/"), x))
|
||||
|
||||
return {
|
||||
"project_root": str(project),
|
||||
"project_name": project.name,
|
||||
"software_name_candidate": normalize_title(package_name or project.name),
|
||||
"package": {
|
||||
"name": package_name,
|
||||
"path": rel(package_path, project) if package_path else "",
|
||||
"version": str(package.get("version") or "V1.0") if package else "V1.0",
|
||||
"scripts": scripts,
|
||||
"dependency_names": sorted(dependencies),
|
||||
},
|
||||
"frameworks": frameworks,
|
||||
"language": language,
|
||||
"source": {
|
||||
"file_count": len(source_files),
|
||||
"line_count": source_lines,
|
||||
"total_file_count": len(source_files),
|
||||
"total_line_count": total_source_lines,
|
||||
"extension_counts": dict(sorted(extension_counts.items())),
|
||||
"category_counts": dict(sorted(class_counts.items())),
|
||||
"categorized_files": {k: v[:80] for k, v in categorized.items() if v},
|
||||
},
|
||||
"routes": route_paths[:80],
|
||||
"readme_excerpt": summarize_readme(project),
|
||||
"run_command_candidates": infer_run_commands(scripts),
|
||||
"feature_candidates": infer_features(categorized, route_paths),
|
||||
}
|
||||
|
||||
|
||||
def infer_workdir(out: Path) -> Path:
|
||||
if out.parent.name == "analysis":
|
||||
return out.parent.parent
|
||||
return out.parent
|
||||
|
||||
|
||||
def check_environment_gate(out: Path) -> None:
|
||||
workdir = infer_workdir(out)
|
||||
env_path = workdir / "环境检查.json"
|
||||
if not env_path.exists():
|
||||
return
|
||||
env = read_json(env_path)
|
||||
if not env.get("requires_user_input"):
|
||||
return
|
||||
confirmation_path = workdir / "环境确认.json"
|
||||
confirmed = False
|
||||
if confirmation_path.exists():
|
||||
confirmed = bool(read_json(confirmation_path).get("environment_confirmed"))
|
||||
if not confirmed:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 完整 DOCX 环境未确认。请先让用户选择安装完整环境或使用基础 DOCX 兜底继续，"
|
||||
"然后运行 `python3 <SKILL_DIR>/scripts/confirm_stage.py --workdir 软件著作权申请资料 --stage environment --note \"<用户选择>\"`。"
|
||||
)
|
||||
|
||||
|
||||
def infer_language(extension_counts: Counter[str], frameworks: list[str]) -> str:
|
||||
langs: list[str] = []
|
||||
if extension_counts.get(".ts") or extension_counts.get(".tsx"):
|
||||
langs.append("TypeScript")
|
||||
if extension_counts.get(".js") or extension_counts.get(".jsx"):
|
||||
langs.append("JavaScript")
|
||||
language_by_ext = {
|
||||
".py": "Python",
|
||||
".java": "Java",
|
||||
".go": "Go",
|
||||
".rs": "Rust",
|
||||
".cs": "C#",
|
||||
".php": "PHP",
|
||||
".rb": "Ruby",
|
||||
".kt": "Kotlin",
|
||||
".swift": "Swift",
|
||||
".sql": "SQL",
|
||||
".sh": "Shell",
|
||||
}
|
||||
for ext, label in language_by_ext.items():
|
||||
if extension_counts.get(ext):
|
||||
langs.append(label)
|
||||
if not langs:
|
||||
langs = [ext.lstrip(".").upper() for ext, _ in extension_counts.most_common(3) if ext]
|
||||
return "、".join(dict.fromkeys(langs)) or "待用户确认"
|
||||
|
||||
|
||||
def infer_run_commands(scripts: dict[str, str]) -> list[str]:
|
||||
preferred = ["dev", "start", "serve", "preview"]
|
||||
commands = []
|
||||
for name in preferred:
|
||||
if name in scripts:
|
||||
commands.append(f"npm run {name}")
|
||||
return commands
|
||||
|
||||
|
||||
def infer_features(categorized: dict[str, list[str]], routes: list[str]) -> list[str]:
|
||||
stop = {
|
||||
"index",
|
||||
"main",
|
||||
"app",
|
||||
"layout",
|
||||
"page",
|
||||
"globals",
|
||||
"providers",
|
||||
"loading",
|
||||
"error",
|
||||
"not-found",
|
||||
"template",
|
||||
"default",
|
||||
"button",
|
||||
"input",
|
||||
"label",
|
||||
"avatar",
|
||||
"card",
|
||||
"textarea",
|
||||
"scroll area",
|
||||
}
|
||||
names: list[str] = []
|
||||
for route in routes:
|
||||
cleaned = route.strip("/").replace("-", " ").replace("_", " ")
|
||||
if cleaned and not cleaned.startswith(":") and cleaned.lower() not in stop:
|
||||
names.append(cleaned)
|
||||
for file in categorized.get("page", [])[:60]:
|
||||
route_name = feature_from_page_path(file)
|
||||
if route_name and route_name.lower() not in stop:
|
||||
names.append(route_name)
|
||||
for category in ("api", "component"):
|
||||
for file in categorized.get(category, [])[:30]:
|
||||
lowered = file.lower()
|
||||
if "/ui/" in lowered or "/components/ui/" in lowered:
|
||||
continue
|
||||
stem = Path(file).stem
|
||||
normalized = stem.replace("-", " ").replace("_", " ").strip()
|
||||
if normalized.lower() not in stop:
|
||||
names.append(normalized)
|
||||
unique: list[str] = []
|
||||
for name in names:
|
||||
normalized = re.sub(r"\s+", " ", name).strip()
|
||||
if normalized and normalized not in unique:
|
||||
unique.append(normalized)
|
||||
return unique[:30]
|
||||
|
||||
|
||||
def feature_from_page_path(file: str) -> str:
|
||||
parts = Path(file).parts
|
||||
useful: list[str] = []
|
||||
for part in parts:
|
||||
if part in {"src", "app", "pages", "views", "screens", "frontend", "client", "web"}:
|
||||
continue
|
||||
if part.startswith("(") and part.endswith(")"):
|
||||
continue
|
||||
stem = Path(part).stem
|
||||
if stem in {"page", "layout", "index", "route", "loading", "error", "globals", "providers"}:
|
||||
continue
|
||||
if stem.startswith("[") and stem.endswith("]"):
|
||||
continue
|
||||
useful.append(stem)
|
||||
return " ".join(useful[-2:]).replace("-", " ").replace("_", " ").strip()
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--project", required=True, help="Project root directory")
|
||||
parser.add_argument("--out", default="软件著作权申请资料/analysis/project.json")
|
||||
args = parser.parse_args()
|
||||
|
||||
project = Path(args.project)
|
||||
if not project.exists():
|
||||
raise SystemExit(f"Project not found: {project}")
|
||||
|
||||
out = Path(args.out)
|
||||
check_environment_gate(out)
|
||||
result = analyze(project)
|
||||
write_json(out, result)
|
||||
print(f"OK analysis: {out}")
|
||||
print(f"Project: {result['project_name']}")
|
||||
print(f"Frameworks: {', '.join(result['frameworks']) or 'unknown'}")
|
||||
print(f"Language: {result['language']}")
|
||||
print(f"Source files: {result['source']['file_count']}")
|
||||
print(f"Source lines: {result['source']['line_count']}")
|
||||
print(f"Total source files: {result['source']['total_file_count']}")
|
||||
print(f"Total source lines: {result['source']['total_line_count']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,861 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Build final DOCX/TXT files from confirmed Markdown drafts."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import tempfile
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import ensure_dir, read_json, safe_filename
|
||||
|
||||
try:
|
||||
from docx import Document
|
||||
from docx.enum.section import WD_SECTION
|
||||
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
|
||||
from docx.oxml import OxmlElement
|
||||
from docx.oxml.ns import qn
|
||||
from docx.shared import Cm, Inches, Pt, RGBColor
|
||||
|
||||
DOCX_AVAILABLE = True
|
||||
except Exception:
|
||||
DOCX_AVAILABLE = False
|
||||
|
||||
|
||||
BLACK_RGB = "000000"
|
||||
|
||||
|
||||
def strip_markdown_links(text: str) -> str:
|
||||
text = re.sub(r"(?<!!)\[([^\]]+)\]\(([^)]+)\)", r"\1", text)
|
||||
text = re.sub(r"<(https?://[^>]+)>", r"\1", text)
|
||||
return text
|
||||
|
||||
|
||||
def parse_application_lines(md_path: Path) -> tuple[list[str], list[str]]:
|
||||
lines = md_path.read_text(encoding="utf-8").splitlines()
|
||||
fields = [line.strip() for line in lines if line.strip().startswith("➤")]
|
||||
warnings = [line for line in fields if "待用户确认" in line]
|
||||
return fields, warnings
|
||||
|
||||
|
||||
def parse_application_field(md_path: Path, field_name: str) -> str:
|
||||
if not md_path.exists():
|
||||
return ""
|
||||
prefix = f"➤{field_name}："
|
||||
for line in md_path.read_text(encoding="utf-8").splitlines():
|
||||
stripped = line.strip()
|
||||
if stripped.startswith(prefix):
|
||||
return stripped[len(prefix) :].strip()
|
||||
return ""
|
||||
|
||||
|
||||
def application_version(draft_dir: Path) -> str:
|
||||
version = parse_application_field(draft_dir / "申请表信息.md", "版本号")
|
||||
if "待用户确认" in version:
|
||||
return ""
|
||||
return version
|
||||
|
||||
|
||||
def application_software_name(draft_dir: Path) -> str:
|
||||
name = parse_application_field(draft_dir / "申请表信息.md", "软件全称")
|
||||
if "待用户确认" in name:
|
||||
return ""
|
||||
return name
|
||||
|
||||
|
||||
def write_application_txt(draft_dir: Path, out_dir: Path) -> tuple[Path | None, list[str]]:
|
||||
md_path = draft_dir / "申请表信息.md"
|
||||
if not md_path.exists():
|
||||
return None, ["缺少草稿/申请表信息.md"]
|
||||
fields, warnings = parse_application_lines(md_path)
|
||||
out_path = out_dir / "申请表信息.txt"
|
||||
out_path.write_text("\n".join(fields) + "\n", encoding="utf-8")
|
||||
return out_path, warnings
|
||||
|
||||
|
||||
def read_json_if_exists(path: Path) -> dict[str, Any]:
|
||||
if not path.exists():
|
||||
return {}
|
||||
return read_json(path)
|
||||
|
||||
|
||||
def confirmation_issues(workdir: Path) -> list[str]:
|
||||
draft_dir = workdir / "草稿"
|
||||
issues: list[str] = []
|
||||
|
||||
business = read_json_if_exists(draft_dir / "业务理解.json")
|
||||
if not business or not business.get("user_confirmed"):
|
||||
issues.append("业务理解尚未确认：请确认 草稿/业务理解.md 后记录 `business` 门禁")
|
||||
|
||||
selection = read_json_if_exists(draft_dir / "代码文件选择.json")
|
||||
if not selection or not selection.get("user_confirmed"):
|
||||
issues.append("代码文件选择尚未确认：请确认 草稿/代码文件选择.json 后记录 `code-selection` 门禁")
|
||||
|
||||
screenshot = read_json_if_exists(workdir / "截图方式确认.json")
|
||||
if not screenshot.get("screenshot_method_confirmed"):
|
||||
issues.append("截图方式尚未确认：请选择截图方式后记录 `screenshot-method` 门禁")
|
||||
|
||||
app_md = draft_dir / "申请表信息.md"
|
||||
if app_md.exists():
|
||||
_, warnings = parse_application_lines(app_md)
|
||||
if warnings:
|
||||
issues.append("申请表信息仍包含“待用户确认”字段")
|
||||
else:
|
||||
issues.append("缺少 草稿/申请表信息.md")
|
||||
|
||||
app_confirmation = read_json_if_exists(draft_dir / "申请表字段确认.json")
|
||||
if not app_confirmation.get("application_fields_confirmed"):
|
||||
issues.append("申请表字段尚未确认：请补全字段后记录 `application-fields` 门禁")
|
||||
|
||||
markdown_confirmation = read_json_if_exists(draft_dir / "最终生成确认.json")
|
||||
if not markdown_confirmation.get("markdown_confirmed"):
|
||||
issues.append("Markdown 草稿尚未最终确认：请确认全部草稿后记录 `markdown` 门禁")
|
||||
|
||||
return issues
|
||||
|
||||
|
||||
def parse_code_pages(md_path: Path) -> list[tuple[int, list[str]]]:
|
||||
pages: list[tuple[int, list[str]]] = []
|
||||
current_no: int | None = None
|
||||
current_lines: list[str] = []
|
||||
in_fence = False
|
||||
|
||||
for raw in md_path.read_text(encoding="utf-8").splitlines():
|
||||
page_match = re.match(r"^##\s+第\s*(\d+)\s*页", raw.strip())
|
||||
if page_match:
|
||||
if current_no is not None:
|
||||
pages.append((current_no, current_lines))
|
||||
current_no = int(page_match.group(1))
|
||||
current_lines = []
|
||||
in_fence = False
|
||||
continue
|
||||
if raw.strip().startswith("```"):
|
||||
in_fence = not in_fence
|
||||
continue
|
||||
if current_no is not None and in_fence:
|
||||
current_lines.append(raw)
|
||||
|
||||
if current_no is not None:
|
||||
pages.append((current_no, current_lines))
|
||||
return pages
|
||||
|
||||
|
||||
def set_run_font(run: Any, name: str, size_pt: float) -> None:
|
||||
run.font.name = name
|
||||
run.font.size = Pt(size_pt)
|
||||
try:
|
||||
run.font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
try:
|
||||
run._element.rPr.rFonts.set(qn("w:eastAsia"), name)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def set_normal_font(document: Any, name: str = "SimSun", size_pt: float = 10.5) -> None:
|
||||
style = document.styles["Normal"]
|
||||
style.font.name = name
|
||||
style.font.size = Pt(size_pt)
|
||||
try:
|
||||
style.font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
try:
|
||||
style._element.rPr.rFonts.set(qn("w:eastAsia"), name)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def set_style_black(document: Any) -> None:
|
||||
for style_name in ("Normal", "Heading 1", "Heading 2", "Heading 3", "List Bullet", "List Number"):
|
||||
try:
|
||||
document.styles[style_name].font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def force_black_document(document: Any) -> None:
|
||||
set_style_black(document)
|
||||
containers = [document]
|
||||
for section in document.sections:
|
||||
containers.extend([section.header, section.footer])
|
||||
for container in containers:
|
||||
for paragraph in container.paragraphs:
|
||||
for run in paragraph.runs:
|
||||
try:
|
||||
run.font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
for table in container.tables:
|
||||
for row in table.rows:
|
||||
for cell in row.cells:
|
||||
for paragraph in cell.paragraphs:
|
||||
for run in paragraph.runs:
|
||||
try:
|
||||
run.font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def configure_a4(document: Any) -> None:
|
||||
section = document.sections[0]
|
||||
section.page_width = Cm(21)
|
||||
section.page_height = Cm(29.7)
|
||||
section.top_margin = Cm(2.54)
|
||||
section.bottom_margin = Cm(2.54)
|
||||
section.left_margin = Cm(3.17)
|
||||
section.right_margin = Cm(2.54)
|
||||
|
||||
|
||||
def configure_code_a4(document: Any) -> None:
|
||||
section = document.sections[0]
|
||||
section.page_width = Cm(21)
|
||||
section.page_height = Cm(29.7)
|
||||
section.top_margin = Cm(2.0)
|
||||
section.bottom_margin = Cm(2.0)
|
||||
section.left_margin = Cm(2.5)
|
||||
section.right_margin = Cm(2.0)
|
||||
|
||||
|
||||
def add_page_field(paragraph: Any) -> None:
|
||||
begin = OxmlElement("w:fldChar")
|
||||
begin.set(qn("w:fldCharType"), "begin")
|
||||
instr = OxmlElement("w:instrText")
|
||||
instr.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
|
||||
instr.text = " PAGE "
|
||||
separate = OxmlElement("w:fldChar")
|
||||
separate.set(qn("w:fldCharType"), "separate")
|
||||
result = OxmlElement("w:t")
|
||||
result.text = "1"
|
||||
end = OxmlElement("w:fldChar")
|
||||
end.set(qn("w:fldCharType"), "end")
|
||||
|
||||
for element in (begin, instr, separate, result, end):
|
||||
run = paragraph.add_run()
|
||||
run._r.append(element)
|
||||
set_run_font(run, "SimSun", 8)
|
||||
|
||||
|
||||
def set_code_header(document: Any, software_name: str, version: str) -> None:
|
||||
section = document.sections[0]
|
||||
section.header.is_linked_to_previous = False
|
||||
header = section.header
|
||||
header.paragraphs[0].text = "" if header.paragraphs else None
|
||||
|
||||
# Build a two-column header: software name on the left, page number on the right.
|
||||
table = header.add_table(rows=1, cols=2, width=Cm(17.5))
|
||||
table.autofit = True
|
||||
left_cell = table.rows[0].cells[0]
|
||||
right_cell = table.rows[0].cells[1]
|
||||
|
||||
left_para = left_cell.paragraphs[0]
|
||||
left_para.alignment = WD_ALIGN_PARAGRAPH.LEFT
|
||||
left_para.paragraph_format.space_before = Pt(0)
|
||||
left_para.paragraph_format.space_after = Pt(0)
|
||||
left_para.paragraph_format.line_spacing_rule = WD_LINE_SPACING.EXACTLY
|
||||
left_para.paragraph_format.line_spacing = Pt(12)
|
||||
left_run = left_para.add_run(f"{software_name} {version}")
|
||||
set_run_font(left_run, "SimSun", 8)
|
||||
|
||||
right_para = right_cell.paragraphs[0]
|
||||
right_para.alignment = WD_ALIGN_PARAGRAPH.RIGHT
|
||||
right_para.paragraph_format.space_before = Pt(0)
|
||||
right_para.paragraph_format.space_after = Pt(0)
|
||||
right_para.paragraph_format.line_spacing_rule = WD_LINE_SPACING.EXACTLY
|
||||
right_para.paragraph_format.line_spacing = Pt(12)
|
||||
prefix = right_para.add_run("第 ")
|
||||
set_run_font(prefix, "SimSun", 8)
|
||||
add_page_field(right_para)
|
||||
suffix = right_para.add_run(" 页")
|
||||
set_run_font(suffix, "SimSun", 8)
|
||||
|
||||
# Remove borders from the header table
|
||||
for cell in table.rows[0].cells:
|
||||
tc_pr = cell._tc.get_or_add_tcPr()
|
||||
tc_borders = OxmlElement("w:tcBorders")
|
||||
for border_name in ("top", "left", "bottom", "right"):
|
||||
border = OxmlElement(f"w:{border_name}")
|
||||
border.set(qn("w:val"), "nil")
|
||||
tc_borders.append(border)
|
||||
tc_pr.append(tc_borders)
|
||||
|
||||
|
||||
def build_code_docx_python(md_path: Path, out_path: Path, software_name: str, version: str) -> None:
|
||||
pages = parse_code_pages(md_path)
|
||||
if not pages:
|
||||
raise RuntimeError(f"No code pages parsed from {md_path}")
|
||||
|
||||
document = Document()
|
||||
configure_code_a4(document)
|
||||
set_normal_font(document, "Consolas", 7.2)
|
||||
set_style_black(document)
|
||||
set_code_header(document, software_name, version)
|
||||
|
||||
# 后30页文档页码从31开始，实现前后文档连续编号1-60
|
||||
start_page_no = pages[0][0] if pages else 1
|
||||
if start_page_no != 1:
|
||||
pg_num_type = OxmlElement("w:pgNumType")
|
||||
pg_num_type.set(qn("w:start"), str(start_page_no))
|
||||
document.sections[0]._sectPr.append(pg_num_type)
|
||||
|
||||
for index, (page_no, lines) in enumerate(pages):
|
||||
for line in lines:
|
||||
p = document.add_paragraph()
|
||||
p.paragraph_format.space_before = Pt(0)
|
||||
p.paragraph_format.space_after = Pt(0)
|
||||
p.paragraph_format.line_spacing_rule = WD_LINE_SPACING.EXACTLY
|
||||
p.paragraph_format.line_spacing = Pt(14)
|
||||
run = p.add_run(line if line else " ")
|
||||
set_run_font(run, "Consolas", 7.2)
|
||||
if index != len(pages) - 1:
|
||||
# 嵌入式分页符：避免 add_page_break() 产生多余空段落导致空白页
|
||||
run = p.add_run()
|
||||
br = OxmlElement('w:br')
|
||||
br.set(qn('w:type'), 'page')
|
||||
run._r.append(br)
|
||||
|
||||
force_black_document(document)
|
||||
document.save(out_path)
|
||||
|
||||
|
||||
def paragraph_xml(text: str, font: str = "SimSun", size_half_points: int = 21, align: str | None = None, line_twips: int = 240) -> str:
|
||||
align_xml = f'<w:jc w:val="{align}"/>' if align else ""
|
||||
escaped = html.escape(text)
|
||||
return (
|
||||
"<w:p>"
|
||||
f"<w:pPr>{align_xml}<w:spacing w:after=\"0\" w:line=\"{line_twips}\" w:lineRule=\"exact\"/></w:pPr>"
|
||||
"<w:r>"
|
||||
f"<w:rPr><w:rFonts w:ascii=\"{font}\" w:hAnsi=\"{font}\" w:eastAsia=\"{font}\"/>"
|
||||
f"<w:color w:val=\"{BLACK_RGB}\"/>"
|
||||
f"<w:sz w:val=\"{size_half_points}\"/><w:szCs w:val=\"{size_half_points}\"/></w:rPr>"
|
||||
f"<w:t xml:space=\"preserve\">{escaped}</w:t>"
|
||||
"</w:r>"
|
||||
"</w:p>"
|
||||
)
|
||||
|
||||
|
||||
def page_break_xml() -> str:
|
||||
return '<w:p><w:r><w:br w:type="page"/></w:r></w:p>'
|
||||
|
||||
|
||||
def page_field_runs_xml() -> str:
|
||||
return (
|
||||
'<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/>'
|
||||
f'<w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr>'
|
||||
'<w:fldChar w:fldCharType="begin"/></w:r>'
|
||||
'<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/>'
|
||||
f'<w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr>'
|
||||
'<w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>'
|
||||
'<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/>'
|
||||
f'<w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr>'
|
||||
'<w:fldChar w:fldCharType="separate"/></w:r>'
|
||||
'<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/>'
|
||||
f'<w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr>'
|
||||
'<w:t>1</w:t></w:r>'
|
||||
'<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/>'
|
||||
f'<w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr>'
|
||||
'<w:fldChar w:fldCharType="end"/></w:r>'
|
||||
)
|
||||
|
||||
|
||||
def header_xml(header_text: str) -> str:
|
||||
"""Build a two-column header: software name left, page number right."""
|
||||
escaped = html.escape(header_text)
|
||||
# Use a borderless table for left/right alignment in header
|
||||
return f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
|
||||
<w:tbl>
|
||||
<w:tblPr>
|
||||
<w:tblW w:w="5000" w:type="pct"/>
|
||||
<w:tblBorders>
|
||||
<w:top w:val="nil"/><w:left w:val="nil"/><w:bottom w:val="nil"/><w:right w:val="nil"/><w:insideH w:val="nil"/><w:insideV w:val="nil"/>
|
||||
</w:tblBorders>
|
||||
</w:tblPr>
|
||||
<w:tr>
|
||||
<w:tc>
|
||||
<w:p>
|
||||
<w:pPr><w:jc w:val="left"/><w:spacing w:after="0" w:line="240" w:lineRule="exact"/></w:pPr>
|
||||
<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/><w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr><w:t xml:space="preserve">{escaped}</w:t></w:r>
|
||||
</w:p>
|
||||
</w:tc>
|
||||
<w:tc>
|
||||
<w:p>
|
||||
<w:pPr><w:jc w:val="right"/><w:spacing w:after="0" w:line="240" w:lineRule="exact"/></w:pPr>
|
||||
<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/><w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr><w:t xml:space="preserve">第 </w:t></w:r>
|
||||
{page_field_runs_xml()}
|
||||
<w:r><w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/><w:color w:val="{BLACK_RGB}"/><w:sz w:val="16"/><w:szCs w:val="16"/></w:rPr><w:t xml:space="preserve"> 页</w:t></w:r>
|
||||
</w:p>
|
||||
</w:tc>
|
||||
</w:tr>
|
||||
</w:tbl>
|
||||
</w:hdr>"""
|
||||
|
||||
|
||||
def minimal_docx(out_path: Path, body_xml: str, header_text: str | None = None, start_page: int = 1) -> None:
|
||||
content_types = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
|
||||
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
|
||||
<Default Extension="xml" ContentType="application/xml"/>
|
||||
<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
|
||||
<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
|
||||
<Override PartName="/word/header1.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"/>
|
||||
</Types>"""
|
||||
rels = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
|
||||
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
|
||||
</Relationships>"""
|
||||
header_rel = (
|
||||
'<Relationship Id="rIdHeader1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" Target="header1.xml"/>'
|
||||
if header_text
|
||||
else ""
|
||||
)
|
||||
doc_rels = f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">{header_rel}</Relationships>"""
|
||||
styles = f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
|
||||
<w:style w:type="paragraph" w:default="1" w:styleId="Normal">
|
||||
<w:name w:val="Normal"/>
|
||||
<w:rPr><w:rFonts w:ascii="SimSun" w:hAnsi="SimSun" w:eastAsia="SimSun"/><w:color w:val="{BLACK_RGB}"/><w:sz w:val="21"/></w:rPr>
|
||||
</w:style>
|
||||
</w:styles>"""
|
||||
document = f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
|
||||
<w:body>
|
||||
{body_xml}
|
||||
<w:sectPr>
|
||||
{'<w:headerReference w:type="default" r:id="rIdHeader1"/>' if header_text else ''}
|
||||
{'<w:pgNumType w:start="' + str(start_page) + '"/>' if start_page != 1 else ''}
|
||||
<w:pgSz w:w="11906" w:h="16838"/>
|
||||
<w:pgMar w:top="1134" w:right="1134" w:bottom="1134" w:left="1418" w:header="283" w:footer="283" w:gutter="0"/>
|
||||
</w:sectPr>
|
||||
</w:body>
|
||||
</w:document>"""
|
||||
with zipfile.ZipFile(out_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
|
||||
zf.writestr("[Content_Types].xml", content_types)
|
||||
zf.writestr("_rels/.rels", rels)
|
||||
zf.writestr("word/_rels/document.xml.rels", doc_rels)
|
||||
zf.writestr("word/styles.xml", styles)
|
||||
zf.writestr("word/document.xml", document)
|
||||
if header_text:
|
||||
zf.writestr("word/header1.xml", header_xml(header_text))
|
||||
|
||||
|
||||
def force_black_xml(xml: str) -> str:
|
||||
xml = re.sub(r"<w:hyperlink\b[^>]*>", "", xml)
|
||||
xml = xml.replace("</w:hyperlink>", "")
|
||||
xml = re.sub(r"<w:color\b[^>]*/>", f'<w:color w:val="{BLACK_RGB}"/>', xml)
|
||||
|
||||
def ensure_rpr_color(match: re.Match[str]) -> str:
|
||||
value = match.group(0)
|
||||
if "<w:color" in value:
|
||||
return value
|
||||
return value.replace("</w:rPr>", f'<w:color w:val="{BLACK_RGB}"/></w:rPr>')
|
||||
|
||||
xml = re.sub(r"<w:rPr\b[^>]*>.*?</w:rPr>", ensure_rpr_color, xml, flags=re.S)
|
||||
xml = re.sub(r"<w:r>(?!<w:rPr>)", f'<w:r><w:rPr><w:color w:val="{BLACK_RGB}"/></w:rPr>', xml)
|
||||
return xml
|
||||
|
||||
|
||||
def normalize_docx_text_color(docx_path: Path) -> None:
|
||||
tmp_path = docx_path.with_suffix(docx_path.suffix + ".tmp")
|
||||
color_xml_parts = (
|
||||
"word/document.xml",
|
||||
"word/styles.xml",
|
||||
"word/numbering.xml",
|
||||
"word/header",
|
||||
"word/footer",
|
||||
)
|
||||
with zipfile.ZipFile(docx_path, "r") as src, zipfile.ZipFile(tmp_path, "w", compression=zipfile.ZIP_DEFLATED) as dst:
|
||||
for item in src.infolist():
|
||||
data = src.read(item.filename)
|
||||
if item.filename.endswith(".xml") and item.filename.startswith(color_xml_parts):
|
||||
text = data.decode("utf-8")
|
||||
data = force_black_xml(text).encode("utf-8")
|
||||
elif item.filename.endswith(".rels"):
|
||||
text = data.decode("utf-8", errors="ignore")
|
||||
if "hyperlink" in text:
|
||||
text = re.sub(r'\s*<Relationship\b[^>]*Type="[^"]*/hyperlink"[^>]*/>', "", text)
|
||||
data = text.encode("utf-8")
|
||||
dst.writestr(item, data)
|
||||
tmp_path.replace(docx_path)
|
||||
|
||||
|
||||
def next_header_part(names: set[str]) -> tuple[str, str]:
|
||||
index = 1
|
||||
while f"word/header{index}.xml" in names:
|
||||
index += 1
|
||||
return f"word/header{index}.xml", f"header{index}.xml"
|
||||
|
||||
|
||||
def unique_relationship_id(rels_xml: str, base: str = "rIdManualHeader") -> str:
|
||||
if f'Id="{base}"' not in rels_xml:
|
||||
return base
|
||||
index = 2
|
||||
while f'Id="{base}{index}"' in rels_xml:
|
||||
index += 1
|
||||
return f"{base}{index}"
|
||||
|
||||
|
||||
def add_header_to_existing_docx(docx_path: Path, header_text: str) -> None:
|
||||
"""Add the same two-column header used by code materials to an existing DOCX."""
|
||||
tmp_path = docx_path.with_suffix(docx_path.suffix + ".tmp")
|
||||
with zipfile.ZipFile(docx_path, "r") as src:
|
||||
names = set(src.namelist())
|
||||
header_part, header_target = next_header_part(names)
|
||||
rels_xml = src.read("word/_rels/document.xml.rels").decode("utf-8")
|
||||
rel_id = unique_relationship_id(rels_xml)
|
||||
|
||||
with zipfile.ZipFile(tmp_path, "w", compression=zipfile.ZIP_DEFLATED) as dst:
|
||||
for item in src.infolist():
|
||||
data = src.read(item.filename)
|
||||
if item.filename == "[Content_Types].xml":
|
||||
text = data.decode("utf-8")
|
||||
override = (
|
||||
f'<Override PartName="/{header_part}" '
|
||||
'ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"/>'
|
||||
)
|
||||
if f'PartName="/{header_part}"' not in text:
|
||||
text = text.replace("</Types>", f"{override}</Types>")
|
||||
data = text.encode("utf-8")
|
||||
elif item.filename == "word/_rels/document.xml.rels":
|
||||
text = data.decode("utf-8")
|
||||
relationship = (
|
||||
f'<Relationship Id="{rel_id}" '
|
||||
'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" '
|
||||
f'Target="{header_target}"/>'
|
||||
)
|
||||
text = text.replace("</Relationships>", f"{relationship}</Relationships>")
|
||||
data = text.encode("utf-8")
|
||||
elif item.filename == "word/document.xml":
|
||||
text = data.decode("utf-8")
|
||||
if "xmlns:r=" not in text:
|
||||
text = text.replace(
|
||||
"<w:document ",
|
||||
'<w:document xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" ',
|
||||
1,
|
||||
)
|
||||
header_ref = f'<w:headerReference w:type="default" r:id="{rel_id}"/>'
|
||||
if "<w:headerReference" in text:
|
||||
text = re.sub(r"<w:headerReference\b[^>]*/>", header_ref, text, count=1)
|
||||
else:
|
||||
text = re.sub(r"(<w:sectPr\b[^>]*>)", rf"\1{header_ref}", text, count=1)
|
||||
data = text.encode("utf-8")
|
||||
dst.writestr(item, data)
|
||||
dst.writestr(header_part, header_xml(header_text))
|
||||
tmp_path.replace(docx_path)
|
||||
|
||||
|
||||
def build_code_docx_ooxml(md_path: Path, out_path: Path, software_name: str, version: str) -> None:
|
||||
pages = parse_code_pages(md_path)
|
||||
if not pages:
|
||||
raise RuntimeError(f"No code pages parsed from {md_path}")
|
||||
start_page_no = pages[0][0] if pages else 1
|
||||
body: list[str] = []
|
||||
for index, (page_no, lines) in enumerate(pages):
|
||||
for line in lines:
|
||||
body.append(paragraph_xml(line if line else " ", font="Consolas", size_half_points=14, line_twips=280))
|
||||
if index != len(pages) - 1:
|
||||
# 嵌入式分页符：嵌入最后一段的 run 避免多余空段落
|
||||
last = body.pop()
|
||||
last = last.replace('</w:r></w:p>', '<w:br w:type="page"/></w:r></w:p>')
|
||||
body.append(last)
|
||||
minimal_docx(out_path, "\n".join(body), header_text=f"{software_name} {version}", start_page=start_page_no)
|
||||
|
||||
|
||||
def add_markdown_table(document: Any, rows: list[list[str]]) -> None:
|
||||
if not rows:
|
||||
return
|
||||
table = document.add_table(rows=1, cols=len(rows[0]))
|
||||
table.style = "Table Grid"
|
||||
for idx, text in enumerate(rows[0]):
|
||||
table.rows[0].cells[idx].text = strip_markdown_links(text)
|
||||
for row in rows[1:]:
|
||||
cells = table.add_row().cells
|
||||
for idx, text in enumerate(row[: len(cells)]):
|
||||
cells[idx].text = strip_markdown_links(text)
|
||||
|
||||
|
||||
def parse_table_line(line: str) -> list[str]:
|
||||
return [cell.strip() for cell in line.strip().strip("|").split("|")]
|
||||
|
||||
|
||||
def add_image(document: Any, image_path: Path) -> None:
|
||||
if not image_path.exists():
|
||||
p = document.add_paragraph()
|
||||
run = p.add_run(f"[截图缺失：{image_path}]")
|
||||
set_run_font(run, "SimSun", 10.5)
|
||||
return
|
||||
try:
|
||||
document.add_picture(str(image_path), width=Inches(5.8))
|
||||
except Exception:
|
||||
p = document.add_paragraph()
|
||||
run = p.add_run(f"[截图无法插入：{image_path}]")
|
||||
set_run_font(run, "SimSun", 10.5)
|
||||
|
||||
|
||||
def build_manual_docx_python(md_path: Path, out_path: Path, base_dir: Path, software_name: str, version: str) -> None:
|
||||
document = Document()
|
||||
configure_a4(document)
|
||||
set_normal_font(document, "SimSun", 10.5)
|
||||
set_style_black(document)
|
||||
set_code_header(document, software_name, version)
|
||||
lines = md_path.read_text(encoding="utf-8").splitlines()
|
||||
table_buf: list[list[str]] = []
|
||||
in_fence = False
|
||||
|
||||
def flush_table() -> None:
|
||||
nonlocal table_buf
|
||||
if table_buf:
|
||||
data = [row for row in table_buf if not all(re.fullmatch(r":?-{3,}:?", cell) for cell in row)]
|
||||
add_markdown_table(document, data)
|
||||
table_buf = []
|
||||
|
||||
for line in lines:
|
||||
stripped = line.strip()
|
||||
stripped = strip_markdown_links(stripped)
|
||||
if stripped.startswith("```"):
|
||||
flush_table()
|
||||
in_fence = not in_fence
|
||||
continue
|
||||
if in_fence:
|
||||
continue
|
||||
if stripped.startswith("<!--") and "截图" in stripped:
|
||||
stripped = "【截图预留：请在此处插入当前功能页面或操作结果截图。】"
|
||||
if stripped.startswith("|") and stripped.endswith("|"):
|
||||
table_buf.append(parse_table_line(stripped))
|
||||
continue
|
||||
flush_table()
|
||||
if not stripped:
|
||||
continue
|
||||
image_match = re.search(r"!\[[^\]]*\]\(([^)]+)\)", stripped)
|
||||
if image_match:
|
||||
add_image(document, (base_dir / image_match.group(1)).resolve())
|
||||
continue
|
||||
heading = re.match(r"^(#{1,4})\s+(.+)$", stripped)
|
||||
if heading:
|
||||
level = min(len(heading.group(1)), 3)
|
||||
p = document.add_heading(heading.group(2), level=level)
|
||||
for run in p.runs:
|
||||
try:
|
||||
run.font.color.rgb = RGBColor(0, 0, 0)
|
||||
except Exception:
|
||||
pass
|
||||
continue
|
||||
if re.match(r"^[-*+]\s+", stripped):
|
||||
p = document.add_paragraph(style="List Bullet")
|
||||
run = p.add_run(re.sub(r"^[-*+]\s+", "", stripped))
|
||||
set_run_font(run, "SimSun", 10.5)
|
||||
continue
|
||||
if re.match(r"^\d+\.\s+", stripped):
|
||||
p = document.add_paragraph(style="List Number")
|
||||
run = p.add_run(re.sub(r"^\d+\.\s+", "", stripped))
|
||||
set_run_font(run, "SimSun", 10.5)
|
||||
continue
|
||||
p = document.add_paragraph()
|
||||
run = p.add_run(stripped)
|
||||
set_run_font(run, "SimSun", 10.5)
|
||||
flush_table()
|
||||
force_black_document(document)
|
||||
document.save(out_path)
|
||||
|
||||
|
||||
def pandoc_available() -> bool:
|
||||
return shutil.which("pandoc") is not None
|
||||
|
||||
|
||||
def build_with_pandoc(md_path: Path, out_path: Path, code_mode: bool = False) -> None:
|
||||
if not pandoc_available():
|
||||
raise RuntimeError("python-docx is unavailable and pandoc is not installed")
|
||||
source = md_path
|
||||
tmp_name: str | None = None
|
||||
original_text = md_path.read_text(encoding="utf-8")
|
||||
text = original_text
|
||||
text = re.sub(r"```text\s*\nSTOP_FOR_USER\n.*?```", "", text, flags=re.S)
|
||||
text = re.sub(r"<!--[^>]*截图[^>]*-->", "【截图预留：请在此处插入当前功能页面或操作结果截图。】", text)
|
||||
text = strip_markdown_links(text)
|
||||
if code_mode:
|
||||
text = re.sub(r"(?=^##\s+第\s*\d+\s*页)", r"\n\\newpage\n", text, flags=re.M)
|
||||
if code_mode or "STOP_FOR_USER" in original_text:
|
||||
with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8") as tmp:
|
||||
tmp.write(text)
|
||||
tmp_name = tmp.name
|
||||
source = Path(tmp_name)
|
||||
try:
|
||||
subprocess.run(["pandoc", "-f", "markdown", "-t", "docx", str(source), "-o", str(out_path)], check=True)
|
||||
finally:
|
||||
if tmp_name:
|
||||
Path(tmp_name).unlink(missing_ok=True)
|
||||
|
||||
|
||||
def build_code_docx(md_path: Path, out_path: Path, software_name: str, version: str) -> None:
|
||||
if DOCX_AVAILABLE:
|
||||
build_code_docx_python(md_path, out_path, software_name, version)
|
||||
else:
|
||||
build_code_docx_ooxml(md_path, out_path, software_name, version)
|
||||
normalize_docx_text_color(out_path)
|
||||
|
||||
|
||||
def build_manual_docx(md_path: Path, out_path: Path, base_dir: Path, software_name: str, version: str) -> None:
|
||||
if DOCX_AVAILABLE:
|
||||
build_manual_docx_python(md_path, out_path, base_dir, software_name, version)
|
||||
else:
|
||||
build_with_pandoc(md_path, out_path, code_mode=False)
|
||||
add_header_to_existing_docx(out_path, f"{software_name} {version}")
|
||||
normalize_docx_text_color(out_path)
|
||||
|
||||
|
||||
def run_command(command: list[str], cwd: Path | None = None, timeout: int = 60) -> tuple[int, str]:
|
||||
try:
|
||||
completed = subprocess.run(command, cwd=cwd, text=True, capture_output=True, timeout=timeout)
|
||||
return completed.returncode, (completed.stdout + completed.stderr).strip()
|
||||
except Exception as exc:
|
||||
return 99, str(exc)
|
||||
|
||||
|
||||
def docx_checks(skill_dir: Path, outputs: list[Path]) -> list[str]:
|
||||
notes: list[str] = []
|
||||
env_script = skill_dir / "vendor/docx-toolkit/scripts/env_check.sh"
|
||||
preview_script = skill_dir / "vendor/docx-toolkit/scripts/docx_preview.sh"
|
||||
if env_script.exists():
|
||||
code, output = run_command(["bash", str(env_script)], cwd=env_script.parent.parent, timeout=30)
|
||||
status = "READY" if code == 0 else "NOT READY"
|
||||
first_lines = "\n".join(output.splitlines()[:12])
|
||||
notes.append(f"DOCX env: {status}\n\n```text\n{first_lines}\n```")
|
||||
else:
|
||||
notes.append("DOCX env: vendor script missing")
|
||||
|
||||
if preview_script.exists():
|
||||
for out in outputs:
|
||||
code, output = run_command(["bash", str(preview_script), str(out)], timeout=45)
|
||||
first_lines = "\n".join(output.splitlines()[:8])
|
||||
notes.append(f"Preview {out.name}: exit={code}\n\n```text\n{first_lines}\n```")
|
||||
return notes
|
||||
|
||||
|
||||
def build_all(workdir: Path, software_name: str, version: str, skip_preview: bool) -> dict[str, Any]:
|
||||
workdir = ensure_dir(workdir)
|
||||
draft_dir = workdir / "草稿"
|
||||
final_dir = ensure_dir(workdir / "正式资料")
|
||||
app_name = application_software_name(draft_dir)
|
||||
app_version = application_version(draft_dir)
|
||||
final_software_name = app_name or software_name
|
||||
final_version = app_version or version
|
||||
safe_name = safe_filename(final_software_name)
|
||||
outputs: list[Path] = []
|
||||
warnings: list[str] = []
|
||||
if app_name and app_name != software_name:
|
||||
warnings.append(f"命令参数软件名称为 {software_name}，正式资料已按申请表信息软件名称 {app_name} 生成")
|
||||
if app_version and app_version != version:
|
||||
warnings.append(f"命令参数版本号为 {version}，正式资料已按申请表信息版本号 {app_version} 生成")
|
||||
screenshot_confirmation = read_json_if_exists(workdir / "截图方式确认.json")
|
||||
screenshot_method = screenshot_confirmation.get("screenshot_method")
|
||||
screenshot_manifest = workdir / "截图/截图清单.json"
|
||||
if screenshot_method == "skip":
|
||||
warnings.append("用户选择暂不截图；操作手册已保留截图预留位置")
|
||||
elif screenshot_method and not screenshot_manifest.exists():
|
||||
warnings.append("操作手册截图未生成或未插入；操作手册应保留截图预留位置")
|
||||
elif screenshot_manifest.exists():
|
||||
screenshots = read_json_if_exists(screenshot_manifest).get("screenshots") or []
|
||||
if not screenshots:
|
||||
warnings.append("操作手册截图清单为空；操作手册应保留截图预留位置")
|
||||
|
||||
app_txt, app_warnings = write_application_txt(draft_dir, final_dir)
|
||||
if app_txt:
|
||||
outputs.append(app_txt)
|
||||
warnings.extend(app_warnings)
|
||||
|
||||
code_specs = [
|
||||
("代码-前30页.md", f"{safe_name}-代码(前30页).docx"),
|
||||
("代码-后30页.md", f"{safe_name}-代码(后30页).docx"),
|
||||
("代码-全部.md", f"{safe_name}-代码(全部).docx"),
|
||||
]
|
||||
for md_name, docx_name in code_specs:
|
||||
md_path = draft_dir / md_name
|
||||
if md_path.exists():
|
||||
out_path = final_dir / docx_name
|
||||
build_code_docx(md_path, out_path, final_software_name, final_version)
|
||||
outputs.append(out_path)
|
||||
|
||||
manual_md = draft_dir / "操作手册.md"
|
||||
if manual_md.exists():
|
||||
manual_out = final_dir / f"{safe_name}_操作手册.docx"
|
||||
manual_source = manual_md
|
||||
tmp_manual: Path | None = None
|
||||
if app_name and app_name != software_name:
|
||||
text = manual_md.read_text(encoding="utf-8").replace(software_name, app_name)
|
||||
with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8") as tmp:
|
||||
tmp.write(text)
|
||||
tmp_manual = Path(tmp.name)
|
||||
manual_source = tmp_manual
|
||||
try:
|
||||
build_manual_docx(manual_source, manual_out, draft_dir, final_software_name, final_version)
|
||||
finally:
|
||||
if tmp_manual:
|
||||
tmp_manual.unlink(missing_ok=True)
|
||||
outputs.append(manual_out)
|
||||
else:
|
||||
warnings.append("缺少草稿/操作手册.md")
|
||||
|
||||
skill_dir = Path(__file__).resolve().parents[1]
|
||||
notes = [] if skip_preview else docx_checks(skill_dir, [p for p in outputs if p.suffix.lower() == ".docx"])
|
||||
report = write_report(final_dir, outputs, warnings, notes)
|
||||
return {"outputs": [str(p) for p in outputs], "warnings": warnings, "report": str(report)}
|
||||
|
||||
|
||||
def write_report(workdir: Path, outputs: list[Path], warnings: list[str], notes: list[str]) -> Path:
|
||||
report = workdir / "生成报告.md"
|
||||
lines = ["# 生成报告", "", "## 输出文件", ""]
|
||||
for path in outputs:
|
||||
size = path.stat().st_size if path.exists() else 0
|
||||
lines.append(f"- `{path.name}` ({size} bytes)")
|
||||
lines.extend(["", "## 警告", ""])
|
||||
if warnings:
|
||||
lines.extend(f"- {warning}" for warning in warnings)
|
||||
else:
|
||||
lines.append("- 无")
|
||||
lines.extend(["", "## DOCX 校验", ""])
|
||||
if notes:
|
||||
lines.extend(notes)
|
||||
else:
|
||||
lines.append("- 已跳过预览校验")
|
||||
report.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
return report
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--workdir", default="软件著作权申请资料")
|
||||
parser.add_argument("--software-name", required=True)
|
||||
parser.add_argument("--version", default="V1.0")
|
||||
parser.add_argument("--skip-preview", action="store_true")
|
||||
args = parser.parse_args()
|
||||
|
||||
workdir = Path(args.workdir)
|
||||
issues = confirmation_issues(workdir)
|
||||
if issues:
|
||||
print("STOP_FOR_USER")
|
||||
print("NEXT_ACTION: 正式 Word/TXT 生成前必须完成以下确认：")
|
||||
for issue in issues:
|
||||
print(f"- {issue}")
|
||||
raise SystemExit(2)
|
||||
|
||||
result = build_all(workdir, args.software_name, args.version, args.skip_preview)
|
||||
print(f"OK final materials: {Path(args.workdir) / '正式资料'}")
|
||||
for output in result["outputs"]:
|
||||
print(output)
|
||||
if result["warnings"]:
|
||||
print("Warnings:")
|
||||
for warning in result["warnings"]:
|
||||
print(f"- {warning}")
|
||||
print(f"Report: {result['report']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,104 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Best-effort screenshot helpers for operation manuals."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import shutil
|
||||
import re
|
||||
from pathlib import Path
|
||||
from urllib.parse import urljoin
|
||||
|
||||
from common import ensure_dir, read_json, write_json
|
||||
|
||||
|
||||
def safe_name(path: str) -> str:
|
||||
value = path.strip("/") or "home"
|
||||
value = re.sub(r"[^A-Za-z0-9._-]+", "_", value)
|
||||
return value[:80] or "page"
|
||||
|
||||
|
||||
def collect_manual_screenshots(input_dir: Path, out_dir: Path) -> dict[str, object]:
|
||||
out_dir = ensure_dir(out_dir)
|
||||
screenshots = []
|
||||
errors = []
|
||||
allowed = {".png", ".jpg", ".jpeg", ".webp"}
|
||||
for index, path in enumerate(sorted(input_dir.iterdir()), start=1):
|
||||
if path.suffix.lower() not in allowed or not path.is_file():
|
||||
continue
|
||||
target = out_dir / f"{index:02d}-{safe_name(path.stem)}{path.suffix.lower()}"
|
||||
if path.resolve() != target.resolve():
|
||||
shutil.copy2(path, target)
|
||||
screenshots.append({"route": "", "url": "", "path": str(target), "source": str(path)})
|
||||
if not screenshots:
|
||||
errors.append({"error": f"no screenshot images found in {input_dir}"})
|
||||
manifest = {
|
||||
"status": "ok" if screenshots else "empty",
|
||||
"method": "user-supplied",
|
||||
"screenshots": screenshots,
|
||||
"errors": errors,
|
||||
}
|
||||
write_json(out_dir / "截图清单.json", manifest)
|
||||
return manifest
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--base-url")
|
||||
parser.add_argument("--analysis")
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/截图")
|
||||
parser.add_argument("--max-pages", type=int, default=8)
|
||||
parser.add_argument("--manual-dir", help="Collect user-supplied screenshots from this directory")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.manual_dir:
|
||||
manifest = collect_manual_screenshots(Path(args.manual_dir), Path(args.out_dir))
|
||||
print(json.dumps(manifest, ensure_ascii=False, indent=2))
|
||||
if not manifest["screenshots"]:
|
||||
raise SystemExit(3)
|
||||
return
|
||||
|
||||
if not args.base_url or not args.analysis:
|
||||
raise SystemExit("Missing --base-url and --analysis unless --manual-dir is provided")
|
||||
|
||||
try:
|
||||
from playwright.sync_api import sync_playwright
|
||||
except Exception as exc:
|
||||
print(json.dumps({"status": "error", "reason": f"playwright unavailable: {exc}"}, ensure_ascii=False))
|
||||
raise SystemExit(2)
|
||||
|
||||
analysis = read_json(Path(args.analysis))
|
||||
paths = analysis.get("routes") or ["/"]
|
||||
clean_paths = []
|
||||
for path in paths:
|
||||
if isinstance(path, str) and path.startswith("/") and path not in clean_paths:
|
||||
clean_paths.append(path)
|
||||
clean_paths = clean_paths[: args.max_pages] or ["/"]
|
||||
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
screenshots = []
|
||||
errors = []
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page(viewport={"width": 1440, "height": 1000})
|
||||
for route in clean_paths:
|
||||
url = urljoin(args.base_url.rstrip("/") + "/", route.lstrip("/"))
|
||||
file_path = out_dir / f"{safe_name(route)}.png"
|
||||
try:
|
||||
page.goto(url, wait_until="networkidle", timeout=15_000)
|
||||
page.screenshot(path=str(file_path), full_page=True)
|
||||
screenshots.append({"route": route, "url": url, "path": str(file_path)})
|
||||
except Exception as exc:
|
||||
errors.append({"route": route, "url": url, "error": str(exc)})
|
||||
browser.close()
|
||||
|
||||
manifest = {"status": "ok" if screenshots else "partial", "screenshots": screenshots, "errors": errors}
|
||||
write_json(out_dir / "截图清单.json", manifest)
|
||||
print(json.dumps(manifest, ensure_ascii=False, indent=2))
|
||||
if not screenshots:
|
||||
raise SystemExit(3)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,150 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Check runtime capabilities at the beginning of the workflow."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import importlib.util
|
||||
import shutil
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import ensure_dir, write_json
|
||||
|
||||
|
||||
def command_version(command: list[str]) -> tuple[bool, str]:
|
||||
if not shutil.which(command[0]):
|
||||
return False, "not found"
|
||||
try:
|
||||
completed = subprocess.run(command, text=True, capture_output=True, timeout=20)
|
||||
output = (completed.stdout or completed.stderr).strip().splitlines()
|
||||
return completed.returncode == 0, output[0] if output else "available"
|
||||
except Exception as exc:
|
||||
return False, str(exc)
|
||||
|
||||
|
||||
def run_docx_env(skill_dir: Path) -> tuple[bool, str]:
|
||||
env_script = skill_dir / "vendor/docx-toolkit/scripts/env_check.sh"
|
||||
if not env_script.exists():
|
||||
return False, "vendor/docx-toolkit/scripts/env_check.sh not found"
|
||||
try:
|
||||
completed = subprocess.run(["bash", str(env_script)], text=True, capture_output=True, timeout=40)
|
||||
return completed.returncode == 0, (completed.stdout + completed.stderr).strip()
|
||||
except Exception as exc:
|
||||
return False, str(exc)
|
||||
|
||||
|
||||
def module_available(name: str) -> bool:
|
||||
return importlib.util.find_spec(name) is not None
|
||||
|
||||
|
||||
def check_environment(skill_dir: Path) -> dict[str, Any]:
|
||||
python_docx = module_available("docx")
|
||||
pandoc_ok, pandoc_version = command_version(["pandoc", "--version"])
|
||||
dotnet_ok, dotnet_version = command_version(["dotnet", "--version"])
|
||||
docx_ready, docx_output = run_docx_env(skill_dir)
|
||||
|
||||
final_docx_mode = "docx-openxml" if docx_ready else ("python-docx" if python_docx else "basic-ooxml")
|
||||
requires_user_input = not docx_ready
|
||||
next_action = (
|
||||
"请选择：1) 安装完整 DOCX 环境；2) 使用基础 DOCX 兜底继续。回复选择后再进入项目分析。"
|
||||
if requires_user_input
|
||||
else "完整 DOCX 环境可用，可以进入项目分析。"
|
||||
)
|
||||
return {
|
||||
"output_directory": "当前目录/软件著作权申请资料",
|
||||
"capabilities": {
|
||||
"markdown_drafts": True,
|
||||
"application_txt": True,
|
||||
"basic_docx": python_docx or True,
|
||||
"python_docx": python_docx,
|
||||
"pandoc_preview": pandoc_ok,
|
||||
"docx_openxml_full": docx_ready,
|
||||
"dotnet_sdk": dotnet_ok,
|
||||
},
|
||||
"versions": {
|
||||
"pandoc": pandoc_version,
|
||||
"dotnet": dotnet_version,
|
||||
},
|
||||
"final_docx_mode": final_docx_mode,
|
||||
"recommendation": (
|
||||
"完整 DOCX OpenXML 环境已就绪，建议使用完整 Word 生成和校验流程。"
|
||||
if docx_ready
|
||||
else "完整 DOCX OpenXML 环境未就绪。可以继续使用兜底 DOCX 生成；如需更规范的 Word 结构和校验，请先安装 .NET SDK 并运行 vendor/docx-toolkit/scripts/setup.sh。"
|
||||
),
|
||||
"install_prompt": (
|
||||
"是否安装完整 DOCX 环境？安装后文档生成和校验更规范；不安装也可以继续生成 Markdown、TXT 和基础 DOCX。"
|
||||
if not docx_ready
|
||||
else "无需安装，完整环境可用。"
|
||||
),
|
||||
"requires_user_input": requires_user_input,
|
||||
"confirmation_stage": "environment" if requires_user_input else None,
|
||||
"next_action": next_action,
|
||||
"docx_env_output": docx_output,
|
||||
}
|
||||
|
||||
|
||||
def write_markdown(path: Path, data: dict[str, Any]) -> None:
|
||||
caps = data["capabilities"]
|
||||
lines = [
|
||||
"# 软著申请资料生成环境检查",
|
||||
"",
|
||||
f"- 输出目录：`{data['output_directory']}`",
|
||||
f"- 最终 Word 模式：`{data['final_docx_mode']}`",
|
||||
"",
|
||||
"## 能力状态",
|
||||
"",
|
||||
f"- Markdown 草稿：{'可用' if caps['markdown_drafts'] else '不可用'}",
|
||||
f"- 申请表 TXT：{'可用' if caps['application_txt'] else '不可用'}",
|
||||
f"- 基础 DOCX 生成：{'可用' if caps['basic_docx'] else '不可用'}",
|
||||
f"- python-docx：{'可用' if caps['python_docx'] else '不可用'}",
|
||||
f"- pandoc 预览：{'可用' if caps['pandoc_preview'] else '不可用'}（{data['versions']['pandoc']}）",
|
||||
f"- .NET SDK：{'可用' if caps['dotnet_sdk'] else '不可用'}（{data['versions']['dotnet']}）",
|
||||
f"- DOCX OpenXML 完整环境：{'可用' if caps['docx_openxml_full'] else '不可用'}",
|
||||
"",
|
||||
"## 建议",
|
||||
"",
|
||||
data["recommendation"],
|
||||
"",
|
||||
"## 用户选择",
|
||||
"",
|
||||
data["install_prompt"],
|
||||
"",
|
||||
"如果完整 DOCX 环境不可用，必须先等待用户选择，并记录 `environment` 门禁后再继续。",
|
||||
"",
|
||||
"```text" if data.get("requires_user_input") else "",
|
||||
"STOP_FOR_USER" if data.get("requires_user_input") else "",
|
||||
f"NEXT_ACTION: {data['next_action']}" if data.get("requires_user_input") else "",
|
||||
"```" if data.get("requires_user_input") else "",
|
||||
"",
|
||||
"## DOCX 环境输出摘要",
|
||||
"",
|
||||
"```text",
|
||||
"\n".join(data["docx_env_output"].splitlines()[:40]),
|
||||
"```",
|
||||
"",
|
||||
]
|
||||
path.write_text("\n".join(lines), encoding="utf-8")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料")
|
||||
args = parser.parse_args()
|
||||
|
||||
skill_dir = Path(__file__).resolve().parents[1]
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
data = check_environment(skill_dir)
|
||||
write_json(out_dir / "环境检查.json", data)
|
||||
write_markdown(out_dir / "环境检查.md", data)
|
||||
print(f"OK environment check: {out_dir}")
|
||||
print(f"Final DOCX mode: {data['final_docx_mode']}")
|
||||
print(data["recommendation"])
|
||||
if data.get("requires_user_input"):
|
||||
print("STOP_FOR_USER")
|
||||
print(f"NEXT_ACTION: {data['next_action']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,258 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Shared helpers for the software copyright materials skill."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterable
|
||||
|
||||
|
||||
EXCLUDE_DIRS = {
|
||||
".git",
|
||||
".hg",
|
||||
".svn",
|
||||
".idea",
|
||||
".vscode",
|
||||
"__pycache__",
|
||||
"node_modules",
|
||||
"dist",
|
||||
"build",
|
||||
".next",
|
||||
".nuxt",
|
||||
".output",
|
||||
"coverage",
|
||||
"target",
|
||||
"vendor",
|
||||
"软件著作权申请资料",
|
||||
"software-copyright-materials",
|
||||
}
|
||||
|
||||
CODE_EXTS = {
|
||||
".vue",
|
||||
".ts",
|
||||
".tsx",
|
||||
".js",
|
||||
".jsx",
|
||||
".mjs",
|
||||
".cjs",
|
||||
".css",
|
||||
".scss",
|
||||
".sass",
|
||||
".less",
|
||||
".html",
|
||||
".svelte",
|
||||
".astro",
|
||||
".json",
|
||||
".md",
|
||||
}
|
||||
|
||||
KNOWN_CONFIG_FILES = {
|
||||
".babelrc",
|
||||
".eslintrc",
|
||||
".eslintrc.json",
|
||||
".eslintrc.yaml",
|
||||
".eslintrc.yml",
|
||||
".prettierrc",
|
||||
".prettierrc.json",
|
||||
".prettierrc.yaml",
|
||||
".prettierrc.yml",
|
||||
".swcrc",
|
||||
"angular.json",
|
||||
"app.json",
|
||||
"astro.config.mjs",
|
||||
"astro.config.ts",
|
||||
"babel.config.js",
|
||||
"babel.config.json",
|
||||
"Cargo.lock",
|
||||
"Cargo.toml",
|
||||
"composer.json",
|
||||
"docker-compose.yaml",
|
||||
"docker-compose.yml",
|
||||
"eslint.config.cjs",
|
||||
"eslint.config.js",
|
||||
"eslint.config.mjs",
|
||||
"go.mod",
|
||||
"go.sum",
|
||||
"jsconfig.json",
|
||||
"lerna.json",
|
||||
"manifest.json",
|
||||
"next.config.js",
|
||||
"next.config.mjs",
|
||||
"next.config.ts",
|
||||
"nuxt.config.js",
|
||||
"nuxt.config.ts",
|
||||
"nx.json",
|
||||
"package-lock.json",
|
||||
"package.json",
|
||||
"playwright.config.js",
|
||||
"playwright.config.ts",
|
||||
"postcss.config.cjs",
|
||||
"postcss.config.js",
|
||||
"prettier.config.cjs",
|
||||
"prettier.config.js",
|
||||
"prettier.config.mjs",
|
||||
"project.json",
|
||||
"pyproject.toml",
|
||||
"rollup.config.js",
|
||||
"rollup.config.mjs",
|
||||
"rollup.config.ts",
|
||||
"svelte.config.js",
|
||||
"stylelintrc.json",
|
||||
"tailwind.config.js",
|
||||
"tailwind.config.ts",
|
||||
"tsconfig.app.json",
|
||||
"tsconfig.json",
|
||||
"tsconfig.node.json",
|
||||
"tslint.json",
|
||||
"turbo.json",
|
||||
"vite.config.js",
|
||||
"vite.config.mjs",
|
||||
"vite.config.ts",
|
||||
"vitest.config.js",
|
||||
"vitest.config.ts",
|
||||
"webpack.config.js",
|
||||
"webpack.config.ts",
|
||||
"workspace.json",
|
||||
}
|
||||
|
||||
FRONTEND_EXTS = {
|
||||
".vue",
|
||||
".ts",
|
||||
".tsx",
|
||||
".js",
|
||||
".jsx",
|
||||
".mjs",
|
||||
".css",
|
||||
".scss",
|
||||
".sass",
|
||||
".less",
|
||||
".html",
|
||||
".svelte",
|
||||
".astro",
|
||||
}
|
||||
|
||||
SUPPLEMENT_CODE_EXTS = {
|
||||
".py",
|
||||
".java",
|
||||
".go",
|
||||
".rs",
|
||||
".cs",
|
||||
".php",
|
||||
".rb",
|
||||
".kt",
|
||||
".swift",
|
||||
".sql",
|
||||
".sh",
|
||||
".json",
|
||||
}
|
||||
|
||||
COPYRIGHT_CODE_EXTS = FRONTEND_EXTS | SUPPLEMENT_CODE_EXTS
|
||||
|
||||
LOCK_FILES = {
|
||||
"package-lock.json",
|
||||
"pnpm-lock.yaml",
|
||||
"yarn.lock",
|
||||
"bun.lockb",
|
||||
"bun.lock",
|
||||
}
|
||||
|
||||
|
||||
def repo_root_from_script() -> Path:
|
||||
return Path(__file__).resolve().parents[3]
|
||||
|
||||
|
||||
def is_excluded(path: Path) -> bool:
|
||||
parts = set(path.parts)
|
||||
if parts & EXCLUDE_DIRS:
|
||||
return True
|
||||
name = path.name
|
||||
if name.startswith(".") and name not in {".env.example"}:
|
||||
return True
|
||||
if name in LOCK_FILES:
|
||||
return True
|
||||
if name.endswith(".map") or name.endswith(".min.js") or name.endswith(".min.css"):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def iter_project_files(project: Path, exts: set[str] | None = None) -> Iterable[Path]:
|
||||
project = project.resolve()
|
||||
for root, dirs, files in os.walk(project):
|
||||
root_path = Path(root)
|
||||
dirs[:] = [d for d in dirs if not is_excluded(root_path / d)]
|
||||
for filename in files:
|
||||
path = root_path / filename
|
||||
if is_excluded(path):
|
||||
continue
|
||||
if exts is not None and path.suffix.lower() not in exts:
|
||||
continue
|
||||
yield path
|
||||
|
||||
|
||||
def rel(path: Path, root: Path) -> str:
|
||||
return path.resolve().relative_to(root.resolve()).as_posix()
|
||||
|
||||
|
||||
def read_text(path: Path, limit: int | None = None) -> str:
|
||||
data = path.read_bytes()
|
||||
if limit is not None:
|
||||
data = data[:limit]
|
||||
for encoding in ("utf-8", "utf-8-sig", "gb18030", "latin-1"):
|
||||
try:
|
||||
return data.decode(encoding)
|
||||
except UnicodeDecodeError:
|
||||
continue
|
||||
return data.decode("utf-8", errors="replace")
|
||||
|
||||
|
||||
def read_json(path: Path) -> dict[str, Any]:
|
||||
return json.loads(read_text(path))
|
||||
|
||||
|
||||
def write_json(path: Path, data: Any) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
|
||||
|
||||
def count_text_lines(path: Path, skip_blank: bool = True) -> int:
|
||||
try:
|
||||
text = read_text(path)
|
||||
except Exception:
|
||||
return 0
|
||||
if not text:
|
||||
return 0
|
||||
if skip_blank:
|
||||
return sum(1 for line in text.splitlines() if line.strip())
|
||||
return len(text.splitlines())
|
||||
|
||||
|
||||
def is_known_config_file(path: Path) -> bool:
|
||||
"""Return True for well-known config files that shouldn't count as source code."""
|
||||
return path.name in KNOWN_CONFIG_FILES
|
||||
|
||||
|
||||
def looks_binary(path: Path) -> bool:
|
||||
try:
|
||||
chunk = path.read_bytes()[:4096]
|
||||
except Exception:
|
||||
return True
|
||||
return b"\x00" in chunk
|
||||
|
||||
|
||||
def normalize_title(value: str) -> str:
|
||||
value = re.sub(r"[-_]+", " ", value).strip()
|
||||
value = re.sub(r"\s+", " ", value)
|
||||
return value or "待命名软件"
|
||||
|
||||
|
||||
def safe_filename(value: str) -> str:
|
||||
value = re.sub(r'[\\/:*?"<>|]+', "_", value).strip()
|
||||
return value or "软件"
|
||||
|
||||
|
||||
def ensure_dir(path: Path) -> Path:
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
return path
|
||||
@@ -0,0 +1,199 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Record explicit user confirmations for gated workflow stages."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import read_json, write_json
|
||||
|
||||
|
||||
def timestamp() -> str:
|
||||
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
||||
|
||||
|
||||
def load_json_or_empty(path: Path) -> dict[str, Any]:
|
||||
if not path.exists():
|
||||
return {}
|
||||
return read_json(path)
|
||||
|
||||
|
||||
def write_confirmation(path: Path, data: dict[str, Any], key: str, note: str) -> None:
|
||||
data[key] = True
|
||||
data["confirmation_note"] = note
|
||||
data["confirmed_at"] = timestamp()
|
||||
write_json(path, data)
|
||||
|
||||
|
||||
def pending_application_fields(md_path: Path) -> list[str]:
|
||||
if not md_path.exists():
|
||||
return [f"缺少 {md_path}"]
|
||||
return [line.strip() for line in md_path.read_text(encoding="utf-8").splitlines() if "待用户确认" in line]
|
||||
|
||||
|
||||
def confirm_environment(workdir: Path, note: str) -> Path:
|
||||
out_path = workdir / "环境确认.json"
|
||||
data = load_json_or_empty(out_path)
|
||||
write_confirmation(out_path, data, "environment_confirmed", note)
|
||||
return out_path
|
||||
|
||||
|
||||
def confirm_project(workdir: Path, note: str) -> Path:
|
||||
out_path = workdir / "项目确认.json"
|
||||
data = load_json_or_empty(out_path)
|
||||
write_confirmation(out_path, data, "project_confirmed", note)
|
||||
return out_path
|
||||
|
||||
|
||||
def confirm_business(workdir: Path, note: str) -> Path:
|
||||
path = workdir / "草稿/业务理解.json"
|
||||
if not path.exists():
|
||||
raise SystemExit("Missing 草稿/业务理解.json")
|
||||
data = read_json(path)
|
||||
write_confirmation(path, data, "user_confirmed", note)
|
||||
return path
|
||||
|
||||
|
||||
def confirm_code_selection(workdir: Path, note: str) -> Path:
|
||||
path = workdir / "草稿/代码文件选择.json"
|
||||
if not path.exists():
|
||||
raise SystemExit("Missing 草稿/代码文件选择.json")
|
||||
data = read_json(path)
|
||||
files = data.get("files") if isinstance(data, dict) else []
|
||||
selected = [item for item in files if isinstance(item, dict) and item.get("selected")]
|
||||
if not selected:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 代码文件选择尚未由模型填写。请先选择至少一个源码文件并填写选择理由，再让用户确认。"
|
||||
)
|
||||
missing_reason = [item.get("path") for item in selected if not str(item.get("model_reason") or "").strip()]
|
||||
if data.get("model_selection_required") and missing_reason:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 已选源码缺少模型选择理由，请补全 `model_reason` 后再确认。\n"
|
||||
+ "\n".join(f"- {item}" for item in missing_reason[:20])
|
||||
)
|
||||
write_confirmation(path, data, "user_confirmed", note)
|
||||
return path
|
||||
|
||||
|
||||
def parse_screenshot_method(method: str, note: str) -> str:
|
||||
value = (method or note or "").lower()
|
||||
if any(key in value for key in ("skip", "no-screenshot", "none", "不截图", "跳过", "暂不", "先不", "不要截图", "无需截图")):
|
||||
return "skip"
|
||||
if any(key in value for key in ("chrome", "devtools", "mcp")):
|
||||
return "chrome-devtools"
|
||||
if any(key in value for key in ("computer", "use", "电脑", "桌面")):
|
||||
return "computer-use"
|
||||
if any(key in value for key in ("user", "manual", "self", "手动", "自己", "用户")):
|
||||
return "user-supplied"
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 请明确截图方式：chrome-devtools、computer-use、user-supplied 或 skip。"
|
||||
)
|
||||
|
||||
|
||||
def confirm_screenshot_method(workdir: Path, note: str, method: str) -> Path:
|
||||
selected = parse_screenshot_method(method, note)
|
||||
out_path = workdir / "截图方式确认.json"
|
||||
data = load_json_or_empty(out_path)
|
||||
data["screenshot_method"] = selected
|
||||
write_confirmation(out_path, data, "screenshot_method_confirmed", note)
|
||||
return out_path
|
||||
|
||||
|
||||
def confirm_application_fields(workdir: Path, note: str) -> Path:
|
||||
pending = pending_application_fields(workdir / "草稿/申请表信息.md")
|
||||
if pending:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 申请表信息仍包含“待用户确认”。请先补全字段，再重新确认。\n"
|
||||
+ "\n".join(f"- {item}" for item in pending[:20])
|
||||
)
|
||||
out_path = workdir / "草稿/申请表字段确认.json"
|
||||
data = load_json_or_empty(out_path)
|
||||
write_confirmation(out_path, data, "application_fields_confirmed", note)
|
||||
return out_path
|
||||
|
||||
|
||||
def confirm_markdown(workdir: Path, note: str) -> Path:
|
||||
issues = []
|
||||
business = workdir / "草稿/业务理解.json"
|
||||
selection = workdir / "草稿/代码文件选择.json"
|
||||
screenshot = workdir / "截图方式确认.json"
|
||||
fields = workdir / "草稿/申请表字段确认.json"
|
||||
|
||||
if not business.exists() or not read_json(business).get("user_confirmed"):
|
||||
issues.append("业务理解尚未确认")
|
||||
if not selection.exists() or not read_json(selection).get("user_confirmed"):
|
||||
issues.append("代码文件选择尚未确认")
|
||||
if not screenshot.exists() or not read_json(screenshot).get("screenshot_method_confirmed"):
|
||||
issues.append("截图方式尚未确认")
|
||||
if not fields.exists() or not read_json(fields).get("application_fields_confirmed"):
|
||||
issues.append("申请表字段尚未确认")
|
||||
pending = pending_application_fields(workdir / "草稿/申请表信息.md")
|
||||
if pending:
|
||||
issues.append("申请表信息仍包含“待用户确认”")
|
||||
|
||||
if issues:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: Markdown 草稿确认前需要先处理以下事项：\n"
|
||||
+ "\n".join(f"- {item}" for item in issues)
|
||||
)
|
||||
|
||||
out_path = workdir / "草稿/最终生成确认.json"
|
||||
data = load_json_or_empty(out_path)
|
||||
write_confirmation(out_path, data, "markdown_confirmed", note)
|
||||
return out_path
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--workdir", default="软件著作权申请资料")
|
||||
parser.add_argument(
|
||||
"--stage",
|
||||
required=True,
|
||||
choices=[
|
||||
"environment",
|
||||
"project",
|
||||
"business",
|
||||
"code-selection",
|
||||
"screenshot-method",
|
||||
"application-fields",
|
||||
"markdown",
|
||||
],
|
||||
)
|
||||
parser.add_argument("--note", default="用户已确认")
|
||||
parser.add_argument(
|
||||
"--method",
|
||||
choices=["chrome-devtools", "computer-use", "user-supplied", "skip"],
|
||||
help="Screenshot capture method when --stage screenshot-method",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
workdir = Path(args.workdir)
|
||||
if args.stage == "environment":
|
||||
path = confirm_environment(workdir, args.note)
|
||||
elif args.stage == "project":
|
||||
path = confirm_project(workdir, args.note)
|
||||
elif args.stage == "business":
|
||||
path = confirm_business(workdir, args.note)
|
||||
elif args.stage == "code-selection":
|
||||
path = confirm_code_selection(workdir, args.note)
|
||||
elif args.stage == "screenshot-method":
|
||||
path = confirm_screenshot_method(workdir, args.note, args.method or "")
|
||||
elif args.stage == "application-fields":
|
||||
path = confirm_application_fields(workdir, args.note)
|
||||
else:
|
||||
path = confirm_markdown(workdir, args.note)
|
||||
|
||||
print(f"OK confirmation recorded: {args.stage}")
|
||||
print(path)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,308 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Extract real source code and create Markdown draft pages."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import COPYRIGHT_CODE_EXTS, FRONTEND_EXTS, ensure_dir, is_known_config_file, iter_project_files, looks_binary, read_json, read_text, rel, safe_filename, write_json
|
||||
|
||||
|
||||
LINES_PER_PAGE = 50
|
||||
SPLIT_THRESHOLD_PAGES = 60
|
||||
|
||||
|
||||
def category_weight(path: Path, project: Path) -> tuple[int, str]:
|
||||
r = rel(path, project).lower()
|
||||
name = path.name.lower()
|
||||
priority = 80
|
||||
if name in {"main.ts", "main.js", "main.tsx", "main.jsx", "app.vue", "app.tsx"} or r in {
|
||||
"src/app/page.tsx",
|
||||
"src/app/layout.tsx",
|
||||
"app/page.tsx",
|
||||
"app/layout.tsx",
|
||||
} or r.endswith("/src/app/page.tsx") or r.endswith("/src/app/layout.tsx"):
|
||||
priority = 0
|
||||
elif path.suffix.lower() in {".css", ".scss", ".sass", ".less"}:
|
||||
priority = 90
|
||||
elif "/router/" in r or "/routes/" in r or "router." in r or "routes." in r:
|
||||
priority = 10
|
||||
elif "/pages/" in r or "/views/" in r or "/app/" in r or "/screens/" in r:
|
||||
priority = 20
|
||||
elif "/api/" in r or "/apis/" in r or "/services/" in r or "request." in r:
|
||||
priority = 30
|
||||
elif "/store/" in r or "/stores/" in r or "/pinia/" in r or "/redux/" in r:
|
||||
priority = 40
|
||||
elif "/components/" in r:
|
||||
priority = 50
|
||||
elif "/utils/" in r or "/lib/" in r or "/hooks/" in r or "/composables/" in r:
|
||||
priority = 60
|
||||
elif path.suffix.lower() not in FRONTEND_EXTS:
|
||||
if any(part in r for part in ("/backend/app/", "/server/", "/api/", "/services/", "/models/", "/schemas/", "/workers/")):
|
||||
priority = 70
|
||||
elif name in {"docker-compose.yml", "docker-compose.yaml", "pyproject.toml"} or path.suffix.lower() in {".toml", ".yml", ".yaml"}:
|
||||
priority = 95
|
||||
else:
|
||||
priority = 100
|
||||
return priority, r
|
||||
|
||||
|
||||
def should_skip_file(path: Path) -> bool:
|
||||
if path.suffix.lower() not in COPYRIGHT_CODE_EXTS:
|
||||
return True
|
||||
if is_known_config_file(path):
|
||||
return True
|
||||
if looks_binary(path):
|
||||
return True
|
||||
try:
|
||||
size = path.stat().st_size
|
||||
except OSError:
|
||||
return True
|
||||
if size <= 0 or size > 800_000:
|
||||
return True
|
||||
try:
|
||||
sample = read_text(path, limit=20_000)
|
||||
except Exception:
|
||||
return True
|
||||
lines = sample.splitlines()
|
||||
if any(len(line) > 3000 for line in lines[:80]):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def selected_line_estimate(item: dict[str, Any]) -> int:
|
||||
try:
|
||||
total = int(item.get("line_count") or 0)
|
||||
except (TypeError, ValueError):
|
||||
total = 0
|
||||
return total + 2 if total > 0 else 0
|
||||
|
||||
|
||||
def available_pages_from_selection(selection_path: Path | None, lines_per_page: int) -> tuple[int, int, int]:
|
||||
if selection_path is None or not selection_path.exists():
|
||||
return 0, 0, 0
|
||||
data = read_json(selection_path)
|
||||
items = data.get("files") if isinstance(data, dict) else []
|
||||
if not isinstance(items, list):
|
||||
return 0, 0, 0
|
||||
available_lines = sum(selected_line_estimate(item) for item in items if isinstance(item, dict))
|
||||
unselected = sum(1 for item in items if isinstance(item, dict) and not item.get("selected") and selected_line_estimate(item) > 0)
|
||||
pages = (available_lines + lines_per_page - 1) // lines_per_page if available_lines else 0
|
||||
return available_lines, pages, unselected
|
||||
|
||||
|
||||
def marker_for(path: Path, project: Path) -> str:
|
||||
return f"// File: {rel(path, project)}"
|
||||
|
||||
|
||||
def load_selected_files(project: Path, selection_path: Path | None) -> list[dict[str, Any]]:
|
||||
if selection_path is None:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 代码抽取必须先使用 propose_code_selection.py 生成并确认 草稿/代码文件选择.json。"
|
||||
)
|
||||
|
||||
data = read_json(selection_path)
|
||||
if isinstance(data, dict) and data.get("selection_required") and not data.get("user_confirmed"):
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 代码文件选择尚未确认。请先确认或修改 草稿/代码文件选择.json，"
|
||||
"再运行 `python3 <SKILL_DIR>/scripts/confirm_stage.py --workdir 软件著作权申请资料 --stage code-selection --note \"<用户确认内容>\"`。"
|
||||
)
|
||||
items = data.get("files") if isinstance(data, dict) else data
|
||||
if not isinstance(items, list):
|
||||
raise SystemExit(f"Invalid selection file: {selection_path}")
|
||||
|
||||
selected = []
|
||||
for item in items:
|
||||
if not isinstance(item, dict) or not item.get("selected"):
|
||||
continue
|
||||
path_value = item.get("path")
|
||||
if not path_value:
|
||||
continue
|
||||
selected.append(
|
||||
{
|
||||
"path": str(path_value),
|
||||
"selected": True,
|
||||
}
|
||||
)
|
||||
return selected
|
||||
|
||||
|
||||
def collect_code_lines(project: Path, selection_path: Path | None) -> tuple[list[str], list[dict[str, Any]]]:
|
||||
selected_items = load_selected_files(project, selection_path)
|
||||
all_lines: list[str] = []
|
||||
manifest_files: list[dict[str, Any]] = []
|
||||
|
||||
for item in selected_items:
|
||||
path = (project / item["path"]).resolve()
|
||||
try:
|
||||
path.relative_to(project.resolve())
|
||||
except ValueError:
|
||||
raise SystemExit(f"Selected file is outside project: {path}")
|
||||
if should_skip_file(path):
|
||||
continue
|
||||
text = read_text(path)
|
||||
source_lines = text.splitlines()
|
||||
selected_lines = source_lines
|
||||
start = len(all_lines) + 1
|
||||
marker = marker_for(path, project)
|
||||
all_lines.append(marker)
|
||||
all_lines.extend(selected_lines)
|
||||
all_lines.append("")
|
||||
end = len(all_lines)
|
||||
source_end_line = len(source_lines)
|
||||
manifest_files.append(
|
||||
{
|
||||
"path": rel(path, project),
|
||||
"source_line_count": len(source_lines),
|
||||
"selected_line_start": 1,
|
||||
"selected_line_end": source_end_line,
|
||||
"selected_line_count": len(selected_lines),
|
||||
"material_line_start": start,
|
||||
"material_line_end": end,
|
||||
}
|
||||
)
|
||||
return all_lines, manifest_files
|
||||
|
||||
|
||||
def paginate(lines: list[str], lines_per_page: int) -> list[list[str]]:
|
||||
return [lines[i : i + lines_per_page] for i in range(0, len(lines), lines_per_page)]
|
||||
|
||||
|
||||
def write_pages_md(path: Path, title: str, software_name: str, version: str, pages: list[tuple[int, list[str]]]) -> None:
|
||||
chunks = [f"# {title}", "", f"软件名称：{software_name}", f"版本号：{version}", ""]
|
||||
for page_no, page_lines in pages:
|
||||
chunks.extend([f"## 第 {page_no} 页", "", "```text"])
|
||||
chunks.extend(page_lines)
|
||||
chunks.extend(["```", ""])
|
||||
path.write_text("\n".join(chunks), encoding="utf-8")
|
||||
|
||||
|
||||
def write_manifest_md(path: Path, manifest: dict[str, Any]) -> None:
|
||||
lines = [
|
||||
"# 代码提取清单",
|
||||
"",
|
||||
f"- 软件名称：{manifest['software_name']}",
|
||||
f"- 版本号：{manifest['version']}",
|
||||
f"- 项目目录：{manifest['project_root']}",
|
||||
f"- 源码文件数：{manifest['file_count']}",
|
||||
f"- 材料代码行数：{manifest['material_line_count']}",
|
||||
f"- 每页行数：{manifest['lines_per_page']}",
|
||||
f"- 总页数：{manifest['total_pages']}",
|
||||
f"- 目标页数：{manifest['target_pages']}",
|
||||
f"- 候选源码可生成页数：{manifest['available_candidate_pages']}",
|
||||
f"- 补充状态：{manifest['supplement_status']}",
|
||||
f"- 输出模式：{manifest['mode']}",
|
||||
"",
|
||||
"## 文件来源",
|
||||
"",
|
||||
"| 文件 | 源码行数 | 抽取源码范围 | 抽取行数 | 材料行范围 |",
|
||||
"| --- | ---: | --- | ---: | --- |",
|
||||
]
|
||||
for item in manifest["files"]:
|
||||
lines.append(
|
||||
f"| `{item['path']}` | {item['source_line_count']} | "
|
||||
f"{item['selected_line_start']}-{item['selected_line_end']} | "
|
||||
f"{item['selected_line_count']} | "
|
||||
f"{item['material_line_start']}-{item['material_line_end']} |"
|
||||
)
|
||||
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def extract(project: Path, out_dir: Path, software_name: str, version: str, lines_per_page: int, selection_path: Path | None) -> dict[str, Any]:
|
||||
ensure_dir(out_dir)
|
||||
code_lines, files = collect_code_lines(project, selection_path)
|
||||
if not code_lines:
|
||||
raise SystemExit("No selected frontend source code files found for extraction.")
|
||||
|
||||
pages = paginate(code_lines, lines_per_page)
|
||||
total_pages = len(pages)
|
||||
available_lines, available_pages, unselected_count = available_pages_from_selection(selection_path, lines_per_page)
|
||||
if total_pages < SPLIT_THRESHOLD_PAGES and available_pages >= SPLIT_THRESHOLD_PAGES and unselected_count > 0:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
f"NEXT_ACTION: 当前已选代码只有 {total_pages} 页，但候选源码足够补齐到 {SPLIT_THRESHOLD_PAGES} 页。"
|
||||
"请在 草稿/代码文件选择.json 中继续选择补充文件，重新记录 code-selection 门禁后再抽取。"
|
||||
)
|
||||
outputs: list[str] = []
|
||||
|
||||
if total_pages >= SPLIT_THRESHOLD_PAGES:
|
||||
front = list(enumerate(pages[:30], start=1))
|
||||
back = [(31 + i, page) for i, page in enumerate(pages[-30:])]
|
||||
front_path = out_dir / "代码-前30页.md"
|
||||
back_path = out_dir / "代码-后30页.md"
|
||||
write_pages_md(front_path, "代码材料（前30页）", software_name, version, front)
|
||||
write_pages_md(back_path, "代码材料（后30页）", software_name, version, back)
|
||||
outputs.extend([front_path.name, back_path.name])
|
||||
mode = "front30_back30"
|
||||
else:
|
||||
all_path = out_dir / "代码-全部.md"
|
||||
all_pages = list(enumerate(pages, start=1))
|
||||
write_pages_md(all_path, "代码材料（全部）", software_name, version, all_pages)
|
||||
outputs.append(all_path.name)
|
||||
mode = "all_under_60_pages"
|
||||
supplement_status = (
|
||||
"候选源码可达到前30页/后30页要求"
|
||||
if available_pages >= SPLIT_THRESHOLD_PAGES
|
||||
else "候选源码不足60页，按全部代码材料生成"
|
||||
)
|
||||
|
||||
manifest = {
|
||||
"software_name": software_name,
|
||||
"version": version,
|
||||
"project_root": str(project.resolve()),
|
||||
"file_count": len(files),
|
||||
"material_line_count": len(code_lines),
|
||||
"source_line_count": sum(item["source_line_count"] for item in files),
|
||||
"selected_source_line_count": sum(item["selected_line_count"] for item in files),
|
||||
"lines_per_page": lines_per_page,
|
||||
"total_pages": total_pages,
|
||||
"target_pages": SPLIT_THRESHOLD_PAGES,
|
||||
"available_candidate_line_count": available_lines,
|
||||
"available_candidate_pages": available_pages,
|
||||
"supplement_status": supplement_status,
|
||||
"mode": mode,
|
||||
"selection_file": str(selection_path) if selection_path else None,
|
||||
"outputs": outputs,
|
||||
"files": files,
|
||||
"safe_software_filename": safe_filename(software_name),
|
||||
}
|
||||
write_json(out_dir / "代码提取清单.json", manifest)
|
||||
write_manifest_md(out_dir / "代码提取清单.md", manifest)
|
||||
return manifest
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--project", required=True)
|
||||
parser.add_argument("--analysis", help="Optional project analysis JSON; retained for workflow traceability")
|
||||
parser.add_argument("--software-name", required=True)
|
||||
parser.add_argument("--version", default="V1.0")
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||||
parser.add_argument("--lines-per-page", type=int, default=LINES_PER_PAGE)
|
||||
parser.add_argument("--selection", help="Editable JSON file created by propose_code_selection.py")
|
||||
args = parser.parse_args()
|
||||
|
||||
project = Path(args.project)
|
||||
if not project.exists():
|
||||
raise SystemExit(f"Project not found: {project}")
|
||||
if args.analysis and not Path(args.analysis).exists():
|
||||
raise SystemExit(f"Analysis JSON not found: {args.analysis}")
|
||||
|
||||
selection = Path(args.selection) if args.selection else None
|
||||
if selection and not selection.exists():
|
||||
raise SystemExit(f"Selection JSON not found: {selection}")
|
||||
|
||||
manifest = extract(project, Path(args.out_dir), args.software_name, args.version, args.lines_per_page, selection)
|
||||
print(f"OK code drafts: {args.out_dir}")
|
||||
print(f"Selected files: {manifest['file_count']}")
|
||||
print(f"Mode: {manifest['mode']}")
|
||||
print(f"Total pages: {manifest['total_pages']}")
|
||||
print(f"Outputs: {', '.join(manifest['outputs'])}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,719 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate the Markdown draft for application form information."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import os
|
||||
import platform
|
||||
import re
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import ensure_dir, read_json, read_text
|
||||
|
||||
|
||||
MIN_MAIN_FUNCTION_CHARS = 500
|
||||
MAX_MAIN_FUNCTION_CHARS = 1300
|
||||
|
||||
|
||||
FIELD_ORDER = [
|
||||
"软件全称",
|
||||
"软件简称",
|
||||
"版本号",
|
||||
"软件分类",
|
||||
"开发完成日期",
|
||||
"开发方式",
|
||||
"软件说明",
|
||||
"发表状态",
|
||||
"首次发表日期",
|
||||
"著作权人",
|
||||
"权利范围",
|
||||
"权利取得方式",
|
||||
"开发的硬件环境",
|
||||
"运行的硬件环境",
|
||||
"开发该软件的操作系统",
|
||||
"软件开发环境 / 开发工具",
|
||||
"该软件的运行平台 / 操作系统",
|
||||
"软件运行支撑环境 / 支持软件",
|
||||
"编程语言",
|
||||
"源程序量",
|
||||
"开发目的",
|
||||
"面向领域 / 行业",
|
||||
"软件的主要功能",
|
||||
"软件的技术特点",
|
||||
"页数",
|
||||
]
|
||||
|
||||
|
||||
def effective_len(value: str) -> int:
|
||||
return len(str(value or "").replace(" ", "").replace("\n", ""))
|
||||
|
||||
|
||||
def clean_text(value: Any) -> str:
|
||||
text = str(value or "").strip()
|
||||
text = re.sub(r"\s+", " ", text)
|
||||
text = text.replace("`", "").replace("#", "").strip()
|
||||
return text
|
||||
|
||||
|
||||
def trim_effective(value: str, max_chars: int = MAX_MAIN_FUNCTION_CHARS) -> str:
|
||||
if effective_len(value) <= max_chars:
|
||||
return value
|
||||
result: list[str] = []
|
||||
count = 0
|
||||
for char in value:
|
||||
if char not in (" ", "\n"):
|
||||
count += 1
|
||||
if count > max_chars:
|
||||
break
|
||||
result.append(char)
|
||||
return "".join(result).rstrip("，。；、 ") + "。"
|
||||
|
||||
|
||||
def business_feature_pairs(business: dict[str, Any] | None) -> list[tuple[str, str]]:
|
||||
if not business:
|
||||
return []
|
||||
features = business.get("business_features") or []
|
||||
details = business.get("business_feature_details") or {}
|
||||
if not isinstance(features, list):
|
||||
return []
|
||||
if not isinstance(details, dict):
|
||||
details = {}
|
||||
pairs: list[tuple[str, str]] = []
|
||||
for feature in features:
|
||||
name = clean_text(feature)
|
||||
if not name:
|
||||
continue
|
||||
detail = clean_text(details.get(name))
|
||||
pairs.append((name, detail))
|
||||
return pairs
|
||||
|
||||
|
||||
def summarize_business_features(software_name: str, business: dict[str, Any] | None) -> str:
|
||||
pairs = business_feature_pairs(business)
|
||||
if not business or not pairs:
|
||||
return ""
|
||||
|
||||
industry = clean_text(business.get("industry"))
|
||||
target_users = business.get("target_users") or []
|
||||
if isinstance(target_users, list):
|
||||
target_text = "、".join(clean_text(item) for item in target_users if clean_text(item))
|
||||
else:
|
||||
target_text = clean_text(target_users)
|
||||
core_value = clean_text(business.get("core_value"))
|
||||
product_positioning = clean_text(business.get("product_positioning"))
|
||||
operation_flow = business.get("operation_flow") or []
|
||||
if isinstance(operation_flow, list):
|
||||
flow_steps = [clean_text(item).rstrip("。") for item in operation_flow if clean_text(item)]
|
||||
flow_text = "，再".join(flow_steps)
|
||||
else:
|
||||
flow_text = clean_text(operation_flow)
|
||||
|
||||
feature_names = "、".join(name for name, _ in pairs[:8])
|
||||
parts: list[str] = []
|
||||
if product_positioning:
|
||||
parts.append(product_positioning.rstrip("。") + "。")
|
||||
else:
|
||||
scope = f"面向{industry}" if industry else "面向实际业务场景"
|
||||
users = f"，服务于{target_text}" if target_text else ""
|
||||
parts.append(f"{software_name}是一套{scope}{users}的应用软件。")
|
||||
parts.append(f"软件主要提供{feature_names}等功能。")
|
||||
if core_value:
|
||||
parts.append(core_value.rstrip("。") + "。")
|
||||
|
||||
for name, detail in pairs[:8]:
|
||||
if detail:
|
||||
detail = detail.rstrip("。")
|
||||
if detail.startswith(("用户", "系统")):
|
||||
parts.append(f"在{name}功能中，{detail}。")
|
||||
else:
|
||||
parts.append(f"{name}功能主要{detail}。")
|
||||
else:
|
||||
parts.append(f"{name}功能支持用户完成相关业务操作，并在处理完成后返回对应结果。")
|
||||
|
||||
if flow_text:
|
||||
parts.append(f"用户通常先{flow_text}，系统在关键步骤提供状态反馈和结果展示。")
|
||||
|
||||
result = "".join(parts)
|
||||
while effective_len(result) < MIN_MAIN_FUNCTION_CHARS:
|
||||
result += (
|
||||
f"围绕{feature_names}等核心功能，软件将用户输入、过程处理、结果查看和资料管理组织在连续的操作流程中，"
|
||||
"用户可以根据页面提示逐步完成业务处理，系统保存必要的数据记录并提供清晰的反馈信息，"
|
||||
"便于用户后续继续查看、复核和调整相关内容。"
|
||||
)
|
||||
return trim_effective(result)
|
||||
|
||||
|
||||
def summarize_features(analysis: dict[str, Any], software_name: str, business: dict[str, Any] | None = None) -> str:
|
||||
"""Generate a substantive main-function description for the application form.
|
||||
|
||||
When business context JSON provides main_functions it will be used upstream; this
|
||||
function is a fallback that assembles the best available evidence into a multi-
|
||||
paragraph description targeting the 500-1300 character window required by the
|
||||
Chinese copyright office.
|
||||
"""
|
||||
business_summary = summarize_business_features(software_name, business)
|
||||
if business_summary:
|
||||
return business_summary
|
||||
|
||||
features = analysis.get("feature_candidates") or []
|
||||
readme = (analysis.get("readme_excerpt") or "").strip()
|
||||
routes = analysis.get("routes") or []
|
||||
|
||||
readable_features = []
|
||||
for feature in features:
|
||||
name = humanize_feature(str(feature))
|
||||
if re.search(r"[A-Za-z]", name):
|
||||
continue
|
||||
if name and name not in readable_features:
|
||||
readable_features.append(name)
|
||||
|
||||
parts: list[str] = []
|
||||
|
||||
# Opening overview paragraph
|
||||
feature_list = "、".join(readable_features[:12]) if readable_features else "信息展示、业务处理、数据管理和系统交互"
|
||||
parts.append(
|
||||
f"{software_name}是一套面向用户业务场景的综合软件系统，"
|
||||
f"主要提供{feature_list}等核心功能模块。"
|
||||
f"系统通过清晰的操作界面和合理的业务流程设计，帮助用户高效完成日常工作和业务协作。"
|
||||
)
|
||||
|
||||
# Module-by-module breakdown
|
||||
detail_parts: list[str] = []
|
||||
for name in readable_features[:8]:
|
||||
skip = {"软件登录", "用户注册", "用户认证", "首页", "数据看板", "系统设置"}
|
||||
if name in skip:
|
||||
continue
|
||||
detail_parts.append(f"{name}模块支持用户进行相关数据的查看、录入和管理操作，提供完整的业务处理能力和结果反馈。")
|
||||
|
||||
if not detail_parts:
|
||||
route_display = [r.strip("/") for r in routes[:6] if r != "/" and not r.startswith("/:")]
|
||||
if route_display:
|
||||
for route_name in route_display[:6]:
|
||||
label = route_name.replace("-", " ").replace("_", " ").title()
|
||||
detail_parts.append(f"{label}模块支持用户进行相关数据的查看、录入和管理操作，提供完整的业务处理能力和结果反馈。")
|
||||
else:
|
||||
detail_parts.append("用户可通过系统界面完成数据查询、信息录入、业务处理和结果导出等操作。")
|
||||
detail_parts.append("系统支持多角色用户的协同工作，不同权限用户可访问相应的功能模块。")
|
||||
detail_parts.append("系统提供数据持久化存储和历史记录追溯能力，保障业务数据的完整性和可审计性。")
|
||||
|
||||
# Limit detail parts to avoid exceeding max length
|
||||
combined = "".join(detail_parts)
|
||||
if len(combined) + len("".join(parts)) > MAX_MAIN_FUNCTION_CHARS:
|
||||
while detail_parts and len("".join(detail_parts)) + len("".join(parts)) > MAX_MAIN_FUNCTION_CHARS:
|
||||
detail_parts.pop()
|
||||
|
||||
parts.extend(detail_parts)
|
||||
|
||||
# Closing paragraph
|
||||
if readme:
|
||||
first_line = readme.splitlines()[0][:80]
|
||||
parts.append(f"系统核心业务围绕{first_line}展开，覆盖从信息采集到结果呈现的完整操作链路。")
|
||||
|
||||
result = "".join(parts)
|
||||
|
||||
while effective_len(result) < MIN_MAIN_FUNCTION_CHARS:
|
||||
padding = (
|
||||
"此外，系统还提供了配套的数据管理、用户操作记录、状态跟踪和系统配置等辅助功能模块，"
|
||||
"各个功能模块之间通过统一的界面布局和操作规范协同运行，用户可以在不同模块间灵活切换和处理跨模块的业务流程。"
|
||||
"系统整体设计注重业务完整性和操作连续性，能够满足用户日常工作中对信息处理和业务管理的核心需求。"
|
||||
"系统界面设计遵循清晰直观的原则，主要操作入口集中展示，用户无需复杂培训即可上手使用。"
|
||||
"系统的数据管理能力包括数据的录入、存储、查询、修改和删除等基本操作，同时支持数据批量处理和导入导出功能。"
|
||||
"在业务处理方面，系统支持多步骤业务流程的串联执行，各环节之间数据自动流转，减少用户重复录入。"
|
||||
"系统还提供了灵活的配置选项，管理员可以根据实际业务需求调整系统参数和功能开关。"
|
||||
)
|
||||
result += padding
|
||||
|
||||
return trim_effective(result)
|
||||
|
||||
|
||||
def humanize_feature(name: str) -> str:
|
||||
value = re.sub(r"([a-z])([A-Z])", r"\1 \2", name)
|
||||
value = value.replace("-", " ").replace("_", " ").strip()
|
||||
key = value.lower().replace(" ", "")
|
||||
mapping = {
|
||||
"login": "软件登录",
|
||||
"register": "用户注册",
|
||||
"auth": "用户认证",
|
||||
"home": "首页",
|
||||
"dashboard": "数据看板",
|
||||
"project": "项目管理",
|
||||
"projects": "项目管理",
|
||||
"projectsettings": "项目设置",
|
||||
"projectssettings": "项目设置",
|
||||
"settings": "系统设置",
|
||||
"asset": "资源管理",
|
||||
"assets": "资源管理",
|
||||
"assethub": "资源中心",
|
||||
"billing": "费用管理",
|
||||
"agentstatusbar": "智能体状态展示",
|
||||
"messagebubble": "消息展示",
|
||||
"chatpanel": "对话面板",
|
||||
"chatinput": "对话输入",
|
||||
"assetpanel": "资源面板",
|
||||
}
|
||||
return mapping.get(key, value.title() if re.search(r"[A-Za-z]", value) else value)
|
||||
|
||||
|
||||
def build_fields(
|
||||
analysis: dict[str, Any],
|
||||
manifest: dict[str, Any],
|
||||
software_name: str,
|
||||
version: str,
|
||||
answers: dict[str, str],
|
||||
business: dict[str, Any] | None = None,
|
||||
) -> dict[str, str]:
|
||||
frameworks = analysis.get("frameworks") or []
|
||||
framework_text = "、".join(frameworks) if frameworks else "前端工程化框架"
|
||||
language = analysis.get("language") or "待用户确认"
|
||||
project = Path(analysis.get("project_root") or ".")
|
||||
hardware_hint = current_hardware_environment()
|
||||
dev_os_hint = current_operating_system()
|
||||
version_hint = version_confirmation_hint(analysis, version)
|
||||
software_name_hint = f"待用户确认（建议：{software_name}；请确认最终软件全称）"
|
||||
|
||||
defaults = {
|
||||
"软件全称": software_name_hint,
|
||||
"软件简称": "",
|
||||
"版本号": version_hint,
|
||||
"软件分类": (business.get("software_category") or "应用软件") if business else "应用软件",
|
||||
"开发完成日期": "待用户确认（YYYY-MM-DD）",
|
||||
"开发方式": (business.get("development_situation") or "单独开发") if business else "单独开发",
|
||||
"软件说明": "原创",
|
||||
"发表状态": "待用户确认（已发表/未发表）",
|
||||
"首次发表日期": "待用户确认（YYYY-MM-DD，未发表则留空）",
|
||||
"著作权人": "待用户确认",
|
||||
"权利范围": (business.get("rights_scope") or "全部权利") if business else "全部权利",
|
||||
"权利取得方式": (business.get("rights_acquisition") or "原始取得") if business else "原始取得",
|
||||
"开发的硬件环境": hardware_hint,
|
||||
"运行的硬件环境": hardware_hint,
|
||||
"开发该软件的操作系统": dev_os_hint,
|
||||
"软件开发环境 / 开发工具": f"开发环境: {dev_os_hint}/开发工具: {infer_ide_name(project)}",
|
||||
"该软件的运行平台 / 操作系统": infer_runtime_os(analysis),
|
||||
"软件运行支撑环境 / 支持软件": infer_runtime_support(analysis, project),
|
||||
"编程语言": language,
|
||||
"源程序量": str(manifest.get("source_line_count") or manifest.get("selected_source_line_count") or "待用户确认"),
|
||||
"开发目的": (business.get("application_purpose") or f"待用户确认（≤50字符，需说明开发目的，不能只写软件名称）") if business else "待用户确认（≤50字符，需说明开发目的，不能只写软件名称）",
|
||||
"面向领域 / 行业": (business.get("industry") or "待用户确认") if business else "待用户确认",
|
||||
"软件的主要功能": (business.get("main_functions") or summarize_features(analysis, software_name, business)) if business else summarize_features(analysis, software_name, business),
|
||||
"软件的技术特点": (business.get("technical_characteristics") or f"系统采用{framework_text}构建前端界面，结合模块化组件、路由组织、接口封装和状态管理实现业务功能") if business else f"系统采用{framework_text}构建前端界面，结合模块化组件、路由组织、接口封装和状态管理实现业务功能",
|
||||
"页数": str(manifest.get("total_pages") or "待用户确认"),
|
||||
}
|
||||
defaults.update({k: v for k, v in answers.items() if v})
|
||||
|
||||
# 未发表时首次发表日期应为空，不触发待确认门禁
|
||||
publish_status = defaults.get("发表状态", "")
|
||||
if "未发表" in publish_status and "已发表" not in publish_status:
|
||||
if "待用户确认" in defaults.get("首次发表日期", "") or not defaults.get("首次发表日期", "").strip():
|
||||
defaults["首次发表日期"] = ""
|
||||
|
||||
# 软件的主要功能：确保业务理解提供的内容也满足最低字数
|
||||
main_func = defaults.get("软件的主要功能", "")
|
||||
if main_func and "待用户确认" not in main_func and effective_len(main_func) < MIN_MAIN_FUNCTION_CHARS:
|
||||
defaults["软件的主要功能"] = summarize_features(analysis, software_name, business)
|
||||
|
||||
return defaults
|
||||
|
||||
|
||||
def version_numbers(value: str) -> tuple[int, ...]:
|
||||
raw = str(value or "").strip()
|
||||
raw = raw.lstrip("vV")
|
||||
parts = re.findall(r"\d+", raw)
|
||||
return tuple(int(part) for part in parts[:3])
|
||||
|
||||
|
||||
def version_less_than_1(value: str) -> bool:
|
||||
numbers = version_numbers(value)
|
||||
return bool(numbers) and numbers[0] < 1
|
||||
|
||||
|
||||
def normalize_version_label(value: str) -> str:
|
||||
raw = str(value or "").strip()
|
||||
if not raw:
|
||||
return ""
|
||||
return raw if raw.upper().startswith("V") else f"V{raw}"
|
||||
|
||||
|
||||
def project_version_candidate(analysis: dict[str, Any]) -> str:
|
||||
value = str((analysis.get("package") or {}).get("version") or "").strip()
|
||||
if value and value.upper() != "V1.0":
|
||||
return normalize_version_label(value)
|
||||
return ""
|
||||
|
||||
|
||||
def version_confirmation_hint(analysis: dict[str, Any], requested_version: str) -> str:
|
||||
project_version = project_version_candidate(analysis)
|
||||
requested = normalize_version_label(requested_version or "V1.0")
|
||||
if project_version and version_less_than_1(project_version):
|
||||
return (
|
||||
f"待用户确认（项目版本号为 {project_version}，软著首次提交通常建议从 V1.0 开始；"
|
||||
f"请确认填写 V1.0 还是 {project_version}）"
|
||||
)
|
||||
if not project_version and version_less_than_1(requested):
|
||||
return (
|
||||
f"待用户确认（当前建议版本号为 {requested}，软著首次提交通常建议从 V1.0 开始；"
|
||||
f"请确认填写 V1.0 还是 {requested}）"
|
||||
)
|
||||
if project_version and project_version != requested:
|
||||
return f"待用户确认（项目版本号为 {project_version}，当前建议为 {requested}；请确认最终申报版本号）"
|
||||
return f"待用户确认（建议：{requested}；请确认最终版本号）"
|
||||
|
||||
|
||||
def format_gb(size: int | None) -> str:
|
||||
if not size:
|
||||
return ""
|
||||
return f"{size / (1024 ** 3):.0f}GB"
|
||||
|
||||
|
||||
def total_memory_bytes() -> int | None:
|
||||
try:
|
||||
return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
|
||||
except (AttributeError, OSError, ValueError):
|
||||
return None
|
||||
|
||||
|
||||
def current_hardware_environment() -> str:
|
||||
parts: list[str] = []
|
||||
cpu_count = os.cpu_count()
|
||||
machine = platform.machine()
|
||||
processor = platform.processor()
|
||||
if processor and processor != machine and processor.lower() != "arm":
|
||||
parts.append(f"CPU {processor}")
|
||||
if cpu_count:
|
||||
parts.append(f"CPU {cpu_count}核")
|
||||
if machine:
|
||||
parts.append(f"架构 {machine}")
|
||||
memory = format_gb(total_memory_bytes())
|
||||
if memory:
|
||||
parts.append(f"内存 {memory}")
|
||||
try:
|
||||
disk = shutil.disk_usage(Path.home())
|
||||
disk_total = format_gb(disk.total)
|
||||
if disk_total:
|
||||
parts.append(f"硬盘 {disk_total}")
|
||||
except OSError:
|
||||
pass
|
||||
if parts:
|
||||
return "、".join(parts)
|
||||
return "待用户确认"
|
||||
|
||||
|
||||
def current_operating_system() -> str:
|
||||
system = platform.system()
|
||||
if system == "Darwin":
|
||||
version = platform.mac_ver()[0]
|
||||
label = f"macOS {version}" if version else f"macOS（Darwin {platform.release()}）"
|
||||
elif system == "Windows":
|
||||
label = f"Windows {platform.release()}"
|
||||
elif system == "Linux":
|
||||
label = f"Linux {platform.release()}"
|
||||
else:
|
||||
label = f"{system} {platform.release()}".strip() or "待用户确认"
|
||||
return label
|
||||
|
||||
|
||||
def infer_ide_name(project: Path) -> str:
|
||||
if (project / ".idea").exists():
|
||||
return "WebStorm 或 IntelliJ IDEA"
|
||||
if (project / ".vscode").exists():
|
||||
return "Visual Studio Code"
|
||||
if list(project.glob("*.code-workspace")):
|
||||
return "Visual Studio Code"
|
||||
return "Visual Studio Code"
|
||||
|
||||
|
||||
def infer_runtime_os(analysis: dict[str, Any]) -> str:
|
||||
frameworks = set(analysis.get("frameworks") or [])
|
||||
deps = set((analysis.get("package") or {}).get("dependency_names") or [])
|
||||
if "Electron" in frameworks or "electron" in deps or "Tauri" in frameworks or "@tauri-apps/api" in deps:
|
||||
return "Windows 10/11 或 macOS 13及以上版本"
|
||||
if frameworks & {"Vue", "React", "Vite", "Next.js", "Nuxt", "Svelte", "Astro", "Angular"}:
|
||||
return "Windows 10/11 或 macOS 13及以上版本"
|
||||
return "Windows 10/11 或 macOS 13及以上版本"
|
||||
|
||||
|
||||
def project_file(project: Path, relative: str) -> Path | None:
|
||||
if not relative:
|
||||
return None
|
||||
path = project / relative
|
||||
return path if path.exists() else None
|
||||
|
||||
|
||||
def load_project_package(project: Path, analysis: dict[str, Any]) -> dict[str, Any]:
|
||||
package_path = project_file(project, (analysis.get("package") or {}).get("path") or "")
|
||||
if package_path:
|
||||
try:
|
||||
return read_json(package_path)
|
||||
except Exception:
|
||||
return {}
|
||||
return {}
|
||||
|
||||
|
||||
def read_readme(project: Path) -> str:
|
||||
for name in ("README.md", "README.zh.md", "readme.md", "Readme.md"):
|
||||
path = project / name
|
||||
if path.exists():
|
||||
try:
|
||||
return read_text(path, limit=12000)
|
||||
except Exception:
|
||||
return ""
|
||||
return ""
|
||||
|
||||
|
||||
def extract_requirement_bullets(text: str) -> list[str]:
|
||||
wanted = ("python", "node", "docker", "compose", "postgres", "redis", "chrome", "edge", "safari")
|
||||
# Patterns that indicate a feature description rather than a runtime requirement.
|
||||
_feature_start = re.compile(r"^(?:[一-鿿]|L\d|P\d|[A-Z]\d\s)")
|
||||
bullets: list[str] = []
|
||||
for line in text.splitlines():
|
||||
match = re.match(r"\s*[-*]\s+(.+)", line)
|
||||
if not match:
|
||||
continue
|
||||
item = match.group(1).strip()
|
||||
if any(key in item.lower() for key in wanted) and item not in bullets:
|
||||
if len(item) > 80:
|
||||
continue
|
||||
if _feature_start.match(item) and "（" in item:
|
||||
continue
|
||||
bullets.append(item)
|
||||
return bullets[:8]
|
||||
|
||||
|
||||
def detect_package_manager(project: Path, package_path: str) -> str:
|
||||
base = (project / package_path).parent if package_path else project
|
||||
checks = [
|
||||
("pnpm-lock.yaml", "pnpm"),
|
||||
("yarn.lock", "Yarn"),
|
||||
("bun.lock", "Bun"),
|
||||
("bun.lockb", "Bun"),
|
||||
("package-lock.json", "npm"),
|
||||
]
|
||||
for filename, manager in checks:
|
||||
if (base / filename).exists() or (project / filename).exists():
|
||||
return manager
|
||||
return "npm"
|
||||
|
||||
|
||||
def has_support_term(items: list[str], term: str) -> bool:
|
||||
return any(term.lower() in item.lower() for item in items)
|
||||
|
||||
|
||||
def infer_runtime_support(analysis: dict[str, Any], project: Path) -> str:
|
||||
"""Infer runtime support environment (≤50 chars plain text)."""
|
||||
package_info = load_project_package(project, analysis)
|
||||
package_path = (analysis.get("package") or {}).get("path") or ""
|
||||
deps = set((analysis.get("package") or {}).get("dependency_names") or [])
|
||||
frameworks = set(analysis.get("frameworks") or [])
|
||||
|
||||
support: list[str] = []
|
||||
readme_requirements = extract_requirement_bullets(read_readme(project))
|
||||
|
||||
if package_info or deps or frameworks & {"Vue", "React", "Vite", "Next.js", "Nuxt", "Svelte", "Astro", "Angular"}:
|
||||
if not has_support_term(support, "node"):
|
||||
node_engine = str((package_info.get("engines") or {}).get("node") or "").strip()
|
||||
support.append(f"Node.js {node_engine}".strip() if node_engine else "Node.js")
|
||||
support.append(detect_package_manager(project, package_path))
|
||||
support.append("现代浏览器")
|
||||
|
||||
if ((project / "pyproject.toml").exists() or any(project.glob("*/pyproject.toml"))) and not has_support_term(support, "python"):
|
||||
support.append("Python")
|
||||
if ((project / "requirements.txt").exists() or list(project.glob("*/requirements*.txt"))) and not has_support_term(support, "python"):
|
||||
support.append("Python")
|
||||
|
||||
if ((project / "docker-compose.yml").exists() or (project / "docker-compose.yaml").exists() or list(project.glob("docker-compose*.yml"))) and not has_support_term(support, "docker"):
|
||||
support.append("Docker")
|
||||
|
||||
compose_text = ""
|
||||
for compose in list(project.glob("docker-compose*.yml")) + list(project.glob("docker-compose*.yaml")):
|
||||
try:
|
||||
compose_text += "\n" + read_text(compose, limit=20000).lower()
|
||||
except Exception:
|
||||
continue
|
||||
if "postgres" in compose_text:
|
||||
support.append("PostgreSQL")
|
||||
if "redis" in compose_text:
|
||||
support.append("Redis")
|
||||
|
||||
# Also incorporate readme requirements into support software
|
||||
for req in readme_requirements:
|
||||
if not has_support_term(support, req.split()[0].lower()):
|
||||
support.append(req)
|
||||
|
||||
# Deduplicate
|
||||
unique: list[str] = []
|
||||
for item in support:
|
||||
clean = str(item).strip().rstrip("；;")
|
||||
if clean and clean not in unique:
|
||||
unique.append(clean)
|
||||
|
||||
if not unique:
|
||||
return "待用户确认"
|
||||
|
||||
# Enforce ≤50 char limit: trim items if needed
|
||||
result = "、".join(unique)
|
||||
if len(result) > 50:
|
||||
trimmed: list[str] = []
|
||||
for item in unique:
|
||||
candidate = "、".join(trimmed + [item])
|
||||
if len(candidate) <= 50:
|
||||
trimmed.append(item)
|
||||
else:
|
||||
break
|
||||
result = "、".join(trimmed) if trimmed else unique[0][:50]
|
||||
return result
|
||||
|
||||
|
||||
def write_application_md(path: Path, fields: dict[str, str], analysis: dict[str, Any], manifest: dict[str, Any], business: dict[str, Any] | None = None) -> None:
|
||||
# 兜底：未发表时首次发表日期不应输出"待用户确认"，直接留空
|
||||
publish_status = fields.get("发表状态", "")
|
||||
if "未发表" in publish_status and "已发表" not in publish_status:
|
||||
if "待用户确认" in (fields.get("首次发表日期") or "") or not (fields.get("首次发表日期") or "").strip():
|
||||
fields["首次发表日期"] = ""
|
||||
|
||||
lines = ["# 申请表信息", ""]
|
||||
for field in FIELD_ORDER:
|
||||
lines.append(f"➤{field}：{fields.get(field, '待用户确认')}")
|
||||
pending = [field for field in FIELD_ORDER if "待用户确认" in (fields.get(field) or "")]
|
||||
|
||||
# Build warnings for common issues
|
||||
warnings: list[str] = []
|
||||
soft_name = fields.get("软件全称", "")
|
||||
clean_name = str(soft_name).strip()
|
||||
raw_name = clean_name
|
||||
if "待用户确认" in clean_name and "建议：" in clean_name:
|
||||
try:
|
||||
raw_name = clean_name.split("建议：")[1].rstrip("）").split("；")[0].strip()
|
||||
except (IndexError, ValueError):
|
||||
raw_name = clean_name
|
||||
for suffix in ["软件", "平台"]:
|
||||
if raw_name.endswith(suffix):
|
||||
warnings.append(f"软件全称以「{suffix}」结尾，存在被驳回风险。建议考虑去掉「{suffix}」后缀或改用其他命名方式。")
|
||||
|
||||
main_func = fields.get("软件的主要功能", "")
|
||||
if main_func and "待用户确认" not in main_func:
|
||||
func_len = len(str(main_func).replace(" ", "").replace("\n", ""))
|
||||
if func_len < MIN_MAIN_FUNCTION_CHARS:
|
||||
warnings.append(f"软件的主要功能仅有 {func_len} 字符，应不少于 {MIN_MAIN_FUNCTION_CHARS} 字符。请扩写功能说明。")
|
||||
elif func_len > MAX_MAIN_FUNCTION_CHARS:
|
||||
warnings.append(f"软件的主要功能共 {func_len} 字符，超过建议上限 {MAX_MAIN_FUNCTION_CHARS} 字符。请精简。")
|
||||
|
||||
# Check character limits for fields with ≤50 or ≤100 constraints
|
||||
char_limit_fields = {
|
||||
"开发的硬件环境": 50,
|
||||
"运行的硬件环境": 50,
|
||||
"开发该软件的操作系统": 50,
|
||||
"软件开发环境 / 开发工具": 50,
|
||||
"该软件的运行平台 / 操作系统": 50,
|
||||
"软件运行支撑环境 / 支持软件": 50,
|
||||
"开发目的": 50,
|
||||
"面向领域 / 行业": 50,
|
||||
"软件的技术特点": 100,
|
||||
}
|
||||
for field_name, limit in char_limit_fields.items():
|
||||
value = fields.get(field_name, "")
|
||||
if value and "待用户确认" not in value and len(value) > limit:
|
||||
warnings.append(f"{field_name}共 {len(value)} 字符，超过限制 {limit} 字符。请精简。")
|
||||
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"## 字段填写口径",
|
||||
"",
|
||||
"- 软件全称：必须由用户确认；最终正式资料文件名、代码页眉和操作手册中的软件名称均以本字段为准。",
|
||||
"- 软件简称：可选；如有常用简称则填写。",
|
||||
"- 版本号：必须由用户确认；如果项目版本小于 V1.0，软著首次提交通常建议使用 V1.0，也可按实际项目版本填写，最终以本字段为准。",
|
||||
"- 软件分类：应用软件/嵌入式软件/中间件/系统软件/其他。",
|
||||
"- 开发完成日期、首次发表日期：必须使用 YYYY-MM-DD 格式。",
|
||||
"- 开发方式：单独开发/合作开发/委托开发/下达任务开发。",
|
||||
"- 软件说明：原创 / 修改（含翻译软件、合成软件）。",
|
||||
"- 发表状态：已发表或未发表；已发表需附首次发表日期。",
|
||||
"- 软件开发环境 / 开发工具：≤50字符，格式 `开发环境: <OS>/开发工具: <IDE名称>`。",
|
||||
"- 开发该软件的操作系统：≤50字符，填写实际开发电脑的操作系统版本。",
|
||||
"- 该软件的运行平台 / 操作系统：≤50字符，填写软件运行所在的操作系统或浏览器环境。",
|
||||
"- 软件运行支撑环境 / 支持软件：≤50字符，直接列出运行依赖（如 Node.js、npm、浏览器），不加格式前缀。",
|
||||
"- 开发的硬件环境和运行的硬件环境：≤50字符，可使用检测到的电脑配置作为建议值。",
|
||||
"- 源程序量：纯数字（不含'行'字），指全部源程序的总行数。",
|
||||
"- 开发目的：≤50字符，用一句话说明目的，不能只写软件名称。",
|
||||
"- 面向领域 / 行业：≤50字符。",
|
||||
"- 软件的主要功能：500~1300字符。",
|
||||
"- 软件的技术特点：多选标签（APP/游戏软件/教育软件/金融软件/医疗软件/地理信息软件/云计算软件/信息安全软件/大数据软件/人工智能软件/VR软件/5G软件/小程序/物联网软件/智慧城市软件）+ 文本描述≤100字符。",
|
||||
"",
|
||||
"## 项目分析摘要",
|
||||
"",
|
||||
f"- 项目目录：{analysis.get('project_root', '')}",
|
||||
f"- 框架：{'、'.join(analysis.get('frameworks') or []) or '未识别'}",
|
||||
f"- 源码文件数：{analysis.get('source', {}).get('total_file_count', analysis.get('source', {}).get('file_count', 0))}",
|
||||
f"- 源程序量（含空行）：{analysis.get('source', {}).get('total_line_count', analysis.get('source', {}).get('line_count', 0))}",
|
||||
f"- 代码材料页数：{manifest.get('total_pages', 0)}",
|
||||
f"- 代码输出模式：{manifest.get('mode', '')}",
|
||||
f"- 业务理解：{'已读取 草稿/业务理解.json' if business else '未提供，使用项目分析兜底'}",
|
||||
"",
|
||||
"## 待确认字段",
|
||||
"",
|
||||
]
|
||||
)
|
||||
if warnings:
|
||||
lines.append("## 字段提醒")
|
||||
lines.append("")
|
||||
lines.extend(f"- {w}" for w in warnings)
|
||||
lines.append("")
|
||||
if pending:
|
||||
lines.extend(f"- {field}" for field in pending)
|
||||
else:
|
||||
lines.append("- 无")
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"```text",
|
||||
"STOP_FOR_USER",
|
||||
"NEXT_ACTION: 请补全并确认申请表字段；确认后运行 confirm_stage.py --stage application-fields。",
|
||||
"```",
|
||||
]
|
||||
)
|
||||
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def require_confirmed_business(business: dict[str, Any] | None) -> None:
|
||||
if business is None:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 申请表信息必须基于已确认的业务理解生成。请先生成并确认 草稿/业务理解.md。"
|
||||
)
|
||||
if business.get("confirmation_required") and not business.get("user_confirmed"):
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解尚未确认。请先确认 草稿/业务理解.md，"
|
||||
"再运行 `python3 <SKILL_DIR>/scripts/confirm_stage.py --workdir 软件著作权申请资料 --stage business --note \"<用户确认内容>\"`。"
|
||||
)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--analysis", required=True)
|
||||
parser.add_argument("--code-manifest", required=True)
|
||||
parser.add_argument("--software-name", required=True)
|
||||
parser.add_argument("--version", default="V1.0")
|
||||
parser.add_argument("--answers", help="Optional JSON object with confirmed field values")
|
||||
parser.add_argument("--business-context", help="Business context JSON generated before material drafting")
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||||
args = parser.parse_args()
|
||||
|
||||
analysis = read_json(Path(args.analysis))
|
||||
manifest = read_json(Path(args.code_manifest))
|
||||
answers = read_json(Path(args.answers)) if args.answers else {}
|
||||
business = read_json(Path(args.business_context)) if args.business_context else None
|
||||
require_confirmed_business(business)
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
|
||||
fields = build_fields(analysis, manifest, args.software_name, args.version, answers, business)
|
||||
out_path = out_dir / "申请表信息.md"
|
||||
write_application_md(out_path, fields, analysis, manifest, business)
|
||||
print(f"OK application draft: {out_path}")
|
||||
print("STOP_FOR_USER")
|
||||
print("NEXT_ACTION: 请补全并确认申请表字段；确认后运行 confirm_stage.py --stage application-fields。")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,431 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Collect project evidence and write a model-authored business context."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import ensure_dir, iter_project_files, read_json, read_text, rel, write_json
|
||||
|
||||
|
||||
DOC_EXTS = {".md", ".txt", ".rst", ".adoc"}
|
||||
MAX_DOC_CHARS = 80_000
|
||||
MAX_DOCS = 40
|
||||
|
||||
|
||||
def normalize_space(text: str) -> str:
|
||||
return re.sub(r"\s+", " ", text).strip()
|
||||
|
||||
|
||||
def strip_md(text: str) -> str:
|
||||
text = re.sub(r"`{3}.*?`{3}", " ", text, flags=re.S)
|
||||
text = re.sub(r"\[(.*?)\]\(.*?\)", r"\1", text)
|
||||
text = re.sub(r"[>#*_`|]", " ", text)
|
||||
return normalize_space(text)
|
||||
|
||||
|
||||
def skip_doc(path: Path, project: Path) -> bool:
|
||||
r = rel(path, project).lower()
|
||||
skip_parts = (
|
||||
"node_modules",
|
||||
".git/",
|
||||
"dist/",
|
||||
"build/",
|
||||
".next/",
|
||||
"coverage/",
|
||||
"软件著作权申请资料",
|
||||
)
|
||||
return any(part in r for part in skip_parts)
|
||||
|
||||
|
||||
def extract_headings(text: str, limit: int = 24) -> list[str]:
|
||||
headings: list[str] = []
|
||||
for line in text.splitlines():
|
||||
clean = line.strip()
|
||||
if clean.startswith("#"):
|
||||
title = clean.lstrip("#").strip()
|
||||
if title and title not in headings:
|
||||
headings.append(title[:120])
|
||||
if len(headings) >= limit:
|
||||
break
|
||||
return headings
|
||||
|
||||
|
||||
def extract_opening(text: str, limit: int = 900) -> str:
|
||||
clean = strip_md(text)
|
||||
return clean[:limit].strip()
|
||||
|
||||
|
||||
def collect_documents(project: Path) -> list[dict[str, Any]]:
|
||||
docs: list[dict[str, Any]] = []
|
||||
for path in iter_project_files(project, DOC_EXTS):
|
||||
if skip_doc(path, project):
|
||||
continue
|
||||
try:
|
||||
text = read_text(path, limit=MAX_DOC_CHARS)
|
||||
except Exception:
|
||||
continue
|
||||
if not text.strip():
|
||||
continue
|
||||
docs.append(
|
||||
{
|
||||
"path": rel(path, project),
|
||||
"size": path.stat().st_size,
|
||||
"headings": extract_headings(text),
|
||||
"opening": extract_opening(text),
|
||||
}
|
||||
)
|
||||
docs.sort(key=lambda item: (item["path"].count("/"), item["path"]))
|
||||
return docs[:MAX_DOCS]
|
||||
|
||||
|
||||
def collect_code_evidence(analysis: dict[str, Any]) -> dict[str, Any]:
|
||||
source = analysis.get("source") or {}
|
||||
categorized = source.get("categorized_files") or {}
|
||||
return {
|
||||
"project_name": analysis.get("project_name"),
|
||||
"software_name_candidate": analysis.get("software_name_candidate"),
|
||||
"frameworks": analysis.get("frameworks") or [],
|
||||
"language": analysis.get("language"),
|
||||
"routes": analysis.get("routes") or [],
|
||||
"feature_name_candidates": analysis.get("feature_candidates") or [],
|
||||
"entry_files": categorized.get("entry") or [],
|
||||
"page_files": categorized.get("page") or [],
|
||||
"component_files": categorized.get("component") or [],
|
||||
"api_files": categorized.get("api") or [],
|
||||
"run_command_candidates": analysis.get("run_command_candidates") or [],
|
||||
"package": analysis.get("package") or {},
|
||||
}
|
||||
|
||||
|
||||
def build_evidence(project: Path, analysis: dict[str, Any], software_name: str, web_notes: str) -> dict[str, Any]:
|
||||
return {
|
||||
"software_name": software_name,
|
||||
"project_root": str(project.resolve()),
|
||||
"instruction": (
|
||||
"本文件只收集证据，不决定行业、功能或手册结构。"
|
||||
"请由模型阅读这些证据以及必要的项目源码后，另行编写业务理解模型稿。"
|
||||
),
|
||||
"documents": collect_documents(project),
|
||||
"code_evidence": collect_code_evidence(analysis),
|
||||
"external_research_notes": web_notes,
|
||||
}
|
||||
|
||||
|
||||
def write_evidence_md(path: Path, evidence: dict[str, Any]) -> None:
|
||||
lines = [
|
||||
"# 业务理解证据",
|
||||
"",
|
||||
f"- 软件名称：{evidence['software_name']}",
|
||||
f"- 项目目录：`{evidence['project_root']}`",
|
||||
"",
|
||||
"本文件只列出可供模型研判的项目证据，不代表最终申报口径。",
|
||||
"模型需要自行判断应阅读哪些文档、抽取哪些功能、采用什么操作手册结构。",
|
||||
"",
|
||||
"## 代码与页面证据",
|
||||
"",
|
||||
]
|
||||
code = evidence["code_evidence"]
|
||||
for key in ("frameworks", "language", "routes", "feature_name_candidates", "entry_files", "page_files", "component_files", "api_files"):
|
||||
value = code.get(key)
|
||||
if value:
|
||||
lines.append(f"- {key}：{value}")
|
||||
lines.extend(["", "## 文档证据", ""])
|
||||
for doc in evidence["documents"]:
|
||||
lines.extend(
|
||||
[
|
||||
f"### {doc['path']}",
|
||||
"",
|
||||
f"- 大小：{doc['size']} bytes",
|
||||
f"- 标题线索：{'；'.join(doc['headings']) if doc['headings'] else '无'}",
|
||||
"",
|
||||
doc["opening"],
|
||||
"",
|
||||
]
|
||||
)
|
||||
if evidence.get("external_research_notes"):
|
||||
lines.extend(["## 外部调研摘要", "", evidence["external_research_notes"], ""])
|
||||
path.write_text("\n".join(lines), encoding="utf-8")
|
||||
|
||||
|
||||
def write_model_template(path: Path, evidence: dict[str, Any]) -> None:
|
||||
template = {
|
||||
"software_name": evidence["software_name"],
|
||||
"product_positioning": "",
|
||||
"industry": "",
|
||||
"target_users": [],
|
||||
"core_value": "",
|
||||
"business_features": [],
|
||||
"business_feature_details": {},
|
||||
"operation_flow": [],
|
||||
"application_purpose": "",
|
||||
"main_functions": "",
|
||||
"technical_characteristics": "",
|
||||
"software_technical_option": "应用软件",
|
||||
"software_category": "应用软件",
|
||||
"manual_sections": [
|
||||
{
|
||||
"title": "模型自行命名章节",
|
||||
"intent": "说明该章节为什么适合当前项目。",
|
||||
"paragraphs": [],
|
||||
"include_feature_overview": False,
|
||||
"include_operation_modules": False,
|
||||
"include_operation_flow": False,
|
||||
}
|
||||
],
|
||||
"manual_modules": [
|
||||
{
|
||||
"title": "真实页面或核心流程名称",
|
||||
"evidence": ["页面、路由、组件、README 或需求文档路径"],
|
||||
"purpose": "该页面或流程在当前软件中的用途。",
|
||||
"usage": "用户在什么业务场景下会使用该页面，正在处理什么具体事务。",
|
||||
"entry": "用户从哪里进入该页面或流程。",
|
||||
"visible_elements": ["用户实际能看到的输入框、按钮、列表、状态或结果区域"],
|
||||
"operation_steps": ["按真实页面顺序描述用户动作，不写代码实现。"],
|
||||
"validation_rules": ["输入限制、必填项、额度、权限、异常提示等规则；没有则留空数组。"],
|
||||
"feedback": ["操作完成后用户能看到的结果、提示或状态变化。"],
|
||||
"screenshot": "截图预留说明",
|
||||
}
|
||||
],
|
||||
"system_requirements": [
|
||||
{"item": "操作系统", "minimum": "按项目实际填写", "recommended": "按项目实际填写"},
|
||||
{"item": "浏览器或客户端", "minimum": "按项目实际填写", "recommended": "按项目实际填写"},
|
||||
],
|
||||
"faq": [
|
||||
{"question": "按当前软件真实使用场景填写常见问题", "answer": "给出面向普通用户的处理方法。"}
|
||||
],
|
||||
"glossary": [
|
||||
{"term": "当前软件中的业务术语", "definition": "用普通中文解释含义。"}
|
||||
],
|
||||
"model_review_notes": [
|
||||
"操作手册应采用软著审核友好的通用骨架：相关文档、说明、功能特点、系统要求、按真实页面/流程逐章操作、常见问题、术语表。",
|
||||
"manual_modules 要按当前项目真实页面、导航入口、按钮、输入限制、系统反馈和截图位置编写，不能只写抽象功能名。",
|
||||
"不要照抄范本文案；范本只说明手册需要具体、可操作、能给审核员看懂。",
|
||||
"不要用关键词表决定行业和功能；必须能从项目证据或用户补充中解释来源。",
|
||||
],
|
||||
}
|
||||
write_json(path, template)
|
||||
|
||||
|
||||
def load_model_context(path: Path) -> dict[str, Any]:
|
||||
data = read_json(path)
|
||||
if not isinstance(data, dict):
|
||||
raise SystemExit(f"Invalid model context JSON: {path}")
|
||||
return data
|
||||
|
||||
|
||||
def required_list(value: Any, field: str) -> list[str]:
|
||||
if not isinstance(value, list):
|
||||
raise SystemExit(f"Model context field must be a list: {field}")
|
||||
items = [str(item).strip() for item in value if str(item).strip()]
|
||||
if not items:
|
||||
raise SystemExit(f"Model context field cannot be empty: {field}")
|
||||
return items
|
||||
|
||||
|
||||
def required_text(data: dict[str, Any], field: str) -> str:
|
||||
value = str(data.get(field) or "").strip()
|
||||
if not value:
|
||||
raise SystemExit(f"Model context field cannot be empty: {field}")
|
||||
return value
|
||||
|
||||
|
||||
def normalize_model_context(model: dict[str, Any], evidence: dict[str, Any], web_notes: str) -> dict[str, Any]:
|
||||
features = required_list(model.get("business_features"), "business_features")
|
||||
details = model.get("business_feature_details") or {}
|
||||
if not isinstance(details, dict):
|
||||
raise SystemExit("Model context field must be an object: business_feature_details")
|
||||
missing = [feature for feature in features if not str(details.get(feature) or "").strip()]
|
||||
if missing:
|
||||
raise SystemExit("Model context missing feature details: " + "、".join(missing[:12]))
|
||||
sections = model.get("manual_sections") or []
|
||||
if sections and not isinstance(sections, list):
|
||||
raise SystemExit("Model context field must be a list: manual_sections")
|
||||
manual_modules = model.get("manual_modules") or []
|
||||
if manual_modules and not isinstance(manual_modules, list):
|
||||
raise SystemExit("Model context field must be a list: manual_modules")
|
||||
if not manual_modules:
|
||||
raise SystemExit("Model context field cannot be empty: manual_modules")
|
||||
for index, module in enumerate(manual_modules, start=1):
|
||||
if not isinstance(module, dict):
|
||||
raise SystemExit(f"manual_modules item {index} must be an object")
|
||||
title = str(module.get("title") or module.get("feature") or "").strip()
|
||||
for field in ("purpose", "usage", "entry", "operation_steps", "feedback"):
|
||||
value = module.get(field)
|
||||
if field == "usage" and not str(value or "").strip():
|
||||
value = module.get("usage_scenario")
|
||||
if isinstance(value, list):
|
||||
missing_value = not any(str(item).strip() for item in value)
|
||||
else:
|
||||
missing_value = not str(value or "").strip()
|
||||
if missing_value:
|
||||
raise SystemExit(f"manual_modules item {index} ({title or 'untitled'}) missing field: {field}")
|
||||
system_requirements = model.get("system_requirements") or []
|
||||
if system_requirements and not isinstance(system_requirements, list):
|
||||
raise SystemExit("Model context field must be a list: system_requirements")
|
||||
if not system_requirements:
|
||||
raise SystemExit("Model context field cannot be empty: system_requirements")
|
||||
faq = model.get("faq") or []
|
||||
if faq and not isinstance(faq, list):
|
||||
raise SystemExit("Model context field must be a list: faq")
|
||||
if not faq:
|
||||
raise SystemExit("Model context field cannot be empty: faq")
|
||||
glossary = model.get("glossary") or []
|
||||
if glossary and not isinstance(glossary, list):
|
||||
raise SystemExit("Model context field must be a list: glossary")
|
||||
if not glossary:
|
||||
raise SystemExit("Model context field cannot be empty: glossary")
|
||||
context = {
|
||||
"software_name": evidence["software_name"],
|
||||
"business_understanding_required": True,
|
||||
"source_documents": [{"path": doc["path"], "size": doc["size"]} for doc in evidence["documents"]],
|
||||
"project_evidence_file": "业务理解证据.md",
|
||||
"product_positioning": required_text(model, "product_positioning"),
|
||||
"industry": required_text(model, "industry"),
|
||||
"target_users": required_list(model.get("target_users"), "target_users"),
|
||||
"core_value": required_text(model, "core_value"),
|
||||
"business_features": features,
|
||||
"business_feature_details": {feature: str(details.get(feature)).strip() for feature in features},
|
||||
"operation_flow": required_list(model.get("operation_flow"), "operation_flow"),
|
||||
"application_purpose": required_text(model, "application_purpose"),
|
||||
"main_functions": required_text(model, "main_functions"),
|
||||
"technical_characteristics": required_text(model, "technical_characteristics"),
|
||||
"software_technical_option": str(model.get("software_technical_option") or "应用软件"),
|
||||
"software_category": str(model.get("software_category") or "应用软件"),
|
||||
"manual_sections": sections,
|
||||
"manual_modules": manual_modules,
|
||||
"system_requirements": system_requirements,
|
||||
"faq": faq,
|
||||
"glossary": glossary,
|
||||
"model_authored": True,
|
||||
"external_research_notes": web_notes,
|
||||
"confirmation_required": True,
|
||||
"user_confirmed": False,
|
||||
"confirmation_stage": "business",
|
||||
"next_action": "请确认 草稿/业务理解.md 中的软件用途、行业、目标用户、核心功能、手册结构和申请口径；确认后运行 confirm_stage.py --stage business。",
|
||||
"review_notes": [
|
||||
"请确认模型判断的行业领域、目标用户和主要功能是否符合实际申报口径。",
|
||||
"请确认操作手册结构是否按真实页面和流程展开，而不是套用抽象功能列表。",
|
||||
],
|
||||
}
|
||||
return context
|
||||
|
||||
|
||||
def write_context_md(path: Path, context: dict[str, Any]) -> None:
|
||||
lines = [
|
||||
"# 业务理解",
|
||||
"",
|
||||
f"- 软件名称：{context['software_name']}",
|
||||
f"- 产品定位：{context['product_positioning']}",
|
||||
f"- 面向领域 / 行业：{context['industry']}",
|
||||
f"- 核心价值：{context['core_value']}",
|
||||
f"- 证据文件：`{context['project_evidence_file']}`",
|
||||
"",
|
||||
"## 目标用户",
|
||||
"",
|
||||
]
|
||||
lines.extend(f"- {item}" for item in context["target_users"])
|
||||
lines.extend(["", "## 主要业务功能", ""])
|
||||
lines.extend(f"- {item}" for item in context["business_features"])
|
||||
lines.extend(["", "## 功能说明", ""])
|
||||
for item in context["business_features"]:
|
||||
lines.append(f"- {item}：{context['business_feature_details'].get(item, '')}")
|
||||
lines.extend(["", "## 典型操作流程", ""])
|
||||
lines.extend(f"{i}. {item}" for i, item in enumerate(context["operation_flow"], start=1))
|
||||
if context.get("manual_sections"):
|
||||
lines.extend(["", "## 操作手册结构建议", ""])
|
||||
for i, section in enumerate(context["manual_sections"], start=1):
|
||||
if isinstance(section, dict):
|
||||
title = section.get("title") or f"章节 {i}"
|
||||
intent = section.get("intent") or ""
|
||||
else:
|
||||
title = str(section)
|
||||
intent = ""
|
||||
lines.append(f"{i}. {title}" + (f"：{intent}" if intent else ""))
|
||||
if context.get("manual_modules"):
|
||||
lines.extend(["", "## 操作手册页面/流程模块", ""])
|
||||
for i, module in enumerate(context["manual_modules"], start=1):
|
||||
if not isinstance(module, dict):
|
||||
lines.append(f"{i}. {module}")
|
||||
continue
|
||||
title = module.get("title") or module.get("feature") or f"模块 {i}"
|
||||
usage = module.get("usage") or module.get("usage_scenario") or ""
|
||||
entry = module.get("entry") or ""
|
||||
steps = module.get("operation_steps") or module.get("steps") or []
|
||||
lines.append(f"{i}. {title}" + (f"：{entry}" if entry else ""))
|
||||
if usage:
|
||||
lines.append(f" - 使用场景：{usage}")
|
||||
if steps:
|
||||
lines.append(f" - 操作要点：{'；'.join(str(item) for item in steps[:4])}")
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"## 申请表建议口径",
|
||||
"",
|
||||
f"- 开发目的：{context['application_purpose']}",
|
||||
f"- 软件的主要功能：{context['main_functions']}",
|
||||
f"- 技术特点：{context['technical_characteristics']}",
|
||||
f"- 软件的技术特点选项：{context['software_technical_option']}",
|
||||
f"- 软件分类：{context['software_category']}",
|
||||
"",
|
||||
"## 证据来源",
|
||||
"",
|
||||
]
|
||||
)
|
||||
lines.extend(f"- `{item['path']}`" for item in context["source_documents"])
|
||||
lines.extend(["", "## 待确认", ""])
|
||||
lines.extend(f"- {item}" for item in context["review_notes"])
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"```text",
|
||||
"STOP_FOR_USER",
|
||||
f"NEXT_ACTION: {context['next_action']}",
|
||||
"```",
|
||||
]
|
||||
)
|
||||
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--project", required=True)
|
||||
parser.add_argument("--analysis", required=True)
|
||||
parser.add_argument("--software-name", required=True)
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||||
parser.add_argument("--web-notes", help="Optional plain-text notes from external/competitor research")
|
||||
parser.add_argument("--model-context", help="Model-authored business context JSON")
|
||||
args = parser.parse_args()
|
||||
|
||||
project = Path(args.project)
|
||||
analysis = read_json(Path(args.analysis))
|
||||
web_notes = read_text(Path(args.web_notes)) if args.web_notes else ""
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
|
||||
evidence = build_evidence(project, analysis, args.software_name, web_notes)
|
||||
write_json(out_dir / "业务理解证据.json", evidence)
|
||||
write_evidence_md(out_dir / "业务理解证据.md", evidence)
|
||||
|
||||
if not args.model_context:
|
||||
write_model_template(out_dir / "业务理解模型稿模板.json", evidence)
|
||||
print(f"OK business evidence: {out_dir / '业务理解证据.md'}")
|
||||
print(f"OK model template: {out_dir / '业务理解模型稿模板.json'}")
|
||||
print("NEXT_ACTION: 模型需要阅读业务理解证据和项目源码，自行编写业务理解模型稿 JSON，然后用 --model-context 生成业务理解.md/json。")
|
||||
return
|
||||
|
||||
model = load_model_context(Path(args.model_context))
|
||||
context = normalize_model_context(model, evidence, web_notes)
|
||||
write_json(out_dir / "业务理解.json", context)
|
||||
write_context_md(out_dir / "业务理解.md", context)
|
||||
print(f"OK business context: {out_dir / '业务理解.md'}")
|
||||
print(f"Features: {len(context['business_features'])}")
|
||||
print("STOP_FOR_USER")
|
||||
print(f"NEXT_ACTION: {context['next_action']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,837 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate a reviewer-oriented operation manual Markdown draft."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import ensure_dir, read_json
|
||||
|
||||
|
||||
def join_items(items: list[str], limit: int = 4) -> str:
|
||||
values = [str(item) for item in items if str(item).strip()]
|
||||
if not values:
|
||||
return "业务用户"
|
||||
return "、".join(values[:limit])
|
||||
|
||||
|
||||
def feature_summary(feature: str, detail: str, software_name: str) -> str:
|
||||
clean_detail = normalize_detail(feature, detail)
|
||||
return clean_detail
|
||||
|
||||
|
||||
def plain_manual_text(text: str) -> str:
|
||||
value = text
|
||||
replacements = {
|
||||
"多 Agent": "多智能体",
|
||||
"多 agent": "多智能体",
|
||||
"业务逻辑": "使用过程",
|
||||
"前端页面": "软件页面",
|
||||
"前端": "界面",
|
||||
"后端服务": "系统服务",
|
||||
"后端": "系统服务",
|
||||
"接口": "数据通道",
|
||||
"组件": "页面组成部分",
|
||||
"路由": "页面入口",
|
||||
"状态管理": "状态记录",
|
||||
"数据持久化": "数据保存",
|
||||
"异步任务": "后台处理任务",
|
||||
"任务队列": "任务处理服务",
|
||||
"模型": "智能服务",
|
||||
"调度中心": "协调中心",
|
||||
"结构化依据": "后续说明",
|
||||
"高成本生成": "耗时较长的内容生成",
|
||||
}
|
||||
for source, target in replacements.items():
|
||||
value = value.replace(source, target)
|
||||
value = re.sub(r"(?<![A-Za-z])Agent(?![A-Za-z])", "智能体", value)
|
||||
value = re.sub(r"(?<![A-Za-z])agent(?![A-Za-z])", "智能体", value)
|
||||
value = re.sub(r"\b(?!Node\.js\b)[A-Za-z]+\.js\b", "相关软件能力", value)
|
||||
value = re.sub(r"\bReact\b|\bVue\b|\bVite\b|\bNext\b|\bNext\.js\b|\bFastAPI\b|\bLangGraph\b|\bCelery\b|\bSSE\b", "相关软件能力", value)
|
||||
value = re.sub(r"相关软件能力、相关软件能力", "相关软件能力", value)
|
||||
value = re.sub(r"多智能体\s+协作", "多智能体协作", value)
|
||||
return value
|
||||
|
||||
|
||||
def plain_feature_name(name: str) -> str:
|
||||
value = plain_manual_text(str(name))
|
||||
value = value.replace("Chat", "对话")
|
||||
return value.strip() or "核心功能"
|
||||
|
||||
|
||||
def normalize_detail(feature: str, detail: str) -> str:
|
||||
value = plain_manual_text(detail or "").strip()
|
||||
value = re.sub(rf"^{re.escape(feature)}(模块|功能)?用于", "", value)
|
||||
value = re.sub(rf"^{re.escape(feature)}主要用于", "", value)
|
||||
value = re.sub(r"^主要用于", "", value)
|
||||
value = re.sub(rf"^{re.escape(feature)}[：:，, ]*", "", value)
|
||||
value = re.sub(rf"^用户使用{re.escape(feature)}时，可以", "", value)
|
||||
value = re.sub(rf"^进入{re.escape(feature)}后，用户可以", "", value)
|
||||
value = re.sub(rf"^在{re.escape(feature)}中，用户可以", "", value)
|
||||
value = re.sub(rf"^用户通过{re.escape(feature)}可以", "", value)
|
||||
value = re.sub(rf"^在{re.escape(feature)}环节，用户可以", "", value)
|
||||
value = re.sub(rf"^通过{re.escape(feature)}，用户可以", "", value)
|
||||
value = value.strip("。；; ，,")
|
||||
if not value or value == feature:
|
||||
value = "支撑软件中的相关业务处理，帮助用户完成信息查看、内容填写、结果确认或资料维护"
|
||||
return value + ("。" if not value.endswith("。") else "")
|
||||
|
||||
|
||||
TECHNICAL_TERMS = [
|
||||
"技术实现",
|
||||
"代码",
|
||||
"框架",
|
||||
"接口封装",
|
||||
"状态管理",
|
||||
"异步任务",
|
||||
"任务队列",
|
||||
"数据持久化",
|
||||
"业务逻辑",
|
||||
"React",
|
||||
"Next.js",
|
||||
"FastAPI",
|
||||
"LangGraph",
|
||||
"Celery",
|
||||
]
|
||||
|
||||
TEMPLATE_MARKERS = [
|
||||
"重要功能之一",
|
||||
"通过清晰的页面入口、信息展示和结果反馈",
|
||||
"对应操作环节",
|
||||
"审核时可重点查看",
|
||||
"审核人员可通过",
|
||||
"按照页面提示填写内容、选择资料、确认方案或点击提交按钮",
|
||||
"系统处理完成后显示结果或提示信息",
|
||||
"帮助用户用户",
|
||||
"帮助用户系统",
|
||||
"主要用于在",
|
||||
"项目管理或资产中心项目管理",
|
||||
"进入方式：",
|
||||
"页面内容：",
|
||||
"操作步骤：",
|
||||
"操作规则：",
|
||||
"操作结果与反馈：",
|
||||
"功能特点根据当前项目资料",
|
||||
"软件围绕",
|
||||
]
|
||||
|
||||
AI_TONE_MARKERS = [
|
||||
"旨在",
|
||||
"赋能",
|
||||
"一站式",
|
||||
"智能化",
|
||||
"高效便捷",
|
||||
"显著提升",
|
||||
"强大能力",
|
||||
"丰富功能",
|
||||
"极大地",
|
||||
"全方位",
|
||||
"多维度",
|
||||
"闭环",
|
||||
"降本增效",
|
||||
"优化体验",
|
||||
"提升效率",
|
||||
]
|
||||
|
||||
|
||||
def manual_section_body(text: str, title: str) -> str:
|
||||
number_pattern = r"(?:\(\d+\)、|[零一二三四五六七八九十百]+、)"
|
||||
pattern = re.compile(rf"^##\s+{number_pattern}\s*{re.escape(title)}\s*$", flags=re.M)
|
||||
match = pattern.search(text)
|
||||
if not match:
|
||||
return ""
|
||||
next_match = re.search(rf"^##\s+{number_pattern}", text[match.end() :], flags=re.M)
|
||||
end = match.end() + next_match.start() if next_match else len(text)
|
||||
return text[match.end() : end].strip()
|
||||
|
||||
|
||||
def manual_quality_issues(text: str, modules: list[dict[str, Any]]) -> list[str]:
|
||||
issues: list[str] = []
|
||||
required_sections = ["相关文档", "说明", "功能特点", "系统要求", "常见问题解答", "术语表"]
|
||||
for title in required_sections:
|
||||
if not manual_section_body(text, title):
|
||||
issues.append(f"缺少通用手册章节：{title}")
|
||||
if re.search(r"^##\s+\(\d+\)、", text, flags=re.M):
|
||||
issues.append("章节标题仍使用括号数字，应使用中文大写序号")
|
||||
related_body = manual_section_body(text, "相关文档")
|
||||
if related_body and "| 文档名称 |" not in related_body:
|
||||
issues.append("相关文档章节应使用表格指向配套文档")
|
||||
for term in TECHNICAL_TERMS:
|
||||
if term in text:
|
||||
issues.append(f"存在偏技术表达：{term}")
|
||||
for marker in TEMPLATE_MARKERS:
|
||||
if marker in text:
|
||||
issues.append(f"存在模板化表达：{marker}")
|
||||
for marker in AI_TONE_MARKERS:
|
||||
if marker in text:
|
||||
issues.append(f"存在疑似 AI 味/空泛表达：{marker}")
|
||||
if text.count("【截图预留：") < len(modules):
|
||||
issues.append("截图预留数量少于核心模块数量")
|
||||
list_lines = [
|
||||
line.strip()
|
||||
for line in text.splitlines()
|
||||
if re.match(r"^(?:[-*+]\s+|\d+\.\s+)", line.strip())
|
||||
]
|
||||
if list_lines:
|
||||
issues.append(f"正文仍存在项目符号或编号列表：{list_lines[0][:40]}")
|
||||
for module in modules:
|
||||
title = str(module.get("feature") or "").strip()
|
||||
if not title:
|
||||
continue
|
||||
body = manual_section_body(text, title)
|
||||
if not body:
|
||||
issues.append(f"缺少核心模块章节：{title}")
|
||||
continue
|
||||
if len(body) < 390:
|
||||
issues.append(f"模块内容偏薄：{title}")
|
||||
for label in ("进入方式：", "页面内容：", "操作步骤：", "操作规则：", "操作结果与反馈："):
|
||||
if label in body:
|
||||
issues.append(f"模块仍使用制式小标题：{title} / {label}")
|
||||
return issues
|
||||
|
||||
|
||||
def clean_field(value: str, default: str) -> str:
|
||||
text = plain_manual_text(str(value or "")).strip()
|
||||
if not text or text == "待用户确认":
|
||||
return default
|
||||
return text + ("。" if not text.endswith(("。", "！", "？")) else "")
|
||||
|
||||
|
||||
def as_text_list(value: Any) -> list[str]:
|
||||
if value is None:
|
||||
return []
|
||||
if isinstance(value, list):
|
||||
return [plain_manual_text(str(item)).strip() for item in value if str(item).strip()]
|
||||
text = plain_manual_text(str(value)).strip()
|
||||
if not text:
|
||||
return []
|
||||
return [item.strip() for item in re.split(r"[；;\n]+", text) if item.strip()]
|
||||
|
||||
|
||||
def required_module_text(item: dict[str, Any], field: str, title: str) -> str:
|
||||
value = plain_manual_text(str(item.get(field) or "")).strip()
|
||||
if not value:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
f"NEXT_ACTION: 操作手册页面模块“{title}”缺少 `{field}`。请回到业务理解阶段，"
|
||||
"由模型根据真实页面证据补全 manual_modules 后再生成操作手册。"
|
||||
)
|
||||
return value
|
||||
|
||||
|
||||
def required_module_list(item: dict[str, Any], field: str, title: str) -> list[str]:
|
||||
values = as_text_list(item.get(field))
|
||||
if not values:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
f"NEXT_ACTION: 操作手册页面模块“{title}”缺少 `{field}`。请回到业务理解阶段，"
|
||||
"由模型根据真实页面证据补全 manual_modules 后再生成操作手册。"
|
||||
)
|
||||
return values
|
||||
|
||||
|
||||
def normalize_manual_modules(
|
||||
business: dict[str, Any] | None,
|
||||
fallback_modules: list[dict[str, Any]],
|
||||
) -> list[dict[str, Any]]:
|
||||
manual_modules = business.get("manual_modules") if business else []
|
||||
if not manual_modules:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解缺少 `manual_modules`。不要由脚本按 auth/query/form 等模板猜测操作手册。"
|
||||
"请模型阅读项目真实页面、路由、按钮、输入项、提示和结果反馈，补全 manual_modules 后再生成操作手册。"
|
||||
)
|
||||
|
||||
modules: list[dict[str, Any]] = []
|
||||
for index, item in enumerate(manual_modules, start=1):
|
||||
if not isinstance(item, dict):
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
f"NEXT_ACTION: manual_modules 第 {index} 项不是对象，无法生成真实操作手册。请补全 title、purpose、entry、operation_steps、feedback 等字段。"
|
||||
)
|
||||
title = plain_feature_name(item.get("title") or item.get("feature") or f"功能模块 {index}")
|
||||
purpose = required_module_text(item, "purpose", title)
|
||||
entry = required_module_text(item, "entry", title)
|
||||
usage = plain_manual_text(
|
||||
str(item.get("usage") or item.get("usage_scenario") or item.get("description") or "")
|
||||
).strip()
|
||||
if not usage:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
f"NEXT_ACTION: 操作手册页面模块“{title}”缺少 `usage` 或 `usage_scenario`。请回到业务理解阶段，"
|
||||
"补充用户在什么场景下会使用该页面、处理什么具体事务，再生成操作手册。"
|
||||
)
|
||||
steps = required_module_list(item, "operation_steps", title)
|
||||
feedback = required_module_list(item, "feedback", title)
|
||||
screenshot_note = plain_manual_text(str(item.get("screenshot") or "")).strip()
|
||||
if not screenshot_note:
|
||||
screenshot_note = f"请在此处插入“{title}”页面或操作结果截图"
|
||||
modules.append(
|
||||
{
|
||||
"feature": title,
|
||||
"raw_feature": title,
|
||||
"purpose": purpose + ("。" if not purpose.endswith(("。", "！", "？")) else ""),
|
||||
"entry": entry + ("。" if not entry.endswith(("。", "！", "？")) else ""),
|
||||
"usage": usage,
|
||||
"visible_elements": as_text_list(item.get("visible_elements") or item.get("page_elements")),
|
||||
"steps": steps,
|
||||
"validation_rules": as_text_list(item.get("validation_rules") or item.get("rules") or item.get("limits")),
|
||||
"feedback": feedback,
|
||||
"result": "；".join(feedback),
|
||||
"screenshot": f"【截图预留：{screenshot_note.strip('。')}。】",
|
||||
}
|
||||
)
|
||||
return modules
|
||||
|
||||
|
||||
def normalize_system_requirements(business: dict[str, Any] | None) -> list[dict[str, str]]:
|
||||
raw_items = business.get("system_requirements") if business else None
|
||||
rows: list[dict[str, str]] = []
|
||||
if isinstance(raw_items, list):
|
||||
for item in raw_items:
|
||||
if isinstance(item, dict):
|
||||
name = str(item.get("item") or item.get("name") or "").strip()
|
||||
minimum = str(item.get("minimum") or item.get("min") or "").strip()
|
||||
recommended = str(item.get("recommended") or item.get("recommend") or "").strip()
|
||||
if name:
|
||||
rows.append(
|
||||
{
|
||||
"item": plain_manual_text(name),
|
||||
"minimum": plain_manual_text(minimum or "按实际部署环境配置"),
|
||||
"recommended": plain_manual_text(recommended or minimum or "按实际部署环境配置"),
|
||||
}
|
||||
)
|
||||
if not rows:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解缺少 `system_requirements`。请根据真实项目运行形态和已确认申请表环境补全后再生成操作手册。"
|
||||
)
|
||||
return rows
|
||||
|
||||
|
||||
def normalize_faq(business: dict[str, Any] | None, software_name: str) -> list[dict[str, str]]:
|
||||
raw_items = business.get("faq") if business else None
|
||||
items: list[dict[str, str]] = []
|
||||
if isinstance(raw_items, list):
|
||||
for item in raw_items:
|
||||
if isinstance(item, dict):
|
||||
question = str(item.get("question") or item.get("q") or "").strip()
|
||||
answer = str(item.get("answer") or item.get("a") or "").strip()
|
||||
if question and answer:
|
||||
items.append({"question": plain_manual_text(question), "answer": plain_manual_text(answer)})
|
||||
if not items:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解缺少 `faq`。请根据当前软件真实使用场景补全常见问题后再生成操作手册。"
|
||||
)
|
||||
return items
|
||||
|
||||
|
||||
def normalize_glossary(business: dict[str, Any] | None, modules: list[dict[str, Any]], software_name: str) -> list[dict[str, str]]:
|
||||
raw_items = business.get("glossary") if business else None
|
||||
items: list[dict[str, str]] = []
|
||||
if isinstance(raw_items, list):
|
||||
for item in raw_items:
|
||||
if isinstance(item, dict):
|
||||
term = str(item.get("term") or item.get("name") or "").strip()
|
||||
definition = str(item.get("definition") or item.get("description") or "").strip()
|
||||
if term and definition:
|
||||
items.append({"term": plain_manual_text(term), "definition": plain_manual_text(definition)})
|
||||
if items:
|
||||
return items
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解缺少 `glossary`。请根据当前软件真实业务对象和页面术语补全术语表后再生成操作手册。"
|
||||
)
|
||||
|
||||
|
||||
def feature_phrase(modules: list[dict[str, Any]], limit: int = 5) -> str:
|
||||
names = [module["feature"] for module in modules if module.get("feature")]
|
||||
return "、".join(names[:limit]) if names else "主要业务处理"
|
||||
|
||||
|
||||
def chinese_number(value: int) -> str:
|
||||
digits = "零一二三四五六七八九"
|
||||
if value <= 0:
|
||||
return str(value)
|
||||
if value < 10:
|
||||
return digits[value]
|
||||
if value == 10:
|
||||
return "十"
|
||||
if value < 20:
|
||||
return "十" + digits[value % 10]
|
||||
if value < 100:
|
||||
tens, ones = divmod(value, 10)
|
||||
return digits[tens] + "十" + (digits[ones] if ones else "")
|
||||
return str(value)
|
||||
|
||||
|
||||
def section_heading(index: int, title: str) -> str:
|
||||
return f"## {chinese_number(index)}、{title}"
|
||||
|
||||
|
||||
def strip_sentence_punctuation(text: str) -> str:
|
||||
return str(text or "").strip().strip("。；;，, ")
|
||||
|
||||
|
||||
def natural_join(items: list[str], limit: int | None = None) -> str:
|
||||
values = [strip_sentence_punctuation(item) for item in items if strip_sentence_punctuation(item)]
|
||||
if limit is not None:
|
||||
values = values[:limit]
|
||||
if not values:
|
||||
return ""
|
||||
if len(values) == 1:
|
||||
return values[0]
|
||||
return "、".join(values[:-1]) + "和" + values[-1]
|
||||
|
||||
|
||||
def ensure_sentence(text: str) -> str:
|
||||
value = strip_sentence_punctuation(plain_manual_text(text))
|
||||
if not value:
|
||||
return ""
|
||||
return value + "。"
|
||||
|
||||
|
||||
def remove_opening_definition(text: str, software_name: str) -> str:
|
||||
value = plain_manual_text(text).strip()
|
||||
if not value:
|
||||
return ""
|
||||
sentences = re.findall(r"[^。！？]+[。！？]?", value)
|
||||
if sentences and sentences[0].startswith(software_name) and "是一款" in sentences[0]:
|
||||
sentences = sentences[1:]
|
||||
return "".join(sentences).strip()
|
||||
|
||||
|
||||
def flow_summary(flow: list[str], modules: list[dict[str, Any]]) -> str:
|
||||
if flow:
|
||||
pieces = [strip_sentence_punctuation(plain_manual_text(item)) for item in flow[:4]]
|
||||
pieces = [item for item in pieces if item]
|
||||
if pieces:
|
||||
return "；".join(pieces) + "。"
|
||||
names = [module["feature"] for module in modules[:4]]
|
||||
if names:
|
||||
return f"用户可依次使用{natural_join(names)}等页面完成主要工作。"
|
||||
return "用户可按照页面提示完成主要业务操作。"
|
||||
|
||||
|
||||
def describe_related_doc(name: str) -> str:
|
||||
if "总体" in name:
|
||||
return "说明软件整体功能、页面组成、运行环境和业务边界。"
|
||||
if "详细" in name:
|
||||
return "说明各功能页面、输入输出、状态变化和处理规则。"
|
||||
if "测试" in name or "案例" in name:
|
||||
return "记录主要功能的操作场景、预期结果和异常提示。"
|
||||
return "记录与本软件功能、操作或验证相关的配套说明。"
|
||||
|
||||
|
||||
def normalize_related_documents(business: dict[str, Any] | None) -> list[dict[str, str]]:
|
||||
raw_items = business.get("related_documents") if business else None
|
||||
rows: list[dict[str, str]] = []
|
||||
if isinstance(raw_items, list):
|
||||
for item in raw_items:
|
||||
if isinstance(item, dict):
|
||||
name = str(item.get("name") or item.get("title") or item.get("document") or "").strip()
|
||||
target = str(item.get("target") or item.get("path") or item.get("file") or "").strip()
|
||||
description = str(item.get("description") or item.get("purpose") or "").strip()
|
||||
if name:
|
||||
rows.append(
|
||||
{
|
||||
"name": plain_manual_text(name),
|
||||
"target": plain_manual_text(target or f"《{name}》"),
|
||||
"description": plain_manual_text(description or describe_related_doc(name)),
|
||||
}
|
||||
)
|
||||
elif str(item).strip():
|
||||
name = str(item).strip()
|
||||
rows.append(
|
||||
{
|
||||
"name": plain_manual_text(name),
|
||||
"target": f"《{plain_manual_text(name)}》",
|
||||
"description": describe_related_doc(name),
|
||||
}
|
||||
)
|
||||
if not rows:
|
||||
for name in ("总体设计", "详细设计", "测试案例"):
|
||||
rows.append({"name": name, "target": f"《{name}》", "description": describe_related_doc(name)})
|
||||
return rows
|
||||
|
||||
|
||||
def clean_purpose_text(feature: str, purpose: str) -> str:
|
||||
value = strip_sentence_punctuation(plain_manual_text(purpose))
|
||||
value = re.sub(rf"^{re.escape(feature)}(页面|功能|模块|环节)?(主要)?用于", "", value)
|
||||
value = re.sub(r"^[^，。；;]{1,30}(页面|功能|模块|环节|状态栏|面板)?(主要)?用于", "", value)
|
||||
value = re.sub(r"^用于", "", value)
|
||||
value = value.strip("。；;，, ")
|
||||
return value or "完成本页面相关操作"
|
||||
|
||||
|
||||
def page_label(feature: str) -> str:
|
||||
value = strip_sentence_punctuation(feature)
|
||||
if value.startswith("用户") and len(value) > 2:
|
||||
value = value[2:]
|
||||
return value
|
||||
|
||||
|
||||
def purpose_core_sentence(feature: str, purpose: str) -> str:
|
||||
value = clean_purpose_text(feature, purpose)
|
||||
label = page_label(feature)
|
||||
if re.match(r"^(展示|集中展示|承载|提供|处理|保存|记录|辅助)", value):
|
||||
return f"{label}页面{value}"
|
||||
if value.startswith("让用户"):
|
||||
return f"{label}页面{value}"
|
||||
return f"用户可在{label}页面{value}"
|
||||
|
||||
|
||||
def purpose_sentence(feature: str, purpose: str) -> str:
|
||||
return purpose_core_sentence(feature, purpose) + "。"
|
||||
|
||||
|
||||
def entry_sentence(entry: str) -> str:
|
||||
value = strip_sentence_punctuation(plain_manual_text(entry))
|
||||
if not value:
|
||||
return ""
|
||||
if value.startswith("用户"):
|
||||
return value + "。"
|
||||
if re.match(r"^(登录|创建|进入|打开|点击|完成|选择|提交)", value):
|
||||
return f"用户{value}。"
|
||||
if value.startswith("当"):
|
||||
return value + "。"
|
||||
return f"用户可以通过{value}。"
|
||||
|
||||
|
||||
def visible_elements_sentence(items: list[str], feature: str, index: int) -> str:
|
||||
value = natural_join(items, limit=8)
|
||||
if not value:
|
||||
return ""
|
||||
variants = [
|
||||
f"页面上主要呈现{value}等内容，这些内容用于帮助用户确认当前位置和可执行操作。",
|
||||
f"用户在{feature}页面会看到{value}等信息，并可依据页面显示继续处理。",
|
||||
f"该部分提供{value}等页面内容，用户可据此查看状态、填写信息或选择下一步操作。",
|
||||
]
|
||||
return variants[(index - 1) % len(variants)]
|
||||
|
||||
|
||||
def steps_sentence(steps: list[str], module_index: int) -> str:
|
||||
values = [strip_sentence_punctuation(step) for step in steps if strip_sentence_punctuation(step)]
|
||||
if not values:
|
||||
return ""
|
||||
connectors = ["先", "随后", "接着", "之后", "再", "继续"]
|
||||
parts: list[str] = []
|
||||
for step_index, step in enumerate(values):
|
||||
if step_index == len(values) - 1 and len(values) > 1:
|
||||
connector = "最后"
|
||||
else:
|
||||
connector = connectors[min(step_index, len(connectors) - 1)]
|
||||
parts.append(f"{connector}{step}")
|
||||
prefixes = ["实际操作时，用户", "使用该功能时，用户", "在该页面中，用户"]
|
||||
return prefixes[(module_index - 1) % len(prefixes)] + "，".join(parts) + "。"
|
||||
|
||||
|
||||
def rules_feedback_sentence(rules: list[str], feedback: list[str], index: int) -> str:
|
||||
parts: list[str] = []
|
||||
rule_text = natural_join(rules, limit=6)
|
||||
if rule_text:
|
||||
rule_templates = [
|
||||
f"操作过程中需要注意{rule_text}。",
|
||||
f"页面会按照{rule_text}等规则限制或提示用户。",
|
||||
f"如果不满足{rule_text}等要求，用户需要根据页面提示调整后再继续。",
|
||||
]
|
||||
parts.append(rule_templates[(index - 1) % len(rule_templates)])
|
||||
feedback_text = natural_join(feedback, limit=6)
|
||||
if feedback_text:
|
||||
feedback_templates = [
|
||||
f"操作完成后，系统会显示{feedback_text}。",
|
||||
f"处理结束后，用户可以看到{feedback_text}。",
|
||||
f"页面反馈通常包括{feedback_text}。",
|
||||
]
|
||||
parts.append(feedback_templates[(index - 1) % len(feedback_templates)])
|
||||
return "".join(parts)
|
||||
|
||||
|
||||
def feature_paragraph(module: dict[str, Any], index: int) -> str:
|
||||
feature = module["feature"]
|
||||
purpose = clean_purpose_text(feature, module.get("purpose") or "")
|
||||
label = page_label(feature)
|
||||
core = purpose_core_sentence(feature, module.get("purpose") or "")
|
||||
elements = natural_join(as_text_list(module.get("visible_elements")), limit=5)
|
||||
feedback = natural_join(as_text_list(module.get("feedback")), limit=3)
|
||||
variants = [
|
||||
f"{core}。页面上的{elements or '相关业务信息'}会集中呈现当前可操作内容，用户处理完成后可以看到{feedback or '相应的处理结果'}。",
|
||||
f"在{label}页面中，用户主要处理{purpose}。系统把{elements or '页面显示内容'}放在当前操作区域，处理结束后会反馈{feedback or '处理结果'}。",
|
||||
f"{label}页面关注的是{purpose}。用户通过{elements or '必要的页面信息'}确认当前状态，并在操作结束后获得{feedback or '当前状态反馈'}。",
|
||||
]
|
||||
return variants[(index - 1) % len(variants)]
|
||||
|
||||
|
||||
def tidy_manual_output(text: str) -> str:
|
||||
replacements = {
|
||||
"用户主要处理处理": "用户主要处理",
|
||||
"主要处理承载一次": "主要围绕一次",
|
||||
"用户可以看到用户可以看到": "用户可以看到",
|
||||
"处理结束后会反馈空对话": "处理结束后会显示空对话",
|
||||
"在AI ": "在 AI ",
|
||||
"把StudioAgent": "把 StudioAgent",
|
||||
"页面上的StudioAgent": "页面上的 StudioAgent",
|
||||
"看到StudioAgent": "看到 StudioAgent",
|
||||
"提供StudioAgent": "提供 StudioAgent",
|
||||
"进入StudioAgent": "进入 StudioAgent",
|
||||
"保证StudioAgent": "保证 StudioAgent",
|
||||
}
|
||||
value = text
|
||||
for source, target in replacements.items():
|
||||
value = value.replace(source, target)
|
||||
value = re.sub(r"(?<=[\u4e00-\u9fff])([A-Za-z][A-Za-z0-9.+-]*)(?=[\u4e00-\u9fff])", r" \1 ", value)
|
||||
value = re.sub(r" {2,}", " ", value)
|
||||
return value
|
||||
|
||||
|
||||
def append_modules_canonical(lines: list[str], modules: list[dict[str, Any]], start_index: int) -> int:
|
||||
for i, module in enumerate(modules, start=start_index):
|
||||
visible_elements = as_text_list(module.get("visible_elements"))
|
||||
validation_rules = as_text_list(module.get("validation_rules"))
|
||||
feedback = as_text_list(module.get("feedback")) or [module["result"]]
|
||||
lines.extend(
|
||||
[
|
||||
section_heading(i, module["feature"]),
|
||||
"",
|
||||
purpose_sentence(module["feature"], module["purpose"]) + entry_sentence(module["entry"]),
|
||||
"",
|
||||
]
|
||||
)
|
||||
if module.get("usage"):
|
||||
lines.extend([ensure_sentence(module["usage"]), ""])
|
||||
element_text = visible_elements_sentence(visible_elements, module["feature"], i)
|
||||
if element_text:
|
||||
lines.extend([element_text, ""])
|
||||
step_text = steps_sentence(module["steps"], i)
|
||||
if step_text:
|
||||
lines.extend([step_text, ""])
|
||||
rule_feedback = rules_feedback_sentence(validation_rules, feedback, i)
|
||||
if rule_feedback:
|
||||
lines.extend([rule_feedback, ""])
|
||||
lines.extend(["", module["screenshot"], ""])
|
||||
return start_index + len(modules)
|
||||
|
||||
|
||||
def append_flow_canonical(lines: list[str], software_name: str, flow: list[str], start_index: int) -> int:
|
||||
lines.extend(
|
||||
[
|
||||
section_heading(start_index, "典型使用流程"),
|
||||
"",
|
||||
f"用户完成一次完整业务时，通常先进入{software_name}，再选择或创建业务对象，随后按照页面提示处理内容并查看结果。",
|
||||
"",
|
||||
flow_summary(flow, []),
|
||||
"",
|
||||
]
|
||||
)
|
||||
return start_index + 1
|
||||
|
||||
|
||||
def render_manual_canonical(
|
||||
software_name: str,
|
||||
version: str,
|
||||
industry: str,
|
||||
users: list[str],
|
||||
positioning: str,
|
||||
core_value: str,
|
||||
modules: list[dict[str, Any]],
|
||||
operation_flow: list[str],
|
||||
manual_sections: list[Any] | None = None,
|
||||
business: dict[str, Any] | None = None,
|
||||
) -> str:
|
||||
industry_text = "相关业务" if not industry or industry == "待用户确认" else industry
|
||||
user_text = join_items([user for user in users if user != "待用户确认"]) or "实际使用人员"
|
||||
positioning_text = remove_opening_definition(positioning, software_name)
|
||||
core_value_text = clean_field(core_value, "软件可以帮助用户统一处理相关业务资料，并减少重复操作。")
|
||||
flow = operation_flow
|
||||
related_documents = normalize_related_documents(business)
|
||||
system_rows = normalize_system_requirements(business)
|
||||
faq_items = normalize_faq(business, software_name)
|
||||
glossary_items = normalize_glossary(business, modules, software_name)
|
||||
overview_paragraphs: list[str] = []
|
||||
for section in manual_sections or []:
|
||||
if isinstance(section, dict) and section.get("paragraphs") and len(overview_paragraphs) < 4:
|
||||
overview_paragraphs.extend(as_text_list(section.get("paragraphs"))[:2])
|
||||
|
||||
lines = [f"# {software_name}操作手册", "", section_heading(1, "相关文档"), ""]
|
||||
lines.extend(["| 文档名称 | 指向资料 | 说明 |", "| --- | --- | --- |"])
|
||||
for item in related_documents:
|
||||
lines.append(f"| {item['name']} | {item['target']} | {item['description']} |")
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
section_heading(2, "说明"),
|
||||
"",
|
||||
f"{software_name} {version}适用于{industry_text}场景。用户进入系统后，可以围绕实际工作内容完成账号进入、业务创建、过程查看、结果确认和资料管理等操作。",
|
||||
"",
|
||||
f"日常使用时，{user_text}可以按照页面提示从入口进入相应页面，查看当前业务状态，并根据页面中的按钮、输入框、列表或弹窗继续处理。{core_value_text}",
|
||||
"",
|
||||
]
|
||||
)
|
||||
if positioning_text:
|
||||
lines.extend([positioning_text, ""])
|
||||
for paragraph in overview_paragraphs:
|
||||
lines.extend([paragraph, ""])
|
||||
lines.extend(
|
||||
[
|
||||
"本手册用于说明软件的用途、功能特点、运行要求和页面操作流程。各功能章节按用户能够看到的页面、入口、按钮、输入项、提示信息和处理结果进行说明。",
|
||||
"",
|
||||
section_heading(3, "功能特点"),
|
||||
"",
|
||||
]
|
||||
)
|
||||
for i, module in enumerate(modules[:8], start=1):
|
||||
lines.extend([feature_paragraph(module, i), ""])
|
||||
lines.extend([section_heading(4, "系统要求"), "", "| 系统要求 | 最低配置 | 推荐配置 |", "| --- | --- | --- |"])
|
||||
for row in system_rows:
|
||||
lines.append(f"| {row['item']} | {row['minimum']} | {row['recommended']} |")
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
f"请确保实际运行环境满足以上要求，以保证{software_name}能够正常打开页面、提交操作和展示处理结果。若部署方式、客户端形态或服务器环境与本表不同，应以实际确认的申请表环境字段为准。",
|
||||
"",
|
||||
]
|
||||
)
|
||||
next_index = append_modules_canonical(lines, modules, start_index=5)
|
||||
if flow:
|
||||
next_index = append_flow_canonical(lines, software_name, flow, start_index=next_index)
|
||||
lines.extend([section_heading(next_index, "常见问题解答"), ""])
|
||||
for item in faq_items:
|
||||
lines.extend([f"问题：{item['question']}", f"解决方法：{item['answer']}", ""])
|
||||
next_index += 1
|
||||
lines.extend([section_heading(next_index, "术语表"), "", "| 术语 | 解释 |", "| --- | --- |"])
|
||||
for item in glossary_items:
|
||||
lines.append(f"| {item['term']} | {item['definition']} |")
|
||||
lines.append("")
|
||||
append_stop(lines)
|
||||
return tidy_manual_output("\n".join(lines))
|
||||
|
||||
|
||||
def append_stop(lines: list[str]) -> None:
|
||||
lines.extend(
|
||||
[
|
||||
"```text",
|
||||
"STOP_FOR_USER",
|
||||
"NEXT_ACTION: 请一次性确认完整操作手册草稿是否符合真实业务；必要时先统一修改段落内容，再运行 confirm_stage.py --stage markdown。",
|
||||
"```",
|
||||
"",
|
||||
]
|
||||
)
|
||||
|
||||
|
||||
def build_manual_text(
|
||||
analysis: dict[str, Any],
|
||||
software_name: str,
|
||||
version: str,
|
||||
business: dict[str, Any] | None = None,
|
||||
) -> tuple[str, list[dict[str, Any]], list[dict[str, Any]]]:
|
||||
positioning = plain_manual_text(business.get("product_positioning") if business else f"{software_name} {version}是一款基于项目实际功能整理的软件系统。")
|
||||
core_value = plain_manual_text(business.get("core_value") if business else "系统通过清晰的软件界面为用户提供主要业务入口，支持用户完成信息查看、业务处理、数据维护和结果反馈等操作。")
|
||||
users = business.get("target_users") if business else ["业务用户"]
|
||||
operation_flow = business.get("operation_flow") if business else []
|
||||
manual_sections = business.get("manual_sections") if business else []
|
||||
industry = business.get("industry") if business else "业务应用"
|
||||
if positioning.rstrip("。") == software_name.rstrip("。"):
|
||||
positioning = "用户可以根据项目资料中体现的业务场景完成相应操作。"
|
||||
elif not positioning.endswith("。"):
|
||||
positioning += "。"
|
||||
modules = normalize_manual_modules(business, [])
|
||||
records: list[dict[str, Any]] = []
|
||||
|
||||
text = render_manual_canonical(software_name, version, industry, users, positioning, core_value, modules, operation_flow, manual_sections, business)
|
||||
records.append({"round": 1, "action": "初稿生成", "issues": manual_quality_issues(text, modules)})
|
||||
|
||||
text = render_manual_canonical(software_name, version, industry, users, positioning, core_value, modules, operation_flow, manual_sections, business)
|
||||
records.append({"round": 2, "action": "真实页面字段复核", "issues": manual_quality_issues(text, modules)})
|
||||
|
||||
text = render_manual_canonical(software_name, version, industry, users, positioning, core_value, modules, operation_flow, manual_sections, business)
|
||||
records.append({"round": 3, "action": "制式模板和 AI 味复核", "issues": manual_quality_issues(text, modules)})
|
||||
|
||||
for round_no in range(4, 7):
|
||||
issues = records[-1]["issues"]
|
||||
if not issues:
|
||||
break
|
||||
text = render_manual_canonical(software_name, version, industry, users, positioning, core_value, modules, operation_flow, manual_sections, business)
|
||||
records.append(
|
||||
{
|
||||
"round": round_no,
|
||||
"action": "复核仍需模型回到业务理解补写",
|
||||
"issues": manual_quality_issues(text, modules),
|
||||
}
|
||||
)
|
||||
break
|
||||
return text, records, modules
|
||||
|
||||
|
||||
def write_review_records(out_dir: Path, records: list[dict[str, Any]], modules: list[dict[str, Any]]) -> None:
|
||||
(out_dir / "操作手册自检记录.json").write_text(
|
||||
json.dumps({"rounds": records, "module_count": len(modules)}, ensure_ascii=False, indent=2),
|
||||
encoding="utf-8",
|
||||
)
|
||||
lines = ["# 操作手册自检记录", ""]
|
||||
for record in records:
|
||||
lines.extend([f"## 第 {record['round']} 轮：{record['action']}", ""])
|
||||
if record["issues"]:
|
||||
lines.extend(f"- {issue}" for issue in record["issues"])
|
||||
else:
|
||||
lines.append("- 未发现需继续修正的问题")
|
||||
lines.append("")
|
||||
lines.extend(["## 模块清单", ""])
|
||||
lines.extend(f"- {module['feature']}" for module in modules)
|
||||
(out_dir / "操作手册自检记录.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def write_manual(path: Path, analysis: dict[str, Any], software_name: str, version: str, business: dict[str, Any] | None = None) -> list[dict[str, Any]]:
|
||||
text, records, modules = build_manual_text(analysis, software_name, version, business)
|
||||
path.write_text(text, encoding="utf-8")
|
||||
write_review_records(path.parent, records, modules)
|
||||
return records
|
||||
|
||||
|
||||
def require_confirmed_business(business: dict[str, Any] | None) -> None:
|
||||
if business is None:
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 操作手册必须基于已确认的业务理解生成。请先生成并确认 草稿/业务理解.md。"
|
||||
)
|
||||
if business.get("confirmation_required") and not business.get("user_confirmed"):
|
||||
raise SystemExit(
|
||||
"STOP_FOR_USER\n"
|
||||
"NEXT_ACTION: 业务理解尚未确认。请先确认 草稿/业务理解.md，"
|
||||
"再运行 `python3 <SKILL_DIR>/scripts/confirm_stage.py --workdir 软件著作权申请资料 --stage business --note \"<用户确认内容>\"`。"
|
||||
)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--analysis", required=True)
|
||||
parser.add_argument("--software-name", required=True)
|
||||
parser.add_argument("--version", default="V1.0")
|
||||
parser.add_argument("--business-context", help="Business context JSON generated before manual drafting")
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||||
args = parser.parse_args()
|
||||
|
||||
analysis = read_json(Path(args.analysis))
|
||||
business = read_json(Path(args.business_context)) if args.business_context else None
|
||||
require_confirmed_business(business)
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
out_path = out_dir / "操作手册.md"
|
||||
records = write_manual(out_path, analysis, args.software_name, args.version, business)
|
||||
print(f"OK manual draft: {out_path}")
|
||||
print(f"OK manual self-review: {out_dir / '操作手册自检记录.md'}")
|
||||
for record in records:
|
||||
print(f"Review round {record['round']}: {record['action']} issues={len(record['issues'])}")
|
||||
if records[-1]["issues"]:
|
||||
print("STOP_FOR_USER")
|
||||
print("NEXT_ACTION: 操作手册自检仍有问题。请回到业务理解阶段补全 manual_modules 中的真实页面内容、操作规则和结果反馈后再重新生成。")
|
||||
raise SystemExit(1)
|
||||
print("STOP_FOR_USER")
|
||||
print("NEXT_ACTION: 请一次性确认完整操作手册草稿是否符合真实业务；必要时先统一修改段落内容，再运行 confirm_stage.py --stage markdown。")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,175 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Create an editable source-file evidence list before code extraction."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from common import COPYRIGHT_CODE_EXTS, FRONTEND_EXTS, ensure_dir, is_known_config_file, iter_project_files, read_json, rel, write_json
|
||||
from extract_code_material import LINES_PER_PAGE, SPLIT_THRESHOLD_PAGES, category_weight, should_skip_file
|
||||
|
||||
|
||||
DEFAULT_MAX_FILES = 0
|
||||
|
||||
|
||||
def evidence_for(path: Path, project: Path) -> str:
|
||||
priority, _ = category_weight(path, project)
|
||||
if priority == 0:
|
||||
return "入口文件证据"
|
||||
if priority == 10:
|
||||
return "路由文件证据"
|
||||
if priority == 20:
|
||||
return "页面文件证据"
|
||||
if priority == 30:
|
||||
return "数据交互文件证据"
|
||||
if priority == 40:
|
||||
return "状态或数据文件证据"
|
||||
if priority == 50:
|
||||
return "页面组成文件证据"
|
||||
if priority == 60:
|
||||
return "通用能力文件证据"
|
||||
if priority == 90:
|
||||
return "样式文件证据"
|
||||
if path.suffix.lower() not in FRONTEND_EXTS:
|
||||
return "补充源码证据"
|
||||
return "普通源码文件"
|
||||
|
||||
|
||||
def build_candidates(project: Path) -> list[dict[str, Any]]:
|
||||
files = [p for p in iter_project_files(project, COPYRIGHT_CODE_EXTS) if not should_skip_file(p) and not is_known_config_file(p)]
|
||||
files.sort(key=lambda p: category_weight(p, project))
|
||||
candidates: list[dict[str, Any]] = []
|
||||
for path in files:
|
||||
try:
|
||||
line_count = len(path.read_text(encoding="utf-8", errors="replace").splitlines())
|
||||
except Exception:
|
||||
line_count = 0
|
||||
priority, _ = category_weight(path, project)
|
||||
candidates.append(
|
||||
{
|
||||
"path": rel(path, project),
|
||||
"selected": False,
|
||||
"line_count": line_count,
|
||||
"priority": priority,
|
||||
"selection_tier": "frontend" if path.suffix.lower() in FRONTEND_EXTS else "supplement",
|
||||
"evidence": evidence_for(path, project),
|
||||
"model_reason": "",
|
||||
}
|
||||
)
|
||||
return candidates
|
||||
|
||||
|
||||
def selected_line_estimate(item: dict[str, Any]) -> int:
|
||||
return int(item.get("line_count") or 0) + 2
|
||||
|
||||
|
||||
def selection_stats(candidates: list[dict[str, Any]]) -> dict[str, int]:
|
||||
selected_items = [item for item in candidates if item.get("selected")]
|
||||
return {
|
||||
"selected_count": len(selected_items),
|
||||
"selected_lines": sum(selected_line_estimate(item) for item in selected_items),
|
||||
}
|
||||
|
||||
|
||||
def all_candidate_lines(candidates: list[dict[str, Any]]) -> int:
|
||||
return sum(selected_line_estimate(item) for item in candidates)
|
||||
|
||||
|
||||
def write_selection_md(path: Path, data: dict[str, Any]) -> None:
|
||||
lines = [
|
||||
"# 代码文件候选清单",
|
||||
"",
|
||||
"请先确认要抽取哪些源码文件，再运行代码材料抽取。",
|
||||
"",
|
||||
"本清单只列出候选源码证据，不默认决定抽取文件。",
|
||||
"模型需要先理解项目业务、页面入口和源码职责，再填写 `selected/model_reason`。",
|
||||
f"当前已选约 {data['estimated_selected_pages']} 页，全部候选源码约 {data['estimated_all_candidate_pages']} 页。",
|
||||
"",
|
||||
"```text",
|
||||
"STOP_FOR_USER",
|
||||
"NEXT_ACTION: 请由模型先填写 草稿/代码文件选择.json 的抽取选择和选择理由，再让用户确认；确认后运行 confirm_stage.py --stage code-selection。",
|
||||
"```",
|
||||
"",
|
||||
"确认方式：",
|
||||
"",
|
||||
"1. 模型根据项目业务和代码入口选择最能体现软件功能的文件。",
|
||||
"2. 把需要抽取的文件设为 `selected: true`，并填写 `model_reason`。",
|
||||
"3. 代码材料按完整文件原样复制，不支持只抽取某个文件的中间行段。",
|
||||
"4. 用户确认模型选择后，再记录 `code-selection` 门禁。",
|
||||
"",
|
||||
"## 默认选中文件",
|
||||
"",
|
||||
"| 文件 | 行数 | 模型选择理由 |",
|
||||
"| --- | ---: | --- |",
|
||||
]
|
||||
for item in data["files"]:
|
||||
if item.get("selected"):
|
||||
lines.append(f"| `{item['path']}` | {item['line_count']} | {item.get('model_reason') or '待模型填写'} |")
|
||||
|
||||
lines.extend(["", "## 未选候选文件", "", "| 文件 | 行数 | 证据类型 |", "| --- | ---: | --- |"])
|
||||
for item in data["files"]:
|
||||
if not item.get("selected"):
|
||||
lines.append(f"| `{item['path']}` | {item['line_count']} | {item['evidence']} |")
|
||||
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--project", required=True)
|
||||
parser.add_argument("--analysis", help="Optional project analysis JSON; retained for workflow traceability")
|
||||
parser.add_argument("--out-dir", default="软件著作权申请资料/草稿")
|
||||
parser.add_argument("--max-files", type=int, default=DEFAULT_MAX_FILES, help="Only limits candidate inventory size; does not auto-select files")
|
||||
parser.add_argument("--target-pages", type=int, default=SPLIT_THRESHOLD_PAGES)
|
||||
parser.add_argument("--lines-per-page", type=int, default=LINES_PER_PAGE)
|
||||
args = parser.parse_args()
|
||||
|
||||
project = Path(args.project)
|
||||
if not project.exists():
|
||||
raise SystemExit(f"Project not found: {project}")
|
||||
if args.analysis and not Path(args.analysis).exists():
|
||||
raise SystemExit(f"Analysis JSON not found: {args.analysis}")
|
||||
|
||||
out_dir = ensure_dir(Path(args.out_dir))
|
||||
candidates = build_candidates(project)
|
||||
target_lines = max(1, args.target_pages) * max(1, args.lines_per_page)
|
||||
if args.max_files:
|
||||
candidates = candidates[: args.max_files]
|
||||
stats = selection_stats(candidates)
|
||||
candidate_lines = all_candidate_lines(candidates)
|
||||
selected_pages = (stats["selected_lines"] + args.lines_per_page - 1) // args.lines_per_page if stats["selected_lines"] else 0
|
||||
all_pages = (candidate_lines + args.lines_per_page - 1) // args.lines_per_page if candidate_lines else 0
|
||||
data = {
|
||||
"project_root": str(project.resolve()),
|
||||
"selection_required": True,
|
||||
"model_selection_required": True,
|
||||
"confirmation_required": True,
|
||||
"user_confirmed": False,
|
||||
"target_pages": args.target_pages,
|
||||
"lines_per_page": args.lines_per_page,
|
||||
"target_lines": target_lines,
|
||||
"estimated_selected_lines": stats["selected_lines"],
|
||||
"estimated_selected_pages": selected_pages,
|
||||
"estimated_all_candidate_lines": candidate_lines,
|
||||
"estimated_all_candidate_pages": all_pages,
|
||||
"supplement_rule": "模型优先选择能体现软件核心功能和真实运行逻辑的源码；不足60页时再从其他相关源码中补充；候选源码仍不足时才生成全部代码材料。",
|
||||
"confirmation_stage": "code-selection",
|
||||
"next_action": "请由模型填写 草稿/代码文件选择.json 的抽取选择和选择理由，再让用户确认；确认后运行 confirm_stage.py --stage code-selection。",
|
||||
"instructions": "The script only inventories source files. The model must choose selected/model_reason before user confirmation. Selected files are copied in full.",
|
||||
"files": candidates,
|
||||
}
|
||||
write_json(out_dir / "代码文件选择.json", data)
|
||||
write_selection_md(out_dir / "代码文件候选清单.md", data)
|
||||
selected_count = sum(1 for item in candidates if item.get("selected"))
|
||||
print(f"OK code selection draft: {out_dir}")
|
||||
print(f"Candidates: {len(candidates)}")
|
||||
print(f"Model selected: {selected_count}")
|
||||
print(f"Estimated selected pages: {selected_pages}")
|
||||
print(f"Estimated all candidate pages: {all_pages}")
|
||||
print("STOP_FOR_USER")
|
||||
print(f"NEXT_ACTION: {data['next_action']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,3 @@
|
||||
obj/
|
||||
bin/
|
||||
*.user
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 DocxToolkit
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: docx-toolkit
|
||||
license: MIT
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
category: document-processing
|
||||
author: DocxToolkit
|
||||
sources:
|
||||
- "ECMA-376 Office Open XML File Formats"
|
||||
- "GB/T 9704-2012 Layout Standard for Official Documents"
|
||||
- "IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides"
|
||||
- "Springer LNCS / Nature / HBR Document Templates"
|
||||
description: >
|
||||
Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET).
|
||||
Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing
|
||||
documents, (C) apply template formatting with XSD validation gate-check.
|
||||
MUST use this skill whenever the user wants to produce, modify, or format a Word document —
|
||||
including when they say "write a report", "draft a proposal", "make a contract",
|
||||
"fill in this form", "reformat to match this template", or any task whose final output
|
||||
is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task
|
||||
implies a printable/formal document, use this skill.
|
||||
triggers:
|
||||
- Word
|
||||
- docx
|
||||
- document
|
||||
- 文档
|
||||
- Word文档
|
||||
- 报告
|
||||
- 合同
|
||||
- 公文
|
||||
- 排版
|
||||
- 套模板
|
||||
---
|
||||
|
||||
# docx-toolkit
|
||||
|
||||
Create, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).
|
||||
|
||||
## Setup
|
||||
|
||||
**First time:** `bash scripts/setup.sh` (or `powershell scripts/setup.ps1` on Windows, `--minimal` to skip optional deps).
|
||||
|
||||
**First operation in session:** `scripts/env_check.sh` — do not proceed if `NOT READY`. (Skip on subsequent operations within the same session.)
|
||||
|
||||
## Quick Start: Direct C# Path
|
||||
|
||||
When the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:
|
||||
|
||||
```csharp
|
||||
// File: scripts/dotnet/task.csx (or a new .cs in a Console project)
|
||||
// dotnet run --project scripts/dotnet/DocxToolkit.Cli -- run-script task.csx
|
||||
#r "nuget: DocumentFormat.OpenXml, 3.2.0"
|
||||
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
|
||||
// --- Your logic here ---
|
||||
// Read the relevant Samples/*.cs file FIRST for tested patterns.
|
||||
// See Samples/ table in References section below.
|
||||
```
|
||||
|
||||
**Before writing any C#, read the relevant `Samples/*.cs` file** — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.
|
||||
|
||||
## CLI shorthand
|
||||
|
||||
All CLI commands below use `$CLI` as shorthand for:
|
||||
```bash
|
||||
dotnet run --project scripts/dotnet/DocxToolkit.Cli --
|
||||
```
|
||||
|
||||
## Pipeline routing
|
||||
|
||||
Route by checking: does the user have an input .docx file?
|
||||
|
||||
```
|
||||
User task
|
||||
├─ No input file → Pipeline A: CREATE
|
||||
│ signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
|
||||
│ → Read references/scenario_a_create.md
|
||||
│
|
||||
└─ Has input .docx
|
||||
├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
|
||||
│ signals: "fill in", "replace", "update", "change text", "add section", "edit"
|
||||
│ → Read references/scenario_b_edit_content.md
|
||||
│
|
||||
└─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
|
||||
signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
|
||||
├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
|
||||
└─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
|
||||
(use template as base, replace example content with user content)
|
||||
→ Read references/scenario_c_apply_template.md
|
||||
```
|
||||
|
||||
If the request spans multiple pipelines, run them sequentially (e.g., Create then Format-Apply).
|
||||
|
||||
## Pre-processing
|
||||
|
||||
Convert `.doc` → `.docx` if needed: `scripts/doc_to_docx.sh input.doc output_dir/`
|
||||
|
||||
Preview before editing (avoids reading raw XML): `scripts/docx_preview.sh document.docx`
|
||||
|
||||
Analyze structure for editing scenarios: `$CLI analyze --input document.docx`
|
||||
|
||||
## Scenario A: Create
|
||||
|
||||
Read `references/scenario_a_create.md`, `references/typography_guide.md`, and `references/design_principles.md` first. Pick an aesthetic recipe from `Samples/AestheticRecipeSamples.cs` that matches the document type — do not invent formatting values. For CJK, also read `references/cjk_typography.md`.
|
||||
|
||||
**Choose your path:**
|
||||
- **Simple** (plain text, minimal formatting): use CLI — `$CLI create --type report --output out.docx --config content.json`
|
||||
- **Structural** (custom styles, multi-section, TOC, images, complex tables): write C# directly. Read the relevant `Samples/*.cs` first.
|
||||
|
||||
CLI options: `--type` (report|letter|memo|academic), `--title`, `--author`, `--page-size` (letter|a4|legal|a3), `--margins` (standard|narrow|wide), `--header`, `--footer`, `--page-numbers`, `--toc`, `--content-json`.
|
||||
|
||||
Then run the **validation pipeline** (below).
|
||||
|
||||
## Scenario B: Edit / Fill
|
||||
|
||||
Read `references/scenario_b_edit_content.md` first. Preview → analyze → edit → validate.
|
||||
|
||||
**Choose your path:**
|
||||
- **Simple** (text replacement, placeholder fill): use CLI subcommands.
|
||||
- **Structural** (add/reorganize sections, modify styles, manipulate tables, insert images): write C# directly. Read `references/openxml_element_order.md` and the relevant `Samples/*.cs`.
|
||||
|
||||
Available CLI edit subcommands:
|
||||
- `replace-text --find "X" --replace "Y"`
|
||||
- `fill-placeholders --data '{"key":"value"}'`
|
||||
- `fill-table --data table.json`
|
||||
- `insert-section`, `remove-section`, `update-header-footer`
|
||||
|
||||
```bash
|
||||
$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
|
||||
$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'
|
||||
```
|
||||
|
||||
Then run the **validation pipeline**. Also run diff to verify minimal changes:
|
||||
```bash
|
||||
$CLI diff --before in.docx --after out.docx
|
||||
```
|
||||
|
||||
## Scenario C: Apply Template
|
||||
|
||||
Read `references/scenario_c_apply_template.md` first. Preview and analyze both source and template.
|
||||
|
||||
```bash
|
||||
$CLI apply-template --input source.docx --template template.docx --output out.docx
|
||||
```
|
||||
|
||||
For complex template operations (multi-template merge, per-section headers/footers, style merging), write C# directly — see Critical Rules below for required patterns.
|
||||
|
||||
Run the **validation pipeline**, then the **hard gate-check**:
|
||||
```bash
|
||||
$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd
|
||||
```
|
||||
Gate-check is a **hard requirement**. Do NOT deliver until it passes. If it fails: diagnose, fix, re-run.
|
||||
|
||||
Also diff to verify content preservation: `$CLI diff --before source.docx --after out.docx`
|
||||
|
||||
## Validation pipeline
|
||||
|
||||
Run after every write operation. For Scenario C the full pipeline is **mandatory**; for A/B it is **recommended** (skip only if the operation was trivially simple).
|
||||
|
||||
```bash
|
||||
$CLI merge-runs --input doc.docx # 1. consolidate runs
|
||||
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd # 2. XSD structure
|
||||
$CLI validate --input doc.docx --business # 3. business rules
|
||||
```
|
||||
|
||||
If XSD fails, auto-repair and retry:
|
||||
```bash
|
||||
$CLI fix-order --input doc.docx
|
||||
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
|
||||
```
|
||||
|
||||
If XSD still fails, fall back to business rules + preview:
|
||||
```bash
|
||||
$CLI validate --input doc.docx --business
|
||||
scripts/docx_preview.sh doc.docx
|
||||
# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct
|
||||
```
|
||||
|
||||
Final preview: `scripts/docx_preview.sh doc.docx`
|
||||
|
||||
## Critical rules
|
||||
|
||||
These prevent file corruption — OpenXML is strict about element ordering.
|
||||
|
||||
**Element order** (properties always first):
|
||||
|
||||
| Parent | Order |
|
||||
|--------|-------|
|
||||
| `w:p` | `pPr` → runs |
|
||||
| `w:r` | `rPr` → `t`/`br`/`tab` |
|
||||
| `w:tbl`| `tblPr` → `tblGrid` → `tr` |
|
||||
| `w:tr` | `trPr` → `tc` |
|
||||
| `w:tc` | `tcPr` → `p` (min 1 `<w:p/>`) |
|
||||
| `w:body` | block content → `sectPr` (LAST child) |
|
||||
|
||||
**Direct format contamination:** When copying content from a source document, inline `rPr` (fonts, color) and `pPr` (borders, shading, spacing) override template styles. Always strip direct formatting — keep only `pStyle` reference and `t` text. Clean tables too (including `pPr/rPr` inside cells).
|
||||
|
||||
**Track changes:** `<w:del>` uses `<w:delText>`, never `<w:t>`. `<w:ins>` uses `<w:t>`, never `<w:delText>`.
|
||||
|
||||
**Font size:** `w:sz` = points × 2 (12pt → `sz="24"`). Margins/spacing in DXA (1 inch = 1440, 1cm ≈ 567).
|
||||
|
||||
**Heading styles MUST have OutlineLevel:** When defining heading styles (Heading1, ThesisH1, etc.), always include `new OutlineLevel { Val = N }` in `StyleParagraphProperties` (H1→0, H2→1, H3→2). Without this, Word sees them as plain styled text — TOC and navigation pane won't work.
|
||||
|
||||
**Multi-template merge:** When given multiple template files (font, heading, breaks), read `references/scenario_c_apply_template.md` section "Multi-Template Merge" FIRST. Key rules:
|
||||
- Merge styles from all templates into one styles.xml. Structure (sections/breaks) comes from the breaks template.
|
||||
- Each content paragraph must appear exactly ONCE — never duplicate when inserting section breaks.
|
||||
- NEVER insert empty/blank paragraphs as padding or section separators. Output paragraph count must equal input. Use section break properties (`w:sectPr` inside `w:pPr`) and style spacing (`w:spacing` before/after) for visual separation.
|
||||
- Insert oddPage section breaks before EVERY chapter heading, not just the first. Even if a chapter has dual-column content, it MUST start with oddPage; use a second continuous break after the heading for column switching.
|
||||
- Dual-column chapters need THREE section breaks: (1) oddPage in preceding para's pPr, (2) continuous+cols=2 in the chapter HEADING's pPr, (3) continuous+cols=1 in the last body para's pPr to revert.
|
||||
- Copy `titlePg` settings from the breaks template for EACH section. Abstract and TOC sections typically need `titlePg=true`.
|
||||
|
||||
**Multi-section headers/footers:** Templates with 10+ sections (e.g., Chinese thesis) have DIFFERENT headers/footers per section (Roman vs Arabic page numbers, different header text per zone). Rules:
|
||||
- Use C-2 Base-Replace: copy the TEMPLATE as output base, then replace body content. This preserves all sections, headers, footers, and titlePg settings automatically.
|
||||
- NEVER recreate headers/footers from scratch — copy template header/footer XML byte-for-byte.
|
||||
- NEVER add formatting (borders, alignment, font size) not present in the template header XML.
|
||||
- Non-cover sections MUST have header/footer XML files (at least empty header + page number footer).
|
||||
- See `references/scenario_c_apply_template.md` section "Multi-Section Header/Footer Transfer".
|
||||
|
||||
## References
|
||||
|
||||
Load as needed — don't load all at once. Pick the most relevant files for the task.
|
||||
|
||||
**The C# samples and design references below are the project's knowledge base ("encyclopedia").** When writing OpenXML code, ALWAYS read the relevant sample file first — it contains compilable, SDK-version-verified patterns that prevent common errors. When making aesthetic decisions, read the design principles and recipe files — they encode tested, harmonious parameter sets from authoritative sources (IEEE, ACM, APA, Nature, etc.), not guesses.
|
||||
|
||||
### Scenario guides (read first for each pipeline)
|
||||
|
||||
| File | When |
|
||||
|------|------|
|
||||
| `references/scenario_a_create.md` | Pipeline A: creating from scratch |
|
||||
| `references/scenario_b_edit_content.md` | Pipeline B: editing existing content |
|
||||
| `references/scenario_c_apply_template.md` | Pipeline C: applying template formatting |
|
||||
|
||||
### C# code samples (compilable, heavily commented — read when writing code)
|
||||
|
||||
| File | Topic |
|
||||
|------|-------|
|
||||
| `Samples/DocumentCreationSamples.cs` | Document lifecycle: create, open, save, streams, doc defaults, settings, properties, page setup, multi-section |
|
||||
| `Samples/StyleSystemSamples.cs` | Styles: Normal/Heading chain, character/table/list styles, DocDefaults, latentStyles, CJK 公文, APA 7th, import, resolve inheritance |
|
||||
| `Samples/CharacterFormattingSamples.cs` | RunProperties: fonts, size, bold/italic, all underlines, color, highlight, strike, sub/super, caps, spacing, shading, border, emphasis marks |
|
||||
| `Samples/ParagraphFormattingSamples.cs` | ParagraphProperties: justification, indentation, line/paragraph spacing, keep/widow, outline level, borders, tabs, numbering, bidi, frame |
|
||||
| `Samples/TableSamples.cs` | Tables: borders, grid, cell props, margins, row height, header repeat, merge (H+V), nested, floating, three-line 三线表, zebra striping |
|
||||
| `Samples/HeaderFooterSamples.cs` | Headers/footers: page numbers, "Page X of Y", first/even/odd, logo image, table layout, 公文 "-X-", per-section |
|
||||
| `Samples/ImageSamples.cs` | Images: inline, floating, text wrapping, border, alt text, in header/table, replace, SVG fallback, dimension calc |
|
||||
| `Samples/ListAndNumberingSamples.cs` | Numbering: bullets, multi-level decimal, custom symbols, outline→headings, legal, Chinese 一/（一）/1./(1), restart/continue |
|
||||
| `Samples/FieldAndTocSamples.cs` | Fields: TOC, SimpleField vs complex field, DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF, TOC styles |
|
||||
| `Samples/FootnoteAndCommentSamples.cs` | Footnotes, endnotes, comments (4-file system), bookmarks, hyperlinks (internal + external) |
|
||||
| `Samples/TrackChangesSamples.cs` | Revisions: insertions (w:t), deletions (w:delText!), formatting changes, accept/reject all, move tracking |
|
||||
| `Samples/AestheticRecipeSamples.cs` | 13 aesthetic recipes from authoritative sources: ModernCorporate, AcademicThesis, ExecutiveBrief, ChineseGovernment (GB/T 9704), MinimalModern, IEEE Conference, ACM sigconf, APA 7th, MLA 9th, Chicago/Turabian, Springer LNCS, Nature, HBR — each with exact values from official style guides |
|
||||
|
||||
Note: `Samples/` path is relative to `scripts/dotnet/DocxToolkit.Core/`.
|
||||
|
||||
### Markdown references (read when you need specifications or design rules)
|
||||
|
||||
| File | When |
|
||||
|------|------|
|
||||
| `references/openxml_element_order.md` | XML element ordering rules (prevents corruption) |
|
||||
| `references/openxml_units.md` | Unit conversion: DXA, EMU, half-points, eighth-points |
|
||||
| `references/openxml_encyclopedia_part1.md` | Detailed C# encyclopedia: document creation, styles, character & paragraph formatting |
|
||||
| `references/openxml_encyclopedia_part2.md` | Detailed C# encyclopedia: page setup, tables, headers/footers, sections, doc properties |
|
||||
| `references/openxml_encyclopedia_part3.md` | Detailed C# encyclopedia: TOC, footnotes, fields, track changes, comments, images, math, numbering, protection |
|
||||
| `references/typography_guide.md` | Font pairing, sizes, spacing, page layout, table design, color schemes |
|
||||
| `references/cjk_typography.md` | CJK fonts, 字号 sizes, RunFonts mapping, GB/T 9704 公文 standard |
|
||||
| `references/cjk_university_template_guide.md` | Chinese university thesis templates: numeric styleIds (1/2/3 vs Heading1), document zone structure (cover→abstract→TOC→body→references), font expectations, common mistakes |
|
||||
| `references/design_principles.md` | **Aesthetic foundations**: 6 design principles (white space, contrast/scale, proximity, alignment, repetition, hierarchy) — teaches WHY, not just WHAT |
|
||||
| `references/design_good_bad_examples.md` | **Good vs Bad comparisons**: 10 categories of typography mistakes with OpenXML values, ASCII mockups, and fixes |
|
||||
| `references/track_changes_guide.md` | Revision marks deep dive |
|
||||
| `references/troubleshooting.md` | **Symptom-driven fixes**: 13 common problems indexed by what you SEE (headings wrong, images missing, TOC broken, etc.) — search by symptom, find the fix |
|
||||
@@ -0,0 +1,250 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
||||
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
|
||||
|
||||
<!-- Document Defaults -->
|
||||
<w:docDefaults>
|
||||
<w:rPrDefault>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:eastAsia="SimSun" w:cs="Times New Roman" />
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
<w:lang w:val="en-US" w:eastAsia="zh-CN" w:bidi="ar-SA" />
|
||||
</w:rPr>
|
||||
</w:rPrDefault>
|
||||
<w:pPrDefault>
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" w:line="480" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
</w:pPrDefault>
|
||||
</w:docDefaults>
|
||||
|
||||
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="0" w:defUnhideWhenUsed="0" w:defQFormat="0" w:count="376" />
|
||||
|
||||
<!-- Normal — Times New Roman 12pt, double spaced, first line indent -->
|
||||
<w:style w:type="paragraph" w:default="1" w:styleId="Normal">
|
||||
<w:name w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="720" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" />
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Default Paragraph Font -->
|
||||
<w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont">
|
||||
<w:name w:val="Default Paragraph Font" />
|
||||
<w:uiPriority w:val="1" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 1 — Bold, 14pt, no color, no indent -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading1">
|
||||
<w:name w:val="heading 1" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="480" w:after="240" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:jc w:val="center" />
|
||||
<w:outlineLvl w:val="0" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:sz w:val="28" />
|
||||
<w:szCs w:val="28" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 2 — Bold, 13pt -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading2">
|
||||
<w:name w:val="heading 2" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="360" w:after="120" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:outlineLvl w:val="1" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:sz w:val="26" />
|
||||
<w:szCs w:val="26" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 3 — Bold, 12pt -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading3">
|
||||
<w:name w:val="heading 3" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="240" w:after="80" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:outlineLvl w:val="2" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Title — Centered, bold, 14pt (academic title page) -->
|
||||
<w:style w:type="paragraph" w:styleId="Title">
|
||||
<w:name w:val="Title" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="10" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="480" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:sz w:val="28" />
|
||||
<w:szCs w:val="28" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Subtitle -->
|
||||
<w:style w:type="paragraph" w:styleId="Subtitle">
|
||||
<w:name w:val="Subtitle" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="11" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="240" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Quote — Block quote, indented 0.5 inch on both sides -->
|
||||
<w:style w:type="paragraph" w:styleId="Quote">
|
||||
<w:name w:val="Quote" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="29" />
|
||||
<w:pPr>
|
||||
<w:spacing w:before="240" w:after="240" w:line="480" w:lineRule="auto" />
|
||||
<w:ind w:left="720" w:right="720" w:firstLine="0" />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Table Normal -->
|
||||
<w:style w:type="table" w:default="1" w:styleId="TableNormal">
|
||||
<w:name w:val="Normal Table" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:tblPr>
|
||||
<w:tblInd w:w="0" w:type="dxa" />
|
||||
<w:tblCellMar>
|
||||
<w:top w:w="0" w:type="dxa" />
|
||||
<w:left w:w="108" w:type="dxa" />
|
||||
<w:bottom w:w="0" w:type="dxa" />
|
||||
<w:right w:w="108" w:type="dxa" />
|
||||
</w:tblCellMar>
|
||||
</w:tblPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Table Grid — Simple borders, no color -->
|
||||
<w:style w:type="table" w:styleId="TableGrid">
|
||||
<w:name w:val="Table Grid" />
|
||||
<w:basedOn w:val="TableNormal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:tblPr>
|
||||
<w:tblBorders>
|
||||
<w:top w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:left w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:right w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
</w:tblBorders>
|
||||
</w:tblPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Header -->
|
||||
<w:style w:type="paragraph" w:styleId="Header">
|
||||
<w:name w:val="header" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Footer -->
|
||||
<w:style w:type="paragraph" w:styleId="Footer">
|
||||
<w:name w:val="footer" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
<w:ind w:firstLine="0" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Hyperlink -->
|
||||
<w:style w:type="character" w:styleId="Hyperlink">
|
||||
<w:name w:val="Hyperlink" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:unhideWhenUsed />
|
||||
<w:rPr>
|
||||
<w:color w:val="0563C1" />
|
||||
<w:u w:val="single" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
</w:styles>
|
||||
@@ -0,0 +1,284 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
||||
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
|
||||
|
||||
<!-- Document Defaults -->
|
||||
<w:docDefaults>
|
||||
<w:rPrDefault>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="Microsoft YaHei" w:cs="Arial" />
|
||||
<w:color w:val="333333" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
<w:lang w:val="en-US" w:eastAsia="zh-CN" w:bidi="ar-SA" />
|
||||
</w:rPr>
|
||||
</w:rPrDefault>
|
||||
<w:pPrDefault>
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="259" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
</w:pPrDefault>
|
||||
</w:docDefaults>
|
||||
|
||||
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="0" w:defUnhideWhenUsed="0" w:defQFormat="0" w:count="376" />
|
||||
|
||||
<!-- Normal -->
|
||||
<w:style w:type="paragraph" w:default="1" w:styleId="Normal">
|
||||
<w:name w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
|
||||
<w:color w:val="333333" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Default Paragraph Font -->
|
||||
<w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont">
|
||||
<w:name w:val="Default Paragraph Font" />
|
||||
<w:uiPriority w:val="1" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 1 — Dark Blue -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading1">
|
||||
<w:name w:val="heading 1" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="480" w:after="240" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="0" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="1F3864" />
|
||||
<w:sz w:val="56" />
|
||||
<w:szCs w:val="56" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 2 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading2">
|
||||
<w:name w:val="heading 2" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="360" w:after="120" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="1" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="1F3864" />
|
||||
<w:sz w:val="48" />
|
||||
<w:szCs w:val="48" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 3 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading3">
|
||||
<w:name w:val="heading 3" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="240" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="2" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="1F3864" />
|
||||
<w:sz w:val="36" />
|
||||
<w:szCs w:val="36" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 4 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading4">
|
||||
<w:name w:val="heading 4" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="160" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="3" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:i />
|
||||
<w:color w:val="1F3864" />
|
||||
<w:sz w:val="28" />
|
||||
<w:szCs w:val="28" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Title -->
|
||||
<w:style w:type="paragraph" w:styleId="Title">
|
||||
<w:name w:val="Title" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="10" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="240" w:line="240" w:lineRule="auto" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:color w:val="1F3864" />
|
||||
<w:sz w:val="72" />
|
||||
<w:szCs w:val="72" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Subtitle -->
|
||||
<w:style w:type="paragraph" w:styleId="Subtitle">
|
||||
<w:name w:val="Subtitle" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="11" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="360" w:line="240" w:lineRule="auto" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:i />
|
||||
<w:color w:val="595959" />
|
||||
<w:sz w:val="32" />
|
||||
<w:szCs w:val="32" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Table Grid — Corporate with blue header -->
|
||||
<w:style w:type="table" w:default="1" w:styleId="TableNormal">
|
||||
<w:name w:val="Normal Table" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:tblPr>
|
||||
<w:tblInd w:w="0" w:type="dxa" />
|
||||
<w:tblCellMar>
|
||||
<w:top w:w="0" w:type="dxa" />
|
||||
<w:left w:w="108" w:type="dxa" />
|
||||
<w:bottom w:w="0" w:type="dxa" />
|
||||
<w:right w:w="108" w:type="dxa" />
|
||||
</w:tblCellMar>
|
||||
</w:tblPr>
|
||||
</w:style>
|
||||
|
||||
<w:style w:type="table" w:styleId="TableGrid">
|
||||
<w:name w:val="Table Grid" />
|
||||
<w:basedOn w:val="TableNormal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:tblPr>
|
||||
<w:tblBorders>
|
||||
<w:top w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
<w:left w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
<w:bottom w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
<w:right w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
<w:insideH w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
<w:insideV w:val="single" w:sz="4" w:space="0" w:color="BFBFBF" />
|
||||
</w:tblBorders>
|
||||
</w:tblPr>
|
||||
<w:tblStylePr w:type="firstRow">
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:color w:val="FFFFFF" />
|
||||
</w:rPr>
|
||||
<w:tcPr>
|
||||
<w:shd w:val="clear" w:color="auto" w:fill="2F5496" />
|
||||
<w:tcBorders>
|
||||
<w:top w:val="single" w:sz="4" w:space="0" w:color="2F5496" />
|
||||
<w:left w:val="single" w:sz="4" w:space="0" w:color="2F5496" />
|
||||
<w:bottom w:val="single" w:sz="4" w:space="0" w:color="2F5496" />
|
||||
<w:right w:val="single" w:sz="4" w:space="0" w:color="2F5496" />
|
||||
<w:insideH w:val="single" w:sz="4" w:space="0" w:color="3A6BC5" />
|
||||
<w:insideV w:val="single" w:sz="4" w:space="0" w:color="3A6BC5" />
|
||||
</w:tcBorders>
|
||||
</w:tcPr>
|
||||
</w:tblStylePr>
|
||||
<w:tblStylePr w:type="band1Horz">
|
||||
<w:tcPr>
|
||||
<w:shd w:val="clear" w:color="auto" w:fill="D9E2F3" />
|
||||
</w:tcPr>
|
||||
</w:tblStylePr>
|
||||
</w:style>
|
||||
|
||||
<!-- Header -->
|
||||
<w:style w:type="paragraph" w:styleId="Header">
|
||||
<w:name w:val="header" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="18" />
|
||||
<w:szCs w:val="18" />
|
||||
<w:color w:val="808080" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Footer -->
|
||||
<w:style w:type="paragraph" w:styleId="Footer">
|
||||
<w:name w:val="footer" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="18" />
|
||||
<w:szCs w:val="18" />
|
||||
<w:color w:val="808080" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Hyperlink -->
|
||||
<w:style w:type="character" w:styleId="Hyperlink">
|
||||
<w:name w:val="Hyperlink" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:unhideWhenUsed />
|
||||
<w:rPr>
|
||||
<w:color w:val="0563C1" />
|
||||
<w:u w:val="single" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
</w:styles>
|
||||
@@ -0,0 +1,449 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
||||
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
|
||||
|
||||
<!-- Document Defaults -->
|
||||
<w:docDefaults>
|
||||
<w:rPrDefault>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
<w:lang w:val="en-US" w:eastAsia="zh-CN" w:bidi="ar-SA" />
|
||||
</w:rPr>
|
||||
</w:rPrDefault>
|
||||
<w:pPrDefault>
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="259" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
</w:pPrDefault>
|
||||
</w:docDefaults>
|
||||
|
||||
<!-- Latent Styles -->
|
||||
<w:latentStyles w:defLockedState="0" w:defUIPriority="99" w:defSemiHidden="0" w:defUnhideWhenUsed="0" w:defQFormat="0" w:count="376" />
|
||||
|
||||
<!-- Normal (Default Paragraph Style) -->
|
||||
<w:style w:type="paragraph" w:default="1" w:styleId="Normal">
|
||||
<w:name w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Default Paragraph Font -->
|
||||
<w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont">
|
||||
<w:name w:val="Default Paragraph Font" />
|
||||
<w:uiPriority w:val="1" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 1 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading1">
|
||||
<w:name w:val="heading 1" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="480" w:after="240" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="0" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="56" />
|
||||
<w:szCs w:val="56" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 2 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading2">
|
||||
<w:name w:val="heading 2" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="360" w:after="120" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="1" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="48" />
|
||||
<w:szCs w:val="48" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 3 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading3">
|
||||
<w:name w:val="heading 3" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="240" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="2" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="36" />
|
||||
<w:szCs w:val="36" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 4 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading4">
|
||||
<w:name w:val="heading 4" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="160" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="3" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:i />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="28" />
|
||||
<w:szCs w:val="28" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 5 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading5">
|
||||
<w:name w:val="heading 5" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="160" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="4" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="24" />
|
||||
<w:szCs w:val="24" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Heading 6 -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading6">
|
||||
<w:name w:val="heading 6" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="9" />
|
||||
<w:pPr>
|
||||
<w:keepNext />
|
||||
<w:keepLines />
|
||||
<w:spacing w:before="160" w:after="80" w:line="240" w:lineRule="auto" />
|
||||
<w:outlineLvl w:val="5" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:b />
|
||||
<w:i />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Title -->
|
||||
<w:style w:type="paragraph" w:styleId="Title">
|
||||
<w:name w:val="Title" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="10" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="240" w:line="240" w:lineRule="auto" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light" />
|
||||
<w:color w:val="2F5496" />
|
||||
<w:sz w:val="72" />
|
||||
<w:szCs w:val="72" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Subtitle -->
|
||||
<w:style w:type="paragraph" w:styleId="Subtitle">
|
||||
<w:name w:val="Subtitle" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="11" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="360" w:line="240" w:lineRule="auto" />
|
||||
<w:jc w:val="center" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:i />
|
||||
<w:color w:val="595959" />
|
||||
<w:sz w:val="32" />
|
||||
<w:szCs w:val="32" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Quote -->
|
||||
<w:style w:type="paragraph" w:styleId="Quote">
|
||||
<w:name w:val="Quote" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="29" />
|
||||
<w:pPr>
|
||||
<w:spacing w:before="240" w:after="240" />
|
||||
<w:ind w:left="720" w:right="720" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:i />
|
||||
<w:color w:val="404040" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Intense Quote -->
|
||||
<w:style w:type="paragraph" w:styleId="IntenseQuote">
|
||||
<w:name w:val="Intense Quote" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:qFormat />
|
||||
<w:uiPriority w:val="30" />
|
||||
<w:pPr>
|
||||
<w:spacing w:before="240" w:after="240" />
|
||||
<w:ind w:left="720" w:right="720" />
|
||||
<w:pBdr>
|
||||
<w:left w:val="single" w:sz="18" w:space="12" w:color="2F5496" />
|
||||
</w:pBdr>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
<w:i />
|
||||
<w:color w:val="2F5496" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- TOC Heading -->
|
||||
<w:style w:type="paragraph" w:styleId="TOCHeading">
|
||||
<w:name w:val="TOC Heading" />
|
||||
<w:basedOn w:val="Heading1" />
|
||||
<w:next w:val="Normal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:outlineLvl w:val="9" />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- TOC 1 -->
|
||||
<w:style w:type="paragraph" w:styleId="TOC1">
|
||||
<w:name w:val="toc 1" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:spacing w:before="120" w:after="0" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- TOC 2 -->
|
||||
<w:style w:type="paragraph" w:styleId="TOC2">
|
||||
<w:name w:val="toc 2" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" />
|
||||
<w:ind w:left="240" />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- TOC 3 -->
|
||||
<w:style w:type="paragraph" w:styleId="TOC3">
|
||||
<w:name w:val="toc 3" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" />
|
||||
<w:ind w:left="480" />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- List Bullet -->
|
||||
<w:style w:type="paragraph" w:styleId="ListBullet">
|
||||
<w:name w:val="List Bullet" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="36" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" />
|
||||
<w:ind w:left="720" w:hanging="360" />
|
||||
<w:contextualSpacing />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- List Number -->
|
||||
<w:style w:type="paragraph" w:styleId="ListNumber">
|
||||
<w:name w:val="List Number" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="36" />
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" />
|
||||
<w:ind w:left="720" w:hanging="360" />
|
||||
<w:contextualSpacing />
|
||||
</w:pPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Table Normal -->
|
||||
<w:style w:type="table" w:default="1" w:styleId="TableNormal">
|
||||
<w:name w:val="Normal Table" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:tblPr>
|
||||
<w:tblInd w:w="0" w:type="dxa" />
|
||||
<w:tblCellMar>
|
||||
<w:top w:w="0" w:type="dxa" />
|
||||
<w:left w:w="108" w:type="dxa" />
|
||||
<w:bottom w:w="0" w:type="dxa" />
|
||||
<w:right w:w="108" w:type="dxa" />
|
||||
</w:tblCellMar>
|
||||
</w:tblPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Table Grid -->
|
||||
<w:style w:type="table" w:styleId="TableGrid">
|
||||
<w:name w:val="Table Grid" />
|
||||
<w:basedOn w:val="TableNormal" />
|
||||
<w:uiPriority w:val="39" />
|
||||
<w:tblPr>
|
||||
<w:tblBorders>
|
||||
<w:top w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:left w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:right w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
<w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto" />
|
||||
</w:tblBorders>
|
||||
</w:tblPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Header -->
|
||||
<w:style w:type="paragraph" w:styleId="Header">
|
||||
<w:name w:val="header" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="18" />
|
||||
<w:szCs w:val="18" />
|
||||
<w:color w:val="808080" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Footer -->
|
||||
<w:style w:type="paragraph" w:styleId="Footer">
|
||||
<w:name w:val="footer" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="center" w:pos="4680" />
|
||||
<w:tab w:val="right" w:pos="9360" />
|
||||
</w:tabs>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="18" />
|
||||
<w:szCs w:val="18" />
|
||||
<w:color w:val="808080" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Hyperlink -->
|
||||
<w:style w:type="character" w:styleId="Hyperlink">
|
||||
<w:name w:val="Hyperlink" />
|
||||
<w:uiPriority w:val="99" />
|
||||
<w:unhideWhenUsed />
|
||||
<w:rPr>
|
||||
<w:color w:val="0563C1" />
|
||||
<w:u w:val="single" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Comment Text -->
|
||||
<w:style w:type="paragraph" w:styleId="CommentText">
|
||||
<w:name w:val="annotation text" />
|
||||
<w:basedOn w:val="Normal" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:pPr>
|
||||
<w:spacing w:line="240" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="20" />
|
||||
<w:szCs w:val="20" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Comment Reference -->
|
||||
<w:style w:type="character" w:styleId="CommentReference">
|
||||
<w:name w:val="annotation reference" />
|
||||
<w:semiHidden />
|
||||
<w:unhideWhenUsed />
|
||||
<w:rPr>
|
||||
<w:sz w:val="16" />
|
||||
<w:szCs w:val="16" />
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
</w:styles>
|
||||
@@ -0,0 +1,470 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- ============================================================================ -->
|
||||
<!-- Aesthetic Rules Schema for docx-toolkit -->
|
||||
<!-- ============================================================================ -->
|
||||
<!-- Purpose: Validates whether a document follows basic aesthetic rules that -->
|
||||
<!-- produce visually harmonious results. This is a "taste checker" that flags -->
|
||||
<!-- common ugly patterns. -->
|
||||
<!-- -->
|
||||
<!-- IMPORTANT: XSD validates STRUCTURE and VALUE RANGES, not SEMANTICS. -->
|
||||
<!-- Many aesthetic rules require cross-element comparison (e.g., "H1 must be -->
|
||||
<!-- larger than H2") which XSD cannot express. These rules are documented in -->
|
||||
<!-- comments and must be enforced by a programmatic validator. -->
|
||||
<!-- -->
|
||||
<!-- Rules that CAN be expressed in XSD: -->
|
||||
<!-- - Font size ranges (body 10-14pt, headings 10-26pt) -->
|
||||
<!-- - Line spacing ranges (1.0x to 2.33x) -->
|
||||
<!-- - Margin minimums (at least 0.5in on all sides) -->
|
||||
<!-- - Table cell padding minimums -->
|
||||
<!-- -->
|
||||
<!-- Rules that CANNOT be expressed in XSD (enforce programmatically): -->
|
||||
<!-- - H1 sz > H2 sz > H3 sz > body sz (hierarchy) -->
|
||||
<!-- - Maximum 3 font families across all styles -->
|
||||
<!-- - Heading space-before >= space-after -->
|
||||
<!-- - Color contrast ratio between text and background -->
|
||||
<!-- - Consistent font family within heading vs body groups -->
|
||||
<!-- - Line spacing and font size harmony (larger text needs tighter spacing) -->
|
||||
<!-- -->
|
||||
<!-- MIT License - docx-toolkit project -->
|
||||
<!-- ============================================================================ -->
|
||||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||||
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
targetNamespace="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
elementFormDefault="qualified">
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 1: Body Font Size Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Body text must be 10-14pt (half-points: 20-28). -->
|
||||
<!-- WHY: Below 10pt is hard to read for most adults. -->
|
||||
<!-- Above 14pt body text looks childish or wasteful. -->
|
||||
<!-- The sweet spot is 10.5-12pt for most font families. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticBodyFontSize">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Body text font size in half-points.
|
||||
Acceptable range: 20-28 (10pt-14pt).
|
||||
- 10pt (20): minimum for comfortable reading
|
||||
- 11pt (22): modern default (Calibri, Aptos)
|
||||
- 12pt (24): traditional default (Times New Roman)
|
||||
- 14pt (28): maximum before body text looks oversized
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="20"/> <!-- 10pt minimum -->
|
||||
<xs:maxInclusive value="28"/> <!-- 14pt maximum -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 2: Heading Font Size Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Headings must be 12-26pt (half-points: 24-52). -->
|
||||
<!-- WHY: Below 12pt, a heading cannot be visually distinguished -->
|
||||
<!-- from body text by size alone. -->
|
||||
<!-- Above 26pt is poster-sized and wastes vertical space. -->
|
||||
<!-- NOTE: Some academic styles use 12pt headings (same as body) -->
|
||||
<!-- and differentiate via bold/italic/centering instead. -->
|
||||
<!-- The lower bound of 24 (12pt) accommodates this. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticHeadingFontSize">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Heading font size in half-points.
|
||||
Acceptable range: 24-52 (12pt-26pt).
|
||||
- 12pt (24): APA-style (hierarchy via bold/italic, not size)
|
||||
- 16pt (32): typical H2/H3
|
||||
- 20pt (40): typical H1
|
||||
- 26pt (52): maximum before headings dominate the page
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="24"/> <!-- 12pt minimum -->
|
||||
<xs:maxInclusive value="52"/> <!-- 26pt maximum -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 3: Line Spacing Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Line spacing (in auto mode) must be 240-560 (1.0x-2.33x). -->
|
||||
<!-- WHY: Below 1.0x, ascenders/descenders overlap — unreadable. -->
|
||||
<!-- Above 2.33x, lines appear disconnected. -->
|
||||
<!-- Sweet spots: 1.15x (276) for sans, 1.5x (360) for -->
|
||||
<!-- generous layouts, 2.0x (480) for academic. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticLineSpacing">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Line spacing value for auto line-spacing rule.
|
||||
In 240ths of single spacing: 240 = 1.0x, 480 = 2.0x.
|
||||
Acceptable range: 240-560 (1.0x to 2.33x).
|
||||
Common values:
|
||||
- 240: single spacing (dense, technical)
|
||||
- 259: Word's 1.08x default
|
||||
- 276: 1.15x (modern corporate default)
|
||||
- 336: 1.4x (executive/generous)
|
||||
- 360: 1.5x (generous/minimal)
|
||||
- 480: 2.0x (academic double spacing)
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="240"/> <!-- 1.0x single spacing -->
|
||||
<xs:maxInclusive value="560"/> <!-- ~2.33x — beyond double feels disconnected -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 3b: Fixed Line Spacing Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- For lineRule="exact", line value is in DXA (twentieths of pt) -->
|
||||
<!-- Range: 200-720 DXA (10pt-36pt fixed line height) -->
|
||||
<!-- Chinese government standard uses 560 DXA (28pt). -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticFixedLineSpacing">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Fixed line spacing value (lineRule="exact") in DXA.
|
||||
Acceptable range: 200-720 (10pt-36pt).
|
||||
- 560: Chinese government standard (28pt, for 16pt body)
|
||||
- 480: double-space equivalent for 12pt body
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="200"/> <!-- 10pt minimum fixed height -->
|
||||
<xs:maxInclusive value="720"/> <!-- 36pt maximum fixed height -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 4: Margin Minimums -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- All margins must be at least 720 DXA (0.5 inch). -->
|
||||
<!-- WHY: Below 0.5in, most printers clip content. -->
|
||||
<!-- Also, narrow margins create a cramped, unprofessional -->
|
||||
<!-- appearance. Even "full bleed" designs need internal -->
|
||||
<!-- text margins. -->
|
||||
<!-- Max set to 4320 DXA (3 inches) to prevent absurd margins. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticMargin">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Page margin in DXA. Minimum 720 (0.5 inch), maximum 4320 (3 inches).
|
||||
Common values:
|
||||
- 720: 0.5in (minimum printable)
|
||||
- 1440: 1.0in (standard US)
|
||||
- 1588: 28mm (Chinese government left margin)
|
||||
- 1800: 1.25in (executive/premium)
|
||||
- 2160: 1.5in (binding margin or narrow-column design)
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="720"/> <!-- 0.5in — minimum for print safety -->
|
||||
<xs:maxInclusive value="4320"/> <!-- 3in — beyond this is absurd -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Top/bottom margins: signed because negative values can create -->
|
||||
<!-- overlap effects, but we still enforce a reasonable minimum. -->
|
||||
<xs:simpleType name="ST_AestheticVerticalMargin">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Vertical (top/bottom) page margin in DXA.
|
||||
Range: 360 to 4320 (0.25in to 3in).
|
||||
Slightly more permissive than horizontal margins because
|
||||
header/footer areas may reduce effective vertical margin.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:integer">
|
||||
<xs:minInclusive value="360"/> <!-- 0.25in — tighter vertical is sometimes acceptable -->
|
||||
<xs:maxInclusive value="4320"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 5: Paragraph Spacing Ranges -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Space before/after paragraphs should be 0-960 DXA (0-48pt). -->
|
||||
<!-- WHY: More than 48pt of space before/after creates awkward -->
|
||||
<!-- gaps that disrupt reading flow. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticParaSpacing">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Paragraph spacing (before/after) in DXA.
|
||||
Range: 0-960 (0pt-48pt).
|
||||
Common values:
|
||||
- 0: academic style (uses first-line indent instead)
|
||||
- 80: 4pt (tight, used after H2/H3)
|
||||
- 120: 6pt (moderate)
|
||||
- 160: 8pt (standard modern spacing)
|
||||
- 200: 10pt (generous/executive)
|
||||
- 240: 12pt (very generous/minimal)
|
||||
- 480: 24pt (heading before — creates section break)
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:nonNegativeInteger">
|
||||
<xs:minInclusive value="0"/>
|
||||
<xs:maxInclusive value="960"/> <!-- 48pt max — beyond this is a page break, not spacing -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 6: Table Cell Padding Minimum -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Table cells need at least 28 DXA (~1.4pt) padding. -->
|
||||
<!-- WHY: Without padding, text touches cell borders — visually -->
|
||||
<!-- cramped and hard to read. Even borderless tables need -->
|
||||
<!-- padding for column separation. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticCellPadding">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Table cell padding in DXA. Minimum 28 DXA (~1.4pt).
|
||||
Recommended: 57 DXA (~2.85pt) for comfortable spacing.
|
||||
Maximum: 288 DXA (~14pt) — beyond this wastes space.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:nonNegativeInteger">
|
||||
<xs:minInclusive value="28"/> <!-- ~1.4pt minimum breathing room -->
|
||||
<xs:maxInclusive value="288"/> <!-- ~14pt — more than this is excessive -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 7: Border Size Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Border size (in eighth-points) should be 2-24 (0.25pt-3pt). -->
|
||||
<!-- WHY: Below 0.25pt borders may not render or print. -->
|
||||
<!-- Above 3pt borders look heavy and distracting. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticBorderSize">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Border width in eighth-points.
|
||||
Range: 2-24 (0.25pt to 3pt).
|
||||
Common values:
|
||||
- 4: 0.5pt (thin, standard)
|
||||
- 6: 0.75pt (header separator in three-line tables)
|
||||
- 8: 1.0pt (medium, good for framing borders)
|
||||
- 12: 1.5pt (heavy, used for top/bottom in three-line tables)
|
||||
- 24: 3.0pt (maximum before borders dominate)
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="2"/> <!-- 0.25pt minimum visible -->
|
||||
<xs:maxInclusive value="24"/> <!-- 3pt maximum tasteful -->
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 8: Color Value Format -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Colors must be valid 6-digit hex (RRGGBB) or "auto". -->
|
||||
<!-- This is structural validation, not aesthetic validation. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticColor">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Color value: 6-digit hex (RRGGBB) or "auto".
|
||||
Examples: "000000", "1F3864", "2C3E50", "auto".
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:pattern value="[0-9A-Fa-f]{6}|auto"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- RULE 9: First-Line Indent Range -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- If first-line indent is used, it should be 360-1440 DXA -->
|
||||
<!-- (0.25in - 1.0in). -->
|
||||
<!-- WHY: Below 0.25in the indent is barely visible. -->
|
||||
<!-- Above 1.0in the indent looks like a tab error. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_AestheticFirstLineIndent">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
First-line indent in DXA. Range: 0-1440 (0in to 1.0in).
|
||||
- 0: no indent (modern style with space-after)
|
||||
- 480: 0.33in (compact)
|
||||
- 640: ~0.44in (2 Chinese characters at 16pt)
|
||||
- 720: 0.5in (standard APA/academic)
|
||||
- 1440: 1.0in (maximum before it looks wrong)
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:restriction base="xs:nonNegativeInteger">
|
||||
<xs:minInclusive value="0"/>
|
||||
<xs:maxInclusive value="1440"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- COMPOSITE TYPE: Aesthetic Run Properties Check -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Validates run-level properties for aesthetic compliance. -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_AestheticRPr">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Aesthetic run properties validator.
|
||||
Checks font size and color format at the run level.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:all>
|
||||
<xs:element name="sz" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="w:ST_AestheticBodyFontSize" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="szCs" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="w:ST_AestheticBodyFontSize" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="color" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="w:ST_AestheticColor" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- COMPOSITE TYPE: Aesthetic Spacing Check -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_AestheticSpacing">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Aesthetic spacing validator for paragraph spacing properties.
|
||||
Validates line spacing and before/after spacing are in range.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:attribute name="line" type="w:ST_AestheticLineSpacing" use="optional"/>
|
||||
<xs:attribute name="before" type="w:ST_AestheticParaSpacing" use="optional"/>
|
||||
<xs:attribute name="after" type="w:ST_AestheticParaSpacing" use="optional"/>
|
||||
<xs:attribute name="lineRule" use="optional">
|
||||
<xs:simpleType>
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="auto"/>
|
||||
<xs:enumeration value="exact"/>
|
||||
<xs:enumeration value="atLeast"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
</xs:attribute>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- COMPOSITE TYPE: Aesthetic Page Margins Check -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_AestheticPageMargins">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Aesthetic page margin validator.
|
||||
Ensures all margins meet minimum print-safe thresholds.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:attribute name="top" type="w:ST_AestheticVerticalMargin" use="required"/>
|
||||
<xs:attribute name="bottom" type="w:ST_AestheticVerticalMargin" use="required"/>
|
||||
<xs:attribute name="left" type="w:ST_AestheticMargin" use="required"/>
|
||||
<xs:attribute name="right" type="w:ST_AestheticMargin" use="required"/>
|
||||
<xs:attribute name="header" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="footer" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="gutter" type="xs:nonNegativeInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- COMPOSITE TYPE: Aesthetic Table Cell Margin Check -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_AestheticTableCellMargin">
|
||||
<xs:annotation>
|
||||
<xs:documentation>
|
||||
Aesthetic table cell margin validator.
|
||||
Ensures minimum padding for readability.
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
<xs:attribute name="w" type="w:ST_AestheticCellPadding" use="required"/>
|
||||
<xs:attribute name="type" use="required">
|
||||
<xs:simpleType>
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="dxa"/>
|
||||
<xs:enumeration value="nil"/>
|
||||
<xs:enumeration value="pct"/>
|
||||
<xs:enumeration value="auto"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
</xs:attribute>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- PROGRAMMATIC RULES (cannot be expressed in XSD) -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- -->
|
||||
<!-- The following rules must be checked by a programmatic -->
|
||||
<!-- validator (e.g., AestheticRuleValidator.cs). They are -->
|
||||
<!-- documented here for completeness. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P1: Heading Size Hierarchy ── -->
|
||||
<!-- H1 sz >= H2 sz >= H3 sz >= body sz -->
|
||||
<!-- Exception: APA-style where all headings = body size. -->
|
||||
<!-- Implementation: Collect sz from Heading1/2/3 styles and -->
|
||||
<!-- docDefaults. Verify monotonic decrease (or equality). -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P2: Maximum 3 Font Families ── -->
|
||||
<!-- Across docDefaults rPr + all style rPr, at most 3 distinct -->
|
||||
<!-- font families (by Ascii name) should be used. -->
|
||||
<!-- WHY: More than 3 fonts creates visual chaos. Professional -->
|
||||
<!-- designs typically use 1-2 families. -->
|
||||
<!-- Implementation: Collect all rFonts.ascii values from -->
|
||||
<!-- docDefaults and all styles. Count distinct. Warn if > 3. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P3: Heading Space-Before >= Space-After ── -->
|
||||
<!-- For heading styles, spaceBefore should be >= spaceAfter. -->
|
||||
<!-- WHY: Headings should be visually closer to the content they -->
|
||||
<!-- introduce than to the content above. This is the -->
|
||||
<!-- "proximity principle" of Gestalt design. -->
|
||||
<!-- Implementation: For each Heading style, compare pPr spacing -->
|
||||
<!-- before vs after values. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P4: Spacing-Size Coherence ── -->
|
||||
<!-- Paragraph after-spacing should be proportional to body size: -->
|
||||
<!-- after >= bodySize * 0.5 AND after <= bodySize * 1.5 -->
|
||||
<!-- WHY: Too little spacing makes paragraphs run together. -->
|
||||
<!-- Too much spacing disconnects them. -->
|
||||
<!-- Implementation: Get body sz from docDefaults, convert to DXA -->
|
||||
<!-- (multiply by 10), check after-spacing ratio. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P5: Color Consistency ── -->
|
||||
<!-- All heading styles should use the same color value. -->
|
||||
<!-- Body text color (if set) should be consistent across styles. -->
|
||||
<!-- WHY: Inconsistent colors look accidental, not designed. -->
|
||||
<!-- Exception: Caption and footnote styles may differ. -->
|
||||
<!-- Implementation: Collect color.val from heading styles. -->
|
||||
<!-- Verify all are identical. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P6: Indent/Spacing Mutual Exclusion ── -->
|
||||
<!-- If first-line indent > 0 in docDefaults, then after-spacing -->
|
||||
<!-- should be 0 (and vice versa). Using BOTH indent AND spacing -->
|
||||
<!-- is visually redundant — it signals uncertainty. -->
|
||||
<!-- Exception: Headings may override this. -->
|
||||
<!-- Implementation: Check docDefaults pPr. If firstLine > 0 AND -->
|
||||
<!-- after > 0, emit a warning (not error). -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P7: Table Border Consistency ── -->
|
||||
<!-- Within a single table, border styles should be internally -->
|
||||
<!-- consistent (all single, or all none — not a random mix). -->
|
||||
<!-- Implementation: Check tblBorders for consistent val values. -->
|
||||
<!-- -->
|
||||
<!-- ── RULE P8: Line Spacing vs Font Size Harmony ── -->
|
||||
<!-- For fixed line spacing (lineRule="exact"): -->
|
||||
<!-- lineHeight >= fontSize * 1.2 -->
|
||||
<!-- WHY: Fixed line spacing less than 1.2x the font size causes -->
|
||||
<!-- ascender/descender clipping. -->
|
||||
<!-- Implementation: When lineRule="exact", compare line value -->
|
||||
<!-- against the effective font size. -->
|
||||
<!-- -->
|
||||
<!-- ============================================================ -->
|
||||
|
||||
</xs:schema>
|
||||
@@ -0,0 +1,130 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- Business Rules Gate-Check Schema for docx-toolkit -->
|
||||
<!-- Used in Scenario C (template application) as hard gate -->
|
||||
<!-- Validates business compliance beyond XML correctness -->
|
||||
<!-- MIT License - docx-toolkit project -->
|
||||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||||
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
targetNamespace="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
elementFormDefault="qualified">
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Page margins: constrained to reasonable bounds -->
|
||||
<!-- Minimum 360 DXA (0.25 inch), maximum 4320 DXA (3 inches) -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_MarginMeasure">
|
||||
<xs:restriction base="xs:integer">
|
||||
<xs:minInclusive value="360"/>
|
||||
<xs:maxInclusive value="4320"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Signed margin (top/bottom can be negative for overlap) -->
|
||||
<xs:simpleType name="ST_SignedMarginMeasure">
|
||||
<xs:restriction base="xs:integer">
|
||||
<xs:minInclusive value="-4320"/>
|
||||
<xs:maxInclusive value="4320"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Font size constraints -->
|
||||
<!-- Body text: 16-144 half-points (8-72pt) -->
|
||||
<!-- Heading text: 20-192 half-points (10-96pt) -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:simpleType name="ST_BodyFontSize">
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="16"/>
|
||||
<xs:maxInclusive value="144"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<xs:simpleType name="ST_HeadingFontSize">
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="20"/>
|
||||
<xs:maxInclusive value="192"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Valid standard page sizes (width x height in DXA) -->
|
||||
<!-- ============================================================ -->
|
||||
<!-- Letter: 12240 x 15840 -->
|
||||
<!-- A4: 11906 x 16838 -->
|
||||
<!-- Legal: 12240 x 20160 -->
|
||||
<!-- A3: 16838 x 23811 -->
|
||||
<!-- A5: 8391 x 11906 -->
|
||||
|
||||
<xs:simpleType name="ST_PageWidth">
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="5040"/>
|
||||
<xs:maxInclusive value="31680"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<xs:simpleType name="ST_PageHeight">
|
||||
<xs:restriction base="xs:positiveInteger">
|
||||
<xs:minInclusive value="5040"/>
|
||||
<xs:maxInclusive value="31680"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Constrained section properties for gate-check -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_GateCheckSectPr">
|
||||
<xs:all>
|
||||
<xs:element name="pgSz" minOccurs="1">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="w" type="w:ST_PageWidth" use="required"/>
|
||||
<xs:attribute name="h" type="w:ST_PageHeight" use="required"/>
|
||||
<xs:attribute name="orient" use="optional">
|
||||
<xs:simpleType>
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="portrait"/>
|
||||
<xs:enumeration value="landscape"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
</xs:attribute>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="pgMar" minOccurs="1">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="top" type="w:ST_SignedMarginMeasure" use="required"/>
|
||||
<xs:attribute name="bottom" type="w:ST_SignedMarginMeasure" use="required"/>
|
||||
<xs:attribute name="left" type="w:ST_MarginMeasure" use="required"/>
|
||||
<xs:attribute name="right" type="w:ST_MarginMeasure" use="required"/>
|
||||
<xs:attribute name="header" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="footer" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="gutter" type="xs:nonNegativeInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Required styles: at minimum Normal and Heading1 must exist -->
|
||||
<!-- This is enforced programmatically by GateCheckValidator -->
|
||||
<!-- rather than via XSD, since XSD cannot validate style presence -->
|
||||
<!-- across separate XML parts. -->
|
||||
<!-- ============================================================ -->
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Constrained run properties for font size validation -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_GateCheckRPr">
|
||||
<xs:all>
|
||||
<xs:element name="sz" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="w:ST_BodyFontSize" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="szCs" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="w:ST_BodyFontSize" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
</xs:schema>
|
||||
@@ -0,0 +1,159 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- Common type definitions for WordprocessingML subset schema -->
|
||||
<!-- MIT License - docx-toolkit project -->
|
||||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||||
targetNamespace="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
elementFormDefault="qualified">
|
||||
|
||||
<!-- Measurement: non-negative twips (1/1440 inch) -->
|
||||
<xs:simpleType name="ST_TwipsMeasure">
|
||||
<xs:restriction base="xs:nonNegativeInteger"/>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Measurement: signed twips (for negative margins/indents) -->
|
||||
<xs:simpleType name="ST_SignedTwipsMeasure">
|
||||
<xs:restriction base="xs:integer"/>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Half-point measure for font sizes (1 = 0.5pt) -->
|
||||
<xs:simpleType name="ST_HpsMeasure">
|
||||
<xs:restriction base="xs:positiveInteger"/>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Hex color: 6 hex digits -->
|
||||
<xs:simpleType name="ST_HexColor">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:pattern value="auto|[0-9a-fA-F]{6}"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- On/Off toggle -->
|
||||
<xs:simpleType name="ST_OnOff">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="true"/>
|
||||
<xs:enumeration value="false"/>
|
||||
<xs:enumeration value="0"/>
|
||||
<xs:enumeration value="1"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Justification -->
|
||||
<xs:simpleType name="ST_Jc">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="left"/>
|
||||
<xs:enumeration value="center"/>
|
||||
<xs:enumeration value="right"/>
|
||||
<xs:enumeration value="both"/>
|
||||
<xs:enumeration value="distribute"/>
|
||||
<xs:enumeration value="start"/>
|
||||
<xs:enumeration value="end"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Break type -->
|
||||
<xs:simpleType name="ST_BrType">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="page"/>
|
||||
<xs:enumeration value="column"/>
|
||||
<xs:enumeration value="textWrapping"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Underline patterns -->
|
||||
<xs:simpleType name="ST_Underline">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="none"/>
|
||||
<xs:enumeration value="single"/>
|
||||
<xs:enumeration value="words"/>
|
||||
<xs:enumeration value="double"/>
|
||||
<xs:enumeration value="thick"/>
|
||||
<xs:enumeration value="dotted"/>
|
||||
<xs:enumeration value="dash"/>
|
||||
<xs:enumeration value="dotDash"/>
|
||||
<xs:enumeration value="dotDotDash"/>
|
||||
<xs:enumeration value="wave"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Vertical alignment for subscript/superscript -->
|
||||
<xs:simpleType name="ST_VerticalAlignRun">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="baseline"/>
|
||||
<xs:enumeration value="superscript"/>
|
||||
<xs:enumeration value="subscript"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Section break type -->
|
||||
<xs:simpleType name="ST_SectionMark">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="nextPage"/>
|
||||
<xs:enumeration value="nextColumn"/>
|
||||
<xs:enumeration value="continuous"/>
|
||||
<xs:enumeration value="evenPage"/>
|
||||
<xs:enumeration value="oddPage"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Header/footer type -->
|
||||
<xs:simpleType name="ST_HdrFtr">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="even"/>
|
||||
<xs:enumeration value="default"/>
|
||||
<xs:enumeration value="first"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Table width type -->
|
||||
<xs:simpleType name="ST_TblWidth">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="auto"/>
|
||||
<xs:enumeration value="dxa"/>
|
||||
<xs:enumeration value="nil"/>
|
||||
<xs:enumeration value="pct"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Vertical merge -->
|
||||
<xs:simpleType name="ST_Merge">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="continue"/>
|
||||
<xs:enumeration value="restart"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Highlight colors -->
|
||||
<xs:simpleType name="ST_HighlightColor">
|
||||
<xs:restriction base="xs:string">
|
||||
<xs:enumeration value="black"/>
|
||||
<xs:enumeration value="blue"/>
|
||||
<xs:enumeration value="cyan"/>
|
||||
<xs:enumeration value="darkBlue"/>
|
||||
<xs:enumeration value="darkCyan"/>
|
||||
<xs:enumeration value="darkGray"/>
|
||||
<xs:enumeration value="darkGreen"/>
|
||||
<xs:enumeration value="darkMagenta"/>
|
||||
<xs:enumeration value="darkRed"/>
|
||||
<xs:enumeration value="darkYellow"/>
|
||||
<xs:enumeration value="green"/>
|
||||
<xs:enumeration value="lightGray"/>
|
||||
<xs:enumeration value="magenta"/>
|
||||
<xs:enumeration value="none"/>
|
||||
<xs:enumeration value="red"/>
|
||||
<xs:enumeration value="white"/>
|
||||
<xs:enumeration value="yellow"/>
|
||||
</xs:restriction>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Percentage (for table width pct, etc.) -->
|
||||
<xs:simpleType name="ST_DecimalNumber">
|
||||
<xs:restriction base="xs:integer"/>
|
||||
</xs:simpleType>
|
||||
|
||||
<!-- Relationship ID reference -->
|
||||
<xs:simpleType name="ST_RelationshipId">
|
||||
<xs:restriction base="xs:string"/>
|
||||
</xs:simpleType>
|
||||
|
||||
</xs:schema>
|
||||
@@ -0,0 +1,589 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- WordprocessingML Subset Schema for docx-toolkit -->
|
||||
<!-- Curated subset of ISO 29500 covering elements agents commonly generate -->
|
||||
<!-- MIT License - docx-toolkit project -->
|
||||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||||
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
||||
xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
|
||||
targetNamespace="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
elementFormDefault="qualified">
|
||||
|
||||
<xs:import namespace="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
|
||||
<xs:import namespace="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"/>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Root element -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:element name="document" type="w:CT_Document"/>
|
||||
|
||||
<xs:complexType name="CT_Document">
|
||||
<xs:sequence>
|
||||
<xs:element name="body" type="w:CT_Body" minOccurs="0"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Body -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_Body">
|
||||
<xs:sequence>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="p" type="w:CT_P"/>
|
||||
<xs:element name="tbl" type="w:CT_Tbl"/>
|
||||
<xs:element name="sdt" type="w:CT_SdtBlock"/>
|
||||
<xs:element name="bookmarkStart" type="w:CT_BookmarkStart"/>
|
||||
<xs:element name="bookmarkEnd" type="w:CT_BookmarkEnd"/>
|
||||
</xs:choice>
|
||||
<xs:element name="sectPr" type="w:CT_SectPr" minOccurs="0"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Paragraph -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_P">
|
||||
<xs:sequence>
|
||||
<xs:element name="pPr" type="w:CT_PPr" minOccurs="0"/>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="r" type="w:CT_R"/>
|
||||
<xs:element name="hyperlink" type="w:CT_Hyperlink"/>
|
||||
<xs:element name="bookmarkStart" type="w:CT_BookmarkStart"/>
|
||||
<xs:element name="bookmarkEnd" type="w:CT_BookmarkEnd"/>
|
||||
<xs:element name="commentRangeStart" type="w:CT_MarkupRange"/>
|
||||
<xs:element name="commentRangeEnd" type="w:CT_MarkupRange"/>
|
||||
<xs:element name="ins" type="w:CT_RunTrackChange"/>
|
||||
<xs:element name="del" type="w:CT_RunTrackChange"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
<xs:attribute ref="r:id" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- Paragraph Properties -->
|
||||
<xs:complexType name="CT_PPr">
|
||||
<xs:all>
|
||||
<xs:element name="pStyle" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="keepNext" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="keepLines" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="pageBreakBefore" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="widowControl" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="numPr" type="w:CT_NumPr" minOccurs="0"/>
|
||||
<xs:element name="spacing" type="w:CT_Spacing" minOccurs="0"/>
|
||||
<xs:element name="ind" type="w:CT_Ind" minOccurs="0"/>
|
||||
<xs:element name="jc" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="outlineLvl" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:integer" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="rPr" type="w:CT_RPr" minOccurs="0"/>
|
||||
<xs:element name="pBdr" type="w:CT_PBdr" minOccurs="0"/>
|
||||
<xs:element name="shd" type="w:CT_Shd" minOccurs="0"/>
|
||||
<xs:element name="tabs" type="w:CT_Tabs" minOccurs="0"/>
|
||||
<xs:element name="sectPr" type="w:CT_SectPr" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Run -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_R">
|
||||
<xs:sequence>
|
||||
<xs:element name="rPr" type="w:CT_RPr" minOccurs="0"/>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="t" type="w:CT_Text"/>
|
||||
<xs:element name="delText" type="w:CT_Text"/>
|
||||
<xs:element name="br" type="w:CT_Br"/>
|
||||
<xs:element name="tab" type="w:CT_Empty"/>
|
||||
<xs:element name="cr" type="w:CT_Empty"/>
|
||||
<xs:element name="drawing" type="w:CT_Drawing"/>
|
||||
<xs:element name="commentReference" type="w:CT_MarkupRef"/>
|
||||
<xs:element name="footnoteReference" type="w:CT_FtnEdnRef"/>
|
||||
<xs:element name="endnoteReference" type="w:CT_FtnEdnRef"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- Run Properties -->
|
||||
<xs:complexType name="CT_RPr">
|
||||
<xs:all>
|
||||
<xs:element name="rStyle" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="rFonts" type="w:CT_Fonts" minOccurs="0"/>
|
||||
<xs:element name="b" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="bCs" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="i" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="iCs" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="caps" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="smallCaps" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="strike" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="dstrike" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="vanish" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="color" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
<xs:attribute name="themeColor" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="spacing" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:integer" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="sz" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:positiveInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="szCs" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:positiveInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="highlight" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="u" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
<xs:attribute name="color" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="vertAlign" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="lang" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="eastAsia" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="bidi" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Text -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_Text" mixed="true">
|
||||
<xs:attribute ref="xml:space" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Table -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_Tbl">
|
||||
<xs:sequence>
|
||||
<xs:element name="tblPr" type="w:CT_TblPr" minOccurs="0"/>
|
||||
<xs:element name="tblGrid" type="w:CT_TblGrid" minOccurs="0"/>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="tr" type="w:CT_Row"/>
|
||||
<xs:element name="bookmarkStart" type="w:CT_BookmarkStart"/>
|
||||
<xs:element name="bookmarkEnd" type="w:CT_BookmarkEnd"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TblPr">
|
||||
<xs:all>
|
||||
<xs:element name="tblStyle" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="tblW" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="jc" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="tblInd" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="tblBorders" type="w:CT_TblBorders" minOccurs="0"/>
|
||||
<xs:element name="shd" type="w:CT_Shd" minOccurs="0"/>
|
||||
<xs:element name="tblLayout" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="type" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="tblCellMar" type="w:CT_TblCellMar" minOccurs="0"/>
|
||||
<xs:element name="tblLook" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="firstRow" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="lastRow" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="firstColumn" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="lastColumn" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="noHBand" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="noVBand" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TblGrid">
|
||||
<xs:sequence>
|
||||
<xs:element name="gridCol" minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="w" type="xs:nonNegativeInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Row">
|
||||
<xs:sequence>
|
||||
<xs:element name="trPr" type="w:CT_TrPr" minOccurs="0"/>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="tc" type="w:CT_Cell"/>
|
||||
<xs:element name="bookmarkStart" type="w:CT_BookmarkStart"/>
|
||||
<xs:element name="bookmarkEnd" type="w:CT_BookmarkEnd"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TrPr">
|
||||
<xs:all>
|
||||
<xs:element name="trHeight" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="hRule" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="tblHeader" type="w:CT_OnOff" minOccurs="0"/>
|
||||
<xs:element name="jc" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Cell">
|
||||
<xs:sequence>
|
||||
<xs:element name="tcPr" type="w:CT_TcPr" minOccurs="0"/>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="p" type="w:CT_P"/>
|
||||
<xs:element name="tbl" type="w:CT_Tbl"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TcPr">
|
||||
<xs:all>
|
||||
<xs:element name="tcW" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="gridSpan" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:positiveInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="vMerge" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="tcBorders" type="w:CT_TcBorders" minOccurs="0"/>
|
||||
<xs:element name="shd" type="w:CT_Shd" minOccurs="0"/>
|
||||
<xs:element name="vAlign" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="noWrap" type="w:CT_OnOff" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Section Properties -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_SectPr">
|
||||
<xs:all>
|
||||
<xs:element name="headerReference" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="type" type="xs:string" use="required"/>
|
||||
<xs:attribute ref="r:id" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="footerReference" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="type" type="xs:string" use="required"/>
|
||||
<xs:attribute ref="r:id" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="type" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="pgSz" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="w" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="h" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="orient" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="pgMar" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="top" type="xs:integer" use="required"/>
|
||||
<xs:attribute name="right" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="bottom" type="xs:integer" use="required"/>
|
||||
<xs:attribute name="left" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="header" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="footer" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="gutter" type="xs:nonNegativeInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="pgNumType" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="fmt" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="start" type="xs:nonNegativeInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="cols" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="space" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="num" type="xs:positiveInteger" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="docGrid" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="linePitch" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="type" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="titlePg" type="w:CT_OnOff" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Hyperlink -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_Hyperlink">
|
||||
<xs:sequence>
|
||||
<xs:element name="r" type="w:CT_R" minOccurs="0" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
<xs:attribute ref="r:id" use="optional"/>
|
||||
<xs:attribute name="anchor" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="history" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Track Changes -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_RunTrackChange">
|
||||
<xs:sequence>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="r" type="w:CT_R"/>
|
||||
</xs:choice>
|
||||
</xs:sequence>
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="author" type="xs:string" use="required"/>
|
||||
<xs:attribute name="date" type="xs:dateTime" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Bookmarks -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_BookmarkStart">
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
<xs:attribute name="name" type="xs:string" use="required"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_BookmarkEnd">
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Comments -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_MarkupRange">
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_MarkupRef">
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Footnote/Endnote reference -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_FtnEdnRef">
|
||||
<xs:attribute name="id" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Drawing (basic inline image) -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_Drawing">
|
||||
<xs:sequence>
|
||||
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Structured Document Tag (content control) -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_SdtBlock">
|
||||
<xs:sequence>
|
||||
<xs:element name="sdtPr" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="sdtContent" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:element name="p" type="w:CT_P"/>
|
||||
<xs:element name="tbl" type="w:CT_Tbl"/>
|
||||
</xs:choice>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- Helper types -->
|
||||
<!-- ============================================================ -->
|
||||
<xs:complexType name="CT_OnOff">
|
||||
<xs:attribute name="val" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Empty"/>
|
||||
|
||||
<xs:complexType name="CT_Br">
|
||||
<xs:attribute name="type" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="clear" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Fonts">
|
||||
<xs:attribute name="ascii" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="hAnsi" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="eastAsia" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="cs" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="asciiTheme" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="hAnsiTheme" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="eastAsiaTheme" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="cstheme" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_NumPr">
|
||||
<xs:all>
|
||||
<xs:element name="ilvl" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="numId" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:nonNegativeInteger" use="required"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Spacing">
|
||||
<xs:attribute name="before" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="after" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="line" type="xs:integer" use="optional"/>
|
||||
<xs:attribute name="lineRule" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="beforeAutospacing" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="afterAutospacing" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Ind">
|
||||
<xs:attribute name="left" type="xs:integer" use="optional"/>
|
||||
<xs:attribute name="right" type="xs:integer" use="optional"/>
|
||||
<xs:attribute name="hanging" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="firstLine" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="start" type="xs:integer" use="optional"/>
|
||||
<xs:attribute name="end" type="xs:integer" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TblWidth">
|
||||
<xs:attribute name="w" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="type" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Shd">
|
||||
<xs:attribute name="val" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="color" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="fill" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="themeFill" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Border">
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
<xs:attribute name="sz" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="space" type="xs:nonNegativeInteger" use="optional"/>
|
||||
<xs:attribute name="color" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="themeColor" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_PBdr">
|
||||
<xs:all>
|
||||
<xs:element name="top" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="left" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="bottom" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="right" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="between" type="w:CT_Border" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TblBorders">
|
||||
<xs:all>
|
||||
<xs:element name="top" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="left" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="bottom" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="right" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="insideH" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="insideV" type="w:CT_Border" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TcBorders">
|
||||
<xs:all>
|
||||
<xs:element name="top" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="left" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="bottom" type="w:CT_Border" minOccurs="0"/>
|
||||
<xs:element name="right" type="w:CT_Border" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_TblCellMar">
|
||||
<xs:all>
|
||||
<xs:element name="top" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="left" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="bottom" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
<xs:element name="right" type="w:CT_TblWidth" minOccurs="0"/>
|
||||
</xs:all>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="CT_Tabs">
|
||||
<xs:sequence>
|
||||
<xs:element name="tab" minOccurs="0" maxOccurs="unbounded">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="val" type="xs:string" use="required"/>
|
||||
<xs:attribute name="pos" type="xs:integer" use="required"/>
|
||||
<xs:attribute name="leader" type="xs:string" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
</xs:schema>
|
||||
@@ -0,0 +1,357 @@
|
||||
# CJK Typography & Mixed-Script Guide
|
||||
|
||||
Rules for Chinese, Japanese, and Korean text in DOCX documents.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Font Selection](#font-selection)
|
||||
2. [Font Size Names (CJK)](#font-size-names)
|
||||
3. [RunFonts Mapping](#runfonts-mapping)
|
||||
4. [Punctuation & Line Breaking](#punctuation--line-breaking)
|
||||
5. [Paragraph Indentation](#paragraph-indentation)
|
||||
6. [Line Spacing for CJK](#line-spacing)
|
||||
7. [Chinese Government Standard (GB/T 9704)](#gbt-9704)
|
||||
8. [Mixed CJK + Latin Best Practices](#mixed-script)
|
||||
9. [OpenXML Quick Reference](#openxml-quick-reference)
|
||||
|
||||
---
|
||||
|
||||
## Font Selection
|
||||
|
||||
### Recommended CJK Fonts
|
||||
|
||||
| Language | Serif (正文) | Sans (标题) | Notes |
|
||||
|----------|-------------|-------------|-------|
|
||||
| **Simplified Chinese** | 宋体 (SimSun) | 微软雅黑 (Microsoft YaHei) | YaHei for screen, SimSun for print |
|
||||
| **Simplified Chinese** | 仿宋 (FangSong) | 黑体 (SimHei) | Government documents |
|
||||
| **Traditional Chinese** | 新細明體 (PMingLiU) | 微軟正黑體 (Microsoft JhengHei) | Taiwan standard |
|
||||
| **Japanese** | MS 明朝 (MS Mincho) | MS ゴシック (MS Gothic) | Classic pairing |
|
||||
| **Japanese** | 游明朝 (Yu Mincho) | 游ゴシック (Yu Gothic) | Modern, Windows 10+ |
|
||||
| **Korean** | 바탕 (Batang) | 맑은 고딕 (Malgun Gothic) | Standard pairing |
|
||||
|
||||
### Government Document Fonts (公文)
|
||||
|
||||
| Element | Font | Size |
|
||||
|---------|------|------|
|
||||
| 标题 (title) | 小标宋 (FZXiaoBiaoSong-B05S) | 二号 (22pt) |
|
||||
| 一级标题 | 黑体 (SimHei) | 三号 (16pt) |
|
||||
| 二级标题 | 楷体_GB2312 (KaiTi_GB2312) | 三号 (16pt) |
|
||||
| 三级标题 | 仿宋_GB2312 加粗 | 三号 (16pt) |
|
||||
| 正文 (body) | 仿宋_GB2312 (FangSong_GB2312) | 三号 (16pt) |
|
||||
| 附注/页码 | 宋体 (SimSun) | 四号 (14pt) |
|
||||
|
||||
---
|
||||
|
||||
## Font Size Names
|
||||
|
||||
CJK uses named sizes. Map to points and `w:sz` half-point values:
|
||||
|
||||
| 字号 | Points | `w:sz` | Common Use |
|
||||
|------|--------|--------|------------|
|
||||
| 初号 | 42pt | 84 | Display title |
|
||||
| 小初 | 36pt | 72 | Large title |
|
||||
| 一号 | 26pt | 52 | Chapter heading |
|
||||
| 小一 | 24pt | 48 | Major heading |
|
||||
| 二号 | 22pt | 44 | Document title (公文) |
|
||||
| 小二 | 18pt | 36 | Western H1 equivalent |
|
||||
| 三号 | 16pt | 32 | CJK heading / 公文 body |
|
||||
| 小三 | 15pt | 30 | Sub-heading |
|
||||
| 四号 | 14pt | 28 | CJK subheading |
|
||||
| 小四 | 12pt | 24 | Standard body (CJK) |
|
||||
| 五号 | 10.5pt | 21 | Compact CJK body |
|
||||
| 小五 | 9pt | 18 | Footnotes |
|
||||
| 六号 | 7.5pt | 15 | Fine print |
|
||||
|
||||
---
|
||||
|
||||
## RunFonts Mapping
|
||||
|
||||
OpenXML uses four font slots to handle multilingual text:
|
||||
|
||||
```xml
|
||||
<w:rFonts
|
||||
w:ascii="Calibri" <!-- Latin characters (U+0000–U+007F) -->
|
||||
w:hAnsi="Calibri" <!-- Latin extended, Greek, Cyrillic -->
|
||||
w:eastAsia="SimSun" <!-- CJK Unified Ideographs, Kana, Hangul -->
|
||||
w:cs="Arial" <!-- Arabic, Hebrew, Thai, Devanagari -->
|
||||
/>
|
||||
```
|
||||
|
||||
**Word's character classification logic:**
|
||||
|
||||
1. Character is in CJK range → uses `w:eastAsia` font
|
||||
2. Character is in complex script range → uses `w:cs` font
|
||||
3. Character is basic Latin (ASCII) → uses `w:ascii` font
|
||||
4. Everything else → uses `w:hAnsi` font
|
||||
|
||||
**Key**: `w:eastAsia` is the **only** way to set CJK fonts. Setting just `w:ascii` will NOT affect CJK characters. Mixed text within a single run auto-switches fonts at the character level — no need for separate runs.
|
||||
|
||||
### Document Defaults
|
||||
|
||||
```xml
|
||||
<w:docDefaults>
|
||||
<w:rPrDefault>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial" />
|
||||
<w:sz w:val="22" />
|
||||
<w:szCs w:val="22" />
|
||||
<w:lang w:val="en-US" w:eastAsia="zh-CN" />
|
||||
</w:rPr>
|
||||
</w:rPrDefault>
|
||||
</w:docDefaults>
|
||||
```
|
||||
|
||||
`w:lang w:eastAsia` helps Word resolve ambiguous characters (e.g., punctuation shared between CJK and Latin).
|
||||
|
||||
---
|
||||
|
||||
## Punctuation & Line Breaking
|
||||
|
||||
### Full-Width vs Half-Width
|
||||
|
||||
CJK text uses full-width punctuation:
|
||||
|
||||
| Type | CJK | Latin |
|
||||
|------|-----|-------|
|
||||
| Period | 。(U+3002) | . |
|
||||
| Comma | ，(U+FF0C) 、(U+3001) | , |
|
||||
| Colon | ：(U+FF1A) | : |
|
||||
| Semicolon | ；(U+FF1B) | ; |
|
||||
| Quotes | 「」『』 or ""'' | "" '' |
|
||||
| Parentheses | （）(U+FF08/09) | () |
|
||||
|
||||
In mixed text, use the punctuation style of the **surrounding language context**.
|
||||
|
||||
### OpenXML Controls
|
||||
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:adjustRightInd w:val="true" /> <!-- Adjust right indent for CJK punctuation -->
|
||||
<w:snapToGrid w:val="true" /> <!-- Align to document grid -->
|
||||
<w:kinsoku w:val="true" /> <!-- Enable CJK line breaking rules -->
|
||||
<w:overflowPunct w:val="true" /> <!-- Allow punctuation to overflow margins -->
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
### Kinsoku Rules (禁則処理)
|
||||
|
||||
Prevents certain characters from appearing at the start or end of a line:
|
||||
- **Cannot start a line**: `）」』】〉》。、，！？；：` and closing brackets
|
||||
- **Cannot end a line**: `（「『【〈《` and opening brackets
|
||||
|
||||
Word applies these automatically when `w:kinsoku` is enabled.
|
||||
|
||||
### Line Breaking
|
||||
|
||||
- CJK characters can break between **any two characters** (no word boundaries needed)
|
||||
- Latin words within CJK text still follow word-boundary breaking
|
||||
- `w:wordWrap w:val="false"` enables CJK-style breaking (break anywhere)
|
||||
|
||||
---
|
||||
|
||||
## Paragraph Indentation
|
||||
|
||||
### Chinese Standard: 2-Character Indent
|
||||
|
||||
Chinese body text conventionally uses a 2-character first-line indent:
|
||||
|
||||
```xml
|
||||
<w:ind w:firstLineChars="200" /> <!-- 200 = 2 characters × 100 -->
|
||||
```
|
||||
|
||||
Preferred over `w:firstLine` with fixed DXA because `firstLineChars` scales with font size.
|
||||
|
||||
| Indent | Value |
|
||||
|--------|-------|
|
||||
| 1 character | `w:firstLineChars="100"` |
|
||||
| 2 characters | `w:firstLineChars="200"` |
|
||||
| 3 characters | `w:firstLineChars="300"` |
|
||||
|
||||
---
|
||||
|
||||
## Line Spacing
|
||||
|
||||
- CJK characters are taller than Latin characters at the same point size
|
||||
- Default `1.0` line spacing may feel cramped with CJK text
|
||||
- Recommended: `1.15–1.5` for mixed CJK+Latin, `1.0` with fixed 28pt for 公文
|
||||
|
||||
### Auto Spacing
|
||||
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:autoSpaceDE w:val="true"/> <!-- auto space between CJK and Latin -->
|
||||
<w:autoSpaceDN w:val="true"/> <!-- auto space between CJK and numbers -->
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
Adds ~¼ em spacing between CJK and non-CJK characters automatically. **Recommended: always enable.**
|
||||
|
||||
---
|
||||
|
||||
## GB/T 9704
|
||||
|
||||
Chinese government document standard (党政机关公文格式). These are **strict requirements**, not suggestions.
|
||||
|
||||
### Page Setup
|
||||
|
||||
| Parameter | Value | OpenXML |
|
||||
|-----------|-------|---------|
|
||||
| Page size | A4 (210×297mm) | Width=11906, Height=16838 |
|
||||
| Top margin | 37mm | 2098 DXA |
|
||||
| Bottom margin | 35mm | 1984 DXA |
|
||||
| Left margin | 28mm | 1588 DXA |
|
||||
| Right margin | 26mm | 1474 DXA |
|
||||
| Characters/line | 28 | |
|
||||
| Lines/page | 22 | |
|
||||
| Line spacing | Fixed 28pt | `line="560"` lineRule="exact" |
|
||||
|
||||
### Document Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ 发文机关标志 (红头) │ ← 小标宋 or 红色大字
|
||||
│ ══════════════════ (红线) │ ← Red #FF0000, 2pt
|
||||
├─────────────────────────────────┤
|
||||
│ 发文字号: X机发〔2025〕X号 │ ← 仿宋 三号, centered
|
||||
│ │
|
||||
│ 标题 (Title) │ ← 小标宋 二号, centered
|
||||
│ │ 可分多行，回行居中
|
||||
│ 主送机关: │ ← 仿宋 三号
|
||||
│ │
|
||||
│ 正文 (Body)... │ ← 仿宋_GB2312 三号
|
||||
│ 一、一级标题 │ ← 黑体 三号
|
||||
│ （一）二级标题 │ ← 楷体 三号
|
||||
│ 1. 三级标题 │ ← 仿宋 三号 加粗
|
||||
│ (1) 四级标题 │ ← 仿宋 三号
|
||||
│ │
|
||||
│ 附件: 1. xxx │ ← 仿宋 三号
|
||||
│ │
|
||||
│ 发文机关署名 │ ← 仿宋 三号
|
||||
│ 成文日期 │ ← 仿宋 三号, 小写中文数字
|
||||
├─────────────────────────────────┤
|
||||
│ ══════════════════ (版记线) │
|
||||
│ 抄送: xxx │ ← 仿宋 四号
|
||||
│ 印发机关及日期 │ ← 仿宋 四号
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Numbering System
|
||||
|
||||
```
|
||||
一、 ← 黑体 (SimHei), no indentation
|
||||
（一） ← 楷体 (KaiTi), indented 2 chars
|
||||
1. ← 仿宋加粗 (FangSong Bold), indented 2 chars
|
||||
(1) ← 仿宋 (FangSong), indented 2 chars
|
||||
```
|
||||
|
||||
### Colors
|
||||
|
||||
| Element | Color | Requirement |
|
||||
|---------|-------|-------------|
|
||||
| All body text | Black #000000 | Mandatory |
|
||||
| 红头 (agency name) | Red #FF0000 | Mandatory |
|
||||
| 红线 (separator) | Red #FF0000 | Mandatory |
|
||||
| 公章 (official seal) | Red | Mandatory |
|
||||
|
||||
### Page Numbers
|
||||
|
||||
- Position: bottom center
|
||||
- Format: `-X-` (dash-number-dash)
|
||||
- Font: 宋体 四号 (SimSun 14pt, `sz="28"`)
|
||||
- No page number on cover page if present
|
||||
|
||||
---
|
||||
|
||||
## Mixed Script
|
||||
|
||||
### Font Size Harmony
|
||||
|
||||
CJK characters appear larger than Latin characters at the same point size. Compensation:
|
||||
|
||||
- If body is Calibri 11pt, pair with CJK at 11pt (same size — CJK looks slightly larger but acceptable)
|
||||
- If precise visual match needed, CJK can be set 0.5–1pt smaller
|
||||
- In practice, same point size is standard — don't over-optimize
|
||||
|
||||
### Bold and Italic
|
||||
|
||||
- **Chinese/Japanese have no true italic.** Word synthesizes a slant which looks poor
|
||||
- Use **bold** for emphasis in CJK text
|
||||
- Use 着重号 (emphasis dots) for traditional emphasis: `<w:em w:val="dot"/>` on RunProperties
|
||||
|
||||
---
|
||||
|
||||
## OpenXML Quick Reference
|
||||
|
||||
### Set EastAsia Font (C#)
|
||||
|
||||
```csharp
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts { EastAsia = "SimSun", Ascii = "Calibri", HighAnsi = "Calibri" },
|
||||
new FontSize { Val = "32" } // 三号 = 16pt = sz 32
|
||||
),
|
||||
new Text("这是正文内容")
|
||||
);
|
||||
```
|
||||
|
||||
### Document Defaults (C#)
|
||||
|
||||
```csharp
|
||||
new DocDefaults(new RunPropertiesDefault(new RunPropertiesBaseStyle(
|
||||
new RunFonts {
|
||||
Ascii = "Calibri", HighAnsi = "Calibri",
|
||||
EastAsia = "Microsoft YaHei"
|
||||
},
|
||||
new Languages { Val = "en-US", EastAsia = "zh-CN" }
|
||||
)));
|
||||
```
|
||||
|
||||
### 公文 Style Definitions (C#)
|
||||
|
||||
```csharp
|
||||
// Title style — 小标宋 二号 centered
|
||||
new Style(
|
||||
new StyleName { Val = "GongWen Title" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new StyleRunProperties(
|
||||
new RunFonts { EastAsia = "FZXiaoBiaoSong-B05S" },
|
||||
new FontSize { Val = "44" }, // 二号 = 22pt
|
||||
new Bold()
|
||||
),
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { Line = "560", LineRule = LineSpacingRuleValues.Exact }
|
||||
)
|
||||
) { Type = StyleValues.Paragraph, StyleId = "GongWenTitle" };
|
||||
|
||||
// Body style — 仿宋_GB2312 三号
|
||||
new Style(
|
||||
new StyleName { Val = "GongWen Body" },
|
||||
new StyleRunProperties(
|
||||
new RunFonts { EastAsia = "FangSong_GB2312", Ascii = "FangSong_GB2312" },
|
||||
new FontSize { Val = "32" } // 三号 = 16pt
|
||||
),
|
||||
new StyleParagraphProperties(
|
||||
new SpacingBetweenLines { Line = "560", LineRule = LineSpacingRuleValues.Exact }
|
||||
)
|
||||
) { Type = StyleValues.Paragraph, StyleId = "GongWenBody" };
|
||||
```
|
||||
|
||||
### Emphasis Dots (着重号)
|
||||
|
||||
```csharp
|
||||
new RunProperties(new Emphasis { Val = EmphasisMarkValues.Dot });
|
||||
```
|
||||
|
||||
### East Asian Text Layout
|
||||
|
||||
```xml
|
||||
<!-- Snap to grid (align CJK chars to character grid) -->
|
||||
<w:snapToGrid w:val="true"/>
|
||||
|
||||
<!-- Two-lines-in-one (双行合一) -->
|
||||
<w:eastAsianLayout w:id="1" w:combine="true"/>
|
||||
|
||||
<!-- Vertical text in a cell -->
|
||||
<w:textDirection w:val="tbRl"/>
|
||||
```
|
||||
@@ -0,0 +1,184 @@
|
||||
# Chinese University Thesis Template Guide (中国高校论文模板指南)
|
||||
|
||||
## Why This Guide Exists
|
||||
|
||||
Chinese university thesis templates (.docx) have structural patterns that differ significantly
|
||||
from Western templates. Agents that assume Western conventions (Heading1/Heading2/Normal) will
|
||||
fail repeatedly. This guide documents the ACTUAL patterns found in Chinese templates.
|
||||
|
||||
## Common StyleId Patterns
|
||||
|
||||
### Pattern A: Numeric IDs (most common in Chinese Word templates)
|
||||
|
||||
| Style Purpose | styleId | w:name | w:basedOn |
|
||||
|--------------|---------|--------|-----------|
|
||||
| Normal body | `a` | "Normal" | — |
|
||||
| Default paragraph font | `a0` | "Default Paragraph Font" | — |
|
||||
| Heading 1 (章标题) | `1` | "heading 1" | `a` |
|
||||
| Heading 2 (节标题) | `2` | "heading 2" | `a` |
|
||||
| Heading 3 (小节标题) | `3` | "heading 3" | `a` |
|
||||
| TOC 1 | `11` | "toc 1" | `a` |
|
||||
| TOC 2 | `21` | "toc 2" | `a` |
|
||||
| TOC 3 | `31` | "toc 3" | `a` |
|
||||
| Header | `a3` | "header" | `a` |
|
||||
| Footer | `a4` | "footer" | `a` |
|
||||
| Table of Contents heading | `10` | "TOC Heading" | `1` |
|
||||
|
||||
### Pattern B: English IDs (less common, usually from international templates)
|
||||
Standard Heading1/Heading2/Heading3/Normal — these follow the Western pattern.
|
||||
|
||||
### Pattern C: Mixed (some Chinese, some English)
|
||||
Some templates define custom styles with Chinese names:
|
||||
| Style Purpose | styleId | w:name |
|
||||
|--------------|---------|--------|
|
||||
| 论文标题 | `lunwenbiaoti` | "论文标题" |
|
||||
| 章标题 | `zhangbiaoti` | "章标题" |
|
||||
| 正文 | `zhengwen` | "正文" |
|
||||
|
||||
### How to Identify Which Pattern
|
||||
|
||||
```bash
|
||||
# Extract all styleIds from the template
|
||||
$CLI analyze --input template.docx --styles-only
|
||||
|
||||
# Or manually:
|
||||
# unzip template.docx word/styles.xml
|
||||
# Search for w:styleId= in the extracted file
|
||||
```
|
||||
|
||||
Look at the first few styleIds. If you see `1`, `2`, `3`, `a`, `a0` → Pattern A.
|
||||
If you see `Heading1`, `Normal` → Pattern B.
|
||||
|
||||
## Standard Thesis Structure
|
||||
|
||||
Chinese university theses follow a highly standardized structure:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 封面 (Cover Page) │ ← Usually 1-2 pages
|
||||
│ - 校名、校徽 │
|
||||
│ - 论文题目 (title) │
|
||||
│ - 作者、导师、院系、日期 │
|
||||
├─────────────────────────────────────┤
|
||||
│ 学术诚信承诺书 / 独创性声明 │ ← 1 page
|
||||
│ (Academic Integrity Declaration) │
|
||||
├─────────────────────────────────────┤
|
||||
│ 中文摘要 (Chinese Abstract) │ ← 1-2 pages
|
||||
│ - "摘 要" heading │
|
||||
│ - Abstract body │
|
||||
│ - "关键词：" line │
|
||||
├─────────────────────────────────────┤
|
||||
│ 英文摘要 (English Abstract) │ ← 1-2 pages
|
||||
│ - "ABSTRACT" heading │
|
||||
│ - Abstract body │
|
||||
│ - "Keywords:" line │
|
||||
├─────────────────────────────────────┤
|
||||
│ 目录 (Table of Contents) │ ← 1-3 pages
|
||||
│ - Often inside SDT block │
|
||||
│ - Static example entries │
|
||||
│ - TOC field code │
|
||||
├─────────────────────────────────────┤
|
||||
│ 正文 (Body) │ ← Main content
|
||||
│ 第1章 绪论 │
|
||||
│ 1.1 研究背景 │
|
||||
│ 1.2 研究目的和意义 │
|
||||
│ 第2章 文献综述 │
|
||||
│ ... │
|
||||
│ 第N章 结论与展望 │
|
||||
├─────────────────────────────────────┤
|
||||
│ 参考文献 (References) │ ← Styled differently
|
||||
├─────────────────────────────────────┤
|
||||
│ 致谢 (Acknowledgments) │ ← Optional
|
||||
├─────────────────────────────────────┤
|
||||
│ 附录 (Appendices) │ ← Optional
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Identifying Zone Boundaries in Templates
|
||||
|
||||
Templates contain EXAMPLE content that must be replaced. Here's how to find the zones:
|
||||
|
||||
### Zone A (Front matter) — KEEP from template
|
||||
- Starts at: paragraph 0
|
||||
- Ends at: the paragraph BEFORE the first chapter heading
|
||||
- Contains: cover, declaration, abstracts, TOC
|
||||
- How to detect end: search for first paragraph with style `1` (or Heading1) containing "第1章" or "绪论"
|
||||
|
||||
### Zone B (Body content) — REPLACE with user content
|
||||
- Starts at: first chapter heading ("第1章...")
|
||||
- Ends at: "参考文献" heading (inclusive) or last body paragraph before acknowledgments
|
||||
- How to detect:
|
||||
```python
|
||||
for i, el in enumerate(body_elements):
|
||||
text = get_text(el)
|
||||
style = get_style(el)
|
||||
if style in ('1', 'Heading1') and ('第1章' in text or '绪论' in text):
|
||||
zone_b_start = i
|
||||
if '参考文献' in text:
|
||||
zone_b_end = i
|
||||
```
|
||||
|
||||
### Zone C (Back matter) — KEEP from template (or remove)
|
||||
- Starts after: 参考文献
|
||||
- Contains: 致谢, 附录, final sectPr
|
||||
|
||||
## Font Expectations in Chinese Thesis Templates
|
||||
|
||||
| Element | Font | Size (字号) | Size (pt) | w:sz |
|
||||
|---------|------|------------|-----------|------|
|
||||
| 论文标题 | 华文中宋 or 黑体 | 二号 or 小二 | 22pt or 18pt | 44 or 36 |
|
||||
| 章标题 (H1) | 黑体 | 三号 | 16pt | 32 |
|
||||
| 节标题 (H2) | 黑体 | 四号 | 14pt | 28 |
|
||||
| 小节标题 (H3) | 黑体 | 小四 | 12pt | 24 |
|
||||
| 正文 | 宋体 | 小四 | 12pt | 24 |
|
||||
| 页眉 | 宋体 | 五号 | 10.5pt | 21 |
|
||||
| 页脚/页码 | 宋体 | 五号 | 10.5pt | 21 |
|
||||
| 表格内容 | 宋体 | 五号 | 10.5pt | 21 |
|
||||
| 参考文献条目 | 宋体 | 五号 | 10.5pt | 21 |
|
||||
|
||||
## RunFonts for CJK Body Text
|
||||
|
||||
```xml
|
||||
<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
|
||||
w:eastAsia="宋体" w:cs="Times New Roman"/>
|
||||
```
|
||||
|
||||
For headings:
|
||||
```xml
|
||||
<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
|
||||
w:eastAsia="黑体" w:cs="Times New Roman"/>
|
||||
```
|
||||
|
||||
IMPORTANT: When cleaning direct formatting, ALWAYS preserve w:eastAsia.
|
||||
Removing it causes Chinese text to fall back to the wrong font.
|
||||
|
||||
## Common Mistakes with Chinese Templates
|
||||
|
||||
1. **Searching for `Heading1`** — Chinese templates use `1`, not `Heading1`
|
||||
2. **Clearing all rFonts** — Must keep eastAsia font declarations
|
||||
3. **Assuming "第1章" is the first paragraph** — It's typically paragraph 100+ after cover/abstract/TOC
|
||||
4. **Ignoring SDT blocks in TOC** — The TOC is wrapped in an SDT, not just field codes
|
||||
5. **Wrong line spacing** — Chinese theses typically use fixed 20pt (line="400") or 22pt (line="440"), not the 28pt used in government documents
|
||||
6. **Missing section breaks** — Each zone (abstract, TOC, body) usually has its own sectPr for different headers/footers
|
||||
|
||||
## Style Mapping Quick Reference
|
||||
|
||||
When source document uses Western IDs and template uses Chinese numeric IDs:
|
||||
|
||||
```json
|
||||
{
|
||||
"Heading1": "1",
|
||||
"Heading2": "2",
|
||||
"Heading3": "3",
|
||||
"Heading4": "3",
|
||||
"Normal": "a",
|
||||
"BodyText": "a",
|
||||
"ListParagraph": "a",
|
||||
"Caption": "a",
|
||||
"TOC1": "11",
|
||||
"TOC2": "21",
|
||||
"TOC3": "31"
|
||||
}
|
||||
```
|
||||
|
||||
When source uses Chinese numeric IDs and template uses Western IDs — reverse the mapping.
|
||||
@@ -0,0 +1,191 @@
|
||||
# Comments System Guide (4-File Architecture)
|
||||
|
||||
## Overview
|
||||
|
||||
Word comments require coordination across **four XML files** plus references in `document.xml`, `[Content_Types].xml`, and `document.xml.rels`.
|
||||
|
||||
---
|
||||
|
||||
## The Four Comment Files
|
||||
|
||||
### 1. `word/comments.xml` — Main Comment Content
|
||||
|
||||
Contains the actual comment text:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
||||
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
|
||||
<w:comment w:id="1" w:author="Alice" w:date="2026-03-21T09:00:00Z" w:initials="A">
|
||||
<w:p>
|
||||
<w:pPr><w:pStyle w:val="CommentText" /></w:pPr>
|
||||
<w:r>
|
||||
<w:rPr><w:rStyle w:val="CommentReference" /></w:rPr>
|
||||
<w:annotationRef />
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:t>This needs clarification.</w:t>
|
||||
</w:r>
|
||||
</w:p>
|
||||
</w:comment>
|
||||
</w:comments>
|
||||
```
|
||||
|
||||
Key attributes: `w:id` (unique integer), `w:author`, `w:date` (ISO 8601), `w:initials`.
|
||||
|
||||
### 2. `word/commentsExtended.xml` — W15 Extensions
|
||||
|
||||
Links comments to paragraphs and tracks resolved status:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">
|
||||
<w15:commentEx w15:paraId="1A2B3C4D" w15:done="0" />
|
||||
</w15:commentsEx>
|
||||
```
|
||||
|
||||
- `w15:paraId` — matches the `w14:paraId` of the comment's paragraph in `comments.xml`
|
||||
- `w15:done` — `"0"` = open, `"1"` = resolved
|
||||
|
||||
### 3. `word/commentsIds.xml` — Persistent ID Mapping
|
||||
|
||||
Provides durable IDs that survive copy/paste across documents:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w16cid:commentsIds xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid">
|
||||
<w16cid:commentId w16cid:paraId="1A2B3C4D" w16cid:durableId="12345678" />
|
||||
</w16cid:commentsIds>
|
||||
```
|
||||
|
||||
- `w16cid:paraId` — same as `w15:paraId`
|
||||
- `w16cid:durableId` — globally unique identifier (8-digit hex)
|
||||
|
||||
### 4. `word/commentsExtensible.xml` — W16 Extensions
|
||||
|
||||
Modern comment extensions (used in newer Word versions):
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
||||
<w16cex:commentsExtensible xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex">
|
||||
<w16cex:commentExtensible w16cex:durableId="12345678" w16cex:dateUtc="2026-03-21T09:00:00Z" />
|
||||
</w16cex:commentsExtensible>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Document.xml References
|
||||
|
||||
Comments are anchored in document content using three elements:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:commentRangeStart w:id="1" />
|
||||
<w:r><w:t>This text has a comment.</w:t></w:r>
|
||||
<w:commentRangeEnd w:id="1" />
|
||||
<w:r>
|
||||
<w:rPr><w:rStyle w:val="CommentReference" /></w:rPr>
|
||||
<w:commentReference w:id="1" />
|
||||
</w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
- `w:commentRangeStart` — marks where the commented text begins
|
||||
- `w:commentRangeEnd` — marks where the commented text ends
|
||||
- `w:commentReference` — the visible comment marker (superscript number), placed in a run after the range end
|
||||
|
||||
The `w:id` on all three must match the `w:id` in `comments.xml`.
|
||||
|
||||
---
|
||||
|
||||
## Content Types Registration
|
||||
|
||||
Add to `[Content_Types].xml`:
|
||||
|
||||
```xml
|
||||
<Override PartName="/word/comments.xml"
|
||||
ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml" />
|
||||
<Override PartName="/word/commentsExtended.xml"
|
||||
ContentType="application/vnd.ms-word.commentsExtended+xml" />
|
||||
<Override PartName="/word/commentsIds.xml"
|
||||
ContentType="application/vnd.ms-word.commentsIds+xml" />
|
||||
<Override PartName="/word/commentsExtensible.xml"
|
||||
ContentType="application/vnd.ms-word.commentsExtensible+xml" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relationship Registration
|
||||
|
||||
Add to `word/_rels/document.xml.rels`:
|
||||
|
||||
```xml
|
||||
<Relationship Id="rId20" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
|
||||
Target="comments.xml" />
|
||||
<Relationship Id="rId21" Type="http://schemas.microsoft.com/office/2011/relationships/commentsExtended"
|
||||
Target="commentsExtended.xml" />
|
||||
<Relationship Id="rId22" Type="http://schemas.microsoft.com/office/2016/09/relationships/commentsIds"
|
||||
Target="commentsIds.xml" />
|
||||
<Relationship Id="rId23" Type="http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible"
|
||||
Target="commentsExtensible.xml" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step: Adding a New Comment
|
||||
|
||||
1. **Choose a unique comment ID** (scan existing `w:id` values, use max + 1)
|
||||
2. **Generate a paraId** (8-character hex, e.g., `"1A2B3C4D"`) and durableId (8-digit hex)
|
||||
3. **Add to `comments.xml`**: Create `w:comment` element with content
|
||||
4. **Add to `commentsExtended.xml`**: Create `w15:commentEx` with `paraId`, `done="0"`
|
||||
5. **Add to `commentsIds.xml`**: Create `w16cid:commentId` with `paraId` and `durableId`
|
||||
6. **Add to `commentsExtensible.xml`**: Create `w16cex:commentExtensible` with `durableId` and `dateUtc`
|
||||
7. **Add to `document.xml`**: Insert `w:commentRangeStart`, `w:commentRangeEnd`, and `w:commentReference` around target text
|
||||
8. **Verify `[Content_Types].xml`** and `document.xml.rels` have entries for all 4 files
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step: Adding a Reply
|
||||
|
||||
Replies are comments whose paragraph's `w14:paraId` links to a parent comment:
|
||||
|
||||
1. Create a new `w:comment` in `comments.xml` with a new `w:id`
|
||||
2. In `commentsExtended.xml`, add `w15:commentEx` with:
|
||||
- `w15:paraId` = new paragraph ID
|
||||
- `w15:paraIdParent` = the `paraId` of the comment being replied to
|
||||
- `w15:done="0"`
|
||||
3. Add entries in `commentsIds.xml` and `commentsExtensible.xml`
|
||||
4. In `document.xml`, the reply does NOT need its own range markers — it shares the parent's range
|
||||
|
||||
```xml
|
||||
<!-- In commentsExtended.xml -->
|
||||
<w15:commentEx w15:paraId="5E6F7A8B" w15:paraIdParent="1A2B3C4D" w15:done="0" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step: Resolving a Comment
|
||||
|
||||
Set `w15:done="1"` on the comment's `w15:commentEx` entry:
|
||||
|
||||
```xml
|
||||
<!-- Before -->
|
||||
<w15:commentEx w15:paraId="1A2B3C4D" w15:done="0" />
|
||||
|
||||
<!-- After -->
|
||||
<w15:commentEx w15:paraId="1A2B3C4D" w15:done="1" />
|
||||
```
|
||||
|
||||
This marks the comment (and all its replies) as resolved. The comment remains visible but appears grayed out in Word.
|
||||
|
||||
---
|
||||
|
||||
## Minimum Viable Comment
|
||||
|
||||
At minimum, a working comment requires:
|
||||
1. `comments.xml` with the `w:comment` element
|
||||
2. `document.xml` with range markers and reference
|
||||
3. Relationship in `document.xml.rels`
|
||||
4. Content type in `[Content_Types].xml`
|
||||
|
||||
The extended files (`commentsExtended`, `commentsIds`, `commentsExtensible`) are optional but recommended for full compatibility with modern Word.
|
||||
@@ -0,0 +1,829 @@
|
||||
# GOOD vs BAD Document Design — Concrete OpenXML Examples
|
||||
|
||||
A side-by-side reference showing common design mistakes and their fixes, with exact OpenXML parameter values. Use this to develop an intuitive sense of what makes a document look professional versus amateur.
|
||||
|
||||
Format: Each comparison shows the **BAD** version first (the mistake), then the **GOOD** version (the fix), with OpenXML markup and a short explanation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Font Size Disasters
|
||||
|
||||
### 1a. No Hierarchy — Everything the Same Size
|
||||
|
||||
**BAD: Body=12pt, H1=12pt bold**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ INTRODUCTION │ ← 12pt bold... same visual weight
|
||||
│ This is the body text of the │ ← 12pt regular
|
||||
│ report. It discusses findings │
|
||||
│ from the quarterly review. │
|
||||
│ METHODOLOGY │ ← Where does the section start?
|
||||
│ We collected data from three │
|
||||
│ sources across the enterprise. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<!-- H1: bold but same size as body — no visual separation -->
|
||||
<w:rPr><w:b/><w:sz w:val="24"/></w:rPr>
|
||||
<!-- Body -->
|
||||
<w:rPr><w:sz w:val="24"/></w:rPr>
|
||||
```
|
||||
|
||||
**GOOD: Modular scale — body=11pt, H3=13pt, H2=16pt, H1=20pt**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ │
|
||||
│ Introduction │ ← 20pt, clearly a title
|
||||
│ │
|
||||
│ This is the body text of the │ ← 11pt, comfortable reading size
|
||||
│ report. It discusses findings │
|
||||
│ from the quarterly review. │
|
||||
│ │
|
||||
│ Methodology │ ← 20pt, section break is obvious
|
||||
│ │
|
||||
│ We collected data from three │
|
||||
│ sources across the enterprise. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<!-- H1: 20pt = w:sz 40 -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="40"/></w:rPr>
|
||||
<!-- H2: 16pt = w:sz 32 -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="32"/></w:rPr>
|
||||
<!-- H3: 13pt = w:sz 26, bold -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:b/><w:sz w:val="26"/></w:rPr>
|
||||
<!-- Body: 11pt = w:sz 22 -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
|
||||
```
|
||||
**Why better:** A clear size progression (ratio ~1.25x per step) lets readers instantly identify structure without reading a word.
|
||||
|
||||
---
|
||||
|
||||
### 1b. Too Much Contrast — Children's Book Look
|
||||
|
||||
**BAD: H1=28pt with body=10pt (ratio 2.8x)**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ │
|
||||
│ QUARTERLY REPORT │ ← 28pt, dominates the page
|
||||
│ │
|
||||
│ This is body text set very small │ ← 10pt, straining to read
|
||||
│ and the contrast with the title │
|
||||
│ makes it feel like a poster. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:rPr><w:b/><w:sz w:val="56"/></w:rPr> <!-- 28pt heading -->
|
||||
<w:rPr><w:sz w:val="20"/></w:rPr> <!-- 10pt body -->
|
||||
```
|
||||
|
||||
**GOOD: H1=20pt with body=11pt (ratio ~1.8x)**
|
||||
```xml
|
||||
<w:rPr><w:sz w:val="40"/></w:rPr> <!-- 20pt heading -->
|
||||
<w:rPr><w:sz w:val="22"/></w:rPr> <!-- 11pt body -->
|
||||
```
|
||||
**Why better:** A heading-to-body ratio between 1.5x and 2.0x reads as "structured" rather than "shouting."
|
||||
|
||||
---
|
||||
|
||||
## 2. Spacing Crimes
|
||||
|
||||
### 2a. Wall of Text — No Paragraph or Line Spacing
|
||||
|
||||
**BAD: Single line spacing, 0pt between paragraphs**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│The findings indicate a strong │
|
||||
│correlation between training hours│
|
||||
│and performance metrics. │
|
||||
│Further analysis revealed that │ ← No gap — where does the new
|
||||
│departments with higher budgets │ paragraph start?
|
||||
│achieved better outcomes in all │
|
||||
│measured categories. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:spacing w:line="240" w:lineRule="auto"/> <!-- 1.0 spacing (240/240) -->
|
||||
<w:spacing w:after="0"/> <!-- no paragraph gap -->
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
**GOOD: 1.15x line spacing, 8pt after each paragraph**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│The findings indicate a strong │
|
||||
│correlation between training │ ← Slightly more air between lines
|
||||
│hours and performance metrics. │
|
||||
│ │ ← 8pt gap signals new paragraph
|
||||
│Further analysis revealed that │
|
||||
│departments with higher budgets │
|
||||
│achieved better outcomes in all │
|
||||
│measured categories. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:spacing w:line="276" w:lineRule="auto"/> <!-- 1.15x (276/240) -->
|
||||
<w:spacing w:after="160"/> <!-- 8pt = 160 twips -->
|
||||
</w:pPr>
|
||||
```
|
||||
**Why better:** Line spacing gives each line room to breathe; paragraph spacing separates ideas without wasting a full blank line.
|
||||
|
||||
---
|
||||
|
||||
### 2b. Floating Headings — Same Space Above and Below
|
||||
|
||||
**BAD: 12pt before and 12pt after heading**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ ...end of previous section. │
|
||||
│ │ ← 12pt gap
|
||||
│ Section Two │ ← Heading floats in the middle
|
||||
│ │ ← 12pt gap
|
||||
│ Start of section two content. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:spacing w:before="240" w:after="240"/> <!-- 12pt both sides -->
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
**GOOD: 24pt before, 8pt after heading**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ ...end of previous section. │
|
||||
│ │
|
||||
│ │ ← 24pt gap — clear section break
|
||||
│ Section Two │ ← Heading is close to its content
|
||||
│ │ ← 8pt gap
|
||||
│ Start of section two content. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:spacing w:before="480" w:after="160"/> <!-- 24pt before, 8pt after -->
|
||||
</w:pPr>
|
||||
```
|
||||
**Why better:** Proximity principle: a heading belongs to the text that follows it, so more space above and less space below anchors it to its content.
|
||||
|
||||
---
|
||||
|
||||
### 2c. Wasteful Gaps — Huge Spacing Everywhere
|
||||
|
||||
**BAD: 24pt after every paragraph, including body text**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ First paragraph of text here. │
|
||||
│ │
|
||||
│ │ ← 24pt gap after every paragraph
|
||||
│ │
|
||||
│ Second paragraph of text here. │
|
||||
│ │
|
||||
│ │
|
||||
│ │
|
||||
│ Third paragraph. │ ← Document looks mostly white space
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:spacing w:after="480"/> <!-- 24pt = 480 twips after every paragraph -->
|
||||
```
|
||||
|
||||
**GOOD: Proportional spacing — body=8pt, H2=6pt after, H1=10pt after**
|
||||
```xml
|
||||
<!-- Body paragraph -->
|
||||
<w:spacing w:after="160"/> <!-- 8pt after body -->
|
||||
<!-- H1 -->
|
||||
<w:spacing w:before="480" w:after="200"/> <!-- 24pt before, 10pt after -->
|
||||
<!-- H2 -->
|
||||
<w:spacing w:before="320" w:after="120"/> <!-- 16pt before, 6pt after -->
|
||||
```
|
||||
**Why better:** Spacing should vary by element role, creating a visual rhythm rather than uniform gaps.
|
||||
|
||||
---
|
||||
|
||||
## 3. Margin Mistakes
|
||||
|
||||
### 3a. Cramped Margins — Text Running to the Edge
|
||||
|
||||
**BAD: 0.5in margins all around**
|
||||
```
|
||||
┌────────────────────────────────────────────────┐
|
||||
│Text starts almost at the paper edge and runs │
|
||||
│all the way across making extremely long lines │
|
||||
│that are hard to track from end back to start. │
|
||||
│The eye loses its place on every line return. │
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pgMar w:top="720" w:right="720" w:bottom="720" w:left="720"/>
|
||||
<!-- 720 twips = 0.5in — line length ~7.5in on letter paper -->
|
||||
```
|
||||
|
||||
**GOOD: 1in margins (standard)**
|
||||
```xml
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
|
||||
<!-- 1440 twips = 1.0in — line length ~6.5in, ideal for 11pt body -->
|
||||
```
|
||||
**Why better:** Optimal line length is 60-75 characters. At 11pt Calibri, 6.5in width achieves roughly 70 characters per line.
|
||||
|
||||
---
|
||||
|
||||
### 3b. Over-Padded Margins — Looks Like the Content is Hiding
|
||||
|
||||
**BAD: 2in margins on a short document**
|
||||
```xml
|
||||
<w:pgMar w:top="2880" w:right="2880" w:bottom="2880" w:left="2880"/>
|
||||
<!-- 2880 twips = 2.0in — only 4.5in of text width, looks padded -->
|
||||
```
|
||||
|
||||
**GOOD: 1in standard, or 1.25in for formal documents**
|
||||
```xml
|
||||
<!-- Standard -->
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
|
||||
<!-- Formal / bound documents with gutter -->
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1800" w:gutter="0"/>
|
||||
<!-- 1800 twips = 1.25in left for binding margin -->
|
||||
```
|
||||
**Why better:** Margins should frame the content, not overwhelm it. 1-1.25in works for virtually all business and academic documents.
|
||||
|
||||
---
|
||||
|
||||
## 4. Table Ugliness
|
||||
|
||||
### 4a. Prison Grid — Full Borders on Every Cell
|
||||
|
||||
**BAD: Every cell with 1pt borders on all four sides**
|
||||
```
|
||||
┌───────┬───────┬───────┬───────┐
|
||||
│ Name │ Dept │ Score │ Grade │
|
||||
├───────┼───────┼───────┼───────┤
|
||||
│ Alice │ Eng │ 92 │ A │
|
||||
├───────┼───────┼───────┼───────┤
|
||||
│ Bob │ Sales │ 85 │ B │
|
||||
├───────┼───────┼───────┼───────┤
|
||||
│ Carol │ Eng │ 78 │ C+ │
|
||||
└───────┴───────┴───────┴───────┘
|
||||
```
|
||||
```xml
|
||||
<w:tcBorders>
|
||||
<w:top w:val="single" w:sz="4" w:color="000000"/>
|
||||
<w:left w:val="single" w:sz="4" w:color="000000"/>
|
||||
<w:bottom w:val="single" w:sz="4" w:color="000000"/>
|
||||
<w:right w:val="single" w:sz="4" w:color="000000"/>
|
||||
</w:tcBorders>
|
||||
```
|
||||
|
||||
**GOOD: Three-line table (三线表) — top thick, header-bottom medium, table-bottom thick**
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ← 1.5pt top border
|
||||
Name Dept Score Grade
|
||||
────────────────────────────────── ← 0.75pt header separator
|
||||
Alice Eng 92 A
|
||||
Bob Sales 85 B
|
||||
Carol Eng 78 C+
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ← 1.5pt bottom border
|
||||
```
|
||||
```xml
|
||||
<!-- Top border of header row cells -->
|
||||
<w:top w:val="single" w:sz="12" w:color="000000"/> <!-- 1.5pt -->
|
||||
<w:left w:val="nil"/><w:right w:val="nil"/>
|
||||
<w:bottom w:val="single" w:sz="6" w:color="000000"/> <!-- 0.75pt -->
|
||||
|
||||
<!-- Data row cells: no left/right/top borders -->
|
||||
<w:top w:val="nil"/><w:left w:val="nil"/><w:right w:val="nil"/>
|
||||
<w:bottom w:val="nil"/>
|
||||
|
||||
<!-- Last row bottom border -->
|
||||
<w:bottom w:val="single" w:sz="12" w:color="000000"/> <!-- 1.5pt -->
|
||||
```
|
||||
**Why better:** Removing inner borders lets the eye scan data freely. Three lines provide structure without visual clutter.
|
||||
|
||||
---
|
||||
|
||||
### 4b. Text Touching Borders — No Cell Padding
|
||||
|
||||
**BAD: Zero cell margins**
|
||||
```
|
||||
┌──────────┬──────────┐
|
||||
│Name │Department│ ← Text cramped against borders
|
||||
├──────────┼──────────┤
|
||||
│Alice │Engineering│
|
||||
└──────────┴──────────┘
|
||||
```
|
||||
```xml
|
||||
<w:tcMar>
|
||||
<w:top w:w="0" w:type="dxa"/>
|
||||
<w:start w:w="0" w:type="dxa"/>
|
||||
<w:bottom w:w="0" w:type="dxa"/>
|
||||
<w:end w:w="0" w:type="dxa"/>
|
||||
</w:tcMar>
|
||||
```
|
||||
|
||||
**GOOD: 0.08in vertical, 0.12in horizontal padding**
|
||||
```xml
|
||||
<w:tcMar>
|
||||
<w:top w:w="115" w:type="dxa"/> <!-- ~0.08in = 115 twips -->
|
||||
<w:start w:w="173" w:type="dxa"/> <!-- ~0.12in = 173 twips -->
|
||||
<w:bottom w:w="115" w:type="dxa"/>
|
||||
<w:end w:w="173" w:type="dxa"/>
|
||||
</w:tcMar>
|
||||
```
|
||||
**Why better:** Padding gives text breathing room inside cells, making every value easier to read.
|
||||
|
||||
---
|
||||
|
||||
### 4c. Invisible Headers — Header Row Same Style as Data
|
||||
|
||||
**BAD: Header row indistinguishable from data**
|
||||
```xml
|
||||
<!-- Header cell run properties — identical to data -->
|
||||
<w:rPr><w:sz w:val="22"/></w:rPr>
|
||||
```
|
||||
|
||||
**GOOD: Bold header text, subtle background fill, bottom border**
|
||||
```xml
|
||||
<!-- Header cell run properties -->
|
||||
<w:rPr><w:b/><w:sz w:val="22"/><w:color w:val="333333"/></w:rPr>
|
||||
|
||||
<!-- Header cell shading -->
|
||||
<w:tcPr>
|
||||
<w:shd w:val="clear" w:color="auto" w:fill="F2F2F2"/> <!-- light gray bg -->
|
||||
<w:tcBorders>
|
||||
<w:bottom w:val="single" w:sz="8" w:color="666666"/> <!-- 1pt separator -->
|
||||
</w:tcBorders>
|
||||
</w:tcPr>
|
||||
|
||||
<!-- Mark row as header (repeats on page break) -->
|
||||
<w:trPr><w:tblHeader/></w:trPr>
|
||||
```
|
||||
**Why better:** Distinct header styling lets readers instantly locate column meanings, especially in long tables that span pages. The `w:tblHeader` element ensures the header row repeats on every page.
|
||||
|
||||
---
|
||||
|
||||
## 5. Font Pairing Failures
|
||||
|
||||
### 5a. Visual Chaos — Too Many Fonts
|
||||
|
||||
**BAD: 4+ fonts in one document**
|
||||
```xml
|
||||
<!-- H1 in Impact -->
|
||||
<w:rPr><w:rFonts w:ascii="Impact"/><w:sz w:val="40"/></w:rPr>
|
||||
<!-- H2 in Georgia -->
|
||||
<w:rPr><w:rFonts w:ascii="Georgia"/><w:sz w:val="32"/></w:rPr>
|
||||
<!-- Body in Verdana -->
|
||||
<w:rPr><w:rFonts w:ascii="Verdana"/><w:sz w:val="22"/></w:rPr>
|
||||
<!-- Captions in Courier New -->
|
||||
<w:rPr><w:rFonts w:ascii="Courier New"/><w:sz w:val="18"/></w:rPr>
|
||||
```
|
||||
|
||||
**GOOD: One font family with weight variation, or two complementary families**
|
||||
```xml
|
||||
<!-- H1: Calibri Light (thin weight of Calibri family) -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="40"/></w:rPr>
|
||||
<!-- H2: Calibri Light -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="32"/></w:rPr>
|
||||
<!-- Body: Calibri (regular weight) -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
|
||||
<!-- Captions: Calibri -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="18"/></w:rPr>
|
||||
```
|
||||
**Why better:** Limiting to one or two font families creates visual coherence. Vary by size and weight, not by font.
|
||||
|
||||
---
|
||||
|
||||
### 5b. Mismatched Personality — Comic Sans Meets Times New Roman
|
||||
|
||||
**BAD:**
|
||||
```xml
|
||||
<w:rPr><w:rFonts w:ascii="Comic Sans MS"/><w:sz w:val="36"/></w:rPr> <!-- heading -->
|
||||
<w:rPr><w:rFonts w:ascii="Times New Roman"/><w:sz w:val="24"/></w:rPr> <!-- body -->
|
||||
```
|
||||
|
||||
**GOOD: Fonts with compatible character**
|
||||
```xml
|
||||
<w:rPr><w:rFonts w:ascii="Calibri Light"/><w:sz w:val="36"/></w:rPr> <!-- heading -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr> <!-- body -->
|
||||
```
|
||||
**Why better:** Paired fonts should share a similar level of formality and geometric character. Comic Sans is playful/informal; Times New Roman is formal/traditional. They clash.
|
||||
|
||||
---
|
||||
|
||||
### 5c. Everything Bold — Nothing Stands Out
|
||||
|
||||
**BAD: Bold on body, headings, captions, everything**
|
||||
```xml
|
||||
<w:rPr><w:b/><w:sz w:val="40"/></w:rPr> <!-- heading: bold -->
|
||||
<w:rPr><w:b/><w:sz w:val="22"/></w:rPr> <!-- body: also bold -->
|
||||
<w:rPr><w:b/><w:sz w:val="18"/></w:rPr> <!-- caption: still bold -->
|
||||
```
|
||||
|
||||
**GOOD: Bold reserved for headings and key terms only**
|
||||
```xml
|
||||
<w:rPr><w:b/><w:sz w:val="40"/></w:rPr> <!-- H1: bold -->
|
||||
<w:rPr><w:sz w:val="32"/></w:rPr> <!-- H2: size alone is enough -->
|
||||
<w:rPr><w:sz w:val="22"/></w:rPr> <!-- body: regular weight -->
|
||||
<w:rPr><w:b/><w:sz w:val="22"/></w:rPr> <!-- key term inline: bold -->
|
||||
<w:rPr><w:sz w:val="18"/></w:rPr> <!-- caption: regular, small -->
|
||||
```
|
||||
**Why better:** When everything is emphasized, nothing is emphasized. Bold should be a signal, not a default.
|
||||
|
||||
---
|
||||
|
||||
## 6. Color Abuse
|
||||
|
||||
### 6a. Rainbow Headings
|
||||
|
||||
**BAD: Each heading level a different bright color**
|
||||
```xml
|
||||
<w:rPr><w:color w:val="FF0000"/><w:sz w:val="40"/></w:rPr> <!-- H1: red -->
|
||||
<w:rPr><w:color w:val="00AA00"/><w:sz w:val="32"/></w:rPr> <!-- H2: green -->
|
||||
<w:rPr><w:color w:val="0000FF"/><w:sz w:val="26"/></w:rPr> <!-- H3: blue -->
|
||||
```
|
||||
|
||||
**GOOD: Single accent color for headings, black or dark gray for body**
|
||||
```xml
|
||||
<!-- All headings use the same muted accent -->
|
||||
<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="40"/></w:rPr> <!-- H1: dark blue -->
|
||||
<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="32"/></w:rPr> <!-- H2: same blue -->
|
||||
<w:rPr><w:color w:val="1F4E79"/><w:sz w:val="26"/></w:rPr> <!-- H3: same blue -->
|
||||
<!-- Body in near-black -->
|
||||
<w:rPr><w:color w:val="333333"/><w:sz w:val="22"/></w:rPr>
|
||||
```
|
||||
**Why better:** A single accent color establishes brand consistency. Multiple bright colors compete for attention and look unprofessional.
|
||||
|
||||
---
|
||||
|
||||
### 6b. Low Contrast — Light Gray on White
|
||||
|
||||
**BAD: #CCCCCC text on white background**
|
||||
```xml
|
||||
<w:rPr><w:color w:val="CCCCCC"/></w:rPr>
|
||||
<!-- Contrast ratio: ~1.6:1 — fails WCAG AA (minimum 4.5:1) -->
|
||||
```
|
||||
|
||||
**GOOD: #333333 text on white**
|
||||
```xml
|
||||
<w:rPr><w:color w:val="333333"/></w:rPr>
|
||||
<!-- Contrast ratio: ~12:1 — passes WCAG AAA -->
|
||||
```
|
||||
**Why better:** Sufficient contrast is not just an accessibility requirement; it makes text physically easier to read for everyone, especially in printed documents.
|
||||
|
||||
---
|
||||
|
||||
### 6c. Bright Body Text
|
||||
|
||||
**BAD: Body text in a saturated color**
|
||||
```xml
|
||||
<w:rPr><w:color w:val="0066FF"/><w:sz w:val="22"/></w:rPr> <!-- blue body text -->
|
||||
```
|
||||
|
||||
**GOOD: Color reserved for headings and inline accents only**
|
||||
```xml
|
||||
<!-- Body: neutral dark -->
|
||||
<w:rPr><w:color w:val="333333"/><w:sz w:val="22"/></w:rPr>
|
||||
<!-- Hyperlink: color is functional here -->
|
||||
<w:rPr><w:color w:val="0563C1"/><w:u w:val="single"/></w:rPr>
|
||||
```
|
||||
**Why better:** Colored body text causes eye fatigue over long reading. Reserve color for elements that need to attract attention (headings, links, warnings).
|
||||
|
||||
---
|
||||
|
||||
## 7. List Formatting Issues
|
||||
|
||||
### 7a. Bullet at the Margin — No Indent
|
||||
|
||||
**BAD: List items start at the left margin**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│Here is a paragraph of text. │
|
||||
│• First item │ ← Bullet at margin, no indent
|
||||
│• Second item │
|
||||
│• Third item │
|
||||
│Next paragraph continues here. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:ind w:left="0" w:hanging="0"/>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
**GOOD: 0.25in left indent with hanging indent for the bullet**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│Here is a paragraph of text. │
|
||||
│ • First item │ ← Indented, clearly a list
|
||||
│ • Second item │
|
||||
│ • Third item │
|
||||
│Next paragraph continues here. │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:ind w:left="360" w:hanging="360"/> <!-- 0.25in = 360 twips -->
|
||||
<w:numPr>
|
||||
<w:ilvl w:val="0"/>
|
||||
<w:numId w:val="1"/>
|
||||
</w:numPr>
|
||||
</w:pPr>
|
||||
```
|
||||
For nested lists, increment by 360 twips per level:
|
||||
```xml
|
||||
<!-- Level 1 -->
|
||||
<w:ind w:left="720" w:hanging="360"/> <!-- 0.5in left -->
|
||||
<!-- Level 2 -->
|
||||
<w:ind w:left="1080" w:hanging="360"/> <!-- 0.75in left -->
|
||||
```
|
||||
**Why better:** Indentation visually separates lists from body text and makes nesting levels clear.
|
||||
|
||||
---
|
||||
|
||||
### 7b. List Items with Full Paragraph Spacing
|
||||
|
||||
**BAD: List items have the same 8-10pt spacing as body paragraphs**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ • First item │
|
||||
│ │ ← 10pt gap — looks like separate
|
||||
│ • Second item │ paragraphs, not a list
|
||||
│ │
|
||||
│ • Third item │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:spacing w:after="200"/> <!-- 10pt after each list item -->
|
||||
```
|
||||
|
||||
**GOOD: Tight spacing between list items (2-4pt)**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ • First item │
|
||||
│ • Second item │ ← 2pt gap — cohesive list
|
||||
│ • Third item │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<w:spacing w:after="40" w:line="276" w:lineRule="auto"/> <!-- 2pt after -->
|
||||
<!-- Or 4pt: -->
|
||||
<w:spacing w:after="80"/>
|
||||
```
|
||||
**Why better:** Tight spacing groups list items as a single unit, matching how readers expect a list to behave.
|
||||
|
||||
---
|
||||
|
||||
## 8. Header/Footer Problems
|
||||
|
||||
### 8a. Header Text Too Large — Competes with Body
|
||||
|
||||
**BAD: Header in 12pt, same as body**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ Quarterly Report - Q3 2025 │ ← 12pt header, same as body
|
||||
│──────────────────────────────────│
|
||||
│ Introduction │
|
||||
│ This is the body text... │ ← 12pt body — header distracts
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<!-- Header paragraph -->
|
||||
<w:rPr><w:sz w:val="24"/></w:rPr> <!-- 12pt, same as body -->
|
||||
```
|
||||
|
||||
**GOOD: Header in 9pt, gray color, subtle**
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ Quarterly Report - Q3 2025 │ ← 9pt, gray — present but quiet
|
||||
│──────────────────────────────────│
|
||||
│ Introduction │
|
||||
│ This is the body text... │ ← Body stands out as primary
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
```xml
|
||||
<!-- Header paragraph -->
|
||||
<w:rPr>
|
||||
<w:sz w:val="18"/> <!-- 9pt -->
|
||||
<w:color w:val="808080"/> <!-- medium gray -->
|
||||
</w:rPr>
|
||||
<w:pPr>
|
||||
<w:pBdr>
|
||||
<w:bottom w:val="single" w:sz="4" w:color="D9D9D9"/> <!-- subtle separator -->
|
||||
</w:pBdr>
|
||||
</w:pPr>
|
||||
```
|
||||
**Why better:** Headers are reference information, not primary content. They should be legible but visually subordinate.
|
||||
|
||||
---
|
||||
|
||||
### 8b. No Page Numbers on a Long Document
|
||||
|
||||
**BAD: 20-page document with no page numbers**
|
||||
```xml
|
||||
<!-- Footer section: empty or missing -->
|
||||
```
|
||||
|
||||
**GOOD: Page numbers in footer, right-aligned or centered**
|
||||
```xml
|
||||
<!-- Footer paragraph with page number field -->
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:jc w:val="center"/>
|
||||
<w:rPr><w:sz w:val="18"/><w:color w:val="808080"/></w:rPr>
|
||||
</w:pPr>
|
||||
<w:r>
|
||||
<w:rPr><w:sz w:val="18"/><w:color w:val="808080"/></w:rPr>
|
||||
<w:fldChar w:fldCharType="begin"/>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:instrText> PAGE </w:instrText>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="separate"/>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:t>1</w:t>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="end"/>
|
||||
</w:r>
|
||||
</w:p>
|
||||
```
|
||||
**Why better:** Page numbers are essential for navigation in any document over ~3 pages. Readers need to reference specific pages, and printed documents need an ordering mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 9. CJK-Specific Mistakes
|
||||
|
||||
### 9a. Using Italic for Chinese Emphasis
|
||||
|
||||
**BAD: Italic applied to Chinese text**
|
||||
```xml
|
||||
<w:rPr>
|
||||
<w:i/>
|
||||
<w:rFonts w:eastAsia="SimSun"/>
|
||||
<w:sz w:val="24"/>
|
||||
</w:rPr>
|
||||
```
|
||||
CJK glyphs have no true italic form. The renderer applies a synthetic slant that looks broken and ugly — characters appear to lean awkwardly.
|
||||
|
||||
**GOOD: Use bold or emphasis dots (着重号) for Chinese emphasis**
|
||||
```xml
|
||||
<!-- Option A: Bold emphasis -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:rFonts w:eastAsia="SimHei"/> <!-- Switch to bold-capable font -->
|
||||
<w:sz w:val="24"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- Option B: Emphasis marks (dots under characters) -->
|
||||
<w:rPr>
|
||||
<w:em w:val="dot"/>
|
||||
<w:rFonts w:eastAsia="SimSun"/>
|
||||
<w:sz w:val="24"/>
|
||||
</w:rPr>
|
||||
```
|
||||
**Why better:** Chinese typography has its own emphasis traditions. Bold and emphasis dots are native CJK conventions; italic is a Latin-script concept that does not translate.
|
||||
|
||||
---
|
||||
|
||||
### 9b. Latin Font for Chinese Characters
|
||||
|
||||
**BAD: Only ASCII font set, no EastAsia font specified**
|
||||
```xml
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Arial"/> <!-- No eastAsia attribute -->
|
||||
<w:sz w:val="24"/>
|
||||
</w:rPr>
|
||||
<!-- Word falls back to a random font. Chinese characters may render
|
||||
with wrong metrics, inconsistent stroke widths, or missing glyphs. -->
|
||||
```
|
||||
|
||||
**GOOD: Explicit EastAsia font alongside ASCII font**
|
||||
```xml
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="Microsoft YaHei"/>
|
||||
<w:sz w:val="22"/>
|
||||
</w:rPr>
|
||||
```
|
||||
For formal/academic Chinese documents:
|
||||
```xml
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman"
|
||||
w:eastAsia="SimSun"/>
|
||||
<w:sz w:val="24"/> <!-- 小四 12pt -->
|
||||
</w:rPr>
|
||||
```
|
||||
**Why better:** Setting `w:eastAsia` ensures Chinese characters render in a font designed for CJK glyphs, with correct stroke widths, spacing, and metrics.
|
||||
|
||||
---
|
||||
|
||||
### 9c. English Line Spacing for Dense CJK Text
|
||||
|
||||
**BAD: 1.15x line spacing for Chinese body text**
|
||||
```xml
|
||||
<w:spacing w:line="276" w:lineRule="auto"/> <!-- 1.15x — too tight for CJK -->
|
||||
```
|
||||
CJK characters are taller and denser than Latin letters. At 1.15x, lines of Chinese text feel cramped and hard to read.
|
||||
|
||||
**GOOD: 1.5x line spacing or fixed 28pt for CJK body at 12pt (小四)**
|
||||
```xml
|
||||
<!-- Option A: 1.5x proportional -->
|
||||
<w:spacing w:line="360" w:lineRule="auto"/> <!-- 360/240 = 1.5x -->
|
||||
|
||||
<!-- Option B: Fixed 28pt (standard for 小四/12pt CJK body) -->
|
||||
<w:spacing w:line="560" w:lineRule="exact"/> <!-- 28pt = 560 twips -->
|
||||
```
|
||||
For 公文 (government documents) at 三号/16pt body:
|
||||
```xml
|
||||
<w:spacing w:line="580" w:lineRule="exact"/> <!-- 29pt fixed line spacing -->
|
||||
```
|
||||
**Why better:** CJK characters occupy a full em square with no ascenders/descenders providing natural gaps. Extra line spacing compensates, improving readability of dense text blocks.
|
||||
|
||||
---
|
||||
|
||||
## 10. Overall Document Feel
|
||||
|
||||
### Student Homework vs Professional Document
|
||||
|
||||
**BAD: "Student homework" — every setting is Word's default, no intentional choices**
|
||||
```xml
|
||||
<!-- Default everything: Calibri 11pt, no heading styles, 1.08 spacing -->
|
||||
<w:rPr><w:rFonts w:ascii="Calibri"/><w:sz w:val="22"/></w:rPr>
|
||||
<w:pPr><w:spacing w:after="160" w:line="259" w:lineRule="auto"/></w:pPr>
|
||||
<!-- Headings: just bold body text, no style applied -->
|
||||
<w:rPr><w:b/><w:sz w:val="22"/></w:rPr>
|
||||
<!-- No section breaks, no headers/footers, no page numbers -->
|
||||
<!-- Tables with default full grid borders -->
|
||||
<!-- No intentional color or spacing variations -->
|
||||
```
|
||||
|
||||
**GOOD: Intentional design at every level**
|
||||
```xml
|
||||
<!-- Theme fonts defined -->
|
||||
<w:rFonts w:asciiTheme="minorHAnsi" w:hAnsiTheme="minorHAnsi"/>
|
||||
|
||||
<!-- H1: Calibri Light 20pt, dark blue, generous spacing -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Heading1"/>
|
||||
<w:spacing w:before="480" w:after="200"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light"/>
|
||||
<w:color w:val="1F4E79"/>
|
||||
<w:sz w:val="40"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- H2: Calibri Light 16pt, same blue -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Heading2"/>
|
||||
<w:spacing w:before="320" w:after="120"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri Light"/>
|
||||
<w:color w:val="1F4E79"/>
|
||||
<w:sz w:val="32"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- Body: Calibri 11pt, dark gray, 1.15 spacing, 8pt after -->
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri"/>
|
||||
<w:color w:val="333333"/>
|
||||
<w:sz w:val="22"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- Tables: three-line style, padded cells, repeated headers -->
|
||||
<!-- Headers/footers: 9pt gray with page numbers -->
|
||||
<!-- Margins: 1in all around -->
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/>
|
||||
```
|
||||
**Why better:** Professional documents result from deliberate, consistent choices across all design dimensions. Each element reinforces the same visual language. The reader may not consciously notice good typography, but they feel the difference in credibility and readability.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Safe Defaults
|
||||
|
||||
A cheat sheet of values that produce a professional result for most Western business documents:
|
||||
|
||||
| Element | Value | OpenXML |
|
||||
|---------|-------|---------|
|
||||
| Body font | Calibri 11pt | `w:sz="22"` |
|
||||
| H1 | Calibri Light 20pt | `w:sz="40"` |
|
||||
| H2 | Calibri Light 16pt | `w:sz="32"` |
|
||||
| H3 | Calibri 13pt bold | `w:sz="26"`, `w:b` |
|
||||
| Body color | #333333 | `w:color="333333"` |
|
||||
| Heading color | #1F4E79 | `w:color="1F4E79"` |
|
||||
| Line spacing | 1.15x | `w:line="276" w:lineRule="auto"` |
|
||||
| Para spacing after | 8pt | `w:after="160"` |
|
||||
| H1 spacing | 24pt before, 10pt after | `w:before="480" w:after="200"` |
|
||||
| H2 spacing | 16pt before, 6pt after | `w:before="320" w:after="120"` |
|
||||
| Margins | 1in all around | `w:pgMar` all `"1440"` |
|
||||
| Table cell padding | 0.08in / 0.12in | `w:w="115"` / `w:w="173"` |
|
||||
| Header/footer size | 9pt gray | `w:sz="18" w:color="808080"` |
|
||||
| List indent | 0.25in per level | `w:left="360" w:hanging="360"` |
|
||||
| List item spacing | 2pt after | `w:after="40"` |
|
||||
|
||||
For CJK documents, adjust: body font to SimSun/YaHei, line spacing to 1.5x (`w:line="360"`), and set `w:eastAsia` on all `w:rFonts`.
|
||||
@@ -0,0 +1,819 @@
|
||||
# Design Principles for Document Typography
|
||||
|
||||
WHY certain typographic choices look good -- the perceptual and psychological
|
||||
reasons behind professional document design. Use this to make judgment calls
|
||||
when exact specs are not provided.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [White Space & Breathing Room](#1-white-space--breathing-room)
|
||||
2. [Contrast & Scale](#2-contrast--scale)
|
||||
3. [Proximity & Grouping](#3-proximity--grouping)
|
||||
4. [Alignment & Grid](#4-alignment--grid)
|
||||
5. [Repetition & Consistency](#5-repetition--consistency)
|
||||
6. [Visual Hierarchy & Flow](#6-visual-hierarchy--flow)
|
||||
|
||||
---
|
||||
|
||||
## 1. White Space & Breathing Room
|
||||
|
||||
### Why It Works
|
||||
|
||||
The human eye does not read continuously. It jumps in saccades, fixating on
|
||||
small clusters of words. White space provides landing zones for these fixations
|
||||
and gives the reader's peripheral vision a "frame" that makes each text block
|
||||
feel manageable. When a page is packed to the edges, every glance returns more
|
||||
text than working memory can buffer, triggering fatigue and avoidance.
|
||||
|
||||
Research on content density consistently shows:
|
||||
|
||||
- **60-70% content coverage** feels comfortable and professional.
|
||||
- **80%+** starts to feel dense and bureaucratic.
|
||||
- **90%+** feels oppressive -- the reader unconsciously rushes or skips.
|
||||
- **Below 50%** feels wasteful or pretentious (unless intentional, like poetry).
|
||||
|
||||
Wider margins also carry cultural signals. Academic and luxury documents use
|
||||
generous margins (1.25-1.5 inches). Internal memos and drafts use narrower
|
||||
margins (0.75-1.0 inches). The margin width tells the reader how much care
|
||||
went into the document before they read a single word.
|
||||
|
||||
Line spacing has a direct physiological basis: the eye must track back to the
|
||||
start of the next line after each line break. If lines are too close, the eye
|
||||
"slips" to the wrong line. If too far apart, the eye loses its sense of
|
||||
continuity. The sweet spot is 120-145% of the font size.
|
||||
|
||||
**Rule of thumb: when in doubt, add more space, not less.**
|
||||
|
||||
### Good Example
|
||||
|
||||
```
|
||||
Margins: 1 inch (1440 twips) all sides for business documents.
|
||||
Line spacing: 1.15 (276 twips at 240 twips-per-line = 115%).
|
||||
Paragraph spacing after: 8pt (160 twips) between body paragraphs.
|
||||
```
|
||||
|
||||
```xml
|
||||
<!-- Page margins: 1 inch = 1440 twips on all sides -->
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
|
||||
w:header="720" w:footer="720" w:gutter="0"/>
|
||||
|
||||
<!-- Body paragraph: 1.15 line spacing, 8pt after -->
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
This produces a page where content occupies roughly 65% of the area. The
|
||||
reader sees clear top/bottom breathing room, and paragraphs are distinct
|
||||
without feeling disconnected.
|
||||
|
||||
```
|
||||
Page layout (good):
|
||||
+----------------------------------+
|
||||
| 1" margin |
|
||||
| +------------------------+ |
|
||||
| | Heading | |
|
||||
| | | |
|
||||
| | Body text here with | |
|
||||
| | comfortable spacing | |
|
||||
| | between lines. | |
|
||||
| | | | <- visible gap between paragraphs
|
||||
| | Another paragraph of | |
|
||||
| | body text follows. | |
|
||||
| | | |
|
||||
| +------------------------+ |
|
||||
| 1" margin |
|
||||
+----------------------------------+
|
||||
```
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- Cramped margins: 0.5 inch = 720 twips -->
|
||||
<w:pgMar w:top="720" w:right="720" w:bottom="720" w:left="720"
|
||||
w:header="360" w:footer="360" w:gutter="0"/>
|
||||
|
||||
<!-- No paragraph spacing, single line spacing -->
|
||||
<w:pPr>
|
||||
<w:spacing w:after="0" w:line="240" w:lineRule="auto"/>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
This fills ~85% of the page. Text runs edge-to-edge with no visual rest stops.
|
||||
The reader sees a wall of text.
|
||||
|
||||
```
|
||||
Page layout (bad):
|
||||
+----------------------------------+
|
||||
| Heading |
|
||||
| Body text crammed right up to |
|
||||
| the margins with no spacing |
|
||||
| between lines or paragraphs. |
|
||||
| Another paragraph starts here |
|
||||
| and the reader cannot tell where |
|
||||
| one idea ends and another begins |
|
||||
| because everything blurs into a |
|
||||
| single dense block of text. |
|
||||
+----------------------------------+
|
||||
```
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. Zoom out to 50% in your document viewer. If you cannot see clear "channels"
|
||||
of white between text blocks, the spacing is too tight.
|
||||
2. Print a test page. Hold it at arm's length. The text area should look like
|
||||
a rectangle floating in white, not filling the page.
|
||||
3. Check: is the line spacing value at least 264 (`w:line` for 1.1x) for body
|
||||
text? If it is 240 (single), it is too tight for anything over 10pt.
|
||||
|
||||
---
|
||||
|
||||
## 2. Contrast & Scale
|
||||
|
||||
### Why It Works
|
||||
|
||||
The brain processes visual hierarchy through relative difference, not absolute
|
||||
size. A 20pt heading above 11pt body text creates a clear "this is important"
|
||||
signal. But if every heading is 20pt and every sub-heading is 19pt, the brain
|
||||
cannot distinguish them -- they merge into the same level.
|
||||
|
||||
The key insight is **modular scale**: font sizes that grow by a consistent
|
||||
ratio. This mirrors natural proportions and feels harmonious for the same
|
||||
reason musical intervals do.
|
||||
|
||||
Common scales and their character:
|
||||
|
||||
| Ratio | Name | Character | Example progression (from 11pt) |
|
||||
|-------|----------------|---------------------------------|---------------------------------|
|
||||
| 1.200 | Minor third | Subtle, refined | 11 → 13.2 → 15.8 → 19.0 |
|
||||
| 1.250 | Major third | Balanced, professional | 11 → 13.75 → 17.2 → 21.5 |
|
||||
| 1.333 | Perfect fourth | Strong, authoritative | 11 → 14.7 → 19.5 → 26.0 |
|
||||
| 1.414 | Augmented 4th | Dramatic, presentation-style | 11 → 15.6 → 22.0 → 31.1 |
|
||||
|
||||
For most business documents, 1.25 (major third) works best:
|
||||
|
||||
```
|
||||
Body = 11pt (w:sz="22")
|
||||
H3 = 13pt (w:sz="26") -- 11 * 1.25 ≈ 13.75, round to 13
|
||||
H2 = 16pt (w:sz="32") -- 13 * 1.25 ≈ 16.25, round to 16
|
||||
H1 = 20pt (w:sz="40") -- 16 * 1.25 = 20
|
||||
```
|
||||
|
||||
Beyond size, **weight contrast** creates hierarchy without consuming vertical
|
||||
space. Regular (400) vs Bold (700) is visible at any size. Semi-bold (600) vs
|
||||
Regular is subtle and best avoided unless you also vary size or color.
|
||||
|
||||
**Color contrast** adds a third dimension. Dark blue headings (#1F3864) against
|
||||
softer dark gray body text (#333333) signals "heading" without needing a huge
|
||||
size jump. Pure black (#000000) body text is harsher than necessary on white
|
||||
backgrounds -- #333333 or #2D2D2D reduces glare without losing legibility.
|
||||
|
||||
### Good Example
|
||||
|
||||
```xml
|
||||
<!-- H1: 20pt, bold, dark navy -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="40"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- H2: 16pt, bold, dark navy -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="32"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- H3: 13pt, bold, dark navy -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="26"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- Body: 11pt, regular, dark gray -->
|
||||
<w:rPr>
|
||||
<w:sz w:val="22"/>
|
||||
<w:color w:val="333333"/>
|
||||
</w:rPr>
|
||||
```
|
||||
|
||||
```
|
||||
Visual hierarchy (good):
|
||||
|
||||
[████████████████████] <- H1: 20pt bold navy (clearly dominant)
|
||||
(generous space)
|
||||
[██████████████] <- H2: 16pt bold navy (distinct step down)
|
||||
(moderate space)
|
||||
[████████████] <- H3: 13pt bold navy (smaller but still bold)
|
||||
[░░░░░░░░░░░░░░░░░░░░░░] <- Body: 11pt regular gray
|
||||
[░░░░░░░░░░░░░░░░░░░░░░]
|
||||
[░░░░░░░░░░░░░░░░░░░░░░]
|
||||
```
|
||||
|
||||
Each level is visually distinct from its neighbors. You can identify the
|
||||
hierarchy even in peripheral vision.
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- H1: 14pt bold black -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="28"/>
|
||||
<w:color w:val="000000"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- H2: 13pt bold black -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="26"/>
|
||||
<w:color w:val="000000"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- H3: 12pt bold black -->
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="24"/>
|
||||
<w:color w:val="000000"/>
|
||||
</w:rPr>
|
||||
|
||||
<!-- Body: 12pt regular black -->
|
||||
<w:rPr>
|
||||
<w:sz w:val="24"/>
|
||||
<w:color w:val="000000"/>
|
||||
</w:rPr>
|
||||
```
|
||||
|
||||
Problems:
|
||||
- H3 (12pt bold) and body (12pt regular) differ only by weight -- too subtle.
|
||||
- H1 (14pt) to H2 (13pt) is a 1pt step -- invisible at reading distance.
|
||||
- Everything is pure black so color provides no differentiating signal.
|
||||
- The ratio between levels is ~1.07, far too flat.
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. **The squint test**: blur your eyes or step back from the screen. Can you
|
||||
count the number of heading levels? If two levels merge, their contrast
|
||||
is insufficient.
|
||||
2. **Ratio check**: divide each heading size by the next smaller size. If any
|
||||
ratio is below 1.15, the levels will look too similar.
|
||||
3. **Color check**: do headings look distinct from body text when you glance
|
||||
at the page? If everything is the same color, you are relying solely on
|
||||
size/weight, which limits your hierarchy to ~3 effective levels.
|
||||
|
||||
---
|
||||
|
||||
## 3. Proximity & Grouping
|
||||
|
||||
### Why It Works
|
||||
|
||||
The Gestalt principle of proximity: items that are close together are perceived
|
||||
as belonging to the same group. In document typography, this means a heading
|
||||
must be **closer to the content it introduces** than to the content above it.
|
||||
|
||||
If a heading sits equidistant between two paragraphs, it looks orphaned -- the
|
||||
reader's eye does not know if it belongs to the text above or below. The fix
|
||||
is asymmetric spacing: **large space before the heading, small space after**.
|
||||
|
||||
The recommended ratio is 2:1 or 3:1 (space-before : space-after).
|
||||
|
||||
This same principle applies to:
|
||||
- **List items**: spacing between items should be less than spacing between
|
||||
paragraphs. Items in a list are a group and should visually cluster.
|
||||
- **Captions**: a figure caption should be close to its figure, not floating
|
||||
in the middle between the figure and the next paragraph.
|
||||
- **Table titles**: the title sits close above the table, with more space
|
||||
separating the title from preceding text.
|
||||
|
||||
### Good Example
|
||||
|
||||
```xml
|
||||
<!-- H2: 18pt before, 6pt after (3:1 ratio) -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Heading2"/>
|
||||
<w:spacing w:before="360" w:after="120"/>
|
||||
</w:pPr>
|
||||
|
||||
<!-- Body paragraph: 0pt before, 8pt after -->
|
||||
<w:pPr>
|
||||
<w:spacing w:before="0" w:after="160"/>
|
||||
</w:pPr>
|
||||
|
||||
<!-- List item: 0pt before, 2pt after (tight grouping) -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="ListParagraph"/>
|
||||
<w:spacing w:before="0" w:after="40"/>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
```
|
||||
Proximity (good):
|
||||
|
||||
...end of previous section text.
|
||||
<- 18pt gap (w:before="360")
|
||||
## Section Heading
|
||||
<- 6pt gap (w:after="120")
|
||||
First paragraph of new section
|
||||
continues here with content.
|
||||
<- 8pt gap (w:after="160")
|
||||
Second paragraph follows.
|
||||
|
||||
The heading clearly "belongs to" the text below it.
|
||||
```
|
||||
|
||||
```
|
||||
List grouping (good):
|
||||
|
||||
Consider these factors:
|
||||
- First item <- 2pt gap between items
|
||||
- Second item <- items cluster as a group
|
||||
- Third item
|
||||
<- 8pt gap after list
|
||||
The next paragraph starts here.
|
||||
```
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- H2: 12pt before, 12pt after (1:1 ratio -- orphaned heading) -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Heading2"/>
|
||||
<w:spacing w:before="240" w:after="240"/>
|
||||
</w:pPr>
|
||||
|
||||
<!-- List item: same spacing as body (10pt after) -->
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="ListParagraph"/>
|
||||
<w:spacing w:before="0" w:after="200"/>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
```
|
||||
Proximity (bad):
|
||||
|
||||
...end of previous section text.
|
||||
<- 12pt gap
|
||||
## Section Heading
|
||||
<- 12pt gap (same!)
|
||||
First paragraph of new section.
|
||||
|
||||
The heading floats between sections. It is unclear what it belongs to.
|
||||
```
|
||||
|
||||
```
|
||||
List grouping (bad):
|
||||
|
||||
Consider these factors:
|
||||
<- 10pt gap
|
||||
- First item
|
||||
<- 10pt gap (same as paragraphs)
|
||||
- Second item
|
||||
<- 10pt gap
|
||||
- Third item
|
||||
<- 10pt gap
|
||||
Next paragraph.
|
||||
|
||||
The list does not feel like a group. Each item looks like a
|
||||
separate paragraph that happens to have a bullet.
|
||||
```
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. **Cover test**: cover the heading text. Looking only at the whitespace,
|
||||
can you tell which block of text the heading belongs to? If the gaps above
|
||||
and below are equal, the answer is "no."
|
||||
2. **Number check**: `w:before` on headings should be at least 2x `w:after`.
|
||||
Common good values: before=360 / after=120, or before=240 / after=80.
|
||||
3. **List check**: `w:after` on list items should be less than half of
|
||||
`w:after` on body paragraphs. If body uses 160, list items should use
|
||||
40-60.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alignment & Grid
|
||||
|
||||
### Why It Works
|
||||
|
||||
Alignment creates invisible lines that the eye follows down the page. When
|
||||
elements share the same left edge, the reader perceives order and intention.
|
||||
When elements are slightly misaligned (off by a few twips), the page looks
|
||||
sloppy even if the reader cannot consciously identify why.
|
||||
|
||||
**Left-align vs Justify:**
|
||||
|
||||
- **Left-aligned** (ragged right) is best for English and other Latin-script
|
||||
languages. The uneven right edge actually helps reading because each line
|
||||
has a unique silhouette, making it easier for the eye to find the next line.
|
||||
Justified text forces uneven word spacing that creates distracting "rivers"
|
||||
of white running vertically through paragraphs.
|
||||
|
||||
- **Justified** is best for CJK text. Chinese, Japanese, and Korean characters
|
||||
are monospaced by design -- each occupies the same cell in an invisible grid.
|
||||
Justification preserves this grid perfectly. Ragged right in CJK text breaks
|
||||
the grid and looks untidy.
|
||||
|
||||
**Indentation rule:** Use first-line indent OR paragraph spacing to separate
|
||||
paragraphs -- never both. They serve the same purpose (marking paragraph
|
||||
boundaries). Using both wastes space and creates visual stutter.
|
||||
|
||||
- Western convention: paragraph spacing (no indent) is more modern.
|
||||
- CJK convention: first-line indent of 2 characters is standard.
|
||||
- Academic convention: first-line indent of 0.5 inch is traditional.
|
||||
|
||||
### Good Example
|
||||
|
||||
```xml
|
||||
<!-- English body: left-aligned, paragraph spacing, no indent -->
|
||||
<w:pPr>
|
||||
<w:jc w:val="left"/>
|
||||
<w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
|
||||
<!-- No w:ind firstLine -->
|
||||
</w:pPr>
|
||||
|
||||
<!-- CJK body: justified, first-line indent 2 chars, no paragraph spacing -->
|
||||
<w:pPr>
|
||||
<w:jc w:val="both"/>
|
||||
<w:spacing w:after="0" w:line="360" w:lineRule="auto"/>
|
||||
<w:ind w:firstLineChars="200"/>
|
||||
</w:pPr>
|
||||
|
||||
<!-- Tab stops creating aligned columns -->
|
||||
<w:pPr>
|
||||
<w:tabs>
|
||||
<w:tab w:val="left" w:pos="2880"/> <!-- 2 inches -->
|
||||
<w:tab w:val="right" w:pos="9360"/> <!-- 6.5 inches (right margin) -->
|
||||
</w:tabs>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
```
|
||||
English paragraph separation (good -- spacing, no indent):
|
||||
|
||||
This is the first paragraph with some text
|
||||
that wraps to a second line naturally.
|
||||
|
||||
This is the second paragraph. The gap above
|
||||
clearly marks the boundary.
|
||||
|
||||
|
||||
CJK paragraph separation (good -- indent, no spacing):
|
||||
|
||||
第一段正文内容从这里开始，使用两个字符
|
||||
的首行缩进来标记段落边界。
|
||||
第二段紧跟其后，没有段间距，但首行缩进
|
||||
清晰地标识了新段落的开始。
|
||||
```
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- English body: justified (creates word-spacing rivers) -->
|
||||
<w:pPr>
|
||||
<w:jc w:val="both"/>
|
||||
<w:spacing w:after="160" w:line="276" w:lineRule="auto"/>
|
||||
<w:ind w:firstLine="720"/> <!-- BOTH indent AND spacing: redundant -->
|
||||
</w:pPr>
|
||||
|
||||
<!-- CJK body: left-aligned (breaks character grid) -->
|
||||
<w:pPr>
|
||||
<w:jc w:val="left"/>
|
||||
<w:spacing w:after="200" w:line="276" w:lineRule="auto"/>
|
||||
<!-- No indent, using spacing instead -- unidiomatic for CJK -->
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
Problems:
|
||||
- Justified English text with narrow columns creates uneven word gaps.
|
||||
- Using both first-line indent AND paragraph spacing is redundant.
|
||||
- Left-aligned CJK breaks the character grid that CJK readers expect.
|
||||
- CJK with spacing-based separation looks like translated western layout.
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. **River test**: in justified English text, squint and look for vertical
|
||||
white streaks running through the paragraph. If you see them, switch to
|
||||
left-align or increase the column width.
|
||||
2. **Double signal check**: does the document use BOTH first-line indent AND
|
||||
paragraph spacing? If yes, remove one. Choose indent for CJK/academic,
|
||||
spacing for modern western.
|
||||
3. **Tab alignment**: if you use tabs for columns, do all tab stops across
|
||||
the document use the same positions? Inconsistent tab stops create jagged
|
||||
invisible grid lines.
|
||||
|
||||
---
|
||||
|
||||
## 5. Repetition & Consistency
|
||||
|
||||
### Why It Works
|
||||
|
||||
Consistency is a trust signal. When a reader sees that every H2 looks the same,
|
||||
every table follows the same pattern, and every page number sits in the same
|
||||
spot, they unconsciously trust that the document was crafted with care. A single
|
||||
inconsistency -- one H2 that is 15pt instead of 14pt, one table with different
|
||||
borders -- breaks that trust and makes the reader question the content.
|
||||
|
||||
Consistency also reduces cognitive load. Once the reader learns "bold dark blue
|
||||
= section heading," they stop spending mental effort on identifying structure
|
||||
and focus entirely on content. Every inconsistency forces them to re-evaluate:
|
||||
"Is this a different kind of heading, or did someone just forget to apply the
|
||||
style?"
|
||||
|
||||
The implementation rule is simple: **use named styles, not direct formatting.**
|
||||
If you define Heading2 as a style and apply it everywhere, consistency is
|
||||
automatic. If you manually set font size, bold, and color on each heading
|
||||
individually, inconsistency is inevitable.
|
||||
|
||||
### Good Example
|
||||
|
||||
```xml
|
||||
<!-- Define styles once in styles.xml -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading2">
|
||||
<w:name w:val="heading 2"/>
|
||||
<w:basedOn w:val="Normal"/>
|
||||
<w:next w:val="Normal"/>
|
||||
<w:pPr>
|
||||
<w:keepNext/>
|
||||
<w:keepLines/>
|
||||
<w:spacing w:before="360" w:after="120"/>
|
||||
<w:outlineLvl w:val="1"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:rFonts w:asciiTheme="majorHAnsi" w:hAnsiTheme="majorHAnsi"/>
|
||||
<w:b/>
|
||||
<w:sz w:val="32"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Apply consistently: every H2 references the style -->
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Heading2"/>
|
||||
<!-- No direct formatting overrides -->
|
||||
</w:pPr>
|
||||
<w:r><w:t>Market Analysis</w:t></w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
When using a table style, define it once and reference it for every table:
|
||||
|
||||
```xml
|
||||
<!-- All tables reference the same style -->
|
||||
<w:tblPr>
|
||||
<w:tblStyle w:val="GridTable4Accent1"/>
|
||||
<w:tblW w:w="0" w:type="auto"/>
|
||||
</w:tblPr>
|
||||
```
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- First H2: manually formatted -->
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:spacing w:before="360" w:after="120"/>
|
||||
</w:pPr>
|
||||
<w:r>
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="32"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
<w:t>Market Analysis</w:t>
|
||||
</w:r>
|
||||
</w:p>
|
||||
|
||||
<!-- Second H2: slightly different (16pt instead of 16pt? No, 15pt!) -->
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:spacing w:before="240" w:after="160"/> <!-- different spacing! -->
|
||||
</w:pPr>
|
||||
<w:r>
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="30"/> <!-- 15pt instead of 16pt! -->
|
||||
<w:color w:val="2E74B5"/> <!-- different shade of blue! -->
|
||||
</w:rPr>
|
||||
<w:t>Financial Overview</w:t>
|
||||
</w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
Problems:
|
||||
- No style references -- everything is direct formatting.
|
||||
- Second H2 has different size (30 vs 32), color, and spacing.
|
||||
- If there are 20 headings, each could drift slightly differently.
|
||||
- Changing the design later means editing every heading individually.
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. **Style audit**: does every paragraph reference a `w:pStyle`? If you find
|
||||
paragraphs with only direct formatting and no style, that is a consistency
|
||||
risk.
|
||||
2. **Search for variance**: search the XML for all `w:sz` values used with
|
||||
`w:b` (bold). If you find three different sizes for what should be the same
|
||||
heading level, there is an inconsistency.
|
||||
3. **Table check**: do all tables in the document reference the same
|
||||
`w:tblStyle`? If some tables have manual border definitions while others
|
||||
use a style, the document will look patchy.
|
||||
4. **Page numbers**: check that header/footer content is defined in the
|
||||
default section properties and inherited by all sections, not redefined
|
||||
inconsistently in each section.
|
||||
|
||||
---
|
||||
|
||||
## 6. Visual Hierarchy & Flow
|
||||
|
||||
### Why It Works
|
||||
|
||||
A well-designed document guides the reader's eye in a predictable path:
|
||||
title at the top, subtitle below it, section headings as signposts, body text
|
||||
as the main content, footnotes and captions as supporting details. This flow
|
||||
mirrors reading priority -- the most important information is the most visually
|
||||
prominent.
|
||||
|
||||
Each level in the hierarchy must be **distinguishable from its adjacent
|
||||
levels**. It is not enough for H1 to differ from body text; H1 must also
|
||||
clearly differ from H2, and H2 from H3. If any two adjacent levels are too
|
||||
similar, the hierarchy collapses at that point.
|
||||
|
||||
Effective hierarchy uses **multiple simultaneous signals**:
|
||||
|
||||
| Level | Size | Weight | Color | Spacing above |
|
||||
|----------|-------|---------|---------|---------------|
|
||||
| Title | 26pt | Bold | #1F3864 | 0 (top) |
|
||||
| Subtitle | 15pt | Regular | #4472C4 | 4pt |
|
||||
| H1 | 20pt | Bold | #1F3864 | 24pt |
|
||||
| H2 | 16pt | Bold | #1F3864 | 18pt |
|
||||
| H3 | 13pt | Bold | #1F3864 | 12pt |
|
||||
| Body | 11pt | Regular | #333333 | 0pt |
|
||||
| Caption | 9pt | Italic | #666666 | 4pt |
|
||||
| Footnote | 9pt | Regular | #666666 | 0pt |
|
||||
|
||||
Notice how each level differs from its neighbors on at least two dimensions
|
||||
(size + weight, or size + color, or weight + style). Single-dimension
|
||||
differences are fragile and can be missed.
|
||||
|
||||
**Section breaks** create rhythm in long documents. A page break before each
|
||||
major section (H1) gives the reader a mental reset. Within sections, consistent
|
||||
heading + body patterns create a predictable cadence that makes long documents
|
||||
less intimidating.
|
||||
|
||||
### Good Example
|
||||
|
||||
```xml
|
||||
<!-- Title: large, bold, navy, centered -->
|
||||
<w:style w:type="paragraph" w:styleId="Title">
|
||||
<w:pPr>
|
||||
<w:jc w:val="center"/>
|
||||
<w:spacing w:after="80"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="52"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Subtitle: medium, regular weight, lighter blue, centered -->
|
||||
<w:style w:type="paragraph" w:styleId="Subtitle">
|
||||
<w:pPr>
|
||||
<w:jc w:val="center"/>
|
||||
<w:spacing w:after="320"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:sz w:val="30"/>
|
||||
<w:color w:val="4472C4"/>
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- H1: page break before, large bold navy -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading1">
|
||||
<w:pPr>
|
||||
<w:pageBreakBefore/>
|
||||
<w:keepNext/>
|
||||
<w:keepLines/>
|
||||
<w:spacing w:before="480" w:after="160"/>
|
||||
<w:outlineLvl w:val="0"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="40"/>
|
||||
<w:color w:val="1F3864"/>
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Caption: small, italic, gray -->
|
||||
<w:style w:type="paragraph" w:styleId="Caption">
|
||||
<w:pPr>
|
||||
<w:spacing w:before="80" w:after="200"/>
|
||||
</w:pPr>
|
||||
<w:rPr>
|
||||
<w:i/>
|
||||
<w:sz w:val="18"/>
|
||||
<w:color w:val="666666"/>
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
```
|
||||
|
||||
```
|
||||
Visual flow (good):
|
||||
|
||||
+----------------------------------+
|
||||
| |
|
||||
| ANNUAL REPORT 2025 | <- Title: 26pt bold navy centered
|
||||
| Acme Corporation | <- Subtitle: 15pt regular blue
|
||||
| |
|
||||
| |
|
||||
+----------------------------------+
|
||||
|
||||
+----------------------------------+
|
||||
| |
|
||||
| 1. Executive Summary | <- H1: 20pt bold navy (page break)
|
||||
| |
|
||||
| Body text introducing the | <- Body: 11pt regular gray
|
||||
| main findings of the year. |
|
||||
| |
|
||||
| 1.1 Revenue Highlights | <- H2: 16pt bold navy
|
||||
| |
|
||||
| Revenue grew by 23% year | <- Body
|
||||
| over year, driven by... |
|
||||
| |
|
||||
| Figure 1: Revenue Growth | <- Caption: 9pt italic gray
|
||||
| |
|
||||
+----------------------------------+
|
||||
|
||||
Each level is immediately identifiable. The eye flows naturally
|
||||
from title -> heading -> body -> caption.
|
||||
```
|
||||
|
||||
### Bad Example
|
||||
|
||||
```xml
|
||||
<!-- All headings same color as body, minimal size difference -->
|
||||
<w:style w:type="paragraph" w:styleId="Heading1">
|
||||
<w:rPr>
|
||||
<w:b/>
|
||||
<w:sz w:val="28"/> <!-- 14pt -- only 3pt above body -->
|
||||
<w:color w:val="000000"/> <!-- same color as body -->
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- Caption same size as body, not italic -->
|
||||
<w:style w:type="paragraph" w:styleId="Caption">
|
||||
<w:rPr>
|
||||
<w:sz w:val="22"/> <!-- same 11pt as body! -->
|
||||
<w:color w:val="000000"/> <!-- same color as body -->
|
||||
</w:rPr>
|
||||
</w:style>
|
||||
|
||||
<!-- No page breaks between major sections -->
|
||||
<!-- H1 has no pageBreakBefore, keepNext, or keepLines -->
|
||||
```
|
||||
|
||||
Problems:
|
||||
- H1 at 14pt is too close to body at 11pt (ratio 1.27 -- acceptable in
|
||||
isolation but with black color matching body, the hierarchy is weak).
|
||||
- Caption is indistinguishable from body text.
|
||||
- No page breaks means major sections bleed into each other with no
|
||||
visual rhythm.
|
||||
- Everything is black, so color provides zero hierarchy signal.
|
||||
|
||||
### Quick Test
|
||||
|
||||
1. **The squint test**: blur your eyes while looking at a full page. You
|
||||
should see 3-4 distinct "weight levels" of gray. If the page looks like
|
||||
one uniform shade, the hierarchy is too flat.
|
||||
2. **The scan test**: flip through pages quickly. Can you identify section
|
||||
boundaries in under one second per page? If yes, the visual hierarchy is
|
||||
working. If pages blur together, you need stronger differentiation at H1.
|
||||
3. **Adjacent level test**: for each heading level, check that it differs
|
||||
from the next level on at least 2 of: size, weight, color, style (italic).
|
||||
Single-dimension differences get lost.
|
||||
4. **Rhythm test**: in a document over 10 pages, do major sections (H1) start
|
||||
on new pages? If not, long documents will feel like an undifferentiated
|
||||
stream. Add `w:pageBreakBefore` to Heading1.
|
||||
|
||||
---
|
||||
|
||||
## Summary: Decision Checklist
|
||||
|
||||
When you are unsure about a typographic choice, run through these checks:
|
||||
|
||||
| Principle | Question | If No... |
|
||||
|-----------|----------|----------|
|
||||
| White Space | Does the page have at least 30% white space? | Increase margins or spacing |
|
||||
| Contrast | Can I count heading levels by squinting? | Increase size ratios (target 1.25x) |
|
||||
| Proximity | Does each heading clearly belong to text below it? | Make space-before > space-after (2:1) |
|
||||
| Alignment | Is English left-aligned and CJK justified? | Switch alignment mode |
|
||||
| Repetition | Do all same-level elements use the same style? | Replace direct formatting with styles |
|
||||
| Hierarchy | Can I see the document structure at arm's length? | Add more differentiation signals |
|
||||
|
||||
**When two principles conflict, prioritize in this order:**
|
||||
|
||||
1. **Readability** (white space, line spacing) -- always wins
|
||||
2. **Hierarchy** (contrast, scale) -- readers must find what they need
|
||||
3. **Consistency** (repetition) -- builds trust
|
||||
4. **Aesthetics** (alignment, grouping) -- the finishing touch
|
||||
@@ -0,0 +1,308 @@
|
||||
# OpenXML Child Element Ordering Rules
|
||||
|
||||
Element ordering in OpenXML is defined by the XSD schema. Incorrect ordering produces invalid documents that Word may refuse to open or silently repair (potentially losing data).
|
||||
|
||||
> **Key rule**: Properties elements (`*Pr`) must always be the **first child** of their parent.
|
||||
|
||||
---
|
||||
|
||||
## w:document
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:background [0..1] — page background color/fill
|
||||
2. w:body [0..1] — document content container
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:body
|
||||
|
||||
```
|
||||
Children in order (repeating group):
|
||||
1. w:p [0..*] — paragraph
|
||||
2. w:tbl [0..*] — table
|
||||
3. w:sdt [0..*] — structured document tag (content control)
|
||||
4. w:sectPr [0..1] — LAST child: final section properties
|
||||
```
|
||||
|
||||
Note: `w:p`, `w:tbl`, and `w:sdt` are interleaved in document order. The only strict rule is that `w:sectPr` must be the **last child** of `w:body`.
|
||||
|
||||
---
|
||||
|
||||
## w:p (Paragraph)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:pPr [0..1] — paragraph properties (MUST be first)
|
||||
|
||||
Then any mix of (interleaved in document order):
|
||||
- w:r [0..*] — run
|
||||
- w:hyperlink [0..*] — hyperlink wrapper
|
||||
- w:ins [0..*] — tracked insertion
|
||||
- w:del [0..*] — tracked deletion
|
||||
- w:bookmarkStart [0..*] — bookmark anchor start
|
||||
- w:bookmarkEnd [0..*] — bookmark anchor end
|
||||
- w:commentRangeStart [0..*] — comment range start
|
||||
- w:commentRangeEnd [0..*] — comment range end
|
||||
- w:proofErr [0..*] — proofing error marker
|
||||
- w:fldSimple [0..*] — simple field
|
||||
- w:sdt [0..*] — inline content control
|
||||
- w:smartTag [0..*] — smart tag
|
||||
```
|
||||
|
||||
**Practical note**: After `w:pPr`, the remaining children appear in document reading order. Runs, hyperlinks, bookmarks, and comment ranges intermix freely based on their position in the text.
|
||||
|
||||
---
|
||||
|
||||
## w:pPr (Paragraph Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:pStyle [0..1] — paragraph style reference
|
||||
2. w:keepNext [0..1] — keep with next paragraph
|
||||
3. w:keepLines [0..1] — keep lines together
|
||||
4. w:pageBreakBefore [0..1] — page break before paragraph
|
||||
5. w:framePr [0..1] — text frame properties
|
||||
6. w:widowControl [0..1] — widow/orphan control
|
||||
7. w:numPr [0..1] — numbering properties
|
||||
8. w:suppressLineNumbers [0..1]
|
||||
9. w:pBdr [0..1] — paragraph borders
|
||||
10. w:shd [0..1] — shading
|
||||
11. w:tabs [0..1] — tab stops
|
||||
12. w:suppressAutoHyphens [0..1]
|
||||
13. w:kinsoku [0..1] — CJK kinsoku settings
|
||||
14. w:wordWrap [0..1]
|
||||
15. w:overflowPunct [0..1]
|
||||
16. w:topLinePunct [0..1]
|
||||
17. w:autoSpaceDE [0..1]
|
||||
18. w:autoSpaceDN [0..1]
|
||||
19. w:bidi [0..1] — right-to-left paragraph
|
||||
20. w:adjustRightInd [0..1]
|
||||
21. w:snapToGrid [0..1]
|
||||
22. w:spacing [0..1] — line and paragraph spacing
|
||||
23. w:ind [0..1] — indentation
|
||||
24. w:contextualSpacing [0..1]
|
||||
25. w:mirrorIndents [0..1]
|
||||
26. w:suppressOverlap [0..1]
|
||||
27. w:jc [0..1] — justification (left/center/right/both)
|
||||
28. w:textDirection [0..1]
|
||||
29. w:textAlignment [0..1]
|
||||
30. w:outlineLvl [0..1] — outline level
|
||||
31. w:divId [0..1]
|
||||
32. w:rPr [0..1] — run properties for paragraph mark
|
||||
33. w:sectPr [0..1] — section break (section ends at this paragraph)
|
||||
34. w:pPrChange [0..1] — tracked paragraph property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:r (Run)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:rPr [0..1] — run properties (MUST be first)
|
||||
|
||||
Then any of (one per run, typically):
|
||||
- w:t [0..*] — text content
|
||||
- w:br [0..*] — break (line, page, column)
|
||||
- w:tab [0..*] — tab character
|
||||
- w:cr [0..*] — carriage return
|
||||
- w:sym [0..*] — symbol character
|
||||
- w:drawing [0..*] — DrawingML object (images)
|
||||
- w:pict [0..*] — VML picture (legacy)
|
||||
- w:fldChar [0..*] — complex field character
|
||||
- w:instrText [0..*] — field instruction text
|
||||
- w:delText [0..*] — deleted text (inside w:del)
|
||||
- w:footnoteReference [0..*]
|
||||
- w:endnoteReference [0..*]
|
||||
- w:commentReference [0..*]
|
||||
- w:lastRenderedPageBreak [0..*]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:rPr (Run Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:rStyle [0..1] — character style reference
|
||||
2. w:rFonts [0..1] — font specification
|
||||
3. w:b [0..1] — bold
|
||||
4. w:bCs [0..1] — complex script bold
|
||||
5. w:i [0..1] — italic
|
||||
6. w:iCs [0..1] — complex script italic
|
||||
7. w:caps [0..1] — all capitals
|
||||
8. w:smallCaps [0..1] — small capitals
|
||||
9. w:strike [0..1] — strikethrough
|
||||
10. w:dstrike [0..1] — double strikethrough
|
||||
11. w:outline [0..1]
|
||||
12. w:shadow [0..1]
|
||||
13. w:emboss [0..1]
|
||||
14. w:imprint [0..1]
|
||||
15. w:noProof [0..1] — suppress proofing
|
||||
16. w:snapToGrid [0..1]
|
||||
17. w:vanish [0..1] — hidden text
|
||||
18. w:color [0..1] — text color
|
||||
19. w:spacing [0..1] — character spacing
|
||||
20. w:w [0..1] — character width scaling
|
||||
21. w:kern [0..1] — font kerning
|
||||
22. w:position [0..1] — vertical position (raise/lower)
|
||||
23. w:sz [0..1] — font size (half-points)
|
||||
24. w:szCs [0..1] — complex script font size
|
||||
25. w:highlight [0..1] — text highlight color
|
||||
26. w:u [0..1] — underline
|
||||
27. w:effect [0..1] — text effect (animated)
|
||||
28. w:bdr [0..1] — run border
|
||||
29. w:shd [0..1] — run shading
|
||||
30. w:vertAlign [0..1] — superscript/subscript
|
||||
31. w:rtl [0..1] — right-to-left
|
||||
32. w:cs [0..1] — complex script
|
||||
33. w:lang [0..1] — language
|
||||
34. w:rPrChange [0..1] — tracked run property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:tbl (Table)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:tblPr [1..1] — table properties (REQUIRED, must be first)
|
||||
2. w:tblGrid [1..1] — column width definitions (REQUIRED)
|
||||
3. w:tr [1..*] — table row(s)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:tblPr (Table Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:tblStyle [0..1] — table style reference
|
||||
2. w:tblpPr [0..1] — table positioning
|
||||
3. w:tblOverlap [0..1]
|
||||
4. w:bidiVisual [0..1] — right-to-left table
|
||||
5. w:tblStyleRowBandSize [0..1]
|
||||
6. w:tblStyleColBandSize [0..1]
|
||||
7. w:tblW [0..1] — preferred table width
|
||||
8. w:jc [0..1] — table alignment
|
||||
9. w:tblCellSpacing [0..1]
|
||||
10. w:tblInd [0..1] — table indent from margin
|
||||
11. w:tblBorders [0..1] — table borders
|
||||
12. w:shd [0..1] — table shading
|
||||
13. w:tblLayout [0..1] — fixed or autofit
|
||||
14. w:tblCellMar [0..1] — default cell margins
|
||||
15. w:tblLook [0..1] — conditional formatting flags
|
||||
16. w:tblCaption [0..1] — accessibility caption
|
||||
17. w:tblDescription [0..1] — accessibility description
|
||||
18. w:tblPrChange [0..1] — tracked table property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:tr (Table Row)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:trPr [0..1] — row properties (must be first)
|
||||
2. w:tc [1..*] — table cell(s)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:trPr (Table Row Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:cnfStyle [0..1] — conditional formatting
|
||||
2. w:divId [0..1]
|
||||
3. w:gridBefore [0..1] — grid columns before first cell
|
||||
4. w:gridAfter [0..1] — grid columns after last cell
|
||||
5. w:wBefore [0..1]
|
||||
6. w:wAfter [0..1]
|
||||
7. w:cantSplit [0..1] — don't split row across pages
|
||||
8. w:trHeight [0..1] — row height
|
||||
9. w:tblHeader [0..1] — repeat as header row
|
||||
10. w:tblCellSpacing [0..1]
|
||||
11. w:jc [0..1] — row alignment
|
||||
12. w:hidden [0..1]
|
||||
13. w:ins [0..1] — tracked row insertion
|
||||
14. w:del [0..1] — tracked row deletion
|
||||
15. w:trPrChange [0..1] — tracked row property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:tc (Table Cell)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:tcPr [0..1] — cell properties (must be first)
|
||||
2. w:p [1..*] — paragraph(s) — at least one required
|
||||
3. w:tbl [0..*] — nested table(s)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:tcPr (Table Cell Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:cnfStyle [0..1]
|
||||
2. w:tcW [0..1] — cell width
|
||||
3. w:gridSpan [0..1] — horizontal merge (column span)
|
||||
4. w:hMerge [0..1] — legacy horizontal merge
|
||||
5. w:vMerge [0..1] — vertical merge
|
||||
6. w:tcBorders [0..1] — cell borders
|
||||
7. w:shd [0..1] — cell shading
|
||||
8. w:noWrap [0..1]
|
||||
9. w:tcMar [0..1] — cell margins
|
||||
10. w:textDirection [0..1]
|
||||
11. w:tcFitText [0..1]
|
||||
12. w:vAlign [0..1] — vertical alignment
|
||||
13. w:hideMark [0..1]
|
||||
14. w:tcPrChange [0..1] — tracked cell property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:sectPr (Section Properties)
|
||||
|
||||
```
|
||||
Children in order:
|
||||
1. w:headerReference [0..*] — header references (type: default/first/even)
|
||||
2. w:footerReference [0..*] — footer references
|
||||
3. w:endnotePr [0..1]
|
||||
4. w:footnotePr [0..1]
|
||||
5. w:type [0..1] — section break type (nextPage/continuous/evenPage/oddPage)
|
||||
6. w:pgSz [0..1] — page size
|
||||
7. w:pgMar [0..1] — page margins
|
||||
8. w:paperSrc [0..1]
|
||||
9. w:pgBorders [0..1] — page borders
|
||||
10. w:lnNumType [0..1] — line numbering
|
||||
11. w:pgNumType [0..1] — page numbering
|
||||
12. w:cols [0..1] — column definitions
|
||||
13. w:formProt [0..1]
|
||||
14. w:vAlign [0..1] — vertical alignment of page
|
||||
15. w:noEndnote [0..1]
|
||||
16. w:titlePg [0..1] — different first page header/footer
|
||||
17. w:textDirection [0..1]
|
||||
18. w:bidi [0..1]
|
||||
19. w:rtlGutter [0..1]
|
||||
20. w:docGrid [0..1] — document grid
|
||||
21. w:sectPrChange [0..1] — tracked section property change
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## w:hdr (Header) / w:ftr (Footer)
|
||||
|
||||
```
|
||||
Children (same structure as w:body content):
|
||||
1. w:p [0..*] — paragraph(s)
|
||||
2. w:tbl [0..*] — table(s)
|
||||
3. w:sdt [0..*] — content controls
|
||||
```
|
||||
|
||||
Headers and footers are essentially mini-documents. They follow the same content model as `w:body` but without a final `w:sectPr`.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,82 @@
|
||||
# OpenXML Namespaces, Relationship Types, and Content Types
|
||||
|
||||
## Core Namespaces
|
||||
|
||||
| Prefix | URI | Used In |
|
||||
|--------|-----|---------|
|
||||
| `w` | `http://schemas.openxmlformats.org/wordprocessingml/2006/main` | document.xml, styles.xml, numbering.xml, headers, footers |
|
||||
| `r` | `http://schemas.openxmlformats.org/officeDocument/2006/relationships` | Relationship references (r:id) |
|
||||
| `wp` | `http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing` | Image/drawing placement in document |
|
||||
| `a` | `http://schemas.openxmlformats.org/drawingml/2006/main` | DrawingML core (shapes, images, themes) |
|
||||
| `pic` | `http://schemas.openxmlformats.org/drawingml/2006/picture` | Picture element in DrawingML |
|
||||
| `v` | `urn:schemas-microsoft-com:vml` | VML (legacy shapes, watermarks) |
|
||||
| `o` | `urn:schemas-microsoft-com:office:office` | Office VML extensions |
|
||||
| `m` | `http://schemas.openxmlformats.org/officeDocument/2006/math` | Math equations (OMML) |
|
||||
| `mc` | `http://schemas.openxmlformats.org/markup-compatibility/2006` | Markup compatibility (Ignorable, AlternateContent) |
|
||||
|
||||
## Extended Namespaces
|
||||
|
||||
| Prefix | URI | Purpose |
|
||||
|--------|-----|---------|
|
||||
| `w14` | `http://schemas.microsoft.com/office/word/2010/wordml` | Word 2010 extensions (contentPart, etc.) |
|
||||
| `w15` | `http://schemas.microsoft.com/office/word/2012/wordml` | Word 2013 extensions (commentEx, etc.) |
|
||||
| `w16cid` | `http://schemas.microsoft.com/office/word/2016/wordml/cid` | Comment IDs (durable IDs) |
|
||||
| `w16cex` | `http://schemas.microsoft.com/office/word/2018/wordml/cex` | Comment extensible |
|
||||
| `w16se` | `http://schemas.microsoft.com/office/word/2015/wordml/symex` | Symbol extensions |
|
||||
| `wps` | `http://schemas.microsoft.com/office/word/2010/wordprocessingShape` | WordprocessingML shapes |
|
||||
| `wpc` | `http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas` | Drawing canvas |
|
||||
|
||||
## Relationship Types
|
||||
|
||||
| Relationship | Type URI |
|
||||
|-------------|----------|
|
||||
| Document | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument` |
|
||||
| Styles | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles` |
|
||||
| Numbering | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering` |
|
||||
| Font Table | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable` |
|
||||
| Settings | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings` |
|
||||
| Theme | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme` |
|
||||
| Image | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/image` |
|
||||
| Hyperlink | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink` |
|
||||
| Header | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/header` |
|
||||
| Footer | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer` |
|
||||
| Comments | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments` |
|
||||
| CommentsExtended | `http://schemas.microsoft.com/office/2011/relationships/commentsExtended` |
|
||||
| CommentsIds | `http://schemas.microsoft.com/office/2016/09/relationships/commentsIds` |
|
||||
| CommentsExtensible | `http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible` |
|
||||
| Footnotes | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes` |
|
||||
| Endnotes | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes` |
|
||||
| Glossary | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/glossaryDocument` |
|
||||
| Web Settings | `http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings` |
|
||||
|
||||
## Content Types (`[Content_Types].xml`)
|
||||
|
||||
### Default Extensions
|
||||
|
||||
```xml
|
||||
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
|
||||
<Default Extension="xml" ContentType="application/xml" />
|
||||
<Default Extension="png" ContentType="image/png" />
|
||||
<Default Extension="jpeg" ContentType="image/jpeg" />
|
||||
<Default Extension="gif" ContentType="image/gif" />
|
||||
<Default Extension="emf" ContentType="image/x-emf" />
|
||||
```
|
||||
|
||||
### Part Overrides
|
||||
|
||||
| Part | Content Type |
|
||||
|------|-------------|
|
||||
| `/word/document.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml` |
|
||||
| `/word/styles.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml` |
|
||||
| `/word/numbering.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml` |
|
||||
| `/word/settings.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml` |
|
||||
| `/word/fontTable.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml` |
|
||||
| `/word/theme/theme1.xml` | `application/vnd.openxmlformats-officedocument.theme+xml` |
|
||||
| `/word/header1.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml` |
|
||||
| `/word/footer1.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml` |
|
||||
| `/word/comments.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml` |
|
||||
| `/word/commentsExtended.xml` | `application/vnd.ms-word.commentsExtended+xml` |
|
||||
| `/word/commentsIds.xml` | `application/vnd.ms-word.commentsIds+xml` |
|
||||
| `/word/commentsExtensible.xml` | `application/vnd.ms-word.commentsExtensible+xml` |
|
||||
| `/word/footnotes.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml` |
|
||||
| `/word/endnotes.xml` | `application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml` |
|
||||
@@ -0,0 +1,72 @@
|
||||
# OpenXML Unit Conversion Quick Reference
|
||||
|
||||
## Master Conversion Table
|
||||
|
||||
| Unit | 1 inch | 1 cm | 1 mm | 1 pt | Description |
|
||||
|------|--------|------|------|------|-------------|
|
||||
| DXA (twips) | 1440 | 567 | 56.7 | 20 | 1/20 of a point. Used for margins, indents, spacing, page size. |
|
||||
| EMU | 914400 | 360000 | 36000 | 12700 | English Metric Unit. Used for images, drawings, shapes. |
|
||||
| Half-points | 144 | 56.7 | 5.67 | 2 | Used for font sizes (`w:sz`, `w:szCs`). |
|
||||
| Points | 72 | 28.35 | 2.835 | 1 | Standard typographic unit. Not used directly in most attributes. |
|
||||
| Eighths of a point | 576 | 226.8 | 22.68 | 8 | Used for `w:spacing` character spacing. |
|
||||
|
||||
## Common Page Sizes
|
||||
|
||||
| Size | Width (DXA) | Height (DXA) | Width (mm) | Height (mm) |
|
||||
|------|-------------|--------------|------------|-------------|
|
||||
| A4 | 11906 | 16838 | 210 | 297 |
|
||||
| Letter | 12240 | 15840 | 215.9 | 279.4 |
|
||||
| Legal | 12240 | 20160 | 215.9 | 355.6 |
|
||||
| A3 | 16838 | 23811 | 297 | 420 |
|
||||
| A5 | 8391 | 11906 | 148 | 210 |
|
||||
|
||||
## Common Margin Values
|
||||
|
||||
| Margin | DXA | Inches | cm |
|
||||
|--------|-----|--------|----|
|
||||
| 0.5 inch | 720 | 0.5 | 1.27 |
|
||||
| 0.75 inch | 1080 | 0.75 | 1.91 |
|
||||
| 1 inch | 1440 | 1.0 | 2.54 |
|
||||
| 1.25 inch | 1800 | 1.25 | 3.18 |
|
||||
| 1.5 inch | 2160 | 1.5 | 3.81 |
|
||||
|
||||
## Font Size Values (`w:sz`)
|
||||
|
||||
| Display Size | w:sz value | Notes |
|
||||
|-------------|-----------|-------|
|
||||
| 8pt | 16 | |
|
||||
| 9pt | 18 | |
|
||||
| 10pt | 20 | |
|
||||
| 10.5pt | 21 | Common CJK body size |
|
||||
| 11pt | 22 | Default Calibri body |
|
||||
| 12pt | 24 | Default TNR body |
|
||||
| 14pt | 28 | Small heading |
|
||||
| 16pt | 32 | |
|
||||
| 18pt | 36 | |
|
||||
| 20pt | 40 | |
|
||||
| 24pt | 48 | |
|
||||
| 28pt | 56 | |
|
||||
| 36pt | 72 | |
|
||||
|
||||
## Line Spacing Values
|
||||
|
||||
Line spacing in `w:spacing` uses the `w:line` attribute in 240ths of a line (when `w:lineRule="auto"`):
|
||||
|
||||
| Spacing | w:line value | w:lineRule |
|
||||
|---------|-------------|-----------|
|
||||
| Single | 240 | auto |
|
||||
| 1.15 (Word default) | 276 | auto |
|
||||
| 1.5 | 360 | auto |
|
||||
| Double | 480 | auto |
|
||||
| Exact 12pt | 240 | exact |
|
||||
| At least 12pt | 240 | atLeast |
|
||||
|
||||
Note: When `lineRule="exact"` or `"atLeast"`, `w:line` is in **twips** (DXA), not 240ths. So `line="240"` with `lineRule="exact"` means exactly 12pt (240/20 = 12pt).
|
||||
|
||||
## Conversion Formulas
|
||||
|
||||
```
|
||||
DXA = inches × 1440 = cm × 567 = pt × 20
|
||||
EMU = inches × 914400 = cm × 360000 = pt × 12700
|
||||
sz = pt × 2 (half-points)
|
||||
```
|
||||
@@ -0,0 +1,284 @@
|
||||
# Scenario A: Creating a New DOCX from Scratch
|
||||
|
||||
## When to Use
|
||||
|
||||
Use Scenario A when:
|
||||
- The user has no existing file and wants a brand new document
|
||||
- The user provides content (text, tables, images) and wants it assembled into a DOCX
|
||||
- The user specifies a document type (report, letter, memo, academic) or describes a custom layout
|
||||
|
||||
Do NOT use when: the user already has a DOCX they want to modify (→ Scenario B) or wants to restyle an existing document (→ Scenario C).
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Workflow
|
||||
|
||||
### 1. Determine Document Type
|
||||
|
||||
Ask or infer the document type from the user's request:
|
||||
|
||||
| Type | Typical Signals |
|
||||
|------|----------------|
|
||||
| Report | "report", "analysis", "whitepaper", sections with headings |
|
||||
| Letter | "letter", "dear", address block, salutation |
|
||||
| Memo | "memo", "memorandum", To/From/Subject fields |
|
||||
| Academic | "paper", "essay", "thesis", APA/MLA/Chicago mention |
|
||||
| Custom | None of the above, or user specifies exact formatting |
|
||||
|
||||
### 2. Gather Content Requirements
|
||||
|
||||
Collect from the user:
|
||||
- Title and subtitle (if any)
|
||||
- Author / organization
|
||||
- Section structure (headings and nesting)
|
||||
- Body content per section
|
||||
- Tables (headers + rows)
|
||||
- Images (file paths or placeholders)
|
||||
- Special elements: TOC, page numbers, watermark, headers/footers
|
||||
|
||||
### 3. Select Style Set
|
||||
|
||||
Based on document type, load the matching styles XML asset:
|
||||
- Report → `assets/styles/default_styles.xml` or `assets/styles/corporate_styles.xml`
|
||||
- Academic → `assets/styles/academic_styles.xml`
|
||||
- Letter / Memo / Custom → `assets/styles/default_styles.xml` (with overrides)
|
||||
|
||||
### 4. Configure Page Setup
|
||||
|
||||
Set `w:sectPr` values based on document type defaults (see below) or user overrides.
|
||||
|
||||
```xml
|
||||
<w:sectPr>
|
||||
<w:pgSz w:w="11906" w:h="16838" /> <!-- A4 -->
|
||||
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
|
||||
w:header="720" w:footer="720" w:gutter="0" />
|
||||
</w:sectPr>
|
||||
```
|
||||
|
||||
### 5. Build Document Structure
|
||||
|
||||
Assemble `word/document.xml` with:
|
||||
1. `w:body` as root container
|
||||
2. Paragraphs (`w:p`) with heading styles for section titles
|
||||
3. Body paragraphs with `Normal` style
|
||||
4. Tables, images, and other elements as needed
|
||||
5. Final `w:sectPr` as last child of `w:body`
|
||||
|
||||
### 6. Apply Typography Defaults
|
||||
|
||||
Set document-level defaults in `styles.xml` under `w:docDefaults`:
|
||||
```xml
|
||||
<w:docDefaults>
|
||||
<w:rPrDefault>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial" />
|
||||
<w:sz w:val="22" /> <!-- 11pt -->
|
||||
<w:szCs w:val="22" />
|
||||
</w:rPr>
|
||||
</w:rPrDefault>
|
||||
<w:pPrDefault>
|
||||
<w:pPr>
|
||||
<w:spacing w:after="160" w:line="259" w:lineRule="auto" />
|
||||
</w:pPr>
|
||||
</w:pPrDefault>
|
||||
</w:docDefaults>
|
||||
```
|
||||
|
||||
### 7. Add Complex Elements
|
||||
|
||||
See the Complex Elements Guide section below.
|
||||
|
||||
### 8. Run Validation Pipeline
|
||||
|
||||
```
|
||||
dotnet run ... validate --xsd wml-subset.xsd
|
||||
dotnet run ... validate --xsd business-rules.xsd # if applying a template
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Document Type Defaults
|
||||
|
||||
### Report
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Body font | Calibri 11pt |
|
||||
| Heading font | Calibri Light |
|
||||
| H1 / H2 / H3 / H4 size | 28pt / 24pt / 18pt / 14pt |
|
||||
| Heading color | #2F5496 (corporate blue) |
|
||||
| Margins | 1 inch (1440 DXA) all sides |
|
||||
| Page size | A4 (11906 × 16838 DXA) |
|
||||
| Line spacing | Single (line="240") |
|
||||
| Paragraph spacing | 0pt before, 8pt after body |
|
||||
|
||||
### Letter
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Font | Calibri 11pt |
|
||||
| Page size | Letter (12240 × 15840 DXA) |
|
||||
| Margins | 1 inch all sides |
|
||||
| Structure | Date → Address → Salutation → Body → Closing → Signature |
|
||||
| Line spacing | Single |
|
||||
|
||||
### Memo
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Font | Arial 11pt |
|
||||
| Page size | Letter |
|
||||
| Margins | 0.75 inch (1080 DXA) |
|
||||
| Header | "MEMO" centered, bold, 16pt |
|
||||
| Fields | To, From, Date, Subject (bold labels, tab-aligned values) |
|
||||
|
||||
### Academic
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Font | Times New Roman 12pt |
|
||||
| Line spacing | Double (line="480") |
|
||||
| Margins | 1 inch all sides |
|
||||
| Page size | Letter |
|
||||
| Headings | Bold, same font, 14/13/12pt for H1/H2/H3 |
|
||||
| First line indent | 0.5 inch (720 DXA) |
|
||||
| Heading color | Black (no color) |
|
||||
|
||||
---
|
||||
|
||||
## Content Configuration JSON Format
|
||||
|
||||
The CLI `create` command accepts a JSON config:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "report",
|
||||
"title": "Quarterly Revenue Analysis",
|
||||
"subtitle": "Q1 2026",
|
||||
"author": "Finance Team",
|
||||
"pageSize": "A4",
|
||||
"margins": { "top": 1440, "right": 1440, "bottom": 1440, "left": 1440 },
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Executive Summary",
|
||||
"level": 1,
|
||||
"content": [
|
||||
{ "type": "paragraph", "text": "Revenue grew 12% year-over-year..." },
|
||||
{
|
||||
"type": "table",
|
||||
"headers": ["Region", "Revenue", "Growth"],
|
||||
"rows": [
|
||||
["North America", "$4.2M", "+15%"],
|
||||
["Europe", "$2.8M", "+8%"],
|
||||
["Asia Pacific", "$1.9M", "+18%"]
|
||||
]
|
||||
},
|
||||
{ "type": "image", "path": "charts/revenue.png", "width": "5in", "alt": "Revenue chart" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Detailed Analysis",
|
||||
"level": 1,
|
||||
"content": [
|
||||
{ "type": "paragraph", "text": "Breaking down by product line..." }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Supported content types:
|
||||
- `paragraph` — body text (applies Normal style)
|
||||
- `table` — headers + rows (applies TableGrid style)
|
||||
- `image` — inline image with width/height control
|
||||
- `list` — bulleted or numbered list items
|
||||
- `pageBreak` — forces a page break
|
||||
|
||||
---
|
||||
|
||||
## Complex Elements Guide
|
||||
|
||||
### Table of Contents
|
||||
|
||||
Insert a TOC field code. Word will update the actual entries when the file is opened:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:pPr><w:pStyle w:val="TOCHeading" /></w:pPr>
|
||||
<w:r><w:t>Table of Contents</w:t></w:r>
|
||||
</w:p>
|
||||
<w:p>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="begin" />
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="separate" />
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:t>[Table of contents — update to populate]</w:t>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="end" />
|
||||
</w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
### Page Numbers in Footer
|
||||
|
||||
Add a footer part (`word/footer1.xml`) and reference it in `w:sectPr`:
|
||||
|
||||
```xml
|
||||
<!-- In footer1.xml -->
|
||||
<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
|
||||
<w:p>
|
||||
<w:pPr><w:jc w:val="center" /></w:pPr>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="begin" />
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:instrText>PAGE</w:instrText>
|
||||
</w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="separate" />
|
||||
</w:r>
|
||||
<w:r><w:t>1</w:t></w:r>
|
||||
<w:r>
|
||||
<w:fldChar w:fldCharType="end" />
|
||||
</w:r>
|
||||
</w:p>
|
||||
</w:ftr>
|
||||
|
||||
<!-- In sectPr -->
|
||||
<w:footerReference w:type="default" r:id="rId8" />
|
||||
```
|
||||
|
||||
### Watermark
|
||||
|
||||
Add a header part with a shape behind the text:
|
||||
|
||||
```xml
|
||||
<w:hdr>
|
||||
<w:p>
|
||||
<w:r>
|
||||
<w:pict>
|
||||
<v:shape style="position:absolute;margin-left:0;margin-top:0;width:468pt;height:180pt;
|
||||
z-index:-251657216;mso-position-horizontal:center;
|
||||
mso-position-vertical:center"
|
||||
fillcolor="silver" stroked="f">
|
||||
<v:textpath style="font-family:'Calibri';font-size:1pt" string="DRAFT" />
|
||||
</v:shape>
|
||||
</w:pict>
|
||||
</w:r>
|
||||
</w:p>
|
||||
</w:hdr>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Creation Checklist
|
||||
|
||||
1. **Validate** against `wml-subset.xsd` — all elements in correct order, required attributes present
|
||||
2. **Merge adjacent runs** with identical formatting to keep XML clean
|
||||
3. **Verify relationships** — every `r:id` in document.xml has a matching entry in `document.xml.rels`
|
||||
4. **Check content types** — every part in the package is registered in `[Content_Types].xml`
|
||||
5. **Preview** — open in Word or LibreOffice to visually confirm layout
|
||||
6. **File size** — confirm images are reasonably sized (compress if > 2MB each)
|
||||
@@ -0,0 +1,295 @@
|
||||
# Scenario B: Editing / Filling Content in Existing DOCX
|
||||
|
||||
## Core Principle
|
||||
|
||||
**"First, do no harm."** When editing an existing document, minimize changes. Touch only what needs to change. Preserve all formatting, styles, relationships, and structure that are not directly involved in the edit.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- Replacing placeholder text (`{{name}}`, `$DATE$`, `[PLACEHOLDER]`)
|
||||
- Updating specific paragraphs or table cells
|
||||
- Filling in form fields
|
||||
- Adding or removing paragraphs in a known location
|
||||
- Inserting tracked changes for review workflows
|
||||
|
||||
Do NOT use when: the user wants to change the look/style of the entire document (→ Scenario C) or create from scratch (→ Scenario A).
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
1. Preview → CLI: analyze <input.docx>
|
||||
2. Analyze → Understand structure: sections, styles, headings, tables
|
||||
3. Identify → Locate exact edit targets (paragraph index, table index, placeholder text)
|
||||
4. Edit → Apply surgical changes via CLI or direct XML
|
||||
5. Validate → CLI: validate <output.docx>
|
||||
6. Diff → Compare before/after to verify only intended changes were made
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use API vs Direct XML
|
||||
|
||||
### Use CLI Edit Command When:
|
||||
- Replacing placeholder text (e.g., `{{fieldName}}` → actual value)
|
||||
- Filling table data from JSON
|
||||
- Updating document properties (title, author)
|
||||
- Simple text insertions or deletions
|
||||
|
||||
### Use Direct XML Manipulation When:
|
||||
- Text spans multiple runs with different formatting (run-boundary issues)
|
||||
- Adding complex structures (nested tables, multi-image layouts)
|
||||
- Manipulating Track Changes markup
|
||||
- Modifying header/footer content
|
||||
- Adjusting section properties
|
||||
|
||||
---
|
||||
|
||||
## Placeholder Patterns
|
||||
|
||||
The CLI natively supports `{{fieldName}}` placeholders:
|
||||
|
||||
```bash
|
||||
# Replace all {{placeholders}} from a JSON map
|
||||
dotnet run ... edit input.docx --fill-placeholders data.json --output filled.docx
|
||||
```
|
||||
|
||||
Where `data.json`:
|
||||
```json
|
||||
{
|
||||
"companyName": "Acme Corp",
|
||||
"date": "March 21, 2026",
|
||||
"amount": "$15,000.00",
|
||||
"recipientName": "Jane Smith"
|
||||
}
|
||||
```
|
||||
|
||||
Other placeholder formats (`$FIELD$`, `[PLACEHOLDER]`) require text replacement:
|
||||
```bash
|
||||
dotnet run ... edit input.docx --replace "$DATE$" "March 21, 2026" --output updated.docx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Text Replacement Strategies
|
||||
|
||||
### Simple Replacement
|
||||
|
||||
When the entire search text is within a single `w:r` (run):
|
||||
|
||||
```xml
|
||||
<!-- Before -->
|
||||
<w:r>
|
||||
<w:rPr><w:b /></w:rPr>
|
||||
<w:t>{{companyName}}</w:t>
|
||||
</w:r>
|
||||
|
||||
<!-- After — formatting preserved -->
|
||||
<w:r>
|
||||
<w:rPr><w:b /></w:rPr>
|
||||
<w:t>Acme Corp</w:t>
|
||||
</w:r>
|
||||
```
|
||||
|
||||
Direct replacement. The run's `w:rPr` is untouched.
|
||||
|
||||
### Complex Replacement (Split Runs)
|
||||
|
||||
When the search text is split across multiple runs (common when Word applies spell-check or formatting mid-text):
|
||||
|
||||
```xml
|
||||
<!-- "{{companyName}}" split into 3 runs -->
|
||||
<w:r><w:rPr><w:b /></w:rPr><w:t>{{company</w:t></w:r>
|
||||
<w:r><w:rPr><w:b /><w:i /></w:rPr><w:t>Na</w:t></w:r>
|
||||
<w:r><w:rPr><w:b /></w:rPr><w:t>me}}</w:t></w:r>
|
||||
```
|
||||
|
||||
Strategy:
|
||||
1. Concatenate text across runs to find the match
|
||||
2. Place the replacement text in the **first** run (preserving its `w:rPr`)
|
||||
3. Remove the text from subsequent runs (or remove the runs entirely if empty)
|
||||
|
||||
```xml
|
||||
<!-- After -->
|
||||
<w:r><w:rPr><w:b /></w:rPr><w:t>Acme Corp</w:t></w:r>
|
||||
```
|
||||
|
||||
**Rule**: Always preserve the formatting of the first run in the match.
|
||||
|
||||
---
|
||||
|
||||
## Table Editing
|
||||
|
||||
### By Index
|
||||
|
||||
Tables are 0-indexed in document order:
|
||||
|
||||
```bash
|
||||
dotnet run ... edit input.docx --table-index 0 --table-data data.json --output updated.docx
|
||||
```
|
||||
|
||||
### By Header Matching
|
||||
|
||||
Find a table by its header row content:
|
||||
|
||||
```bash
|
||||
dotnet run ... edit input.docx --table-match "Name,Amount,Date" --table-data data.json
|
||||
```
|
||||
|
||||
### Table Data JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"rows": [
|
||||
["Alice Johnson", "$5,000", "2026-03-15"],
|
||||
["Bob Smith", "$3,200", "2026-03-18"]
|
||||
],
|
||||
"appendRows": true
|
||||
}
|
||||
```
|
||||
|
||||
- `appendRows: true` — add rows after existing data
|
||||
- `appendRows: false` (default) — replace all data rows (keeps header row)
|
||||
|
||||
### Direct XML Table Editing
|
||||
|
||||
To modify a specific cell, locate it by row/column index:
|
||||
|
||||
```xml
|
||||
<!-- Row 2 (0-indexed), Column 1 -->
|
||||
<w:tr> <!-- tr[2] -->
|
||||
<w:tc>...</w:tc>
|
||||
<w:tc> <!-- tc[1] — target cell -->
|
||||
<w:p>
|
||||
<w:r><w:t>Old Value</w:t></w:r>
|
||||
</w:p>
|
||||
</w:tc>
|
||||
</w:tr>
|
||||
```
|
||||
|
||||
Replace the `w:t` content. Do NOT modify `w:tcPr` (cell properties) or `w:tblPr` (table properties).
|
||||
|
||||
---
|
||||
|
||||
## Track Changes Guidance
|
||||
|
||||
### When to Add Revision Marks
|
||||
- User explicitly requests tracked changes
|
||||
- Document already has tracking enabled (`w:trackChanges` in settings)
|
||||
- Collaborative review workflow
|
||||
|
||||
### When NOT to Add Revision Marks
|
||||
- Form filling / placeholder replacement (these are "completing" the document, not "revising" it)
|
||||
- Direct edits where the user wants a clean result
|
||||
- Batch data filling operations
|
||||
|
||||
### Adding Tracked Changes
|
||||
|
||||
See `references/track_changes_guide.md` for full XML examples.
|
||||
|
||||
Quick reference — inserting text with tracking:
|
||||
```xml
|
||||
<w:ins w:id="1" w:author="DocxToolkit" w:date="2026-03-21T10:00:00Z">
|
||||
<w:r>
|
||||
<w:t>New text here</w:t>
|
||||
</w:r>
|
||||
</w:ins>
|
||||
```
|
||||
|
||||
Deleting text with tracking:
|
||||
```xml
|
||||
<w:del w:id="2" w:author="DocxToolkit" w:date="2026-03-21T10:00:00Z">
|
||||
<w:r>
|
||||
<w:delText>Removed text</w:delText> <!-- MUST use delText, not t -->
|
||||
</w:r>
|
||||
</w:del>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Breaking Run Boundaries
|
||||
|
||||
**Problem**: Replacing text that spans runs by naively modifying individual runs destroys inline formatting.
|
||||
|
||||
**Fix**: Concatenate run text, find match boundaries, consolidate into the first run, remove consumed runs.
|
||||
|
||||
### 2. Hyperlink Content
|
||||
|
||||
**Problem**: Replacing text inside a `w:hyperlink` element without preserving the hyperlink wrapper removes the link.
|
||||
|
||||
```xml
|
||||
<w:hyperlink r:id="rId5">
|
||||
<w:r>
|
||||
<w:rPr><w:rStyle w:val="Hyperlink" /></w:rPr>
|
||||
<w:t>Click here</w:t> <!-- Only replace this text -->
|
||||
</w:r>
|
||||
</w:hyperlink>
|
||||
```
|
||||
|
||||
**Fix**: Only modify the `w:t` inside the hyperlink's run. Never remove or replace the `w:hyperlink` element itself.
|
||||
|
||||
### 3. Tracked Change Context
|
||||
|
||||
**Problem**: Replacing text that is inside a `w:ins` or `w:del` element without understanding the revision context creates invalid markup.
|
||||
|
||||
**Fix**: If the target text is inside a revision mark, either:
|
||||
- Replace within the revision context (preserving the `w:ins`/`w:del` wrapper)
|
||||
- Or delete the old revision and create a new one
|
||||
|
||||
### 4. Style Preservation
|
||||
|
||||
**Problem**: Adding new paragraphs without specifying a style causes them to inherit `Normal`, which may not match the surrounding context.
|
||||
|
||||
**Fix**: When inserting paragraphs, copy the `w:pStyle` from an adjacent paragraph of the same type.
|
||||
|
||||
### 5. Numbering Continuity
|
||||
|
||||
**Problem**: Inserting a new list item breaks numbering sequence.
|
||||
|
||||
**Fix**: Ensure the new paragraph has the same `w:numId` and `w:ilvl` as adjacent list items. If continuing a sequence, set `w:numPr` to match.
|
||||
|
||||
### 6. XML Special Characters
|
||||
|
||||
**Problem**: User content contains `&`, `<`, `>`, `"`, `'` — these must be escaped in XML.
|
||||
|
||||
**Fix**: Always XML-escape user-provided text before inserting into `w:t` elements:
|
||||
- `&` → `&`
|
||||
- `<` → `<`
|
||||
- `>` → `>`
|
||||
- `"` → `"`
|
||||
- `'` → `'`
|
||||
|
||||
### 7. Whitespace Preservation
|
||||
|
||||
**Problem**: Leading/trailing spaces in `w:t` are stripped by XML parsers.
|
||||
|
||||
**Fix**: Add `xml:space="preserve"` attribute:
|
||||
```xml
|
||||
<w:t xml:space="preserve"> text with leading space</w:t>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diff Verification
|
||||
|
||||
After editing, always compare the before and after states:
|
||||
|
||||
```bash
|
||||
# Structural diff — shows only changed elements
|
||||
dotnet run ... diff original.docx modified.docx
|
||||
|
||||
# Text-only diff — shows content changes
|
||||
dotnet run ... diff original.docx modified.docx --text-only
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Only intended text changed
|
||||
- No styles were modified
|
||||
- No relationships were added/removed unexpectedly
|
||||
- Table structure intact (same number of rows/columns unless intentionally changed)
|
||||
- Images and other media unchanged
|
||||
@@ -0,0 +1,456 @@
|
||||
# Scenario C: Applying Formatting / Templates
|
||||
|
||||
## When to Use
|
||||
|
||||
Use Scenario C when:
|
||||
- The user has an existing document and wants to apply a different visual style
|
||||
- The user wants to rebrand a document (new fonts, colors, heading styles)
|
||||
- The user provides a template DOCX and wants its look applied to a content document
|
||||
- The user wants consistent formatting across multiple documents
|
||||
|
||||
Do NOT use when: the user wants to edit content (→ Scenario B) or create from scratch (→ Scenario A).
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
1. Analyze source → CLI: analyze source.docx (list styles, fonts, structure)
|
||||
2. Analyze template → CLI: analyze template.docx (list styles, fonts, structure)
|
||||
3. Map styles → Create mapping plan (source style → template style)
|
||||
4. Apply template → CLI: apply-template source.docx --template template.docx --output result.docx
|
||||
5. Validate (XSD) → CLI: validate result.docx --xsd wml-subset.xsd
|
||||
6. GATE-CHECK → CLI: validate result.docx --xsd business-rules.xsd ← MUST PASS
|
||||
7. Diff verify → CLI: diff source.docx result.docx --text-only (content must be identical)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Gets Copied from Template
|
||||
|
||||
| Part | File | Description |
|
||||
|------|------|-------------|
|
||||
| Styles | `word/styles.xml` | All style definitions (paragraph, character, table, numbering) |
|
||||
| Theme | `word/theme/theme1.xml` | Color scheme, font scheme, format scheme |
|
||||
| Numbering | `word/numbering.xml` | List and numbering definitions |
|
||||
| Headers | `word/header*.xml` | Header content and formatting |
|
||||
| Footers | `word/footer*.xml` | Footer content and formatting |
|
||||
| Section props | `w:sectPr` | Margins, page size, orientation, columns |
|
||||
|
||||
## What Does NOT Get Copied
|
||||
|
||||
| Part | Reason |
|
||||
|------|--------|
|
||||
| Document content | Paragraphs, tables, images stay from source |
|
||||
| Comments | Belong to source document's review history |
|
||||
| Tracked changes | Belong to source document's revision history |
|
||||
| Custom XML parts | Application-specific data, not visual |
|
||||
| Document properties | Title, author, dates belong to source |
|
||||
| Glossary document | Template's building blocks are not transferred |
|
||||
|
||||
---
|
||||
|
||||
## Template Structure Analysis (REQUIRED)
|
||||
|
||||
Before choosing Overlay or Base-Replace, you MUST analyze the template's internal structure. This is the #1 cause of failure when skipped.
|
||||
|
||||
### Step 1: Count template paragraphs and identify structural zones
|
||||
|
||||
Run `$CLI analyze --input template.docx` or manually inspect:
|
||||
|
||||
```bash
|
||||
# Quick structure scan
|
||||
scripts/docx_preview.sh template.docx
|
||||
```
|
||||
|
||||
Identify these zones in the template:
|
||||
```
|
||||
Zone A: Front matter (cover page, declaration, abstract, TOC)
|
||||
→ These are KEPT from template, never replaced
|
||||
Zone B: Example/placeholder body content ("第1章 XXX", sample paragraphs)
|
||||
→ This is REPLACED with user's actual content
|
||||
Zone C: Back matter (appendices, acknowledgments, blank pages)
|
||||
→ These are KEPT from template or removed
|
||||
Zone D: Final sectPr
|
||||
→ ALWAYS kept from template
|
||||
```
|
||||
|
||||
### Step 2: Find Zone B boundaries (replacement range)
|
||||
|
||||
Search the template's document.xml for anchor text that marks the start and end of example content:
|
||||
|
||||
**Start anchor patterns** (first paragraph of example body):
|
||||
- "第1章", "第一章", "Chapter 1", "1 Introduction", "绪论"
|
||||
- The first paragraph with a Heading1-equivalent style after TOC
|
||||
|
||||
**End anchor patterns** (last paragraph before back matter):
|
||||
- "参考文献", "References", "致谢", "Acknowledgments"
|
||||
- The last paragraph before appendices or final sectPr
|
||||
|
||||
```python
|
||||
# Pseudocode for finding replacement range
|
||||
for i, element in enumerate(template_body_elements):
|
||||
text = get_text(element)
|
||||
style = get_style(element)
|
||||
if style in heading1_styles and ("第1章" in text or "Chapter 1" in text):
|
||||
replace_start = i
|
||||
if "参考文献" in text or "References" in text:
|
||||
replace_end = i
|
||||
break
|
||||
```
|
||||
|
||||
**CRITICAL**: Verify the range by printing what's inside:
|
||||
```
|
||||
Template elements [0..replace_start-1]: front matter (KEEP)
|
||||
Template elements [replace_start..replace_end]: example content (REPLACE)
|
||||
Template elements [replace_end+1..end]: back matter (KEEP)
|
||||
```
|
||||
|
||||
If replace_start or replace_end cannot be found, DO NOT proceed. Ask the user to identify the replacement boundaries.
|
||||
|
||||
### Step 3: Decide Overlay vs Base-Replace
|
||||
|
||||
Now that you know the structure:
|
||||
|
||||
| Observation | Decision |
|
||||
|-------------|----------|
|
||||
| Template has ≤30 paragraphs, no cover/TOC | **C-1: Overlay** (pure style template) |
|
||||
| Template has >100 paragraphs with cover/TOC/example sections | **C-2: Base-Replace** |
|
||||
| Template paragraph count ≈ user document | **C-1: Overlay** (similar structure) |
|
||||
| Template paragraph count >> user document (e.g., 263 vs 134) | **C-2: Base-Replace** |
|
||||
|
||||
### Step 4: For Base-Replace, execute the replacement
|
||||
|
||||
1. Load template as base (all files)
|
||||
2. Extract user content elements using `list(body)` — NOT `findall('w:p')` (which misses tables)
|
||||
3. Build new body: `template[0:replace_start] + cleaned_user_content + template[replace_end+1:]`
|
||||
4. Apply style mapping to every paragraph
|
||||
5. Clean direct formatting (see rules below)
|
||||
6. Rebuild document.xml, keeping template's namespace declarations
|
||||
7. Merge relationships (images + hyperlinks)
|
||||
8. Write output using template as ZIP base
|
||||
|
||||
---
|
||||
|
||||
## Style Mapping Strategy
|
||||
|
||||
When template style names differ from source style names, a mapping is required. **This step is mandatory** — skipping it is the #1 cause of formatting failures in template application.
|
||||
|
||||
### Step 0: Extract StyleIds from Both Documents (REQUIRED)
|
||||
|
||||
Before any template application, extract and compare styleIds from both documents:
|
||||
|
||||
```bash
|
||||
# Extract all styleIds from source
|
||||
$CLI analyze --input source.docx --styles-only
|
||||
# Output example:
|
||||
# Heading1 (paragraph, basedOn: Normal)
|
||||
# Heading2 (paragraph, basedOn: Normal)
|
||||
# Normal (paragraph)
|
||||
# ListBullet (paragraph, basedOn: Normal)
|
||||
|
||||
# Extract all styleIds from template
|
||||
$CLI analyze --input template.docx --styles-only
|
||||
# Output example:
|
||||
# 1 (paragraph, basedOn: a, name: "heading 1")
|
||||
# 2 (paragraph, basedOn: a, name: "heading 2")
|
||||
# 3 (paragraph, basedOn: a, name: "heading 3")
|
||||
# a (paragraph, name: "Normal")
|
||||
# a0 (character, name: "Default Paragraph Font")
|
||||
```
|
||||
|
||||
**Critical distinction**: `w:styleId` vs `w:name`:
|
||||
```xml
|
||||
<!-- styleId="1" but name="heading 1" -->
|
||||
<w:style w:type="paragraph" w:styleId="1">
|
||||
<w:name w:val="heading 1"/>
|
||||
<w:basedOn w:val="a"/>
|
||||
</w:style>
|
||||
```
|
||||
|
||||
The `w:styleId` attribute is what `<w:pStyle w:val="..."/>` references. The `w:name` attribute is the human-readable display name. **They can be completely different.** Many CJK templates use numeric styleIds (`1`, `2`, `3`, `a`, `a0`) instead of English names.
|
||||
|
||||
### Tier 1: Exact StyleId Match
|
||||
If source uses `Heading1` and template defines `Heading1` as a styleId, map directly. No action needed.
|
||||
|
||||
### Tier 2: Name-Based Match
|
||||
If no exact styleId match, try matching by `w:name` attribute:
|
||||
- Source `Heading1` (name="heading 1") → Template styleId `1` (name="heading 1")
|
||||
- Match is case-insensitive on the name value
|
||||
|
||||
Within the same type, also try matching by:
|
||||
- Built-in style ID (Word's internal ID, e.g., heading 1 = built-in ID 1)
|
||||
- Style type (paragraph → paragraph, character → character, table → table)
|
||||
|
||||
### Tier 3: Manual Mapping
|
||||
For renamed or custom styles, provide an explicit mapping:
|
||||
|
||||
```json
|
||||
{
|
||||
"styleMap": {
|
||||
"Heading1": "1",
|
||||
"Heading2": "2",
|
||||
"Heading3": "3",
|
||||
"Heading4": "3",
|
||||
"Normal": "a",
|
||||
"BodyText": "a",
|
||||
"ListBullet": "a",
|
||||
"CompanyName": "Title",
|
||||
"OldTableStyle": "TableGrid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Non-Standard StyleId Patterns
|
||||
|
||||
| Template Origin | StyleId Pattern | Example |
|
||||
|----------------|-----------------|---------|
|
||||
| Chinese Word (default) | Numeric/alphabetic | `1`, `2`, `3`, `a`, `a0` |
|
||||
| English Word (default) | English names | `Heading1`, `Normal`, `Title` |
|
||||
| Google Docs export | Prefixed | `Subtitle`, `NormalWeb` |
|
||||
| WPS Office | Mixed | `1`, `Heading1`, custom names |
|
||||
| Academic templates | Custom | `ThesisHeading1`, `ThesisBody` |
|
||||
|
||||
### Building the Mapping Table
|
||||
|
||||
Follow this algorithm:
|
||||
|
||||
1. **List source styleIds** actually used in `document.xml` (not all defined in `styles.xml`):
|
||||
```python
|
||||
# Pseudocode: find all unique pStyle values in source document.xml
|
||||
used_styles = set()
|
||||
for p in body.iter('w:p'):
|
||||
pStyle = p.find('w:pPr/w:pStyle')
|
||||
if pStyle is not None:
|
||||
used_styles.add(pStyle.get('val'))
|
||||
```
|
||||
|
||||
2. **For each used style**, find the best match in template:
|
||||
- First try: exact styleId match
|
||||
- Second try: match by `w:name` value (case-insensitive)
|
||||
- Third try: match by style purpose (any heading → template's heading style)
|
||||
- Fallback: map to template's default paragraph style (usually `Normal` or `a`)
|
||||
|
||||
3. **Validate the mapping** — every source styleId must map to an existing template styleId:
|
||||
```
|
||||
✓ Heading1 → 1 (name match: "heading 1")
|
||||
✓ Heading2 → 2 (name match: "heading 2")
|
||||
✓ Normal → a (name match: "Normal")
|
||||
✗ CustomCallout → ??? (no match found, will fallback to 'a')
|
||||
```
|
||||
|
||||
4. **Apply the mapping** when copying content — update every `<w:pStyle w:val="..."/>`:
|
||||
```xml
|
||||
<!-- Source -->
|
||||
<w:pPr><w:pStyle w:val="Heading1"/></w:pPr>
|
||||
<!-- After mapping -->
|
||||
<w:pPr><w:pStyle w:val="1"/></w:pPr>
|
||||
```
|
||||
|
||||
### Unmapped Styles
|
||||
Styles in the source document that have no match in the template are logged as warnings:
|
||||
```
|
||||
WARNING: Style 'CustomCallout' has no mapping in template. Content will fall back to 'a' (Normal).
|
||||
```
|
||||
|
||||
The content is preserved; only the style reference is updated to the template's default paragraph style.
|
||||
|
||||
### C-2 BASE-REPLACE: Additional StyleId Considerations
|
||||
|
||||
When using the template as a base document (C-2 strategy), the template's `styles.xml` is already in place. You must:
|
||||
|
||||
1. **Never copy source `styles.xml`** — the template's styles are the authority
|
||||
2. **Map every content paragraph's pStyle** to the template's styleId before insertion
|
||||
3. **Strip direct formatting selectively** (see detailed rules below) — let the template style control appearance
|
||||
4. **Verify table styles** — if source tables use `TableGrid` but template defines it as `a3` or similar, remap `<w:tblStyle>` too
|
||||
5. **Check character styles** — `rPr` inside runs may reference character styles like `Hyperlink` or `Strong` that have different IDs in the template
|
||||
|
||||
### Direct Formatting Cleanup Rules (Detailed)
|
||||
|
||||
When copying content from source to template, apply these rules to EACH paragraph and run:
|
||||
|
||||
**REMOVE from `<w:rPr>`:**
|
||||
- `<w:rFonts w:ascii="..." w:hAnsi="..."/>` — Latin font overrides (EXCEPT: keep `w:eastAsia`)
|
||||
- `<w:sz>`, `<w:szCs>` — font size (let style control)
|
||||
- `<w:color>` — text color
|
||||
- `<w:highlight>` — highlight color
|
||||
- `<w:shd>` — shading
|
||||
- `<w:b>`, `<w:i>` — bold/italic UNLESS the source style requires it (e.g., emphasis)
|
||||
- `<w:u>` — underline
|
||||
- `<w:spacing>` — character spacing
|
||||
|
||||
**KEEP in `<w:rPr>`:**
|
||||
- `<w:rFonts w:eastAsia="宋体"/>` — CJK font declaration (MUST keep, or Chinese text renders wrong)
|
||||
- `<w:rFonts w:eastAsia="华文中宋"/>` — same reason
|
||||
- Anything inside `<w:drawing>` — image references (handle separately via rId remapping)
|
||||
|
||||
**REMOVE from `<w:pPr>`:**
|
||||
- `<w:pBdr>` — paragraph borders
|
||||
- `<w:shd>` — paragraph shading
|
||||
- `<w:spacing>` — line/paragraph spacing (let style control)
|
||||
- `<w:jc>` — justification (let style control)
|
||||
- `<w:tabs>` — custom tab stops
|
||||
- `<w:rPr>` inside pPr — default run formatting for the paragraph
|
||||
|
||||
**KEEP in `<w:pPr>`:**
|
||||
- `<w:pStyle>` — style reference (after mapping to template's styleId)
|
||||
- `<w:sectPr>` — section properties (if intentionally inserting section breaks)
|
||||
- `<w:numPr>` — numbering reference (after mapping numId to template's numbering)
|
||||
|
||||
**Table cells (`<w:tc>`):**
|
||||
Apply the same rPr/pPr cleanup to every paragraph inside every cell. Also:
|
||||
- Keep `<w:tcPr>` structural properties (column span, row span, width)
|
||||
- Remove `<w:tcPr><w:shd>` (cell shading — let table style control)
|
||||
|
||||
---
|
||||
|
||||
## Relationship ID Remapping
|
||||
|
||||
When copying parts (headers, footers, images) from the template into the source package, relationship IDs (`r:id`) may collide.
|
||||
|
||||
**Problem**:
|
||||
- Source has `rId7` → `image1.png`
|
||||
- Template has `rId7` → `header1.xml`
|
||||
- Copying template's `rId7` overwrites source's image reference
|
||||
|
||||
**Solution**:
|
||||
1. Scan source's `document.xml.rels` for all existing `rId` values
|
||||
2. Find the maximum numeric ID (e.g., `rId12`)
|
||||
3. Remap all template relationship IDs starting from `rId13`
|
||||
4. Update all references in copied parts to use new IDs
|
||||
|
||||
```xml
|
||||
<!-- Template original -->
|
||||
<Relationship Id="rId1" Type="...header" Target="header1.xml" />
|
||||
|
||||
<!-- After remapping into source package -->
|
||||
<Relationship Id="rId13" Type="...header" Target="header1.xml" />
|
||||
|
||||
<!-- Update sectPr reference -->
|
||||
<w:headerReference w:type="default" r:id="rId13" />
|
||||
```
|
||||
|
||||
### Hyperlink Relationship Merging
|
||||
|
||||
When the source document contains external hyperlinks (e.g., URLs in references or footnotes), these are stored as relationships in `word/_rels/document.xml.rels`:
|
||||
|
||||
```xml
|
||||
<Relationship Id="rId15" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
|
||||
Target="https://example.com/paper" TargetMode="External"/>
|
||||
```
|
||||
|
||||
The corresponding text in document.xml references this rId:
|
||||
```xml
|
||||
<w:hyperlink r:id="rId15">
|
||||
<w:r><w:t>https://example.com/paper</w:t></w:r>
|
||||
</w:hyperlink>
|
||||
```
|
||||
|
||||
**Merging steps:**
|
||||
1. Scan source document.xml for all `<w:hyperlink r:id="...">` elements
|
||||
2. For each, find the corresponding relationship in source's rels file
|
||||
3. Check if template already has a relationship with the same Target URL
|
||||
- If yes: reuse the existing rId, update the hyperlink reference
|
||||
- If no: assign a new rId (starting from template's max rId + 1), add the relationship to template's rels, update the hyperlink reference
|
||||
4. Also check for hyperlink relationships used in footnotes (`word/_rels/footnotes.xml.rels`) and endnotes
|
||||
|
||||
**Common mistake:** Copying hyperlink paragraphs without merging rels → hyperlinks silently break (clicking does nothing in Word).
|
||||
|
||||
---
|
||||
|
||||
## XSD Gate-Check
|
||||
|
||||
### What It Is
|
||||
|
||||
After template application, the output document **MUST** pass `business-rules.xsd` validation. This is a **hard gate** — if it fails, the document is **NOT deliverable**.
|
||||
|
||||
### What business-rules.xsd Checks
|
||||
|
||||
| Rule | What It Validates |
|
||||
|------|-------------------|
|
||||
| Template styles exist | All styles referenced by content paragraphs are defined in `styles.xml` |
|
||||
| Margins match | Page margins match template specification |
|
||||
| Fonts correct | `w:docDefaults` fonts match template's font scheme |
|
||||
| Heading hierarchy | Heading levels are sequential (no H1 → H3 without H2) |
|
||||
| Required styles present | `Normal`, `Heading1`-`Heading3`, `TableGrid` exist |
|
||||
| Page size | Matches template's declared page size |
|
||||
|
||||
### Handling Failures
|
||||
|
||||
```
|
||||
GATE-CHECK FAILED:
|
||||
- Style 'CustomStyle1' referenced in paragraph 14 but not defined in styles.xml
|
||||
- Margin w:left=1080 does not match template requirement 1440
|
||||
```
|
||||
|
||||
Fix each failure:
|
||||
1. **Missing style**: Add the style definition to `styles.xml`, or remap the paragraph to an existing style
|
||||
2. **Margin mismatch**: Update `w:sectPr` margins to match template
|
||||
3. **Font mismatch**: Update `w:docDefaults` to match template font scheme
|
||||
4. **Heading hierarchy gap**: Insert intermediate heading levels or adjust existing levels
|
||||
|
||||
Re-validate after every fix until gate-check passes.
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Orphaned Numbering References
|
||||
|
||||
**Problem**: Source document uses `w:numId="5"` in list paragraphs, but after replacing `numbering.xml` with the template's version, numbering ID 5 doesn't exist.
|
||||
|
||||
**Symptom**: Lists appear as plain paragraphs (no bullets/numbers).
|
||||
|
||||
**Fix**:
|
||||
- Map source numbering IDs to template numbering IDs
|
||||
- Update all `w:numId` references in document content
|
||||
- Or merge source numbering definitions into template's `numbering.xml`
|
||||
|
||||
### 2. Missing Theme Colors
|
||||
|
||||
**Problem**: Source document's styles reference theme colors (`w:themeColor="accent1"`) that have different values in the template's theme.
|
||||
|
||||
**Symptom**: Colors change unexpectedly (usually acceptable — this IS the point of re-theming). But if a style uses `w:color` with both `w:val` and `w:themeColor`, the theme color wins in Word.
|
||||
|
||||
**Fix**: Review color changes. If specific colors must be preserved, use explicit `w:val` without `w:themeColor`.
|
||||
|
||||
### 3. Section Property Conflicts
|
||||
|
||||
**Problem**: Source document has multiple sections (e.g., portrait + landscape pages), but the template assumes a single section.
|
||||
|
||||
**Symptom**: All sections get the same margins/orientation, breaking landscape pages.
|
||||
|
||||
**Fix**:
|
||||
- Only apply template section properties to the final `w:sectPr` in `w:body`
|
||||
- Preserve intermediate `w:sectPr` elements (inside `w:pPr`) from the source
|
||||
- Or apply template properties to all sections but preserve orientation overrides
|
||||
|
||||
### 4. Embedded Font Conflicts
|
||||
|
||||
**Problem**: Template specifies fonts not available on the target system.
|
||||
|
||||
**Fix**: Either embed fonts in the DOCX (`word/fonts/`) or use web-safe alternatives:
|
||||
- Calibri → available on Windows/Mac/Office online
|
||||
- Arial → universal fallback
|
||||
- Times New Roman → universal serif fallback
|
||||
|
||||
### 5. Broken Style Inheritance
|
||||
|
||||
**Problem**: Template has `Heading1` based on `Normal`, but after applying template, `Normal` has different properties, cascading unwanted changes to headings.
|
||||
|
||||
**Fix**: Verify the `w:basedOn` chain for all critical styles. Ensure base styles are also correctly transferred from template.
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After template application, verify:
|
||||
|
||||
1. **Content preserved** — text diff shows zero content changes
|
||||
2. **Gate-check passed** — `business-rules.xsd` validation succeeds
|
||||
3. **Styles applied** — headings, body text, tables use template formatting
|
||||
4. **Images intact** — all images render correctly (relationship IDs valid)
|
||||
5. **Lists working** — numbered and bulleted lists display correctly
|
||||
6. **Headers/footers** — template headers/footers appear on all pages
|
||||
7. **Page layout** — margins, page size, orientation match template
|
||||
8. **No corruption** — file opens without errors in Word
|
||||
@@ -0,0 +1,200 @@
|
||||
# Track Changes Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Track Changes in OpenXML uses revision markup elements to record insertions, deletions, and formatting changes. Each revision has a unique ID, author, and timestamp.
|
||||
|
||||
---
|
||||
|
||||
## Insertion: `<w:ins>`
|
||||
|
||||
Wraps runs that were inserted during tracking:
|
||||
|
||||
```xml
|
||||
<w:ins w:id="1" w:author="John Smith" w:date="2026-03-21T10:30:00Z">
|
||||
<w:r>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
|
||||
<w:sz w:val="22" />
|
||||
</w:rPr>
|
||||
<w:t>This text was inserted.</w:t>
|
||||
</w:r>
|
||||
</w:ins>
|
||||
```
|
||||
|
||||
- `w:id` — unique revision ID (integer, must be unique across document)
|
||||
- `w:author` — free text string identifying the author
|
||||
- `w:date` — ISO 8601 format with timezone: `YYYY-MM-DDTHH:MM:SSZ`
|
||||
- Content inside is normal runs (`w:r`) with optional formatting
|
||||
|
||||
---
|
||||
|
||||
## Deletion: `<w:del>`
|
||||
|
||||
Wraps runs that were deleted during tracking:
|
||||
|
||||
```xml
|
||||
<w:del w:id="2" w:author="John Smith" w:date="2026-03-21T10:31:00Z">
|
||||
<w:r>
|
||||
<w:rPr>
|
||||
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" />
|
||||
<w:sz w:val="22" />
|
||||
</w:rPr>
|
||||
<w:delText xml:space="preserve">This text was deleted.</w:delText>
|
||||
</w:r>
|
||||
</w:del>
|
||||
```
|
||||
|
||||
**CRITICAL**: Inside `<w:del>`, text MUST use `<w:delText>`, NOT `<w:t>`. Using `<w:t>` inside a deletion is invalid and will cause corruption or unexpected behavior. Word may silently repair it, but other consumers will fail.
|
||||
|
||||
---
|
||||
|
||||
## Formatting Change: `<w:rPrChange>`
|
||||
|
||||
Records that a run's formatting was changed. Placed inside `w:rPr`, it stores the **previous** formatting:
|
||||
|
||||
```xml
|
||||
<w:r>
|
||||
<w:rPr>
|
||||
<w:b /> <!-- Current: bold -->
|
||||
<w:rPrChange w:id="3" w:author="Jane Doe" w:date="2026-03-21T11:00:00Z">
|
||||
<w:rPr>
|
||||
<!-- Previous: not bold (empty rPr means no formatting) -->
|
||||
</w:rPr>
|
||||
</w:rPrChange>
|
||||
</w:rPr>
|
||||
<w:t>This text was made bold.</w:t>
|
||||
</w:r>
|
||||
```
|
||||
|
||||
The outer `w:rPr` holds the **new** (current) formatting. The `w:rPrChange` child holds the **old** (previous) formatting.
|
||||
|
||||
---
|
||||
|
||||
## Paragraph Property Change: `<w:pPrChange>`
|
||||
|
||||
Records paragraph-level formatting changes (alignment, spacing, style):
|
||||
|
||||
```xml
|
||||
<w:pPr>
|
||||
<w:jc w:val="center" /> <!-- Current: centered -->
|
||||
<w:pPrChange w:id="4" w:author="Jane Doe" w:date="2026-03-21T11:05:00Z">
|
||||
<w:pPr>
|
||||
<w:jc w:val="left" /> <!-- Previous: left-aligned -->
|
||||
</w:pPr>
|
||||
</w:pPrChange>
|
||||
</w:pPr>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Revision ID Management
|
||||
|
||||
- Every revision element (`w:ins`, `w:del`, `w:rPrChange`, `w:pPrChange`, `w:tblPrChange`, etc.) requires a `w:id` attribute
|
||||
- IDs must be **unique integers** across the entire document
|
||||
- IDs should be **monotonically increasing** (not strictly required, but expected by Word)
|
||||
- When adding revisions, scan for the current maximum `w:id` and increment from there
|
||||
|
||||
```
|
||||
Existing max ID: 47
|
||||
New insertion: w:id="48"
|
||||
New deletion: w:id="49"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Author and Date
|
||||
|
||||
- **Author**: Free text. Use consistent strings (e.g., `"DocxToolkit"` for all automated edits)
|
||||
- **Date**: ISO 8601 with UTC timezone marker: `2026-03-21T10:30:00Z`
|
||||
- Must include the `T` separator and `Z` suffix (or `+HH:MM` offset)
|
||||
- Omitting the date is allowed but not recommended
|
||||
|
||||
---
|
||||
|
||||
## Operations
|
||||
|
||||
### Propose Insertion
|
||||
|
||||
Add `<w:ins>` wrapper around new content at the target location:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:r><w:t>Existing text. </w:t></w:r>
|
||||
<w:ins w:id="5" w:author="DocxToolkit" w:date="2026-03-21T12:00:00Z">
|
||||
<w:r><w:t>Proposed new text. </w:t></w:r>
|
||||
</w:ins>
|
||||
<w:r><w:t>More existing text.</w:t></w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
### Propose Deletion
|
||||
|
||||
Wrap existing content in `<w:del>` and change `<w:t>` to `<w:delText>`:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:r><w:t>Keep this. </w:t></w:r>
|
||||
<w:del w:id="6" w:author="DocxToolkit" w:date="2026-03-21T12:01:00Z">
|
||||
<w:r>
|
||||
<w:rPr><w:b /></w:rPr>
|
||||
<w:delText>Remove this.</w:delText>
|
||||
</w:r>
|
||||
</w:del>
|
||||
<w:r><w:t> Keep this too.</w:t></w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
### Accept a Tracked Change
|
||||
|
||||
- **Accept insertion**: Remove the `<w:ins>` wrapper, keep the inner runs as normal content
|
||||
- **Accept deletion**: Remove the entire `<w:del>` element and its content
|
||||
|
||||
### Reject a Tracked Change
|
||||
|
||||
- **Reject insertion**: Remove the entire `<w:ins>` element and its content
|
||||
- **Reject deletion**: Remove the `<w:del>` wrapper, change `<w:delText>` back to `<w:t>`
|
||||
|
||||
---
|
||||
|
||||
## Cross-Paragraph Operations
|
||||
|
||||
### Deleting a Paragraph Break (Merging Paragraphs)
|
||||
|
||||
When tracked deletion spans a paragraph boundary, use `<w:pPrChange>` on the merged paragraph:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:pPrChange w:id="7" w:author="DocxToolkit" w:date="2026-03-21T12:05:00Z">
|
||||
<w:pPr>
|
||||
<w:pStyle w:val="Normal" />
|
||||
</w:pPr>
|
||||
</w:pPrChange>
|
||||
</w:pPr>
|
||||
<w:r><w:t>First paragraph text. </w:t></w:r>
|
||||
<w:del w:id="8" w:author="DocxToolkit" w:date="2026-03-21T12:05:00Z">
|
||||
<w:r><w:delText> </w:delText></w:r>
|
||||
</w:del>
|
||||
<w:r><w:t>Second paragraph text (now merged).</w:t></w:r>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
### Inserting a New Paragraph
|
||||
|
||||
The entire new paragraph is wrapped in `<w:ins>`:
|
||||
|
||||
```xml
|
||||
<w:p>
|
||||
<w:pPr>
|
||||
<w:rPr>
|
||||
<w:ins w:id="9" w:author="DocxToolkit" w:date="2026-03-21T12:10:00Z" />
|
||||
</w:rPr>
|
||||
</w:pPr>
|
||||
<w:ins w:id="10" w:author="DocxToolkit" w:date="2026-03-21T12:10:00Z">
|
||||
<w:r><w:t>Entirely new paragraph.</w:t></w:r>
|
||||
</w:ins>
|
||||
</w:p>
|
||||
```
|
||||
|
||||
The paragraph mark itself is marked as inserted via `w:ins` inside `w:pPr > w:rPr`.
|
||||
@@ -0,0 +1,506 @@
|
||||
# Troubleshooting Guide — Symptom-Driven
|
||||
|
||||
## How to Use This Guide
|
||||
|
||||
Search by the **SYMPTOM** you observe, not the technical concept. Each entry follows:
|
||||
- **Symptom** — what you see or what the user reports
|
||||
- **Diagnosis** — how to confirm the root cause
|
||||
- **Fix** — exact steps, commands, or code
|
||||
- **Prevention** — how to avoid it next time
|
||||
|
||||
**Quick search keywords:** headings wrong, body text, repair, corrupt, font, tables missing, images missing, TOC broken, update table, page break, section break, hyperlink, numbered list, bullets, margins, page size, Chinese tofu, cover page, track changes, revision marks
|
||||
|
||||
---
|
||||
|
||||
## 1. "All headings look like body text" (Heading Styles Not Applied)
|
||||
|
||||
**Symptom:** After template application, headings have no formatting — they look like Normal paragraphs. Font size, bold, spacing are all wrong.
|
||||
|
||||
**Diagnosis:** The `pStyle` values in `document.xml` don't match the `styleId` values in `styles.xml`.
|
||||
|
||||
Common mismatches:
|
||||
- Source uses `Heading1` but template defines the style as `1` (Chinese templates often use numeric styleIds)
|
||||
- Source uses `heading1` (lowercase) but template has `Heading1` (case-sensitive!)
|
||||
- `pStyle` references a style that simply doesn't exist in the output's `styles.xml`
|
||||
|
||||
Check with:
|
||||
```bash
|
||||
# List all pStyle values used in the document
|
||||
$CLI analyze --input output.docx | grep -i "pStyle"
|
||||
|
||||
# List all styleIds defined in styles.xml
|
||||
$CLI analyze --input template.docx --part styles | grep "styleId"
|
||||
```
|
||||
|
||||
**Fix:** Build a styleId mapping table before applying the template. Update every `pStyle` value in the document content.
|
||||
|
||||
```csharp
|
||||
// Build mapping: source styleId → template styleId
|
||||
var mapping = new Dictionary<string, string>();
|
||||
// Compare by style name (w:name), not by styleId
|
||||
foreach (var srcStyle in sourceStyles)
|
||||
{
|
||||
var templateStyle = templateStyles.FirstOrDefault(
|
||||
s => s.StyleName?.Val?.Value == srcStyle.StyleName?.Val?.Value);
|
||||
if (templateStyle != null)
|
||||
mapping[srcStyle.StyleId!] = templateStyle.StyleId!;
|
||||
}
|
||||
|
||||
// Apply mapping to all paragraphs
|
||||
foreach (var para in body.Descendants<Paragraph>())
|
||||
{
|
||||
var pStyle = para.ParagraphProperties?.ParagraphStyleId;
|
||||
if (pStyle != null && mapping.TryGetValue(pStyle.Val!, out var newId))
|
||||
pStyle.Val = newId;
|
||||
}
|
||||
```
|
||||
|
||||
**Prevention:** ALWAYS extract and compare styleIds from both source and template before template application. Never assume styleIds are the same across documents.
|
||||
|
||||
---
|
||||
|
||||
## 2. "Document opens with repair warnings" (XML Corruption)
|
||||
|
||||
**Symptom:** Word says "We found a problem with some content" or "Word found unreadable content" when opening.
|
||||
|
||||
**Diagnosis:** Element ordering is wrong. OpenXML is strict about child element order.
|
||||
|
||||
Common violations:
|
||||
- `pPr` must come before runs in `w:p`
|
||||
- `tblPr` must come before `tblGrid` in `w:tbl`
|
||||
- `rPr` must come before `t`/`br`/`tab` in `w:r`
|
||||
- `trPr` must come before `tc` in `w:tr`
|
||||
- `tcPr` must come before content in `w:tc`
|
||||
|
||||
```bash
|
||||
# Validate to find ordering issues
|
||||
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
|
||||
|
||||
# Auto-fix element ordering
|
||||
$CLI fix-order --input doc.docx
|
||||
|
||||
# Re-validate
|
||||
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
$CLI fix-order --input doc.docx
|
||||
```
|
||||
|
||||
If auto-fix doesn't resolve it, unpack and inspect manually:
|
||||
```bash
|
||||
$CLI unpack --input doc.docx --output unpacked/
|
||||
# Check word/document.xml for ordering issues
|
||||
# Fix, then repack:
|
||||
$CLI pack --input unpacked/ --output fixed.docx
|
||||
```
|
||||
|
||||
**Prevention:** Read `references/openxml_element_order.md` before writing any XML manipulation code. Always append properties elements first, then content elements.
|
||||
|
||||
---
|
||||
|
||||
## 3. "All text is in wrong font" (Font Contamination)
|
||||
|
||||
**Symptom:** Template specifies 宋体/Times New Roman but document shows Google Sans, Arial, Calibri, or whatever font the source document used.
|
||||
|
||||
**Diagnosis:** Source document's `rPr` contains inline `rFonts` declarations that override template styles. Direct formatting always wins over style-based formatting in OpenXML.
|
||||
|
||||
```bash
|
||||
# Check for font contamination
|
||||
$CLI analyze --input output.docx | grep -i "font"
|
||||
# Look for rFonts in the content — if present, they're overriding styles
|
||||
```
|
||||
|
||||
**Fix:** Strip `rFonts` from `rPr` when copying content, but KEEP `w:eastAsia` for CJK text:
|
||||
|
||||
```csharp
|
||||
foreach (var rPr in body.Descendants<RunProperties>())
|
||||
{
|
||||
var rFonts = rPr.GetFirstChild<RunFonts>();
|
||||
if (rFonts != null)
|
||||
{
|
||||
// Preserve EastAsia font for CJK — removing it causes tofu (□□□)
|
||||
var eastAsia = rFonts.EastAsia?.Value;
|
||||
rFonts.Remove();
|
||||
|
||||
// Re-add only eastAsia if it was set and text contains CJK
|
||||
if (!string.IsNullOrEmpty(eastAsia))
|
||||
{
|
||||
rPr.Append(new RunFonts { EastAsia = eastAsia });
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Also strip these common direct formatting overrides:
|
||||
- `w:sz` / `w:szCs` (font size)
|
||||
- `w:color` (text color)
|
||||
- `w:b` / `w:i` when they contradict the style
|
||||
|
||||
**Prevention:** Always clean direct formatting when copying content between documents. Keep only `pStyle`/`rStyle` references and `w:t` text.
|
||||
|
||||
---
|
||||
|
||||
## 4. "Tables are missing" (Tables Lost During Copy)
|
||||
|
||||
**Symptom:** Source had 5 tables but output only has 2 (or 0).
|
||||
|
||||
**Diagnosis:** Code used `body.findall('w:p')` or `body.Descendants<Paragraph>()` at the top level instead of iterating all children. This skips `w:tbl` elements.
|
||||
|
||||
```bash
|
||||
# Verify table count
|
||||
$CLI analyze --input source.docx | grep -i "table"
|
||||
$CLI analyze --input output.docx | grep -i "table"
|
||||
```
|
||||
|
||||
**Fix:** Use `list(body)` or `body.ChildElements` to get ALL top-level children including tables:
|
||||
|
||||
```csharp
|
||||
// WRONG — skips tables, section properties, and other non-paragraph elements
|
||||
var paragraphs = body.Elements<Paragraph>();
|
||||
|
||||
// CORRECT — gets everything: paragraphs, tables, SDT blocks, etc.
|
||||
var allElements = body.ChildElements.ToList();
|
||||
```
|
||||
|
||||
In Python with lxml:
|
||||
```python
|
||||
# WRONG
|
||||
elements = body.findall('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p')
|
||||
|
||||
# CORRECT
|
||||
elements = list(body) # all direct children
|
||||
```
|
||||
|
||||
**Prevention:** Always use `list(body)` or `body.ChildElements` for iteration, never filter by a single element type alone when copying content.
|
||||
|
||||
---
|
||||
|
||||
## 5. "Images are missing or show broken icon"
|
||||
|
||||
**Symptom:** Image placeholders appear but images don't render. Or images are completely absent.
|
||||
|
||||
**Diagnosis:** The `r:embed` rId in `w:drawing` doesn't match any relationship in `document.xml.rels`, or the media file wasn't copied to the output ZIP.
|
||||
|
||||
```bash
|
||||
# Check relationships
|
||||
$CLI analyze --input output.docx --part rels | grep -i "image"
|
||||
|
||||
# Check if media files exist
|
||||
$CLI unpack --input output.docx --output unpacked/
|
||||
ls unpacked/word/media/
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
1. Check source rels for image file paths
|
||||
2. Copy media files from source to output
|
||||
3. Add/update relationships in output rels
|
||||
4. Update `r:embed` values in drawing elements
|
||||
|
||||
```csharp
|
||||
// When copying content with images between documents:
|
||||
foreach (var drawing in body.Descendants<Drawing>())
|
||||
{
|
||||
var blip = drawing.Descendants<DocumentFormat.OpenXml.Drawing.Blip>().FirstOrDefault();
|
||||
if (blip?.Embed?.Value != null)
|
||||
{
|
||||
var sourceRel = sourcePart.GetReferenceRelationship(blip.Embed.Value);
|
||||
// Copy the image part to the target document
|
||||
var imagePart = targetPart.AddImagePart(ImagePartType.Png);
|
||||
using var stream = sourcePart.GetPartById(blip.Embed.Value).GetStream();
|
||||
imagePart.FeedData(stream);
|
||||
// Update the rId reference
|
||||
blip.Embed = targetPart.GetIdOfPart(imagePart);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Prevention:** Always do rId remapping + media file copy when moving content between documents. Never assume rIds are portable across documents.
|
||||
|
||||
---
|
||||
|
||||
## 6. "TOC shows stale/wrong entries" or "Update Table doesn't work"
|
||||
|
||||
**Symptom:** Table of contents shows the template's example entries (e.g., "第1章 绪论...1") instead of actual headings. Or clicking "Update Table" in Word does nothing.
|
||||
|
||||
**Diagnosis:**
|
||||
- **Stale entries (normal):** TOC entries are static text cached inside the field. They don't auto-update until the user explicitly updates in Word.
|
||||
- **Update Table fails:** The SDT wrapper or field code structure is damaged. The TOC in real templates is a mixed structure: SDT block + field code + static entries.
|
||||
|
||||
```bash
|
||||
# Check if TOC SDT exists
|
||||
$CLI analyze --input output.docx | grep -i "sdt\|toc"
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
- **If entries are just stale:** This is expected behavior. The user must right-click TOC, then "Update Field" in Word. Or enable auto-update:
|
||||
```csharp
|
||||
// See FieldAndTocSamples.EnableUpdateFieldsOnOpen()
|
||||
FieldAndTocSamples.EnableUpdateFieldsOnOpen(settingsPart);
|
||||
```
|
||||
- **If SDT is damaged:** Keep the entire SDT block from the template intact. Do not modify it.
|
||||
- **If field code is missing:** Ensure the TOC contains: `fldChar begin` + `instrText` + `fldChar separate` + static entries + `fldChar end`. See `FieldAndTocSamples.CreateMixedTocStructure()` for the complete pattern.
|
||||
- **If you rebuilt TOC from scratch (common mistake):** You likely destroyed the SDT wrapper. Use the template's original SDT block instead. See `Samples/FieldAndTocSamples.cs` method `CreateMixedTocStructure` for how real-world TOC is structured.
|
||||
|
||||
**Prevention:** When doing Base-Replace (C-2), keep the template's TOC zone completely untouched. Do not strip, rebuild, or modify the SDT block. The TOC will auto-update when the user opens in Word.
|
||||
|
||||
---
|
||||
|
||||
## 7. "Chapters don't start on new pages" (Missing Section Breaks)
|
||||
|
||||
**Symptom:** Content flows continuously without page breaks between chapters. Chapter 2 starts right after Chapter 1's last paragraph on the same page.
|
||||
|
||||
**Diagnosis:** No `sectPr` elements or page break paragraphs between chapters.
|
||||
|
||||
**Fix:** Insert a paragraph with `sectPr` in its `pPr` before each chapter heading, or insert a page break:
|
||||
|
||||
```csharp
|
||||
// Option 1: Section break (preserves per-section settings like headers/margins)
|
||||
var breakPara = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new SectionProperties(
|
||||
new SectionType { Val = SectionMarkValues.NextPage })));
|
||||
|
||||
// Option 2: Simple page break (lighter weight)
|
||||
var breakPara = new Paragraph(
|
||||
new Run(new Break { Type = BreakValues.Page }));
|
||||
|
||||
// Insert before each Heading1
|
||||
body.InsertBefore(breakPara, heading1Paragraph);
|
||||
```
|
||||
|
||||
**Prevention:** When copying content, insert page/section breaks before Heading1 paragraphs as needed. Check source document's section structure before copying.
|
||||
|
||||
---
|
||||
|
||||
## 8. "Hyperlinks don't work" (Broken Links)
|
||||
|
||||
**Symptom:** Clicking a hyperlink in the output document does nothing, or it navigates to the wrong URL.
|
||||
|
||||
**Diagnosis:** `w:hyperlink r:id` points to a relationship that doesn't exist in `document.xml.rels`.
|
||||
|
||||
```bash
|
||||
# Check hyperlink relationships
|
||||
$CLI analyze --input output.docx --part rels | grep -i "hyperlink"
|
||||
```
|
||||
|
||||
**Fix:** Merge source document's hyperlink relationships into output's rels file. Update rId references.
|
||||
|
||||
```csharp
|
||||
foreach (var hyperlink in body.Descendants<Hyperlink>())
|
||||
{
|
||||
if (hyperlink.Id?.Value != null)
|
||||
{
|
||||
var sourceRel = sourcePart.HyperlinkRelationships
|
||||
.FirstOrDefault(r => r.Id == hyperlink.Id.Value);
|
||||
if (sourceRel != null)
|
||||
{
|
||||
targetPart.AddHyperlinkRelationship(sourceRel.Uri, sourceRel.IsExternal);
|
||||
var newRel = targetPart.HyperlinkRelationships.Last();
|
||||
hyperlink.Id = newRel.Id;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Prevention:** Always merge ALL relationship types (images, hyperlinks, headers, footers) when combining documents. Never assume source rIds work in the target.
|
||||
|
||||
---
|
||||
|
||||
## 9. "Numbered lists show wrong numbers" or "Bullets disappeared"
|
||||
|
||||
**Symptom:** Lists that were numbered 1, 2, 3 now show 1, 1, 1 or have no numbers/bullets at all.
|
||||
|
||||
**Diagnosis:** `numId` in `pPr` references a numbering definition that doesn't exist in `numbering.xml`, or `abstractNumId` mapping is broken.
|
||||
|
||||
```bash
|
||||
# Check numbering definitions
|
||||
$CLI analyze --input output.docx --part numbering
|
||||
```
|
||||
|
||||
**Fix:** Map source numIds to template numIds, or merge numbering definitions:
|
||||
|
||||
```csharp
|
||||
// 1. Copy abstractNum definitions from source to target numbering.xml
|
||||
// 2. Create new num entries pointing to the copied abstractNum
|
||||
// 3. Update all numId references in document content
|
||||
|
||||
var sourceNumbering = sourceNumberingPart.Numbering;
|
||||
var targetNumbering = targetNumberingPart.Numbering;
|
||||
|
||||
// Get max existing IDs to avoid collisions
|
||||
int maxAbstractNumId = targetNumbering.Elements<AbstractNum>()
|
||||
.Max(a => a.AbstractNumberId?.Value ?? 0) + 1;
|
||||
int maxNumId = targetNumbering.Elements<NumberingInstance>()
|
||||
.Max(n => n.NumberID?.Value ?? 0) + 1;
|
||||
```
|
||||
|
||||
**Prevention:** Include `numbering.xml` reconciliation in template application workflow. See `Samples/ListAndNumberingSamples.cs` for correct numbering setup.
|
||||
|
||||
---
|
||||
|
||||
## 10. "Page margins/size are wrong"
|
||||
|
||||
**Symptom:** Output has different margins, page size, or orientation than the template.
|
||||
|
||||
**Diagnosis:** Source document's `sectPr` is overriding the template's `sectPr`. The final `sectPr` (child of `body`) controls the last section's layout.
|
||||
|
||||
```bash
|
||||
# Compare section properties
|
||||
$CLI analyze --input template.docx | grep -i "sectPr\|margin\|pgSz"
|
||||
$CLI analyze --input output.docx | grep -i "sectPr\|margin\|pgSz"
|
||||
```
|
||||
|
||||
**Fix:** Use the template's final `sectPr`. For intermediate `sectPr` elements (multi-section documents), merge carefully.
|
||||
|
||||
```csharp
|
||||
// Replace output's final sectPr with template's
|
||||
var templateSectPr = templateBody.Elements<SectionProperties>().LastOrDefault();
|
||||
var outputSectPr = outputBody.Elements<SectionProperties>().LastOrDefault();
|
||||
|
||||
if (templateSectPr != null)
|
||||
{
|
||||
var cloned = templateSectPr.CloneNode(true) as SectionProperties;
|
||||
if (outputSectPr != null)
|
||||
outputBody.ReplaceChild(cloned!, outputSectPr);
|
||||
else
|
||||
outputBody.Append(cloned!);
|
||||
}
|
||||
```
|
||||
|
||||
**Prevention:** Always use the template's `sectPr` as authority for page layout. Strip source document's `sectPr` before copying content.
|
||||
|
||||
---
|
||||
|
||||
## 11. "Chinese text renders as boxes/tofu"
|
||||
|
||||
**Symptom:** Chinese characters display as square boxes (□□□) or missing glyphs.
|
||||
|
||||
**Diagnosis:** `rFonts w:eastAsia` is set to a font that doesn't exist on the system, or is missing entirely. Without an East Asian font declaration, the rendering engine may fall back to a font without CJK coverage.
|
||||
|
||||
**Fix:** Ensure all CJK text has `w:eastAsia` set to an available font:
|
||||
|
||||
```csharp
|
||||
foreach (var run in body.Descendants<Run>())
|
||||
{
|
||||
var text = run.InnerText;
|
||||
if (ContainsCjk(text))
|
||||
{
|
||||
var rPr = run.RunProperties ?? new RunProperties();
|
||||
var rFonts = rPr.GetFirstChild<RunFonts>();
|
||||
if (rFonts == null)
|
||||
{
|
||||
rFonts = new RunFonts();
|
||||
rPr.Append(rFonts);
|
||||
}
|
||||
// Set to a universally available CJK font
|
||||
rFonts.EastAsia = "SimSun"; // 宋体 — safest default
|
||||
if (run.RunProperties == null) run.PrependChild(rPr);
|
||||
}
|
||||
}
|
||||
|
||||
static bool ContainsCjk(string text)
|
||||
{
|
||||
return text.Any(c => c >= 0x4E00 && c <= 0x9FFF);
|
||||
}
|
||||
```
|
||||
|
||||
Common safe CJK fonts: 宋体 (SimSun), 黑体 (SimHei), 仿宋 (FangSong), 楷体 (KaiTi).
|
||||
|
||||
**Prevention:** When cleaning `rPr` formatting, ALWAYS preserve `w:eastAsia` font declarations. See also `references/cjk_typography.md`.
|
||||
|
||||
---
|
||||
|
||||
## 12. "Template's cover page / declaration page is missing"
|
||||
|
||||
**Symptom:** Output document starts directly with body content — no cover page, no declaration, no abstract, no table of contents. The template's structural front matter was discarded.
|
||||
|
||||
**Diagnosis:** Used Overlay (C-1) strategy when Base-Replace (C-2) was needed. Overlay applies styles to the source document but discards the template's structural content (cover, declaration, abstract, TOC).
|
||||
|
||||
```bash
|
||||
# Check template structure
|
||||
$CLI analyze --input template.docx
|
||||
# If template has >50 paragraphs with cover/TOC/declaration, C-2 is needed
|
||||
```
|
||||
|
||||
**Fix:** Use Base-Replace (C-2) strategy — template is the base, only replace the example body content zone with the user's content:
|
||||
|
||||
1. Identify the template's "body zone" (everything between TOC and final sectPr)
|
||||
2. Remove the template's example body content
|
||||
3. Insert the user's content into the body zone
|
||||
4. Keep everything else from the template (cover, declaration, abstract, TOC, sectPr)
|
||||
|
||||
```bash
|
||||
$CLI apply-template --input source.docx --template template.docx --output out.docx --strategy base-replace
|
||||
```
|
||||
|
||||
**Prevention:** Analyze template structure FIRST. If template has structural content (cover, TOC, declaration sections), always use C-2 (Base-Replace). Read `references/scenario_c_apply_template.md` for detailed decision criteria.
|
||||
|
||||
---
|
||||
|
||||
## 13. "Track changes markers appear unexpectedly"
|
||||
|
||||
**Symptom:** Output shows red/green revision marks (insertions, deletions) that weren't in the source document.
|
||||
|
||||
**Diagnosis:** Template had track changes enabled, or content was inserted as revisions rather than normal text.
|
||||
|
||||
```bash
|
||||
# Check for revision marks
|
||||
$CLI analyze --input output.docx | grep -i "revision\|ins\|del\|track"
|
||||
```
|
||||
|
||||
**Fix:** Accept all revisions by flattening `w:ins` and `w:del` elements:
|
||||
|
||||
```csharp
|
||||
// Accept insertions: unwrap w:ins, keep content
|
||||
foreach (var ins in body.Descendants<InsertedRun>().ToList())
|
||||
{
|
||||
var parent = ins.Parent!;
|
||||
foreach (var child in ins.ChildElements.ToList())
|
||||
{
|
||||
parent.InsertBefore(child.CloneNode(true), ins);
|
||||
}
|
||||
ins.Remove();
|
||||
}
|
||||
|
||||
// Accept deletions: remove w:del and its content entirely
|
||||
foreach (var del in body.Descendants<DeletedRun>().ToList())
|
||||
{
|
||||
del.Remove();
|
||||
}
|
||||
```
|
||||
|
||||
Or disable tracking in settings:
|
||||
```csharp
|
||||
var settings = settingsPart.Settings;
|
||||
var trackChanges = settings.GetFirstChild<TrackChanges>();
|
||||
trackChanges?.Remove();
|
||||
```
|
||||
|
||||
**Prevention:** Check template's `settings.xml` for `trackChanges` before starting. If present, accept all revisions in the template first.
|
||||
|
||||
---
|
||||
|
||||
## Recovery Strategy — When Multiple Issues Exist
|
||||
|
||||
When a document has multiple problems, fix them in this priority order:
|
||||
|
||||
```
|
||||
1. [Content_Types].xml — without this, nothing opens
|
||||
2. _rels/.rels — package relationships
|
||||
3. word/_rels/document.xml.rels — part relationships (images, hyperlinks)
|
||||
4. word/document.xml — element ordering (fix-order)
|
||||
5. word/styles.xml — style definitions and styleId mapping
|
||||
6. word/numbering.xml — list/numbering definitions
|
||||
7. Everything else — headers, footers, comments, settings
|
||||
```
|
||||
|
||||
```bash
|
||||
# Full recovery pipeline
|
||||
$CLI unpack --input broken.docx --output unpacked/
|
||||
$CLI validate --input broken.docx --xsd assets/xsd/wml-subset.xsd # find all errors
|
||||
$CLI fix-order --input broken.docx # fix element ordering
|
||||
$CLI validate --input broken.docx --business # check business rules
|
||||
scripts/docx_preview.sh broken.docx # visual check
|
||||
```
|
||||
@@ -0,0 +1,294 @@
|
||||
# Professional Document Design & Typography Guide
|
||||
|
||||
## Table of Contents
|
||||
1. [Font Pairing](#font-pairing)
|
||||
2. [Font Sizes by Document Type](#font-sizes-by-document-type)
|
||||
3. [Line Spacing](#line-spacing)
|
||||
4. [Paragraph Spacing](#paragraph-spacing)
|
||||
5. [Page Layout](#page-layout)
|
||||
6. [Table Design](#table-design)
|
||||
7. [Color Schemes](#color-schemes)
|
||||
8. [Visual Hierarchy](#visual-hierarchy)
|
||||
9. [Quick Reference Defaults](#quick-reference-defaults)
|
||||
|
||||
---
|
||||
|
||||
## Font Pairing
|
||||
|
||||
### Recommended Pairs
|
||||
|
||||
| Headings | Body | Style | Best For |
|
||||
|----------|------|-------|----------|
|
||||
| Calibri Light | Calibri | Modern sans | Corporate reports |
|
||||
| Aptos | Aptos | Office 365 default | Modern business docs |
|
||||
| Cambria | Calibri | Serif + sans | Academic-corporate hybrid |
|
||||
| Times New Roman | Times New Roman | Traditional serif | Academic, legal |
|
||||
| Arial | Arial | Clean sans | Memos, internal docs |
|
||||
| Georgia | Garamond | Classical serif pair | Formal reports |
|
||||
|
||||
### Rules
|
||||
|
||||
- **Limit**: 2 font families max (3 if CJK mixed)
|
||||
- **Contrast**: Pair serif with sans-serif, OR use weight contrast within one family
|
||||
- **Consistency**: Same font for all body text, same font for all headings
|
||||
|
||||
---
|
||||
|
||||
## Font Sizes by Document Type
|
||||
|
||||
| Document Type | Body | H1 | H2 | H3 | Footnotes |
|
||||
|--------------|------|----|----|----|----|
|
||||
| **Business report** | 11pt | 18-20pt | 14-16pt | 12-13pt bold | 9pt |
|
||||
| **Business letter** | 11-12pt | — | — | — | 9-10pt |
|
||||
| **Memo** | 11pt | 14pt bold | 12pt bold | 11pt bold | 9pt |
|
||||
| **Contract / Legal** | 12pt | 14pt bold caps | 12pt bold | 12pt bold | 10pt |
|
||||
| **Academic (APA 7)** | 12pt | 12pt bold center | 12pt bold left | 12pt bold italic | 10pt |
|
||||
| **Resume / CV** | 10-11pt | 14-16pt | 12pt bold | 11pt bold | 8-9pt |
|
||||
| **Chinese 公文** | 三号(16pt) | 二号(22pt) | 三号(16pt) | 四号(14pt) | 小四(12pt) |
|
||||
|
||||
### OpenXML `w:sz` Values (half-points)
|
||||
|
||||
| Point Size | `w:sz` Val | Common Use |
|
||||
|-----------|-----------|------------|
|
||||
| 9pt | 18 | Footnotes, captions |
|
||||
| 10pt | 20 | Compact body text |
|
||||
| 10.5pt (五号) | 21 | CJK body small |
|
||||
| 11pt | 22 | Standard body (Calibri) |
|
||||
| 12pt (小四) | 24 | Standard body (TNR), CJK |
|
||||
| 14pt (四号) | 28 | CJK body, subheading |
|
||||
| 16pt (三号) | 32 | CJK heading, western H2 |
|
||||
| 18pt (小二) | 36 | Western H1 |
|
||||
| 22pt (二号) | 44 | CJK document title |
|
||||
| 26pt (一号) | 52 | Large title |
|
||||
|
||||
---
|
||||
|
||||
## Line Spacing
|
||||
|
||||
| Spacing | OpenXML `w:spacing line` | When to Use |
|
||||
|---------|--------------------------|-------------|
|
||||
| Single (1.0) | `line="240"` lineRule="auto" | Tables, footnotes, captions |
|
||||
| 1.08 (MS default) | `line="259"` lineRule="auto" | Modern Office documents |
|
||||
| 1.15 | `line="276"` lineRule="auto" | Business reports — best general default |
|
||||
| 1.5 | `line="360"` lineRule="auto" | Some academic, drafts for markup |
|
||||
| Double (2.0) | `line="480"` lineRule="auto" | APA/MLA manuscripts, legal briefs |
|
||||
| Fixed 28pt | `line="560"` lineRule="exact" | Chinese 公文 (GB/T 9704) |
|
||||
|
||||
**`lineRule` values**: `auto` = proportional (240 = 1 line), `exact` = fixed height, `atLeast` = minimum.
|
||||
|
||||
---
|
||||
|
||||
## Paragraph Spacing
|
||||
|
||||
| Element | Space Before (DXA) | Space After (DXA) |
|
||||
|---------|-------------------|-------------------|
|
||||
| Body paragraph | 0 | 120-160 (6-8pt) |
|
||||
| Heading 1 | 480 (24pt) | 120-240 |
|
||||
| Heading 2 | 360 (18pt) | 120 |
|
||||
| Heading 3 | 240 (12pt) | 80-120 |
|
||||
| List items | 0 | 40-80 (2-4pt) |
|
||||
| Block quote | 120-240 | 120-240 |
|
||||
| Table/Figure caption | 240 | 240 |
|
||||
|
||||
**Principle**: Space before a heading > space after, so heading visually "belongs to" content below (2:1 or 3:1 ratio).
|
||||
|
||||
---
|
||||
|
||||
## Page Layout
|
||||
|
||||
### Margins by Document Type
|
||||
|
||||
| Document Type | Top | Bottom | Left | Right | DXA Values |
|
||||
|--------------|-----|--------|------|-------|------------|
|
||||
| **Standard business** | 1 in | 1 in | 1 in | 1 in | 1440 all |
|
||||
| **Academic (APA/MLA)** | 1 in | 1 in | 1 in | 1 in | 1440 all |
|
||||
| **Thesis (binding)** | 1 in | 1 in | 1.5 in | 1 in | T/B:1440 L:2160 R:1440 |
|
||||
| **Chinese 公文** | 37mm | 35mm | 28mm | 26mm | T:2098 B:1984 L:1588 R:1474 |
|
||||
| **Narrow modern** | 0.75 in | 0.75 in | 0.75 in | 0.75 in | 1080 all |
|
||||
| **Wide** | 1 in | 1 in | 2 in | 2 in | T/B:1440 L/R:2880 |
|
||||
|
||||
### Page Sizes
|
||||
|
||||
| Size | Width × Height | DXA Width × Height |
|
||||
|------|---------------|-------------------|
|
||||
| US Letter | 8.5 × 11 in | 12240 × 15840 |
|
||||
| A4 | 210 × 297 mm | 11906 × 16838 |
|
||||
| Legal | 8.5 × 14 in | 12240 × 20160 |
|
||||
| A3 | 297 × 420 mm | 16838 × 23811 |
|
||||
|
||||
**Rule**: A4 for international audiences, Letter for US-only.
|
||||
|
||||
### Page Numbers
|
||||
|
||||
| Convention | Placement | Common In |
|
||||
|-----------|-----------|-----------|
|
||||
| Bottom center | Footer, centered | Academic, government |
|
||||
| Bottom right | Footer, right-aligned | Business reports |
|
||||
| "Page X of Y" | Footer, right-aligned | Contracts, legal |
|
||||
| Bottom outside | Alternating L/R for odd/even | Books, bound reports |
|
||||
| Chinese 公文 | Bottom center, format "-X-" | Government documents |
|
||||
|
||||
---
|
||||
|
||||
## Table Design
|
||||
|
||||
### Style Patterns
|
||||
|
||||
| Style | Description | When to Use |
|
||||
|-------|------------|-------------|
|
||||
| **Three-line (三线表)** | Top rule + header-bottom rule + bottom rule only, no vertical lines | Academic, scientific — gold standard |
|
||||
| **Banded rows** | Alternating white/light-gray, no borders | Modern corporate |
|
||||
| **Light grid** | Thin 0.5pt gray borders all cells | Business reports |
|
||||
| **Header-accent** | Dark/colored header row, no other borders | Modern templates |
|
||||
| **Full border** | All cells bordered | Financial tables, forms |
|
||||
|
||||
### Border Weights (OpenXML `w:sz` in eighths of a point)
|
||||
|
||||
| Visual | `Size` value | Points |
|
||||
|--------|-------------|--------|
|
||||
| Hairline | 2 | 0.25pt |
|
||||
| Thin | 4 | 0.5pt |
|
||||
| Medium | 8 | 1pt |
|
||||
| Thick | 12 | 1.5pt |
|
||||
|
||||
### Cell Padding
|
||||
|
||||
- **Minimum**: 0.05 in (28 DXA) — too tight for most uses
|
||||
- **Recommended**: 0.08-0.1 in (57-72 DXA) top/bottom, 0.1-0.15 in (72-108 DXA) left/right
|
||||
- **Spacious**: 0.12 in (86 DXA) top/bottom, 0.19 in (137 DXA) left/right
|
||||
|
||||
### Header Row Best Practices
|
||||
|
||||
- Bold text, optionally SMALL CAPS
|
||||
- Background: light gray (#F2F2F2) or dark with white text (#2F5496 + white)
|
||||
- Repeat header row on each page (`w:tblHeader` on `w:trPr`)
|
||||
- Right-align number columns, left-align text columns
|
||||
|
||||
---
|
||||
|
||||
## Color Schemes
|
||||
|
||||
### Corporate / Business
|
||||
|
||||
| Element | Hex | Notes |
|
||||
|---------|-----|-------|
|
||||
| Primary heading | #1F3864 | Dark navy, authoritative |
|
||||
| Secondary heading | #2E75B6 | Medium blue |
|
||||
| Body text | #333333 | Near-black (softer than #000) |
|
||||
| Table header bg | #4472C4 | With white #FFFFFF text |
|
||||
| Alternate row | #F2F2F2 | Subtle gray banding |
|
||||
| Hyperlink | #0563C1 | Standard blue |
|
||||
|
||||
### Academic
|
||||
|
||||
All text **#000000** (black). Color only in figures/charts.
|
||||
|
||||
### Chinese Government (公文)
|
||||
|
||||
| Element | Color |
|
||||
|---------|-------|
|
||||
| All body text | Black (required) |
|
||||
| 红头 agency name | Red #FF0000 |
|
||||
| 红线 separator | Red #FF0000 |
|
||||
| 公章 seal | Red |
|
||||
|
||||
### Accessibility
|
||||
|
||||
- Minimum contrast ratio 4.5:1 for normal text, 3:1 for large text (WCAG AA)
|
||||
- Never use color as sole means of conveying information
|
||||
- Ensure distinguishable in grayscale for printed documents
|
||||
|
||||
---
|
||||
|
||||
## Visual Hierarchy
|
||||
|
||||
### Heading Levels by Document Length
|
||||
|
||||
| Pages | Recommended Levels |
|
||||
|-------|-------------------|
|
||||
| 1-5 (memo, letter) | 1-2 levels |
|
||||
| 5-20 (report) | 2-3 levels |
|
||||
| 20-100 (long report) | 3-4 levels |
|
||||
| 100+ (thesis) | 4-5 levels max |
|
||||
|
||||
### Numbering Systems
|
||||
|
||||
**Decimal (ISO 2145)** — technical, international:
|
||||
```
|
||||
1 → 1.1 → 1.1.1 → 1.1.1.1
|
||||
```
|
||||
|
||||
**Traditional outline (US legal):**
|
||||
```
|
||||
I. → A. → 1. → a. → (1) → (a)
|
||||
```
|
||||
|
||||
**Chinese government (公文):**
|
||||
```
|
||||
一、(黑体) → （一）(楷体) → 1.(仿宋加粗) → (1)(仿宋)
|
||||
```
|
||||
|
||||
### Typography Emphasis
|
||||
|
||||
| Format | Use For | Avoid |
|
||||
|--------|---------|-------|
|
||||
| **Bold** | Key terms, headings, emphasis | Entire paragraphs |
|
||||
| *Italic* | Titles, foreign words, mild emphasis | Long passages (hard to read) |
|
||||
| Underline | Hyperlinks only (digital) | General emphasis (archaic) |
|
||||
| SMALL CAPS | Legal defined terms, acronyms | Body text |
|
||||
| ALL CAPS | Very short headings | Long text (reduces readability 15%) |
|
||||
|
||||
**CJK note**: Chinese/Japanese have no true italic. Use bold for emphasis.
|
||||
|
||||
### List Formatting
|
||||
|
||||
**Bullets** (unordered): `•` → `○` → `■` by level
|
||||
|
||||
**Numbers** (ordered): `1.` → `a.` → `i.` by level
|
||||
|
||||
- Indent each level 0.25-0.5 in (360-720 DXA)
|
||||
- Hanging indent: number hangs, text aligns consistently
|
||||
- Spacing between items: 2-4pt (less than paragraph spacing)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Defaults
|
||||
|
||||
### Business Report (Safe Default)
|
||||
|
||||
| Parameter | Value | OpenXML |
|
||||
|-----------|-------|---------|
|
||||
| Body font | Calibri 11pt | sz="22", RunFonts Ascii="Calibri" |
|
||||
| H1 | 18pt Bold Dark Blue | sz="36", Bold, Color="#1F3864" |
|
||||
| H2 | 14pt Bold Dark Blue | sz="28", Bold |
|
||||
| H3 | 12pt Bold Dark Blue | sz="24", Bold |
|
||||
| Line spacing | 1.15 | line="276" lineRule="auto" |
|
||||
| Para after | 8pt | after="160" |
|
||||
| Margins | 1 in all | 1440 DXA all |
|
||||
| Page size | Letter or A4 | 12240×15840 or 11906×16838 |
|
||||
| Page numbers | Bottom right, 10pt | |
|
||||
|
||||
### Academic Paper (APA 7th)
|
||||
|
||||
| Parameter | Value | OpenXML |
|
||||
|-----------|-------|---------|
|
||||
| Font | Times New Roman 12pt | sz="24" |
|
||||
| Line spacing | Double | line="480" lineRule="auto" |
|
||||
| First-line indent | 0.5 in | ind firstLine="720" |
|
||||
| Margins | 1 in all | 1440 DXA all |
|
||||
| Page numbers | Top right | Header, right-aligned |
|
||||
|
||||
### Chinese Government (公文 GB/T 9704)
|
||||
|
||||
| Parameter | Value | OpenXML |
|
||||
|-----------|-------|---------|
|
||||
| Body font | 仿宋_GB2312 三号 | sz="32", EastAsia="FangSong_GB2312" |
|
||||
| Title | 小标宋 二号 centered | sz="44" |
|
||||
| L1 heading | 黑体 三号 | sz="32", EastAsia="SimHei" |
|
||||
| L2 heading | 楷体 三号 | sz="32", EastAsia="KaiTi_GB2312" |
|
||||
| Line spacing | Fixed 28pt | line="560" lineRule="exact" |
|
||||
| Margins | T:37mm B:35mm L:28mm R:26mm | T:2098 B:1984 L:1588 R:1474 |
|
||||
| Page size | A4 | 11906×16838 |
|
||||
| Page numbers | Bottom center, 宋体 四号, "-X-" | sz="28" |
|
||||
| Chars/line | 28 | |
|
||||
| Lines/page | 22 | |
|
||||
@@ -0,0 +1,158 @@
|
||||
# XSD Validation Guide
|
||||
|
||||
## Running Validation
|
||||
|
||||
```bash
|
||||
# Validate against the WML subset schema
|
||||
dotnet run --project docx-toolkit validate input.docx --xsd assets/xsd/wml-subset.xsd
|
||||
|
||||
# Validate against business rules (REQUIRED for Scenario C gate-check)
|
||||
dotnet run --project docx-toolkit validate input.docx --xsd assets/xsd/business-rules.xsd
|
||||
|
||||
# Validate against both
|
||||
dotnet run --project docx-toolkit validate input.docx --xsd assets/xsd/wml-subset.xsd --xsd assets/xsd/business-rules.xsd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What wml-subset.xsd Covers
|
||||
|
||||
The subset schema validates the most common WordprocessingML elements:
|
||||
|
||||
| Area | Elements Validated |
|
||||
|------|--------------------|
|
||||
| Document structure | `w:document`, `w:body`, `w:sectPr` |
|
||||
| Paragraphs | `w:p`, `w:pPr`, `w:r`, `w:rPr`, `w:t` |
|
||||
| Tables | `w:tbl`, `w:tblPr`, `w:tblGrid`, `w:tr`, `w:tc` |
|
||||
| Styles | `w:styles`, `w:style`, `w:docDefaults` |
|
||||
| Lists | `w:numbering`, `w:abstractNum`, `w:num` |
|
||||
| Headers/Footers | `w:hdr`, `w:ftr` |
|
||||
| Track Changes | `w:ins`, `w:del`, `w:rPrChange`, `w:pPrChange` |
|
||||
| Comments | `w:comment`, `w:commentRangeStart`, `w:commentRangeEnd` |
|
||||
|
||||
### What It Does NOT Cover
|
||||
|
||||
- DrawingML elements (`a:`, `pic:`, `wp:`) — image/shape internals
|
||||
- VML elements (`v:`, `o:`) — legacy shapes
|
||||
- Math elements (`m:`) — equations
|
||||
- Extended namespaces (`w14`, `w15`, `w16*`) — vendor extensions
|
||||
- Custom XML data parts
|
||||
- Relationship and content type validation (structural, not schema-based)
|
||||
|
||||
---
|
||||
|
||||
## Interpreting Errors
|
||||
|
||||
### Element Ordering Error
|
||||
|
||||
```
|
||||
ERROR: Element 'w:jc' is not expected at this position.
|
||||
Expected: w:spacing, w:ind, w:contextualSpacing, ...
|
||||
Location: /word/document.xml, line 45
|
||||
```
|
||||
|
||||
**Cause**: Child elements are in wrong order. See `references/openxml_element_order.md`.
|
||||
**Fix**: Reorder children to match schema sequence.
|
||||
|
||||
### Missing Required Element
|
||||
|
||||
```
|
||||
ERROR: Element 'w:tbl' missing required child 'w:tblPr'.
|
||||
Location: /word/document.xml, line 102
|
||||
```
|
||||
|
||||
**Cause**: A required child element is absent.
|
||||
**Fix**: Add the missing element. Tables require both `w:tblPr` and `w:tblGrid`.
|
||||
|
||||
### Invalid Attribute Value
|
||||
|
||||
```
|
||||
ERROR: Attribute 'w:val' has invalid value 'middle'.
|
||||
Expected: 'left', 'center', 'right', 'both', 'distribute'
|
||||
Location: /word/document.xml, line 78
|
||||
```
|
||||
|
||||
**Cause**: An attribute value is not in the allowed enumeration.
|
||||
**Fix**: Use one of the valid values listed in the error.
|
||||
|
||||
### Unexpected Element
|
||||
|
||||
```
|
||||
ERROR: Element 'w:customTag' is not expected.
|
||||
Location: /word/document.xml, line 200
|
||||
```
|
||||
|
||||
**Cause**: An element not defined in the subset schema. May be a vendor extension.
|
||||
**Fix**: Check if it's a known extension (w14/w15/w16). If so, it's likely safe. If unknown, investigate or remove.
|
||||
|
||||
---
|
||||
|
||||
## Business Rules XSD
|
||||
|
||||
The `business-rules.xsd` schema enforces project-specific constraints beyond standard OpenXML validity:
|
||||
|
||||
| Rule | What It Checks |
|
||||
|------|---------------|
|
||||
| Required styles | `Normal`, `Heading1`-`Heading3`, `TableGrid` must exist in `styles.xml` |
|
||||
| Font consistency | `w:docDefaults` fonts match expected values |
|
||||
| Margin ranges | Page margins within acceptable range (720-2160 DXA) |
|
||||
| Page size | Must be A4 or Letter |
|
||||
| Heading hierarchy | No gaps (e.g., H1 → H3 without H2) |
|
||||
| Style chain | `w:basedOn` references must resolve to existing styles |
|
||||
|
||||
### Extending Business Rules
|
||||
|
||||
To add project-specific rules, add `xs:assert` or `xs:restriction` elements:
|
||||
|
||||
```xml
|
||||
<!-- Require minimum 1-inch margins -->
|
||||
<xs:element name="pgMar">
|
||||
<xs:complexType>
|
||||
<xs:attribute name="top" type="xs:integer">
|
||||
<xs:restriction>
|
||||
<xs:minInclusive value="1440" />
|
||||
</xs:restriction>
|
||||
</xs:attribute>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gate-Check: Scenario C Hard Gate
|
||||
|
||||
In Scenario C (Apply Template), the output document **MUST** pass `business-rules.xsd` validation before delivery:
|
||||
|
||||
```
|
||||
1. Apply template → output.docx
|
||||
2. Validate → dotnet run ... validate output.docx --xsd business-rules.xsd
|
||||
3. PASS? → Deliver to user
|
||||
4. FAIL? → Fix issues, re-validate, repeat until PASS
|
||||
```
|
||||
|
||||
**This is a hard gate.** A document that fails business-rules validation is NOT deliverable, even if it opens correctly in Word.
|
||||
|
||||
---
|
||||
|
||||
## False Positives
|
||||
|
||||
### Vendor Extensions
|
||||
|
||||
Elements from extended namespaces (`w14`, `w15`, `w16*`) are not in the subset schema and may trigger warnings:
|
||||
|
||||
```
|
||||
WARNING: Element '{http://schemas.microsoft.com/office/word/2010/wordml}shadow' is not expected.
|
||||
```
|
||||
|
||||
These are generally safe to ignore — they are Microsoft extensions for newer features (e.g., advanced text effects, comment extensions).
|
||||
|
||||
### Markup Compatibility
|
||||
|
||||
Documents may contain `mc:AlternateContent` blocks with fallback content. The subset schema may not recognize the `mc:` namespace processing. These are safe if the document opens correctly in Word.
|
||||
|
||||
### Recommended Approach
|
||||
|
||||
1. Run validation
|
||||
2. Treat **errors** as must-fix
|
||||
3. Review **warnings** — ignore known vendor extensions, investigate unknown elements
|
||||
4. After fixing errors, re-validate to confirm
|
||||
@@ -0,0 +1,40 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
echo "Usage: $(basename "$0") <file.doc> [output_directory]"
|
||||
echo "Convert .doc to .docx using LibreOffice."
|
||||
exit 1
|
||||
}
|
||||
|
||||
if [ $# -lt 1 ]; then
|
||||
usage
|
||||
fi
|
||||
|
||||
INPUT="$1"
|
||||
OUTDIR="${2:-.}"
|
||||
|
||||
if [ ! -f "$INPUT" ]; then
|
||||
echo "Error: File not found: $INPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! command -v soffice &>/dev/null; then
|
||||
echo "Error: soffice (LibreOffice) is required for .doc conversion but not found."
|
||||
echo "Install LibreOffice: brew install --cask libreoffice"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
BASENAME=$(basename "$INPUT" .doc)
|
||||
mkdir -p "$OUTDIR"
|
||||
|
||||
echo "Converting: $INPUT -> $OUTDIR/$BASENAME.docx"
|
||||
soffice --headless --convert-to docx --outdir "$OUTDIR" "$INPUT" >/dev/null 2>&1
|
||||
|
||||
OUTPUT="$OUTDIR/$BASENAME.docx"
|
||||
if [ ! -f "$OUTPUT" ]; then
|
||||
echo "Error: Conversion failed. Output file not created: $OUTPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Success: $OUTPUT"
|
||||
@@ -0,0 +1,37 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
echo "Usage: $(basename "$0") <file.docx>"
|
||||
echo "Preview DOCX content as plain text."
|
||||
exit 1
|
||||
}
|
||||
|
||||
if [ $# -lt 1 ]; then
|
||||
usage
|
||||
fi
|
||||
|
||||
INPUT="$1"
|
||||
|
||||
if [ ! -f "$INPUT" ]; then
|
||||
echo "Error: File not found: $INPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
FILE_SIZE=$(du -h "$INPUT" | cut -f1)
|
||||
echo "=== DOCX Preview: $(basename "$INPUT") ==="
|
||||
echo "File size: $FILE_SIZE"
|
||||
|
||||
if command -v pandoc &>/dev/null; then
|
||||
CONTENT=$(pandoc -f docx -t plain "$INPUT" 2>/dev/null)
|
||||
WORD_COUNT=$(echo "$CONTENT" | wc -w | tr -d ' ')
|
||||
EST_PAGES=$(( (WORD_COUNT + 249) / 250 ))
|
||||
echo "Word count: $WORD_COUNT"
|
||||
echo "Estimated pages: $EST_PAGES"
|
||||
echo "---"
|
||||
echo "$CONTENT"
|
||||
else
|
||||
echo "(pandoc not available, falling back to raw XML extract)"
|
||||
echo "---"
|
||||
unzip -p "$INPUT" word/document.xml 2>/dev/null | head -100
|
||||
fi
|
||||
@@ -0,0 +1,19 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\DocxToolkit.Core\DocxToolkit.Core.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="System.CommandLine" Version="2.0.5" />
|
||||
</ItemGroup>
|
||||
|
||||
<PropertyGroup>
|
||||
<OutputType>Exe</OutputType>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<NeutralLanguage>en</NeutralLanguage>
|
||||
</PropertyGroup>
|
||||
|
||||
</Project>
|
||||
@@ -0,0 +1,18 @@
|
||||
using System.CommandLine;
|
||||
using DocxToolkit.Core.Commands;
|
||||
|
||||
var rootCommand = new RootCommand("docx-toolkit: OpenXML document generation and manipulation CLI");
|
||||
|
||||
// Scenario commands
|
||||
rootCommand.Add(CreateCommand.Create());
|
||||
rootCommand.Add(EditContentCommand.Create());
|
||||
rootCommand.Add(ApplyTemplateCommand.Create());
|
||||
|
||||
// Tool commands
|
||||
rootCommand.Add(ValidateCommand.Create());
|
||||
rootCommand.Add(MergeRunsCommand.Create());
|
||||
rootCommand.Add(FixOrderCommand.Create());
|
||||
rootCommand.Add(AnalyzeCommand.Create());
|
||||
rootCommand.Add(DiffCommand.Create());
|
||||
|
||||
return rootCommand.Parse(args).Invoke();
|
||||
@@ -0,0 +1,147 @@
|
||||
using System.CommandLine;
|
||||
using System.IO.Compression;
|
||||
using System.Text.Json;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
public static class AnalyzeCommand
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
private static readonly XNamespace WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
|
||||
|
||||
public static Command Create()
|
||||
{
|
||||
var inputOption = new Option<string>("--input") { Description = "DOCX file to analyze", Required = true };
|
||||
var jsonOption = new Option<bool>("--json") { Description = "Output as JSON" };
|
||||
|
||||
var cmd = new Command("analyze", "Analyze document structure and styles")
|
||||
{
|
||||
inputOption, jsonOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOption)!;
|
||||
var asJson = parseResult.GetValue(jsonOption);
|
||||
|
||||
if (!File.Exists(input))
|
||||
{
|
||||
Console.Error.WriteLine($"File not found: {input}");
|
||||
return;
|
||||
}
|
||||
|
||||
using var zip = ZipFile.OpenRead(input);
|
||||
var docEntry = zip.GetEntry("word/document.xml");
|
||||
if (docEntry == null)
|
||||
{
|
||||
Console.Error.WriteLine("Not a valid DOCX");
|
||||
return;
|
||||
}
|
||||
|
||||
XDocument doc;
|
||||
using (var stream = docEntry.Open())
|
||||
doc = XDocument.Load(stream);
|
||||
|
||||
var body = doc.Root?.Element(W + "body");
|
||||
if (body == null) return;
|
||||
|
||||
// Sections
|
||||
var sections = body.Descendants(W + "sectPr").ToList();
|
||||
var sectionBreaks = sections.Select(s => (string?)s.Element(W + "type")?.Attribute(W + "val") ?? "nextPage").ToList();
|
||||
|
||||
// Headings
|
||||
var headings = new List<object>();
|
||||
foreach (var p in body.Descendants(W + "p"))
|
||||
{
|
||||
var style = (string?)p.Element(W + "pPr")?.Element(W + "pStyle")?.Attribute(W + "val");
|
||||
if (style?.StartsWith("Heading", StringComparison.OrdinalIgnoreCase) == true)
|
||||
{
|
||||
var text = string.Concat(p.Descendants(W + "t").Select(t => t.Value));
|
||||
headings.Add(new { style, text });
|
||||
}
|
||||
}
|
||||
|
||||
// Tables
|
||||
var tables = body.Descendants(W + "tbl").Select(tbl => new
|
||||
{
|
||||
rows = tbl.Elements(W + "tr").Count(),
|
||||
cols = tbl.Elements(W + "tr").FirstOrDefault()?.Elements(W + "tc").Count() ?? 0
|
||||
}).ToList();
|
||||
|
||||
// Images
|
||||
var images = body.Descendants(W + "drawing").Count();
|
||||
|
||||
// Headers/footers
|
||||
var headerRefs = sections.SelectMany(s => s.Elements(W + "headerReference")).Count();
|
||||
var footerRefs = sections.SelectMany(s => s.Elements(W + "footerReference")).Count();
|
||||
|
||||
// Paragraphs and word count
|
||||
var paragraphs = body.Descendants(W + "p").ToList();
|
||||
var allText = string.Concat(body.Descendants(W + "t").Select(t => t.Value));
|
||||
var wordCount = allText.Split(new[] { ' ', '\t', '\n', '\r' }, StringSplitOptions.RemoveEmptyEntries).Length;
|
||||
|
||||
// XML file sizes
|
||||
var fileSizes = zip.Entries
|
||||
.Where(e => e.FullName.StartsWith("word/") && e.FullName.EndsWith(".xml"))
|
||||
.Select(e => new { file = e.FullName, size = e.Length })
|
||||
.OrderByDescending(e => e.size)
|
||||
.ToList();
|
||||
|
||||
// Styles
|
||||
var styleNames = new List<string>();
|
||||
var stylesEntry = zip.GetEntry("word/styles.xml");
|
||||
if (stylesEntry != null)
|
||||
{
|
||||
using var stream = stylesEntry.Open();
|
||||
var stylesDoc = XDocument.Load(stream);
|
||||
styleNames = stylesDoc.Descendants(W + "style")
|
||||
.Where(s => (string?)s.Attribute(W + "customStyle") == "1")
|
||||
.Select(s => (string?)s.Attribute(W + "styleId") ?? "")
|
||||
.Where(s => s != "")
|
||||
.ToList();
|
||||
}
|
||||
|
||||
var analysis = new
|
||||
{
|
||||
sections = new { count = sections.Count, breakTypes = sectionBreaks },
|
||||
headings,
|
||||
tables = new { count = tables.Count, details = tables },
|
||||
images,
|
||||
headerFooter = new { headers = headerRefs, footers = footerRefs },
|
||||
paragraphs = paragraphs.Count,
|
||||
estimatedWordCount = wordCount,
|
||||
xmlFileSizes = fileSizes,
|
||||
customStyles = new { count = styleNames.Count, names = styleNames }
|
||||
};
|
||||
|
||||
if (asJson)
|
||||
{
|
||||
Console.WriteLine(JsonSerializer.Serialize(analysis, new JsonSerializerOptions { WriteIndented = true }));
|
||||
}
|
||||
else
|
||||
{
|
||||
Console.WriteLine($"Sections: {sections.Count} ({string.Join(", ", sectionBreaks)})");
|
||||
Console.WriteLine($"Headings: {headings.Count}");
|
||||
foreach (var h in headings)
|
||||
Console.WriteLine($" {h}");
|
||||
Console.WriteLine($"Tables: {tables.Count}");
|
||||
foreach (var t in tables)
|
||||
Console.WriteLine($" {t.rows} rows x {t.cols} cols");
|
||||
Console.WriteLine($"Images: {images}");
|
||||
Console.WriteLine($"Headers: {headerRefs}");
|
||||
Console.WriteLine($"Footers: {footerRefs}");
|
||||
Console.WriteLine($"Paragraphs: {paragraphs.Count}");
|
||||
Console.WriteLine($"Word count: ~{wordCount}");
|
||||
Console.WriteLine($"Custom styles: {styleNames.Count}");
|
||||
foreach (var s in styleNames)
|
||||
Console.WriteLine($" {s}");
|
||||
Console.WriteLine("XML file sizes:");
|
||||
foreach (var f in fileSizes)
|
||||
Console.WriteLine($" {f.file}: {f.size:N0} bytes");
|
||||
}
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,322 @@
|
||||
using System.CommandLine;
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
/// <summary>
|
||||
/// Scenario C: Apply formatting from a template DOCX to a source DOCX.
|
||||
/// Copies styles, theme, numbering, headers/footers, and section properties
|
||||
/// from the template while preserving all content from the source.
|
||||
/// </summary>
|
||||
public static class ApplyTemplateCommand
|
||||
{
|
||||
public static Command Create()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Source DOCX (content to keep)", Required = true };
|
||||
var templateOpt = new Option<string>("--template") { Description = "Template DOCX (formatting to apply)", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output DOCX file path", Required = true };
|
||||
var applyStylesOpt = new Option<bool>("--apply-styles") { Description = "Copy styles.xml from template" };
|
||||
applyStylesOpt.DefaultValueFactory = _ => true;
|
||||
var applyThemeOpt = new Option<bool>("--apply-theme") { Description = "Copy theme from template" };
|
||||
applyThemeOpt.DefaultValueFactory = _ => true;
|
||||
var applyNumberingOpt = new Option<bool>("--apply-numbering") { Description = "Copy numbering.xml from template" };
|
||||
applyNumberingOpt.DefaultValueFactory = _ => true;
|
||||
var applyHeadersFootersOpt = new Option<bool>("--apply-headers-footers") { Description = "Copy headers/footers from template" };
|
||||
var applySectionsOpt = new Option<bool>("--apply-sections") { Description = "Apply section properties from template" };
|
||||
applySectionsOpt.DefaultValueFactory = _ => true;
|
||||
|
||||
var cmd = new Command("apply-template", "Apply template formatting to a DOCX")
|
||||
{
|
||||
inputOpt, templateOpt, outputOpt, applyStylesOpt, applyThemeOpt,
|
||||
applyNumberingOpt, applyHeadersFootersOpt, applySectionsOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var inputPath = parseResult.GetValue(inputOpt)!;
|
||||
var templatePath = parseResult.GetValue(templateOpt)!;
|
||||
var outputPath = parseResult.GetValue(outputOpt)!;
|
||||
var applyStyles = parseResult.GetValue(applyStylesOpt);
|
||||
var applyTheme = parseResult.GetValue(applyThemeOpt);
|
||||
var applyNumbering = parseResult.GetValue(applyNumberingOpt);
|
||||
var applyHeadersFooters = parseResult.GetValue(applyHeadersFootersOpt);
|
||||
var applySections = parseResult.GetValue(applySectionsOpt);
|
||||
|
||||
if (!File.Exists(inputPath)) { Console.Error.WriteLine($"Input file not found: {inputPath}"); return; }
|
||||
if (!File.Exists(templatePath)) { Console.Error.WriteLine($"Template file not found: {templatePath}"); return; }
|
||||
|
||||
// Create output as a copy of the source
|
||||
File.Copy(inputPath, outputPath, overwrite: true);
|
||||
|
||||
using var output = WordprocessingDocument.Open(outputPath, true);
|
||||
using var template = WordprocessingDocument.Open(templatePath, false);
|
||||
|
||||
var outputMain = output.MainDocumentPart;
|
||||
var templateMain = template.MainDocumentPart;
|
||||
if (outputMain == null || templateMain == null)
|
||||
{
|
||||
Console.Error.WriteLine("Invalid document: missing main document part.");
|
||||
return;
|
||||
}
|
||||
|
||||
int appliedCount = 0;
|
||||
|
||||
if (applyStyles)
|
||||
{
|
||||
CopyStyles(templateMain, outputMain);
|
||||
appliedCount++;
|
||||
Console.WriteLine(" Applied: styles");
|
||||
}
|
||||
|
||||
if (applyTheme)
|
||||
{
|
||||
CopyTheme(templateMain, outputMain);
|
||||
appliedCount++;
|
||||
Console.WriteLine(" Applied: theme");
|
||||
}
|
||||
|
||||
if (applyNumbering)
|
||||
{
|
||||
CopyNumbering(templateMain, outputMain);
|
||||
appliedCount++;
|
||||
Console.WriteLine(" Applied: numbering");
|
||||
}
|
||||
|
||||
if (applyHeadersFooters)
|
||||
{
|
||||
CopyHeadersAndFooters(templateMain, outputMain);
|
||||
appliedCount++;
|
||||
Console.WriteLine(" Applied: headers/footers");
|
||||
}
|
||||
|
||||
if (applySections)
|
||||
{
|
||||
CopySectionProperties(templateMain, outputMain);
|
||||
appliedCount++;
|
||||
Console.WriteLine(" Applied: section properties");
|
||||
}
|
||||
|
||||
outputMain.Document.Save();
|
||||
Console.WriteLine($"Applied {appliedCount} formatting component(s) from template to {outputPath}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Replaces the output's StyleDefinitionsPart with the template's version.
|
||||
/// </summary>
|
||||
private static void CopyStyles(MainDocumentPart template, MainDocumentPart output)
|
||||
{
|
||||
var templateStyles = template.StyleDefinitionsPart;
|
||||
if (templateStyles == null) return;
|
||||
|
||||
if (output.StyleDefinitionsPart != null)
|
||||
output.DeletePart(output.StyleDefinitionsPart);
|
||||
|
||||
var newStylesPart = output.AddNewPart<StyleDefinitionsPart>();
|
||||
|
||||
using var stream = templateStyles.GetStream(FileMode.Open, FileAccess.Read);
|
||||
newStylesPart.FeedData(stream);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Replaces the output's ThemePart with the template's version.
|
||||
/// </summary>
|
||||
private static void CopyTheme(MainDocumentPart template, MainDocumentPart output)
|
||||
{
|
||||
var templateTheme = template.ThemePart;
|
||||
if (templateTheme == null) return;
|
||||
|
||||
if (output.ThemePart != null)
|
||||
output.DeletePart(output.ThemePart);
|
||||
|
||||
var newThemePart = output.AddNewPart<ThemePart>();
|
||||
|
||||
using var stream = templateTheme.GetStream(FileMode.Open, FileAccess.Read);
|
||||
newThemePart.FeedData(stream);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Copies numbering definitions from template, remapping numbering IDs
|
||||
/// referenced in the output document's paragraphs.
|
||||
/// </summary>
|
||||
private static void CopyNumbering(MainDocumentPart template, MainDocumentPart output)
|
||||
{
|
||||
var templateNumbering = template.NumberingDefinitionsPart;
|
||||
if (templateNumbering == null) return;
|
||||
|
||||
var referencedNumIds = new HashSet<string>();
|
||||
var body = output.Document.Body;
|
||||
if (body != null)
|
||||
{
|
||||
foreach (var numId in body.Descendants<NumberingId>())
|
||||
{
|
||||
if (numId.Val?.Value != null)
|
||||
referencedNumIds.Add(numId.Val.Value.ToString());
|
||||
}
|
||||
}
|
||||
|
||||
if (output.NumberingDefinitionsPart != null)
|
||||
output.DeletePart(output.NumberingDefinitionsPart);
|
||||
|
||||
var newNumberingPart = output.AddNewPart<NumberingDefinitionsPart>();
|
||||
|
||||
using var stream = templateNumbering.GetStream(FileMode.Open, FileAccess.Read);
|
||||
newNumberingPart.FeedData(stream);
|
||||
|
||||
if (referencedNumIds.Count > 0)
|
||||
{
|
||||
Console.WriteLine($" Note: {referencedNumIds.Count} numbering reference(s) in document content mapped to template definitions.");
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Copies headers and footers from the template, remapping relationship IDs.
|
||||
/// </summary>
|
||||
private static void CopyHeadersAndFooters(MainDocumentPart template, MainDocumentPart output)
|
||||
{
|
||||
var outputBody = output.Document.Body;
|
||||
if (outputBody == null) return;
|
||||
|
||||
// Remove existing header/footer parts from output
|
||||
foreach (var hp in output.HeaderParts.ToList())
|
||||
output.DeletePart(hp);
|
||||
foreach (var fp in output.FooterParts.ToList())
|
||||
output.DeletePart(fp);
|
||||
|
||||
// Remove existing header/footer references from all section properties
|
||||
foreach (var sectPr in outputBody.Descendants<SectionProperties>())
|
||||
{
|
||||
foreach (var hr in sectPr.Elements<HeaderReference>().ToList())
|
||||
hr.Remove();
|
||||
foreach (var fr in sectPr.Elements<FooterReference>().ToList())
|
||||
fr.Remove();
|
||||
}
|
||||
|
||||
var templateBody = template.Document?.Body;
|
||||
if (templateBody == null) return;
|
||||
|
||||
var templateFinalSectPr = templateBody.Descendants<SectionProperties>().LastOrDefault();
|
||||
if (templateFinalSectPr == null) return;
|
||||
|
||||
var outputFinalSectPr = outputBody.Descendants<SectionProperties>().LastOrDefault();
|
||||
if (outputFinalSectPr == null)
|
||||
{
|
||||
outputFinalSectPr = new SectionProperties();
|
||||
outputBody.Append(outputFinalSectPr);
|
||||
}
|
||||
|
||||
// Copy headers
|
||||
foreach (var headerRef in templateFinalSectPr.Elements<HeaderReference>())
|
||||
{
|
||||
var templateHeaderPart = template.GetPartById(headerRef.Id!) as HeaderPart;
|
||||
if (templateHeaderPart == null) continue;
|
||||
|
||||
var newHeaderPart = output.AddNewPart<HeaderPart>();
|
||||
using (var stream = templateHeaderPart.GetStream(FileMode.Open, FileAccess.Read))
|
||||
{
|
||||
newHeaderPart.FeedData(stream);
|
||||
}
|
||||
|
||||
CopyPartRelationships(templateHeaderPart, newHeaderPart);
|
||||
|
||||
var newRefId = output.GetIdOfPart(newHeaderPart);
|
||||
outputFinalSectPr.InsertAt(new HeaderReference
|
||||
{
|
||||
Type = headerRef.Type,
|
||||
Id = newRefId
|
||||
}, 0);
|
||||
}
|
||||
|
||||
// Copy footers
|
||||
foreach (var footerRef in templateFinalSectPr.Elements<FooterReference>())
|
||||
{
|
||||
var templateFooterPart = template.GetPartById(footerRef.Id!) as FooterPart;
|
||||
if (templateFooterPart == null) continue;
|
||||
|
||||
var newFooterPart = output.AddNewPart<FooterPart>();
|
||||
using (var stream = templateFooterPart.GetStream(FileMode.Open, FileAccess.Read))
|
||||
{
|
||||
newFooterPart.FeedData(stream);
|
||||
}
|
||||
|
||||
CopyPartRelationships(templateFooterPart, newFooterPart);
|
||||
|
||||
var newRefId = output.GetIdOfPart(newFooterPart);
|
||||
var lastHeaderRef = outputFinalSectPr.Elements<HeaderReference>().LastOrDefault();
|
||||
if (lastHeaderRef != null)
|
||||
lastHeaderRef.InsertAfterSelf(new FooterReference { Type = footerRef.Type, Id = newRefId });
|
||||
else
|
||||
outputFinalSectPr.InsertAt(new FooterReference { Type = footerRef.Type, Id = newRefId }, 0);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Copies sub-relationships (images, etc.) from a source part to a target part.
|
||||
/// </summary>
|
||||
private static void CopyPartRelationships(OpenXmlPart source, OpenXmlPart target)
|
||||
{
|
||||
foreach (var rel in source.ExternalRelationships)
|
||||
{
|
||||
target.AddExternalRelationship(rel.RelationshipType, rel.Uri, rel.Id);
|
||||
}
|
||||
|
||||
foreach (var childPart in source.Parts)
|
||||
{
|
||||
try
|
||||
{
|
||||
var contentType = childPart.OpenXmlPart.ContentType;
|
||||
if (contentType.StartsWith("image/"))
|
||||
{
|
||||
var newChild = target.AddNewPart<ImagePart>(contentType, childPart.RelationshipId);
|
||||
using var stream = childPart.OpenXmlPart.GetStream(FileMode.Open, FileAccess.Read);
|
||||
newChild.FeedData(stream);
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.Error.WriteLine($"[WARN] Skipped non-image embedded part: {ex.Message}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Copies page size, margins, columns, and document grid from template section properties.
|
||||
/// </summary>
|
||||
private static void CopySectionProperties(MainDocumentPart template, MainDocumentPart output)
|
||||
{
|
||||
var templateBody = template.Document?.Body;
|
||||
var outputBody = output.Document?.Body;
|
||||
if (templateBody == null || outputBody == null) return;
|
||||
|
||||
var templateSectPr = templateBody.Descendants<SectionProperties>().LastOrDefault();
|
||||
if (templateSectPr == null) return;
|
||||
|
||||
var outputSectPr = outputBody.Descendants<SectionProperties>().LastOrDefault();
|
||||
if (outputSectPr == null)
|
||||
{
|
||||
outputSectPr = new SectionProperties();
|
||||
outputBody.Append(outputSectPr);
|
||||
}
|
||||
|
||||
CopyChildElement<PageSize>(templateSectPr, outputSectPr);
|
||||
CopyChildElement<PageMargin>(templateSectPr, outputSectPr);
|
||||
CopyChildElement<Columns>(templateSectPr, outputSectPr);
|
||||
CopyChildElement<DocGrid>(templateSectPr, outputSectPr);
|
||||
CopyChildElement<PageBorders>(templateSectPr, outputSectPr);
|
||||
}
|
||||
|
||||
private static void CopyChildElement<T>(SectionProperties source, SectionProperties target) where T : OpenXmlElement
|
||||
{
|
||||
var sourceElement = source.GetFirstChild<T>();
|
||||
if (sourceElement == null) return;
|
||||
|
||||
var existing = target.GetFirstChild<T>();
|
||||
existing?.Remove();
|
||||
|
||||
target.Append((T)sourceElement.CloneNode(true));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,324 @@
|
||||
using System.CommandLine;
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
using DocxToolkit.Core.OpenXml;
|
||||
using DocxToolkit.Core.Typography;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
/// <summary>
|
||||
/// Scenario A: Create a new DOCX document from scratch with proper styles, sections,
|
||||
/// headers/footers, and typography defaults.
|
||||
/// </summary>
|
||||
public static class CreateCommand
|
||||
{
|
||||
public static Command Create()
|
||||
{
|
||||
var outputOption = new Option<string>("--output") { Description = "Output DOCX file path", Required = true };
|
||||
var typeOption = new Option<string>("--type") { Description = "Document type: report, letter, memo, academic" };
|
||||
typeOption.DefaultValueFactory = _ => "report";
|
||||
var titleOption = new Option<string>("--title") { Description = "Document title" };
|
||||
var authorOption = new Option<string>("--author") { Description = "Document author" };
|
||||
var pageSizeOption = new Option<string>("--page-size") { Description = "Page size: letter, a4, legal, a3" };
|
||||
pageSizeOption.DefaultValueFactory = _ => "letter";
|
||||
var marginsOption = new Option<string>("--margins") { Description = "Margin preset: standard, narrow, wide" };
|
||||
marginsOption.DefaultValueFactory = _ => "standard";
|
||||
var headerTextOption = new Option<string>("--header") { Description = "Header text" };
|
||||
var footerTextOption = new Option<string>("--footer") { Description = "Footer text" };
|
||||
var pageNumbersOption = new Option<bool>("--page-numbers") { Description = "Add page numbers in footer" };
|
||||
var tocOption = new Option<bool>("--toc") { Description = "Insert table of contents placeholder" };
|
||||
var contentJsonOption = new Option<string>("--content-json") { Description = "Path to JSON file describing document content" };
|
||||
|
||||
var cmd = new Command("create", "Create a new DOCX document from scratch")
|
||||
{
|
||||
outputOption, typeOption, titleOption, authorOption, pageSizeOption,
|
||||
marginsOption, headerTextOption, footerTextOption, pageNumbersOption,
|
||||
tocOption, contentJsonOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var output = parseResult.GetValue(outputOption)!;
|
||||
var docType = parseResult.GetValue(typeOption) ?? "report";
|
||||
var title = parseResult.GetValue(titleOption);
|
||||
var author = parseResult.GetValue(authorOption);
|
||||
var pageSizeName = parseResult.GetValue(pageSizeOption) ?? "letter";
|
||||
var marginsName = parseResult.GetValue(marginsOption) ?? "standard";
|
||||
var headerText = parseResult.GetValue(headerTextOption);
|
||||
var footerText = parseResult.GetValue(footerTextOption);
|
||||
var pageNumbers = parseResult.GetValue(pageNumbersOption);
|
||||
var tocPlaceholder = parseResult.GetValue(tocOption);
|
||||
var contentJson = parseResult.GetValue(contentJsonOption);
|
||||
|
||||
var fontConfig = GetFontConfig(docType);
|
||||
var pageSize = GetPageSizeConfig(pageSizeName);
|
||||
var margins = GetMargins(marginsName);
|
||||
|
||||
using var doc = WordprocessingDocument.Create(output, WordprocessingDocumentType.Document);
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
var body = mainPart.Document.Body!;
|
||||
|
||||
// Add styles part with defaults
|
||||
AddDefaultStyles(mainPart, fontConfig);
|
||||
|
||||
// Add section properties (page size, margins)
|
||||
var sectPr = new SectionProperties();
|
||||
sectPr.Append(new DocumentFormat.OpenXml.Wordprocessing.PageSize
|
||||
{
|
||||
Width = (UInt32Value)(uint)pageSize.WidthDxa,
|
||||
Height = (UInt32Value)(uint)pageSize.HeightDxa
|
||||
});
|
||||
sectPr.Append(new PageMargin
|
||||
{
|
||||
Top = margins.TopDxa,
|
||||
Bottom = margins.BottomDxa,
|
||||
Left = (UInt32Value)(uint)margins.LeftDxa,
|
||||
Right = (UInt32Value)(uint)margins.RightDxa
|
||||
});
|
||||
|
||||
// Add header if requested
|
||||
if (!string.IsNullOrEmpty(headerText))
|
||||
{
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
headerPart.Header = new Header(
|
||||
new Paragraph(new Run(new Text(headerText))));
|
||||
var headerRefId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// Add footer if requested
|
||||
if (!string.IsNullOrEmpty(footerText) || pageNumbers)
|
||||
{
|
||||
var footerPart = mainPart.AddNewPart<FooterPart>();
|
||||
var footerParagraph = new Paragraph();
|
||||
|
||||
if (!string.IsNullOrEmpty(footerText))
|
||||
{
|
||||
footerParagraph.Append(new Run(new Text(footerText)));
|
||||
}
|
||||
|
||||
if (pageNumbers)
|
||||
{
|
||||
if (!string.IsNullOrEmpty(footerText))
|
||||
footerParagraph.Append(new Run(new Text(" — ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
footerParagraph.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
footerParagraph.Append(new Run(
|
||||
new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
footerParagraph.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
}
|
||||
|
||||
footerPart.Footer = new Footer(footerParagraph);
|
||||
var footerRefId = mainPart.GetIdOfPart(footerPart);
|
||||
sectPr.Append(new FooterReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = footerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// Title
|
||||
if (!string.IsNullOrEmpty(title))
|
||||
{
|
||||
var titlePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Title" }),
|
||||
new Run(new Text(title)));
|
||||
body.Append(titlePara);
|
||||
}
|
||||
|
||||
// Author subtitle
|
||||
if (!string.IsNullOrEmpty(author))
|
||||
{
|
||||
var authorPara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Subtitle" }),
|
||||
new Run(new Text(author)));
|
||||
body.Append(authorPara);
|
||||
}
|
||||
|
||||
// TOC placeholder
|
||||
if (tocPlaceholder)
|
||||
{
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
|
||||
new Run(new Text("Table of Contents"))));
|
||||
|
||||
// Insert TOC field
|
||||
var tocPara = new Paragraph();
|
||||
tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
tocPara.Append(new Run(new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
tocPara.Append(new Run(new Text("Update this field to generate table of contents.")));
|
||||
tocPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
body.Append(tocPara);
|
||||
|
||||
// Page break after TOC
|
||||
body.Append(new Paragraph(new Run(new Break { Type = BreakValues.Page })));
|
||||
}
|
||||
|
||||
// Content from JSON (if provided)
|
||||
if (!string.IsNullOrEmpty(contentJson) && File.Exists(contentJson))
|
||||
{
|
||||
var jsonContent = File.ReadAllText(contentJson);
|
||||
AddContentFromJson(body, jsonContent, fontConfig);
|
||||
}
|
||||
|
||||
// Ensure body has at least one paragraph
|
||||
if (!body.Elements<Paragraph>().Any())
|
||||
{
|
||||
body.Append(new Paragraph());
|
||||
}
|
||||
|
||||
// sectPr must be the last child of body
|
||||
body.Append(sectPr);
|
||||
|
||||
mainPart.Document.Save();
|
||||
Console.WriteLine($"Created {docType} document: {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static FontConfig GetFontConfig(string docType) => docType.ToLowerInvariant() switch
|
||||
{
|
||||
"letter" => FontDefaults.Letter,
|
||||
"memo" => FontDefaults.Memo,
|
||||
"academic" => FontDefaults.Academic,
|
||||
_ => FontDefaults.Report,
|
||||
};
|
||||
|
||||
private static Typography.PageSize GetPageSizeConfig(string name) => name.ToLowerInvariant() switch
|
||||
{
|
||||
"a4" => PageSizes.A4,
|
||||
"legal" => PageSizes.Legal,
|
||||
"a3" => PageSizes.A3,
|
||||
_ => PageSizes.Letter,
|
||||
};
|
||||
|
||||
private static MarginConfig GetMargins(string name) => name.ToLowerInvariant() switch
|
||||
{
|
||||
"narrow" => PageSizes.NarrowMargins,
|
||||
"wide" => PageSizes.WideMargins,
|
||||
_ => PageSizes.StandardMargins,
|
||||
};
|
||||
|
||||
private static void AddDefaultStyles(MainDocumentPart mainPart, FontConfig fontConfig)
|
||||
{
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
var styles = new Styles();
|
||||
|
||||
// Default run properties
|
||||
var defaultRPr = new StyleRunProperties(
|
||||
new RunFonts { Ascii = fontConfig.BodyFont, HighAnsi = fontConfig.BodyFont },
|
||||
new FontSize { Val = UnitConverter.FontSizeToSz(fontConfig.BodySize) },
|
||||
new FontSizeComplexScript { Val = UnitConverter.FontSizeToSz(fontConfig.BodySize) });
|
||||
|
||||
// Normal style
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "Normal" },
|
||||
new PrimaryStyle(),
|
||||
defaultRPr)
|
||||
{ Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });
|
||||
|
||||
// Heading styles 1-6
|
||||
double[] headingSizes = [fontConfig.Heading1Size, fontConfig.Heading2Size, fontConfig.Heading3Size,
|
||||
fontConfig.Heading4Size, fontConfig.Heading5Size, fontConfig.Heading6Size];
|
||||
for (int i = 0; i < 6; i++)
|
||||
{
|
||||
var level = i + 1;
|
||||
var headingStyle = new Style(
|
||||
new StyleName { Val = $"heading {level}" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines { Before = "240", After = "120" },
|
||||
new OutlineLevel { Val = i }),
|
||||
new StyleRunProperties(
|
||||
new RunFonts { Ascii = fontConfig.HeadingFont, HighAnsi = fontConfig.HeadingFont },
|
||||
new FontSize { Val = UnitConverter.FontSizeToSz(headingSizes[i]) },
|
||||
new FontSizeComplexScript { Val = UnitConverter.FontSizeToSz(headingSizes[i]) },
|
||||
new Bold()))
|
||||
{ Type = StyleValues.Paragraph, StyleId = $"Heading{level}" };
|
||||
styles.Append(headingStyle);
|
||||
}
|
||||
|
||||
// Title style
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "Title" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { After = "300" }),
|
||||
new StyleRunProperties(
|
||||
new RunFonts { Ascii = fontConfig.HeadingFont, HighAnsi = fontConfig.HeadingFont },
|
||||
new FontSize { Val = UnitConverter.FontSizeToSz(fontConfig.Heading1Size + 6) },
|
||||
new FontSizeComplexScript { Val = UnitConverter.FontSizeToSz(fontConfig.Heading1Size + 6) }))
|
||||
{ Type = StyleValues.Paragraph, StyleId = "Title" });
|
||||
|
||||
// Subtitle style
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "Subtitle" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { After = "200" }),
|
||||
new StyleRunProperties(
|
||||
new Color { Val = "5A5A5A" },
|
||||
new FontSize { Val = UnitConverter.FontSizeToSz(fontConfig.BodySize + 2) }))
|
||||
{ Type = StyleValues.Paragraph, StyleId = "Subtitle" });
|
||||
|
||||
stylesPart.Styles = styles;
|
||||
stylesPart.Styles.Save();
|
||||
}
|
||||
|
||||
private static void AddContentFromJson(Body body, string jsonContent, FontConfig fontConfig)
|
||||
{
|
||||
// Simple JSON content format: array of {type, text, level?}
|
||||
// e.g. [{"type":"heading","text":"Introduction","level":1},{"type":"paragraph","text":"..."}]
|
||||
try
|
||||
{
|
||||
using var jsonDoc = System.Text.Json.JsonDocument.Parse(jsonContent);
|
||||
foreach (var element in jsonDoc.RootElement.EnumerateArray())
|
||||
{
|
||||
var type = element.GetProperty("type").GetString() ?? "paragraph";
|
||||
var text = element.GetProperty("text").GetString() ?? "";
|
||||
|
||||
switch (type)
|
||||
{
|
||||
case "heading":
|
||||
var level = element.TryGetProperty("level", out var lvl) ? lvl.GetInt32() : 1;
|
||||
level = Math.Clamp(level, 1, 6);
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = $"Heading{level}" }),
|
||||
new Run(new Text(text))));
|
||||
break;
|
||||
|
||||
case "paragraph":
|
||||
body.Append(new Paragraph(new Run(new Text(text))));
|
||||
break;
|
||||
|
||||
case "pagebreak":
|
||||
body.Append(new Paragraph(new Run(new Break { Type = BreakValues.Page })));
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
catch (System.Text.Json.JsonException ex)
|
||||
{
|
||||
Console.Error.WriteLine($"Warning: could not parse content JSON: {ex.Message}");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,155 @@
|
||||
using System.CommandLine;
|
||||
using System.IO.Compression;
|
||||
using System.Text.Json;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
public static class DiffCommand
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
|
||||
public static Command Create()
|
||||
{
|
||||
var beforeOption = new Option<string>("--before") { Description = "Original DOCX", Required = true };
|
||||
var afterOption = new Option<string>("--after") { Description = "Modified DOCX", Required = true };
|
||||
var jsonOption = new Option<bool>("--json") { Description = "Output as JSON" };
|
||||
|
||||
var cmd = new Command("diff", "Compare two DOCX files")
|
||||
{
|
||||
beforeOption, afterOption, jsonOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var before = parseResult.GetValue(beforeOption)!;
|
||||
var after = parseResult.GetValue(afterOption)!;
|
||||
var asJson = parseResult.GetValue(jsonOption);
|
||||
|
||||
if (!File.Exists(before)) { Console.Error.WriteLine($"File not found: {before}"); return; }
|
||||
if (!File.Exists(after)) { Console.Error.WriteLine($"File not found: {after}"); return; }
|
||||
|
||||
var beforeParas = ExtractParagraphs(before);
|
||||
var afterParas = ExtractParagraphs(after);
|
||||
var beforeStyles = ExtractStyleIds(before);
|
||||
var afterStyles = ExtractStyleIds(after);
|
||||
var beforeStructure = ExtractStructure(before);
|
||||
var afterStructure = ExtractStructure(after);
|
||||
|
||||
// Text diff
|
||||
var textChanges = new List<object>();
|
||||
int maxLen = Math.Max(beforeParas.Count, afterParas.Count);
|
||||
int changedParas = 0;
|
||||
for (int i = 0; i < maxLen; i++)
|
||||
{
|
||||
var bText = i < beforeParas.Count ? beforeParas[i] : null;
|
||||
var aText = i < afterParas.Count ? afterParas[i] : null;
|
||||
|
||||
if (bText != aText)
|
||||
{
|
||||
changedParas++;
|
||||
textChanges.Add(new
|
||||
{
|
||||
paragraph = i + 1,
|
||||
before = bText ?? "(absent)",
|
||||
after = aText ?? "(absent)"
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Style diff
|
||||
var addedStyles = afterStyles.Except(beforeStyles).ToList();
|
||||
var removedStyles = beforeStyles.Except(afterStyles).ToList();
|
||||
|
||||
// Structure diff
|
||||
var structureChanges = new List<string>();
|
||||
if (beforeStructure.Sections != afterStructure.Sections)
|
||||
structureChanges.Add($"Sections: {beforeStructure.Sections} -> {afterStructure.Sections}");
|
||||
if (beforeStructure.Tables != afterStructure.Tables)
|
||||
structureChanges.Add($"Tables: {beforeStructure.Tables} -> {afterStructure.Tables}");
|
||||
if (beforeStructure.Images != afterStructure.Images)
|
||||
structureChanges.Add($"Images: {beforeStructure.Images} -> {afterStructure.Images}");
|
||||
|
||||
var result = new
|
||||
{
|
||||
textChanges,
|
||||
styleChanges = new { added = addedStyles, removed = removedStyles },
|
||||
structureChanges,
|
||||
summary = $"{changedParas} paragraphs changed, {addedStyles.Count + removedStyles.Count} styles modified, {structureChanges.Count} structural changes"
|
||||
};
|
||||
|
||||
if (asJson)
|
||||
{
|
||||
Console.WriteLine(JsonSerializer.Serialize(result, new JsonSerializerOptions { WriteIndented = true }));
|
||||
}
|
||||
else
|
||||
{
|
||||
Console.WriteLine(result.summary);
|
||||
Console.WriteLine();
|
||||
|
||||
if (textChanges.Count > 0)
|
||||
{
|
||||
Console.WriteLine($"Text changes ({textChanges.Count}):");
|
||||
foreach (var tc in textChanges.Take(20))
|
||||
Console.WriteLine($" {tc}");
|
||||
if (textChanges.Count > 20)
|
||||
Console.WriteLine($" ... and {textChanges.Count - 20} more");
|
||||
}
|
||||
|
||||
if (addedStyles.Count > 0)
|
||||
Console.WriteLine($"Added styles: {string.Join(", ", addedStyles)}");
|
||||
if (removedStyles.Count > 0)
|
||||
Console.WriteLine($"Removed styles: {string.Join(", ", removedStyles)}");
|
||||
|
||||
foreach (var sc in structureChanges)
|
||||
Console.WriteLine($"Structure: {sc}");
|
||||
}
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static List<string> ExtractParagraphs(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/document.xml");
|
||||
if (entry == null) return new();
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
return doc.Descendants(W + "p")
|
||||
.Select(p => string.Concat(p.Descendants(W + "t").Select(t => t.Value)))
|
||||
.ToList();
|
||||
}
|
||||
|
||||
private static HashSet<string> ExtractStyleIds(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/styles.xml");
|
||||
if (entry == null) return new();
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
return doc.Descendants(W + "style")
|
||||
.Select(s => (string?)s.Attribute(W + "styleId"))
|
||||
.Where(id => id != null)
|
||||
.ToHashSet()!;
|
||||
}
|
||||
|
||||
private record StructureInfo(int Sections, int Tables, int Images);
|
||||
|
||||
private static StructureInfo ExtractStructure(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/document.xml");
|
||||
if (entry == null) return new(0, 0, 0);
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
return new(
|
||||
doc.Descendants(W + "sectPr").Count(),
|
||||
doc.Descendants(W + "tbl").Count(),
|
||||
doc.Descendants(W + "drawing").Count()
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,487 @@
|
||||
using System.CommandLine;
|
||||
using System.Text.RegularExpressions;
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
using DocxToolkit.Core.OpenXml;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
/// <summary>
|
||||
/// Scenario B: Surgical content editing operations on existing DOCX files.
|
||||
/// Preserves all existing formatting and minimizes XML changes.
|
||||
/// </summary>
|
||||
public static class EditContentCommand
|
||||
{
|
||||
public static Command Create()
|
||||
{
|
||||
var cmd = new Command("edit", "Edit existing DOCX content");
|
||||
|
||||
cmd.Add(CreateReplaceTextCommand());
|
||||
cmd.Add(CreateFillTableCommand());
|
||||
cmd.Add(CreateInsertParagraphCommand());
|
||||
cmd.Add(CreateUpdateFieldCommand());
|
||||
cmd.Add(CreateListPlaceholdersCommand());
|
||||
cmd.Add(CreateFillPlaceholdersCommand());
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateReplaceTextCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output file path (defaults to overwriting input)" };
|
||||
var searchOpt = new Option<string>("--search") { Description = "Text to search for", Required = true };
|
||||
var replaceOpt = new Option<string>("--replace") { Description = "Replacement text", Required = true };
|
||||
var regexOpt = new Option<bool>("--regex") { Description = "Treat search as a regex pattern" };
|
||||
|
||||
var cmd = new Command("replace-text", "Replace text while preserving formatting")
|
||||
{
|
||||
inputOpt, outputOpt, searchOpt, replaceOpt, regexOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var output = parseResult.GetValue(outputOpt) ?? input;
|
||||
var search = parseResult.GetValue(searchOpt)!;
|
||||
var replace = parseResult.GetValue(replaceOpt)!;
|
||||
var useRegex = parseResult.GetValue(regexOpt);
|
||||
|
||||
if (output != input) File.Copy(input, output, overwrite: true);
|
||||
|
||||
using var doc = WordprocessingDocument.Open(output, true);
|
||||
var body = doc.MainDocumentPart?.Document.Body;
|
||||
if (body == null) { Console.Error.WriteLine("No document body found."); return; }
|
||||
|
||||
int count = 0;
|
||||
foreach (var paragraph in body.Descendants<Paragraph>())
|
||||
{
|
||||
count += ReplaceInParagraph(paragraph, search, replace, useRegex);
|
||||
}
|
||||
|
||||
doc.MainDocumentPart!.Document.Save();
|
||||
Console.WriteLine($"Replaced {count} occurrence(s) in {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateFillTableCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output file path" };
|
||||
var tableIndexOpt = new Option<int>("--table-index") { Description = "Zero-based index of the table to fill" };
|
||||
tableIndexOpt.DefaultValueFactory = _ => 0;
|
||||
var csvOpt = new Option<string>("--csv") { Description = "CSV file with data to fill", Required = true };
|
||||
var appendOpt = new Option<bool>("--append") { Description = "Append rows instead of replacing existing data rows" };
|
||||
|
||||
var cmd = new Command("fill-table", "Fill a table with data from CSV")
|
||||
{
|
||||
inputOpt, outputOpt, tableIndexOpt, csvOpt, appendOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var output = parseResult.GetValue(outputOpt) ?? input;
|
||||
var tableIndex = parseResult.GetValue(tableIndexOpt);
|
||||
var csvPath = parseResult.GetValue(csvOpt)!;
|
||||
var append = parseResult.GetValue(appendOpt);
|
||||
|
||||
if (output != input) File.Copy(input, output, overwrite: true);
|
||||
|
||||
if (!File.Exists(csvPath)) { Console.Error.WriteLine($"CSV file not found: {csvPath}"); return; }
|
||||
|
||||
using var doc = WordprocessingDocument.Open(output, true);
|
||||
var body = doc.MainDocumentPart?.Document.Body;
|
||||
if (body == null) { Console.Error.WriteLine("No document body found."); return; }
|
||||
|
||||
var tables = body.Elements<Table>().ToList();
|
||||
if (tableIndex >= tables.Count)
|
||||
{
|
||||
Console.Error.WriteLine($"Table index {tableIndex} out of range (found {tables.Count} tables).");
|
||||
return;
|
||||
}
|
||||
|
||||
var table = tables[tableIndex];
|
||||
var csvLines = File.ReadAllLines(csvPath);
|
||||
if (csvLines.Length == 0) { Console.WriteLine("CSV is empty, nothing to fill."); return; }
|
||||
|
||||
// Get template row properties from the first data row (second row, after header)
|
||||
var existingRows = table.Elements<TableRow>().ToList();
|
||||
TableRow? templateRow = existingRows.Count > 1 ? existingRows[1] : existingRows.FirstOrDefault();
|
||||
var templateTrPr = templateRow?.TableRowProperties?.CloneNode(true) as TableRowProperties;
|
||||
|
||||
if (!append)
|
||||
{
|
||||
// Remove all rows except the header row
|
||||
for (int i = existingRows.Count - 1; i >= 1; i--)
|
||||
existingRows[i].Remove();
|
||||
}
|
||||
|
||||
int rowsAdded = 0;
|
||||
// Skip header line in CSV (index 0)
|
||||
for (int i = 1; i < csvLines.Length; i++)
|
||||
{
|
||||
var values = ParseCsvLine(csvLines[i]);
|
||||
var newRow = new TableRow();
|
||||
if (templateTrPr != null)
|
||||
newRow.Append(templateTrPr.CloneNode(true));
|
||||
|
||||
foreach (var val in values)
|
||||
{
|
||||
var cell = new TableCell(
|
||||
new Paragraph(new Run(new Text(val))));
|
||||
newRow.Append(cell);
|
||||
}
|
||||
|
||||
table.Append(newRow);
|
||||
rowsAdded++;
|
||||
}
|
||||
|
||||
doc.MainDocumentPart!.Document.Save();
|
||||
Console.WriteLine($"Added {rowsAdded} rows to table {tableIndex} in {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateInsertParagraphCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output file path" };
|
||||
var textOpt = new Option<string>("--text") { Description = "Paragraph text", Required = true };
|
||||
var styleOpt = new Option<string>("--style") { Description = "Paragraph style (e.g. Heading1, Normal)" };
|
||||
var afterOpt = new Option<int>("--after-paragraph") { Description = "Insert after this paragraph index (0-based)" };
|
||||
afterOpt.DefaultValueFactory = _ => -1; // -1 = append at end
|
||||
|
||||
var cmd = new Command("insert-paragraph", "Insert a new paragraph")
|
||||
{
|
||||
inputOpt, outputOpt, textOpt, styleOpt, afterOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var output = parseResult.GetValue(outputOpt) ?? input;
|
||||
var text = parseResult.GetValue(textOpt)!;
|
||||
var style = parseResult.GetValue(styleOpt);
|
||||
var afterIndex = parseResult.GetValue(afterOpt);
|
||||
|
||||
if (output != input) File.Copy(input, output, overwrite: true);
|
||||
|
||||
using var doc = WordprocessingDocument.Open(output, true);
|
||||
var body = doc.MainDocumentPart?.Document.Body;
|
||||
if (body == null) { Console.Error.WriteLine("No document body found."); return; }
|
||||
|
||||
var newPara = new Paragraph();
|
||||
if (!string.IsNullOrEmpty(style))
|
||||
newPara.Append(new ParagraphProperties(new ParagraphStyleId { Val = style }));
|
||||
newPara.Append(new Run(new Text(text)));
|
||||
|
||||
var paragraphs = body.Elements<Paragraph>().ToList();
|
||||
if (afterIndex >= 0 && afterIndex < paragraphs.Count)
|
||||
{
|
||||
paragraphs[afterIndex].InsertAfterSelf(newPara);
|
||||
}
|
||||
else
|
||||
{
|
||||
// Insert before sectPr if present, otherwise append
|
||||
var sectPr = body.Elements<SectionProperties>().FirstOrDefault();
|
||||
if (sectPr != null)
|
||||
sectPr.InsertBeforeSelf(newPara);
|
||||
else
|
||||
body.Append(newPara);
|
||||
}
|
||||
|
||||
doc.MainDocumentPart!.Document.Save();
|
||||
Console.WriteLine($"Inserted paragraph in {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateUpdateFieldCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output file path" };
|
||||
var fieldNameOpt = new Option<string>("--field") { Description = "Document property field name (e.g. TITLE, AUTHOR)", Required = true };
|
||||
var valueOpt = new Option<string>("--value") { Description = "New field value", Required = true };
|
||||
|
||||
var cmd = new Command("update-field", "Update a document property field value")
|
||||
{
|
||||
inputOpt, outputOpt, fieldNameOpt, valueOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var output = parseResult.GetValue(outputOpt) ?? input;
|
||||
var fieldName = parseResult.GetValue(fieldNameOpt)!;
|
||||
var value = parseResult.GetValue(valueOpt)!;
|
||||
|
||||
if (output != input) File.Copy(input, output, overwrite: true);
|
||||
|
||||
using var doc = WordprocessingDocument.Open(output, true);
|
||||
|
||||
// Update core properties
|
||||
var props = doc.PackageProperties;
|
||||
switch (fieldName.ToUpperInvariant())
|
||||
{
|
||||
case "TITLE": props.Title = value; break;
|
||||
case "AUTHOR": props.Creator = value; break;
|
||||
case "SUBJECT": props.Subject = value; break;
|
||||
case "KEYWORDS": props.Keywords = value; break;
|
||||
case "DESCRIPTION": props.Description = value; break;
|
||||
case "CATEGORY": props.Category = value; break;
|
||||
default:
|
||||
Console.Error.WriteLine($"Unknown field: {fieldName}. Supported: TITLE, AUTHOR, SUBJECT, KEYWORDS, DESCRIPTION, CATEGORY");
|
||||
return;
|
||||
}
|
||||
|
||||
Console.WriteLine($"Updated {fieldName} to \"{value}\" in {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateListPlaceholdersCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var patternOpt = new Option<string>("--pattern") { Description = "Placeholder pattern (regex)" };
|
||||
patternOpt.DefaultValueFactory = _ => @"\{\{(\w+)\}\}"; // {{PLACEHOLDER}}
|
||||
|
||||
var cmd = new Command("list-placeholders", "List all placeholders found in the document")
|
||||
{
|
||||
inputOpt, patternOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var pattern = parseResult.GetValue(patternOpt)!;
|
||||
|
||||
using var doc = WordprocessingDocument.Open(input, false);
|
||||
var body = doc.MainDocumentPart?.Document.Body;
|
||||
if (body == null) { Console.Error.WriteLine("No document body found."); return; }
|
||||
|
||||
var placeholders = new HashSet<string>();
|
||||
var regex = new Regex(pattern);
|
||||
|
||||
foreach (var paragraph in body.Descendants<Paragraph>())
|
||||
{
|
||||
var fullText = string.Concat(paragraph.Descendants<Text>().Select(t => t.Text));
|
||||
foreach (Match match in regex.Matches(fullText))
|
||||
{
|
||||
placeholders.Add(match.Value);
|
||||
}
|
||||
}
|
||||
|
||||
if (placeholders.Count == 0)
|
||||
{
|
||||
Console.WriteLine("No placeholders found.");
|
||||
return;
|
||||
}
|
||||
|
||||
Console.WriteLine($"Found {placeholders.Count} unique placeholder(s):");
|
||||
foreach (var p in placeholders.OrderBy(x => x))
|
||||
Console.WriteLine($" {p}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
private static Command CreateFillPlaceholdersCommand()
|
||||
{
|
||||
var inputOpt = new Option<string>("--input") { Description = "Input DOCX file", Required = true };
|
||||
var outputOpt = new Option<string>("--output") { Description = "Output file path" };
|
||||
var mappingOpt = new Option<string>("--mapping") { Description = "JSON file mapping placeholder names to values", Required = true };
|
||||
var patternOpt = new Option<string>("--pattern") { Description = "Placeholder pattern with capture group for the name" };
|
||||
patternOpt.DefaultValueFactory = _ => @"\{\{(\w+)\}\}";
|
||||
|
||||
var cmd = new Command("fill-placeholders", "Replace placeholders with values from a mapping file")
|
||||
{
|
||||
inputOpt, outputOpt, mappingOpt, patternOpt
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOpt)!;
|
||||
var output = parseResult.GetValue(outputOpt) ?? input;
|
||||
var mappingPath = parseResult.GetValue(mappingOpt)!;
|
||||
var pattern = parseResult.GetValue(patternOpt)!;
|
||||
|
||||
if (!File.Exists(mappingPath)) { Console.Error.WriteLine($"Mapping file not found: {mappingPath}"); return; }
|
||||
|
||||
var mappingJson = File.ReadAllText(mappingPath);
|
||||
Dictionary<string, string> mapping;
|
||||
try
|
||||
{
|
||||
mapping = System.Text.Json.JsonSerializer.Deserialize<Dictionary<string, string>>(mappingJson) ?? [];
|
||||
}
|
||||
catch (System.Text.Json.JsonException ex)
|
||||
{
|
||||
Console.Error.WriteLine($"Invalid mapping JSON: {ex.Message}");
|
||||
return;
|
||||
}
|
||||
|
||||
if (output != input) File.Copy(input, output, overwrite: true);
|
||||
|
||||
using var doc = WordprocessingDocument.Open(output, true);
|
||||
var body = doc.MainDocumentPart?.Document.Body;
|
||||
if (body == null) { Console.Error.WriteLine("No document body found."); return; }
|
||||
|
||||
int totalReplacements = 0;
|
||||
var regex = new Regex(pattern);
|
||||
|
||||
foreach (var paragraph in body.Descendants<Paragraph>())
|
||||
{
|
||||
var fullText = string.Concat(paragraph.Descendants<Text>().Select(t => t.Text));
|
||||
var matches = regex.Matches(fullText);
|
||||
if (matches.Count == 0) continue;
|
||||
|
||||
foreach (Match match in matches)
|
||||
{
|
||||
var placeholderName = match.Groups.Count > 1 ? match.Groups[1].Value : match.Value;
|
||||
if (mapping.TryGetValue(placeholderName, out var replacement))
|
||||
{
|
||||
totalReplacements += ReplaceInParagraph(paragraph, match.Value, replacement, false);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
doc.MainDocumentPart!.Document.Save();
|
||||
Console.WriteLine($"Filled {totalReplacements} placeholder(s) in {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Replaces text within a paragraph while preserving run formatting.
|
||||
/// Handles the case where search text may span multiple runs.
|
||||
/// </summary>
|
||||
private static int ReplaceInParagraph(Paragraph paragraph, string search, string replace, bool useRegex)
|
||||
{
|
||||
var runs = paragraph.Elements<Run>().ToList();
|
||||
if (runs.Count == 0) return 0;
|
||||
|
||||
// Build the full paragraph text and a map from character index to (run, position within run)
|
||||
var fullText = string.Concat(runs.SelectMany(r => r.Elements<Text>().Select(t => t.Text)));
|
||||
if (string.IsNullOrEmpty(fullText)) return 0;
|
||||
|
||||
int count = 0;
|
||||
|
||||
if (!useRegex)
|
||||
{
|
||||
// Simple case: search within each run first
|
||||
foreach (var run in runs)
|
||||
{
|
||||
foreach (var textElement in run.Elements<Text>().ToList())
|
||||
{
|
||||
if (textElement.Text.Contains(search))
|
||||
{
|
||||
var newText = textElement.Text.Replace(search, replace);
|
||||
count += (textElement.Text.Length - newText.Length + replace.Length - search.Length) == 0 ? 0 :
|
||||
CountOccurrences(textElement.Text, search);
|
||||
textElement.Text = newText;
|
||||
if (newText.StartsWith(' ') || newText.EndsWith(' '))
|
||||
textElement.Space = SpaceProcessingModeValues.Preserve;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Handle cross-run matches by concatenating all runs, replacing, and rebuilding
|
||||
if (count == 0 && fullText.Contains(search))
|
||||
{
|
||||
var newFullText = fullText.Replace(search, replace);
|
||||
count = CountOccurrences(fullText, search);
|
||||
RebuildRunsWithText(paragraph, runs, newFullText);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
var regex = new Regex(search);
|
||||
if (regex.IsMatch(fullText))
|
||||
{
|
||||
count = regex.Matches(fullText).Count;
|
||||
var newFullText = regex.Replace(fullText, replace);
|
||||
RebuildRunsWithText(paragraph, runs, newFullText);
|
||||
}
|
||||
}
|
||||
|
||||
return count;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Replaces the text content of existing runs with new text,
|
||||
/// preserving the formatting of the first run.
|
||||
/// </summary>
|
||||
private static void RebuildRunsWithText(Paragraph paragraph, List<Run> runs, string newText)
|
||||
{
|
||||
if (runs.Count == 0) return;
|
||||
|
||||
// Keep the first run's formatting, set its text to the full new text
|
||||
var firstRun = runs[0];
|
||||
var firstText = firstRun.Elements<Text>().FirstOrDefault();
|
||||
if (firstText != null)
|
||||
{
|
||||
firstText.Text = newText;
|
||||
if (newText.StartsWith(' ') || newText.EndsWith(' '))
|
||||
firstText.Space = SpaceProcessingModeValues.Preserve;
|
||||
}
|
||||
|
||||
// Remove all other runs
|
||||
for (int i = 1; i < runs.Count; i++)
|
||||
runs[i].Remove();
|
||||
}
|
||||
|
||||
private static int CountOccurrences(string text, string search)
|
||||
{
|
||||
int count = 0;
|
||||
int index = 0;
|
||||
while ((index = text.IndexOf(search, index, StringComparison.Ordinal)) != -1)
|
||||
{
|
||||
count++;
|
||||
index += search.Length;
|
||||
}
|
||||
return count;
|
||||
}
|
||||
|
||||
private static string[] ParseCsvLine(string line)
|
||||
{
|
||||
// Simple CSV parser (handles quoted fields)
|
||||
var result = new List<string>();
|
||||
bool inQuotes = false;
|
||||
var current = new System.Text.StringBuilder();
|
||||
|
||||
for (int i = 0; i < line.Length; i++)
|
||||
{
|
||||
char c = line[i];
|
||||
if (c == '"')
|
||||
{
|
||||
if (inQuotes && i + 1 < line.Length && line[i + 1] == '"')
|
||||
{
|
||||
current.Append('"');
|
||||
i++;
|
||||
}
|
||||
else
|
||||
{
|
||||
inQuotes = !inQuotes;
|
||||
}
|
||||
}
|
||||
else if (c == ',' && !inQuotes)
|
||||
{
|
||||
result.Add(current.ToString());
|
||||
current.Clear();
|
||||
}
|
||||
else
|
||||
{
|
||||
current.Append(c);
|
||||
}
|
||||
}
|
||||
result.Add(current.ToString());
|
||||
return result.ToArray();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,108 @@
|
||||
using System.CommandLine;
|
||||
using System.IO.Compression;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
public static class FixOrderCommand
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
|
||||
// Canonical element ordering within common parent elements per ISO 29500
|
||||
private static readonly Dictionary<string, List<string>> ElementOrder = new()
|
||||
{
|
||||
["pPr"] = new() { "pStyle", "keepNext", "keepLines", "pageBreakBefore", "widowControl", "numPr", "suppressLineNumbers", "pBdr", "shd", "tabs", "suppressAutoHyphens", "spacing", "ind", "jc", "outlineLvl", "rPr" },
|
||||
["rPr"] = new() { "rStyle", "rFonts", "b", "bCs", "i", "iCs", "caps", "smallCaps", "strike", "dstrike", "vanish", "color", "spacing", "w", "kern", "position", "sz", "szCs", "highlight", "u", "effect", "vertAlign", "lang" },
|
||||
["tblPr"] = new() { "tblStyle", "tblpPr", "tblOverlap", "tblW", "jc", "tblInd", "tblBorders", "shd", "tblLayout", "tblCellMar", "tblLook" },
|
||||
["tcPr"] = new() { "cnfStyle", "tcW", "gridSpan", "hMerge", "vMerge", "tcBorders", "shd", "noWrap", "tcMar", "textDirection", "tcFitText", "vAlign" },
|
||||
["sectPr"] = new() { "headerReference", "footerReference", "footnotePr", "endnotePr", "type", "pgSz", "pgMar", "paperSrc", "pgBorders", "lnNumType", "pgNumType", "cols", "docGrid" },
|
||||
};
|
||||
|
||||
public static Command Create()
|
||||
{
|
||||
var inputOption = new Option<string>("--input") { Description = "DOCX file to fix", Required = true };
|
||||
var outputOption = new Option<string>("--output") { Description = "Output path (default: overwrite input)" };
|
||||
var backupOption = new Option<bool>("--backup") { Description = "Create .bak before modifying", DefaultValueFactory = (_) => true };
|
||||
|
||||
var cmd = new Command("fix-order", "Fix OpenXML element ordering per ISO 29500")
|
||||
{
|
||||
inputOption, outputOption, backupOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOption)!;
|
||||
var output = parseResult.GetValue(outputOption) ?? input;
|
||||
var backup = parseResult.GetValue(backupOption);
|
||||
|
||||
if (!File.Exists(input))
|
||||
{
|
||||
Console.Error.WriteLine($"File not found: {input}");
|
||||
return;
|
||||
}
|
||||
|
||||
if (backup && output == input)
|
||||
File.Copy(input, input + ".bak", true);
|
||||
|
||||
var tempPath = Path.GetTempFileName();
|
||||
File.Copy(input, tempPath, true);
|
||||
|
||||
using var zip = ZipFile.Open(tempPath, ZipArchiveMode.Update);
|
||||
var entry = zip.GetEntry("word/document.xml");
|
||||
if (entry == null)
|
||||
{
|
||||
Console.Error.WriteLine("Not a valid DOCX");
|
||||
return;
|
||||
}
|
||||
|
||||
XDocument doc;
|
||||
using (var stream = entry.Open())
|
||||
doc = XDocument.Load(stream);
|
||||
|
||||
int reorderedCount = 0;
|
||||
|
||||
foreach (var (parentName, order) in ElementOrder)
|
||||
{
|
||||
foreach (var parent in doc.Descendants(W + parentName))
|
||||
{
|
||||
var children = parent.Elements().ToList();
|
||||
var sorted = children.OrderBy(e =>
|
||||
{
|
||||
var idx = order.IndexOf(e.Name.LocalName);
|
||||
return idx >= 0 ? idx : order.Count;
|
||||
}).ToList();
|
||||
|
||||
bool changed = false;
|
||||
for (int i = 0; i < children.Count; i++)
|
||||
{
|
||||
if (children[i] != sorted[i])
|
||||
{
|
||||
changed = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (changed)
|
||||
{
|
||||
parent.ReplaceNodes(sorted);
|
||||
reorderedCount++;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
entry.Delete();
|
||||
var newEntry = zip.CreateEntry("word/document.xml", CompressionLevel.Optimal);
|
||||
using (var stream = newEntry.Open())
|
||||
doc.Save(stream);
|
||||
|
||||
zip.Dispose();
|
||||
File.Copy(tempPath, output, true);
|
||||
File.Delete(tempPath);
|
||||
|
||||
Console.WriteLine($"Reordered {reorderedCount} element group(s)");
|
||||
Console.WriteLine($"Written to: {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
using System.CommandLine;
|
||||
using System.IO.Compression;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
public static class MergeRunsCommand
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
|
||||
public static Command Create()
|
||||
{
|
||||
var inputOption = new Option<string>("--input") { Description = "DOCX file to optimize", Required = true };
|
||||
var outputOption = new Option<string>("--output") { Description = "Output path (default: overwrite input)" };
|
||||
var dryRunOption = new Option<bool>("--dry-run") { Description = "Report without modifying" };
|
||||
|
||||
var cmd = new Command("merge-runs", "Merge adjacent runs with identical formatting")
|
||||
{
|
||||
inputOption, outputOption, dryRunOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOption)!;
|
||||
var output = parseResult.GetValue(outputOption) ?? input;
|
||||
var dryRun = parseResult.GetValue(dryRunOption);
|
||||
|
||||
if (!File.Exists(input))
|
||||
{
|
||||
Console.Error.WriteLine($"File not found: {input}");
|
||||
return;
|
||||
}
|
||||
|
||||
var tempPath = Path.GetTempFileName();
|
||||
File.Copy(input, tempPath, true);
|
||||
|
||||
using var zip = ZipFile.Open(tempPath, ZipArchiveMode.Update);
|
||||
var entry = zip.GetEntry("word/document.xml");
|
||||
if (entry == null)
|
||||
{
|
||||
Console.Error.WriteLine("Not a valid DOCX: missing word/document.xml");
|
||||
return;
|
||||
}
|
||||
|
||||
XDocument doc;
|
||||
using (var stream = entry.Open())
|
||||
doc = XDocument.Load(stream);
|
||||
|
||||
int originalCount = 0;
|
||||
int mergedCount = 0;
|
||||
|
||||
foreach (var p in doc.Descendants(W + "p"))
|
||||
{
|
||||
var runs = p.Elements(W + "r").ToList();
|
||||
originalCount += runs.Count;
|
||||
|
||||
for (int i = runs.Count - 1; i > 0; i--)
|
||||
{
|
||||
var current = runs[i];
|
||||
var previous = runs[i - 1];
|
||||
|
||||
var curProps = current.Element(W + "rPr")?.ToString() ?? "";
|
||||
var prevProps = previous.Element(W + "rPr")?.ToString() ?? "";
|
||||
|
||||
if (curProps == prevProps)
|
||||
{
|
||||
// Only merge if both contain only text elements
|
||||
var curChildren = current.Elements().Where(e => e.Name != W + "rPr").ToList();
|
||||
var prevChildren = previous.Elements().Where(e => e.Name != W + "rPr").ToList();
|
||||
|
||||
if (curChildren.All(e => e.Name == W + "t") && prevChildren.All(e => e.Name == W + "t"))
|
||||
{
|
||||
var prevText = previous.Elements(W + "t").LastOrDefault();
|
||||
var curText = current.Elements(W + "t").FirstOrDefault();
|
||||
|
||||
if (prevText != null && curText != null)
|
||||
{
|
||||
prevText.Value += curText.Value;
|
||||
prevText.SetAttributeValue(XNamespace.Xml + "space", "preserve");
|
||||
|
||||
foreach (var extra in current.Elements(W + "t").Skip(1))
|
||||
{
|
||||
previous.Add(new XElement(extra));
|
||||
}
|
||||
|
||||
current.Remove();
|
||||
runs.RemoveAt(i);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
mergedCount += runs.Count;
|
||||
}
|
||||
|
||||
if (dryRun)
|
||||
{
|
||||
Console.WriteLine($"Original runs: {originalCount}");
|
||||
Console.WriteLine($"After merge: {mergedCount}");
|
||||
Console.WriteLine($"Reduction: {(originalCount > 0 ? (originalCount - mergedCount) * 100.0 / originalCount : 0):F1}%");
|
||||
File.Delete(tempPath);
|
||||
return;
|
||||
}
|
||||
|
||||
entry.Delete();
|
||||
var newEntry = zip.CreateEntry("word/document.xml", CompressionLevel.Optimal);
|
||||
using (var stream = newEntry.Open())
|
||||
doc.Save(stream);
|
||||
|
||||
zip.Dispose();
|
||||
File.Copy(tempPath, output, true);
|
||||
File.Delete(tempPath);
|
||||
|
||||
Console.WriteLine($"Original runs: {originalCount}");
|
||||
Console.WriteLine($"After merge: {mergedCount}");
|
||||
Console.WriteLine($"Reduction: {(originalCount > 0 ? (originalCount - mergedCount) * 100.0 / originalCount : 0):F1}%");
|
||||
Console.WriteLine($"Written to: {output}");
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
using System.CommandLine;
|
||||
using System.Text.Json;
|
||||
using DocxToolkit.Core.Validation;
|
||||
|
||||
namespace DocxToolkit.Core.Commands;
|
||||
|
||||
public static class ValidateCommand
|
||||
{
|
||||
public static Command Create()
|
||||
{
|
||||
var inputOption = new Option<string>("--input") { Description = "DOCX file to validate", Required = true };
|
||||
var xsdOption = new Option<string>("--xsd") { Description = "XSD schema path for XML validation" };
|
||||
var businessOption = new Option<bool>("--business") { Description = "Run business rule validation" };
|
||||
var gateCheckOption = new Option<string>("--gate-check") { Description = "Template DOCX for gate-check validation" };
|
||||
var jsonOption = new Option<bool>("--json") { Description = "Output results as JSON" };
|
||||
|
||||
var cmd = new Command("validate", "Validate DOCX structure and content")
|
||||
{
|
||||
inputOption, xsdOption, businessOption, gateCheckOption, jsonOption
|
||||
};
|
||||
|
||||
cmd.SetAction((parseResult) =>
|
||||
{
|
||||
var input = parseResult.GetValue(inputOption)!;
|
||||
var xsd = parseResult.GetValue(xsdOption);
|
||||
var business = parseResult.GetValue(businessOption);
|
||||
var gateCheck = parseResult.GetValue(gateCheckOption);
|
||||
var asJson = parseResult.GetValue(jsonOption);
|
||||
|
||||
if (!File.Exists(input))
|
||||
{
|
||||
Console.Error.WriteLine($"File not found: {input}");
|
||||
return;
|
||||
}
|
||||
|
||||
var combinedResult = new ValidationResult();
|
||||
GateCheckResult? gateResult = null;
|
||||
|
||||
if (xsd != null)
|
||||
{
|
||||
var xsdValidator = new XsdValidator();
|
||||
combinedResult.Merge(xsdValidator.Validate(input, xsd));
|
||||
}
|
||||
|
||||
if (business)
|
||||
{
|
||||
var bizValidator = new BusinessRuleValidator();
|
||||
combinedResult.Merge(bizValidator.Validate(input));
|
||||
}
|
||||
|
||||
if (gateCheck != null)
|
||||
{
|
||||
var gateValidator = new GateCheckValidator();
|
||||
gateResult = gateValidator.Validate(input, gateCheck);
|
||||
}
|
||||
|
||||
if (asJson)
|
||||
{
|
||||
var output = new
|
||||
{
|
||||
isValid = combinedResult.IsValid && (gateResult?.Passed ?? true),
|
||||
errors = combinedResult.Errors,
|
||||
warnings = combinedResult.Warnings,
|
||||
gateCheck = gateResult == null ? null : new
|
||||
{
|
||||
passed = gateResult.Passed,
|
||||
violations = gateResult.Violations
|
||||
}
|
||||
};
|
||||
Console.WriteLine(JsonSerializer.Serialize(output, new JsonSerializerOptions { WriteIndented = true }));
|
||||
}
|
||||
else
|
||||
{
|
||||
if (combinedResult.Errors.Count > 0)
|
||||
{
|
||||
Console.WriteLine($"ERRORS ({combinedResult.Errors.Count}):");
|
||||
foreach (var e in combinedResult.Errors)
|
||||
Console.WriteLine($" [{e.Severity}] {e.Message}" + (e.LineNumber > 0 ? $" (line {e.LineNumber}:{e.LinePosition})" : ""));
|
||||
}
|
||||
|
||||
if (combinedResult.Warnings.Count > 0)
|
||||
{
|
||||
Console.WriteLine($"WARNINGS ({combinedResult.Warnings.Count}):");
|
||||
foreach (var w in combinedResult.Warnings)
|
||||
Console.WriteLine($" [{w.Severity}] {w.Message}");
|
||||
}
|
||||
|
||||
if (gateResult != null)
|
||||
{
|
||||
Console.WriteLine(gateResult.Passed ? "GATE CHECK: PASSED" : "GATE CHECK: FAILED");
|
||||
foreach (var v in gateResult.Violations)
|
||||
Console.WriteLine($" - {v}");
|
||||
}
|
||||
|
||||
if (combinedResult.IsValid && (gateResult?.Passed ?? true))
|
||||
Console.WriteLine("Validation: PASSED");
|
||||
else
|
||||
Console.WriteLine("Validation: FAILED");
|
||||
}
|
||||
|
||||
if (!combinedResult.IsValid || gateResult is { Passed: false })
|
||||
Environment.ExitCode = 1;
|
||||
});
|
||||
|
||||
return cmd;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<NeutralLanguage>en</NeutralLanguage>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="DocumentFormat.OpenXml" Version="3.5.1" />
|
||||
<PackageReference Include="System.CommandLine" Version="2.0.5" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
@@ -0,0 +1,169 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// Manages the 4-file comment system (comments.xml, commentsExtended.xml,
|
||||
/// commentsIds.xml, commentsExtensible.xml) plus document.xml markers.
|
||||
/// </summary>
|
||||
public static class CommentSynchronizer
|
||||
{
|
||||
/// <summary>
|
||||
/// Adds a comment to the document, updating all required parts.
|
||||
/// </summary>
|
||||
public static int AddComment(WordprocessingDocument doc, string text, string author, string rangeBookmark)
|
||||
{
|
||||
var mainPart = doc.MainDocumentPart
|
||||
?? throw new InvalidOperationException("Document has no main part.");
|
||||
|
||||
int commentId = GetNextCommentId(doc);
|
||||
|
||||
// Ensure comments part exists
|
||||
var commentsPart = mainPart.WordprocessingCommentsPart
|
||||
?? mainPart.AddNewPart<WordprocessingCommentsPart>();
|
||||
|
||||
if (commentsPart.Comments == null)
|
||||
commentsPart.Comments = new Comments();
|
||||
|
||||
// Create the comment
|
||||
var comment = new Comment
|
||||
{
|
||||
Id = commentId.ToString(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Initials = author.Length > 0 ? author[..1].ToUpperInvariant() : "A"
|
||||
};
|
||||
comment.Append(new Paragraph(new Run(new Text(text))));
|
||||
commentsPart.Comments.Append(comment);
|
||||
|
||||
// Add range markers in document body
|
||||
var body = mainPart.Document.Body;
|
||||
if (body != null)
|
||||
{
|
||||
// Find bookmark or append at end
|
||||
var rangeStart = new CommentRangeStart { Id = commentId.ToString() };
|
||||
var rangeEnd = new CommentRangeEnd { Id = commentId.ToString() };
|
||||
var reference = new Run(new CommentReference { Id = commentId.ToString() });
|
||||
|
||||
body.Append(rangeStart);
|
||||
body.Append(rangeEnd);
|
||||
body.Append(new Paragraph(reference));
|
||||
}
|
||||
|
||||
return commentId;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds a reply to an existing comment.
|
||||
/// </summary>
|
||||
public static int AddReply(WordprocessingDocument doc, int parentCommentId, string text, string author)
|
||||
{
|
||||
var mainPart = doc.MainDocumentPart
|
||||
?? throw new InvalidOperationException("Document has no main part.");
|
||||
|
||||
var commentsPart = mainPart.WordprocessingCommentsPart
|
||||
?? throw new InvalidOperationException("Document has no comments part.");
|
||||
|
||||
int replyId = GetNextCommentId(doc);
|
||||
|
||||
var reply = new Comment
|
||||
{
|
||||
Id = replyId.ToString(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Initials = author.Length > 0 ? author[..1].ToUpperInvariant() : "A"
|
||||
};
|
||||
reply.Append(new Paragraph(new Run(new Text(text))));
|
||||
commentsPart.Comments?.Append(reply);
|
||||
|
||||
// Link reply to parent via commentsExtended.xml
|
||||
LinkReplyToParent(doc, replyId, parentCommentId);
|
||||
|
||||
return replyId;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Marks a comment as resolved/done by setting done="1" in commentsExtended.xml.
|
||||
/// Uses raw XML manipulation since these extended parts lack typed SDK support.
|
||||
/// </summary>
|
||||
public static void ResolveComment(WordprocessingDocument doc, int commentId)
|
||||
{
|
||||
var mainPart = doc.MainDocumentPart;
|
||||
if (mainPart == null) return;
|
||||
|
||||
// commentsExtended.xml is an untyped part — manipulate via raw XML
|
||||
const string ceUri = "http://schemas.microsoft.com/office/word/2018/wordml/cex";
|
||||
foreach (var part in mainPart.Parts)
|
||||
{
|
||||
if (part.OpenXmlPart.ContentType.Contains("commentsExtensible"))
|
||||
{
|
||||
using var stream = part.OpenXmlPart.GetStream(FileMode.Open, FileAccess.ReadWrite);
|
||||
var xdoc = System.Xml.Linq.XDocument.Load(stream);
|
||||
var ns = System.Xml.Linq.XNamespace.Get(ceUri);
|
||||
var commentEl = xdoc.Descendants(ns + "comment")
|
||||
.FirstOrDefault(e => e.Attribute(ns + "paraId")?.Value != null);
|
||||
// Set done flag if element found for this comment
|
||||
if (commentEl != null)
|
||||
{
|
||||
commentEl.SetAttributeValue("done", "1");
|
||||
stream.SetLength(0);
|
||||
xdoc.Save(stream);
|
||||
}
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Links a reply comment to its parent via commentsExtended.xml (w15:commentEx).
|
||||
/// Uses raw XML since the extended comment parts lack typed SDK support.
|
||||
/// </summary>
|
||||
private static void LinkReplyToParent(WordprocessingDocument doc, int replyId, int parentCommentId)
|
||||
{
|
||||
var mainPart = doc.MainDocumentPart;
|
||||
if (mainPart == null) return;
|
||||
|
||||
const string w15Uri = "http://schemas.microsoft.com/office/word/2012/wordml";
|
||||
var w15 = System.Xml.Linq.XNamespace.Get(w15Uri);
|
||||
|
||||
// Find or create commentsExtended part
|
||||
foreach (var part in mainPart.Parts)
|
||||
{
|
||||
if (part.OpenXmlPart.ContentType.Contains("commentsExtended"))
|
||||
{
|
||||
using var stream = part.OpenXmlPart.GetStream(FileMode.Open, FileAccess.ReadWrite);
|
||||
var xdoc = System.Xml.Linq.XDocument.Load(stream);
|
||||
var root = xdoc.Root;
|
||||
if (root == null) return;
|
||||
|
||||
root.Add(new System.Xml.Linq.XElement(w15 + "commentEx",
|
||||
new System.Xml.Linq.XAttribute(w15 + "paraId", replyId.ToString("X8")),
|
||||
new System.Xml.Linq.XAttribute(w15 + "paraIdParent", parentCommentId.ToString("X8")),
|
||||
new System.Xml.Linq.XAttribute(w15 + "done", "0")));
|
||||
|
||||
stream.SetLength(0);
|
||||
xdoc.Save(stream);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Finds the maximum existing comment ID and returns the next one.
|
||||
/// </summary>
|
||||
public static int GetNextCommentId(WordprocessingDocument doc)
|
||||
{
|
||||
var commentsPart = doc.MainDocumentPart?.WordprocessingCommentsPart;
|
||||
if (commentsPart?.Comments == null) return 1;
|
||||
|
||||
int maxId = 0;
|
||||
foreach (var comment in commentsPart.Comments.Elements<Comment>())
|
||||
{
|
||||
if (comment.Id?.Value != null && int.TryParse(comment.Id.Value, out int id) && id > maxId)
|
||||
maxId = id;
|
||||
}
|
||||
return maxId + 1;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,80 @@
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// Defines canonical child element ordering for key OpenXML parent elements
|
||||
/// and provides reordering utilities.
|
||||
/// </summary>
|
||||
public static class ElementOrder
|
||||
{
|
||||
private static readonly Dictionary<string, string[]> OrderMap = new()
|
||||
{
|
||||
["w:body"] = ["w:p", "w:tbl", "w:sdt", "w:sectPr"],
|
||||
["w:p"] = ["w:pPr", "w:hyperlink", "w:r", "w:ins", "w:del", "w:bookmarkStart", "w:bookmarkEnd", "w:commentRangeStart", "w:commentRangeEnd", "w:fldSimple"],
|
||||
["w:pPr"] = ["w:pStyle", "w:keepNext", "w:keepLines", "w:pageBreakBefore", "w:widowControl", "w:numPr", "w:pBdr", "w:shd", "w:tabs", "w:suppressAutoHyphens", "w:spacing", "w:ind", "w:jc", "w:rPr", "w:sectPr", "w:pPrChange"],
|
||||
["w:r"] = ["w:rPr", "w:t", "w:br", "w:tab", "w:cr", "w:sym", "w:drawing", "w:delText", "w:fldChar", "w:instrText", "w:lastRenderedPageBreak", "w:noBreakHyphen", "w:softHyphen"],
|
||||
["w:rPr"] = ["w:rStyle", "w:rFonts", "w:b", "w:bCs", "w:i", "w:iCs", "w:caps", "w:smallCaps", "w:strike", "w:dstrike", "w:vanish", "w:color", "w:sz", "w:szCs", "w:u", "w:shd", "w:highlight", "w:lang", "w:rPrChange"],
|
||||
["w:tbl"] = ["w:tblPr", "w:tblGrid", "w:tr"],
|
||||
["w:tblPr"] = ["w:tblStyle", "w:tblpPr", "w:tblOverlap", "w:tblW", "w:jc", "w:tblCellSpacing", "w:tblInd", "w:tblBorders", "w:shd", "w:tblLayout", "w:tblCellMar", "w:tblLook", "w:tblPrChange"],
|
||||
["w:tr"] = ["w:trPr", "w:tc"],
|
||||
["w:trPr"] = ["w:cnfStyle", "w:divId", "w:gridBefore", "w:gridAfter", "w:wBefore", "w:wAfter", "w:cantSplit", "w:trHeight", "w:tblHeader", "w:tblCellSpacing", "w:jc", "w:hidden", "w:ins", "w:del", "w:trPrChange"],
|
||||
["w:tc"] = ["w:tcPr", "w:p", "w:tbl"],
|
||||
["w:tcPr"] = ["w:cnfStyle", "w:tcW", "w:gridSpan", "w:hMerge", "w:vMerge", "w:tcBorders", "w:shd", "w:noWrap", "w:tcMar", "w:textDirection", "w:tcFitText", "w:vAlign", "w:hideMark", "w:headers", "w:cellIns", "w:cellDel", "w:cellMerge", "w:tcPrChange"],
|
||||
["w:sectPr"] = ["w:headerReference", "w:footerReference", "w:type", "w:pgSz", "w:pgMar", "w:paperSrc", "w:pgBorders", "w:lnNumType", "w:pgNumType", "w:cols", "w:formProt", "w:vAlign", "w:noEndnote", "w:titlePg", "w:textDirection", "w:bidi", "w:rtlGutter", "w:docGrid"],
|
||||
["w:hdr"] = ["w:p", "w:tbl", "w:sdt"],
|
||||
["w:ftr"] = ["w:p", "w:tbl", "w:sdt"],
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Returns the canonical child ordering for a given parent element name (e.g. "w:p").
|
||||
/// Returns null if no ordering is defined.
|
||||
/// </summary>
|
||||
public static string[]? GetChildOrder(string parentElement)
|
||||
{
|
||||
return OrderMap.TryGetValue(parentElement, out var order) ? order : null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Reorders children of the given XElement according to the canonical ordering rules.
|
||||
/// Children not listed in the ordering are placed at the end in their original order.
|
||||
/// </summary>
|
||||
public static void ReorderChildren(XElement parent)
|
||||
{
|
||||
var qualifiedName = GetQualifiedName(parent);
|
||||
var order = GetChildOrder(qualifiedName);
|
||||
if (order == null) return;
|
||||
|
||||
var children = parent.Elements().ToList();
|
||||
if (children.Count <= 1) return;
|
||||
|
||||
var orderIndex = new Dictionary<string, int>();
|
||||
for (int i = 0; i < order.Length; i++)
|
||||
orderIndex[order[i]] = i;
|
||||
|
||||
int unknownBase = order.Length;
|
||||
int unknownCounter = 0;
|
||||
|
||||
var sorted = children
|
||||
.Select(c => (Element: c, QName: GetQualifiedName(c)))
|
||||
.OrderBy(x => orderIndex.TryGetValue(x.QName, out var idx) ? idx : unknownBase + unknownCounter++)
|
||||
.Select(x => x.Element)
|
||||
.ToList();
|
||||
|
||||
parent.RemoveNodes();
|
||||
foreach (var child in sorted)
|
||||
parent.Add(child);
|
||||
}
|
||||
|
||||
private static string GetQualifiedName(XElement element)
|
||||
{
|
||||
var ns = element.Name.Namespace;
|
||||
var local = element.Name.LocalName;
|
||||
|
||||
if (ns == Ns.W) return $"w:{local}";
|
||||
if (ns == Ns.R) return $"r:{local}";
|
||||
if (ns == Ns.MC) return $"mc:{local}";
|
||||
|
||||
return local;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// All OpenXML namespace URIs and common content/relationship type constants.
|
||||
/// </summary>
|
||||
public static class Ns
|
||||
{
|
||||
public static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
public static readonly XNamespace R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
|
||||
public static readonly XNamespace WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
|
||||
public static readonly XNamespace A = "http://schemas.openxmlformats.org/drawingml/2006/main";
|
||||
public static readonly XNamespace MC = "http://schemas.openxmlformats.org/markup-compatibility/2006";
|
||||
public static readonly XNamespace PIC = "http://schemas.openxmlformats.org/drawingml/2006/picture";
|
||||
public static readonly XNamespace W14 = "http://schemas.microsoft.com/office/word/2010/wordml";
|
||||
public static readonly XNamespace W15 = "http://schemas.microsoft.com/office/word/2012/wordml";
|
||||
public static readonly XNamespace W16CID = "http://schemas.microsoft.com/office/word/2016/wordml/cid";
|
||||
public static readonly XNamespace W16CEX = "http://schemas.microsoft.com/office/word/2018/wordml/cex";
|
||||
public static readonly XNamespace WPC = "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas";
|
||||
public static readonly XNamespace WPS = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape";
|
||||
|
||||
// Content types
|
||||
public const string MainDocumentContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
|
||||
public const string StylesContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml";
|
||||
public const string HeaderContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml";
|
||||
public const string FooterContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml";
|
||||
public const string CommentsContentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
|
||||
|
||||
// Relationship types
|
||||
public const string DocumentRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
|
||||
public const string StylesRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
|
||||
public const string HeaderRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
|
||||
public const string FooterRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
|
||||
public const string CommentsRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
|
||||
public const string ImageRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
|
||||
public const string HyperlinkRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
|
||||
public const string NumberingRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
|
||||
public const string FontTableRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
|
||||
public const string ThemeRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
|
||||
public const string SettingsRelationshipType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// Result of a run merge operation.
|
||||
/// </summary>
|
||||
public record RunMergeResult(int OriginalRunCount, int MergedRunCount, int SizeReductionBytes);
|
||||
|
||||
/// <summary>
|
||||
/// Merges adjacent w:r elements with identical w:rPr formatting to reduce document size.
|
||||
/// </summary>
|
||||
public static class RunMerger
|
||||
{
|
||||
/// <summary>
|
||||
/// Merges adjacent runs with identical formatting in all paragraphs of the document body.
|
||||
/// </summary>
|
||||
public static RunMergeResult MergeRuns(XDocument document)
|
||||
{
|
||||
var body = document.Root?.Element(Ns.W + "body");
|
||||
if (body == null) return new(0, 0, 0);
|
||||
|
||||
int originalCount = 0;
|
||||
int removedCount = 0;
|
||||
|
||||
foreach (var paragraph in body.Descendants(Ns.W + "p"))
|
||||
{
|
||||
var runs = paragraph.Elements(Ns.W + "r").ToList();
|
||||
originalCount += runs.Count;
|
||||
|
||||
for (int i = runs.Count - 1; i > 0; i--)
|
||||
{
|
||||
var current = runs[i];
|
||||
var previous = runs[i - 1];
|
||||
|
||||
if (!AreRunPropertiesEqual(previous, current)) continue;
|
||||
|
||||
// Merge text content from current into previous
|
||||
var prevText = GetOrCreateTextElement(previous);
|
||||
var currText = current.Element(Ns.W + "t");
|
||||
if (currText != null && prevText != null)
|
||||
{
|
||||
prevText.Value += currText.Value;
|
||||
// Preserve xml:space="preserve" if either has it
|
||||
if (currText.Attribute(XNamespace.Xml + "space")?.Value == "preserve" ||
|
||||
prevText.Value.StartsWith(' ') || prevText.Value.EndsWith(' '))
|
||||
{
|
||||
prevText.SetAttributeValue(XNamespace.Xml + "space", "preserve");
|
||||
}
|
||||
}
|
||||
|
||||
current.Remove();
|
||||
removedCount++;
|
||||
}
|
||||
}
|
||||
|
||||
return new(originalCount, originalCount - removedCount, 0);
|
||||
}
|
||||
|
||||
private static bool AreRunPropertiesEqual(XElement run1, XElement run2)
|
||||
{
|
||||
var rPr1 = run1.Element(Ns.W + "rPr");
|
||||
var rPr2 = run2.Element(Ns.W + "rPr");
|
||||
|
||||
if (rPr1 == null && rPr2 == null) return true;
|
||||
if (rPr1 == null || rPr2 == null) return false;
|
||||
|
||||
return XNode.DeepEquals(rPr1, rPr2);
|
||||
}
|
||||
|
||||
private static XElement? GetOrCreateTextElement(XElement run)
|
||||
{
|
||||
var t = run.Element(Ns.W + "t");
|
||||
if (t == null)
|
||||
{
|
||||
t = new XElement(Ns.W + "t");
|
||||
run.Add(t);
|
||||
}
|
||||
return t;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
public record StyleInfo(string Id, string? Name, string Type, string? BasedOn, bool IsDefault);
|
||||
|
||||
public record StyleReport(
|
||||
List<StyleInfo> AllStyles,
|
||||
Dictionary<string, List<string>> InheritanceTree,
|
||||
string? DefaultParagraphStyle,
|
||||
string? DefaultCharacterStyle,
|
||||
int DirectFormattingCount);
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes the style hierarchy of a DOCX document.
|
||||
/// </summary>
|
||||
public static class StyleAnalyzer
|
||||
{
|
||||
/// <summary>
|
||||
/// Analyzes styles.xml content and document.xml for direct formatting usage.
|
||||
/// </summary>
|
||||
public static StyleReport Analyze(XDocument stylesXml, XDocument documentXml)
|
||||
{
|
||||
var styles = ExtractStyles(stylesXml);
|
||||
var tree = BuildInheritanceTree(styles);
|
||||
var defaultPara = styles.FirstOrDefault(s => s.Type == "paragraph" && s.IsDefault)?.Id;
|
||||
var defaultChar = styles.FirstOrDefault(s => s.Type == "character" && s.IsDefault)?.Id;
|
||||
var directCount = CountDirectFormatting(documentXml);
|
||||
|
||||
return new(styles, tree, defaultPara, defaultChar, directCount);
|
||||
}
|
||||
|
||||
private static List<StyleInfo> ExtractStyles(XDocument stylesXml)
|
||||
{
|
||||
var result = new List<StyleInfo>();
|
||||
var root = stylesXml.Root;
|
||||
if (root == null) return result;
|
||||
|
||||
foreach (var style in root.Elements(Ns.W + "style"))
|
||||
{
|
||||
var id = style.Attribute(Ns.W + "styleId")?.Value ?? "";
|
||||
var name = style.Element(Ns.W + "name")?.Attribute(Ns.W + "val")?.Value;
|
||||
var type = style.Attribute(Ns.W + "type")?.Value ?? "unknown";
|
||||
var basedOn = style.Element(Ns.W + "basedOn")?.Attribute(Ns.W + "val")?.Value;
|
||||
var isDefault = style.Attribute(Ns.W + "default")?.Value == "1";
|
||||
result.Add(new(id, name, type, basedOn, isDefault));
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
private static Dictionary<string, List<string>> BuildInheritanceTree(List<StyleInfo> styles)
|
||||
{
|
||||
var tree = new Dictionary<string, List<string>>();
|
||||
foreach (var style in styles)
|
||||
{
|
||||
var parent = style.BasedOn ?? "(root)";
|
||||
if (!tree.ContainsKey(parent))
|
||||
tree[parent] = [];
|
||||
tree[parent].Add(style.Id);
|
||||
}
|
||||
return tree;
|
||||
}
|
||||
|
||||
private static int CountDirectFormatting(XDocument documentXml)
|
||||
{
|
||||
var body = documentXml.Root?.Element(Ns.W + "body");
|
||||
if (body == null) return 0;
|
||||
|
||||
int count = 0;
|
||||
// Count inline rPr on runs (direct character formatting)
|
||||
count += body.Descendants(Ns.W + "r")
|
||||
.Count(r => r.Element(Ns.W + "rPr") != null);
|
||||
// Count inline pPr that contain more than just pStyle (direct paragraph formatting)
|
||||
count += body.Descendants(Ns.W + "p")
|
||||
.Select(p => p.Element(Ns.W + "pPr"))
|
||||
.Count(pPr => pPr != null && pPr.Elements().Any(e => e.Name != Ns.W + "pStyle"));
|
||||
|
||||
return count;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// Helpers for Track Changes (revision marks) operations.
|
||||
/// </summary>
|
||||
public static class TrackChangesHelper
|
||||
{
|
||||
/// <summary>
|
||||
/// Wraps a run in a w:ins element to propose an insertion.
|
||||
/// </summary>
|
||||
public static InsertedRun ProposeInsertion(Run run, string author, DateTime date)
|
||||
{
|
||||
var ins = new InsertedRun
|
||||
{
|
||||
Author = author,
|
||||
Date = date,
|
||||
Id = run.Parent is Body body ? GetNextRevisionId(body).ToString() : "1"
|
||||
};
|
||||
run.Remove();
|
||||
ins.Append(run);
|
||||
return ins;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Wraps a run in a w:del element, converting w:t to w:delText.
|
||||
/// </summary>
|
||||
public static DeletedRun ProposeDeletion(Run run, string author, DateTime date)
|
||||
{
|
||||
// Convert w:t elements to w:delText
|
||||
foreach (var text in run.Elements<Text>().ToList())
|
||||
{
|
||||
var delText = new DeletedText { Text = text.Text, Space = SpaceProcessingModeValues.Preserve };
|
||||
text.InsertAfterSelf(delText);
|
||||
text.Remove();
|
||||
}
|
||||
|
||||
var del = new DeletedRun
|
||||
{
|
||||
Author = author,
|
||||
Date = date,
|
||||
Id = run.Parent is Body body ? GetNextRevisionId(body).ToString() : "1"
|
||||
};
|
||||
run.Remove();
|
||||
del.Append(run);
|
||||
return del;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Accepts an insertion by removing the w:ins wrapper and keeping content.
|
||||
/// </summary>
|
||||
public static void AcceptInsertion(OpenXmlElement insElement)
|
||||
{
|
||||
if (insElement is not InsertedRun) return;
|
||||
var parent = insElement.Parent;
|
||||
if (parent == null) return;
|
||||
|
||||
var children = insElement.ChildElements.ToList();
|
||||
foreach (var child in children)
|
||||
{
|
||||
child.Remove();
|
||||
insElement.InsertBeforeSelf(child);
|
||||
}
|
||||
insElement.Remove();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Accepts a deletion by removing the entire w:del element and its content.
|
||||
/// </summary>
|
||||
public static void AcceptDeletion(OpenXmlElement delElement)
|
||||
{
|
||||
delElement.Remove();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Finds the maximum existing revision ID in the document and returns the next one.
|
||||
/// </summary>
|
||||
public static int GetNextRevisionId(WordprocessingDocument doc)
|
||||
{
|
||||
var body = doc.MainDocumentPart?.Document?.Body;
|
||||
if (body == null) return 1;
|
||||
return GetNextRevisionId(body);
|
||||
}
|
||||
|
||||
private static int GetNextRevisionId(OpenXmlElement root)
|
||||
{
|
||||
int maxId = 0;
|
||||
foreach (var element in root.Descendants())
|
||||
{
|
||||
var idAttr = element.GetAttributes().FirstOrDefault(a => a.LocalName == "id");
|
||||
if (idAttr.Value != null && int.TryParse(idAttr.Value, out int id) && id > maxId)
|
||||
maxId = id;
|
||||
}
|
||||
return maxId + 1;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
namespace DocxToolkit.Core.OpenXml;
|
||||
|
||||
/// <summary>
|
||||
/// Conversion utilities between OpenXML measurement units (DXA, EMU, points, half-points).
|
||||
/// </summary>
|
||||
public static class UnitConverter
|
||||
{
|
||||
// 1 inch = 1440 DXA = 914400 EMU = 72 pt = 144 half-pt
|
||||
|
||||
public static int InchesToDxa(double inches) => (int)(inches * 1440);
|
||||
public static int CmToDxa(double cm) => (int)(cm * 567.0);
|
||||
public static int PtToDxa(double pt) => (int)(pt * 20);
|
||||
public static long InchesToEmu(double inches) => (long)(inches * 914400);
|
||||
public static long CmToEmu(double cm) => (long)(cm * 360000);
|
||||
public static int PtToHalfPt(double pt) => (int)(pt * 2);
|
||||
public static string FontSizeToSz(double ptSize) => ((int)(ptSize * 2)).ToString();
|
||||
|
||||
public static double DxaToInches(int dxa) => dxa / 1440.0;
|
||||
public static double DxaToCm(int dxa) => dxa / 567.0;
|
||||
public static double DxaToPt(int dxa) => dxa / 20.0;
|
||||
public static double EmuToInches(long emu) => emu / 914400.0;
|
||||
public static double EmuToCm(long emu) => emu / 360000.0;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,910 @@
|
||||
// ============================================================================
|
||||
// AestheticRecipeSamples_Batch1.cs — IEEE & ACM conference paper recipes
|
||||
// ============================================================================
|
||||
// Two-column academic conference styles faithfully reproducing the typographic
|
||||
// conventions of IEEEtran.cls and acmart.cls for DOCX output.
|
||||
//
|
||||
// UNIT REFERENCE:
|
||||
// Font size: half-points (20 = 10pt, 18 = 9pt, 16 = 8pt)
|
||||
// Spacing: DXA = twentieths of a point (1440 DXA = 1 inch)
|
||||
// Borders: eighth-points (4 = 0.5pt, 8 = 1pt, 12 = 1.5pt)
|
||||
// Line spacing "line": 240ths of single spacing (240 = 1.0x)
|
||||
// ============================================================================
|
||||
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
using WpColumns = DocumentFormat.OpenXml.Wordprocessing.Columns;
|
||||
using WpPageSize = DocumentFormat.OpenXml.Wordprocessing.PageSize;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
public static partial class AestheticRecipeSamples
|
||||
{
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
// RECIPE 6: IEEE CONFERENCE (IEEEtran)
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
|
||||
/// <summary>
|
||||
/// Recipe: IEEE Conference Paper (IEEEtran.cls v1.8b)
|
||||
/// Source: IEEEtran.cls v1.8b — the standard LaTeX class for IEEE transactions
|
||||
/// and conference proceedings.
|
||||
///
|
||||
/// Feel: Dense, formal, information-rich two-column layout.
|
||||
/// Best for: IEEE conference submissions, transactions papers, technical reports
|
||||
/// following IEEE style.
|
||||
///
|
||||
/// Design rationale (all values from IEEEtran.cls source):
|
||||
/// - US Letter, narrow margins (0.625in L/R): maximizes text area for the
|
||||
/// two-column layout. IEEE papers prioritize information density.
|
||||
/// - Two columns with 0.25in (360 DXA) gutter: standard IEEE column separation.
|
||||
/// Narrow gutter is feasible because the small font creates short line lengths.
|
||||
/// - 10pt Times New Roman body (sz=20): IEEE's standard body size. TNR is the
|
||||
/// required typeface. 10pt in two columns yields ~40 characters per line —
|
||||
/// optimal for rapid technical reading.
|
||||
/// - 24pt title, centered, NOT bold (sz=48): IEEEtran titles are large but
|
||||
/// use regular weight. The size alone provides hierarchy.
|
||||
/// - Section headings (H1): 10pt small caps, centered, Roman numeral prefix
|
||||
/// convention (sz=20). Small caps at body size creates subtle hierarchy
|
||||
/// without disrupting the dense layout.
|
||||
/// - Subsection headings (H2): 10pt italic, flush left (sz=20). Italic at
|
||||
/// body size is the minimal viable distinction from body text.
|
||||
/// - Single spacing (line=240): mandatory for IEEE camera-ready format.
|
||||
/// - First-line indent 0.125in (180 DXA): very small indent suits the narrow
|
||||
/// column width.
|
||||
/// - 0pt paragraph spacing: IEEE uses no inter-paragraph space; the first-line
|
||||
/// indent is the sole paragraph separator.
|
||||
/// - Captions: 8pt (sz=16) — subordinate to body, centered under figures/tables.
|
||||
/// </summary>
|
||||
public static void CreateIEEEConferenceDocument(string outputPath)
|
||||
{
|
||||
using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
|
||||
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
var body = mainPart.Document.Body!;
|
||||
|
||||
// ── Styles ──
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
stylesPart.Styles = new Styles();
|
||||
var styles = stylesPart.Styles;
|
||||
|
||||
// DocDefaults: Times New Roman 10pt, single spacing, 0.125in first-line indent
|
||||
styles.Append(new DocDefaults(
|
||||
new RunPropertiesDefault(
|
||||
new RunPropertiesBaseStyle(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt body (IEEEtran standard)
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" }, // Pure black
|
||||
new Languages { Val = "en-US", EastAsia = "zh-CN" }
|
||||
)
|
||||
),
|
||||
new ParagraphPropertiesDefault(
|
||||
new ParagraphPropertiesBaseStyle(
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
// Single spacing: mandatory for IEEE camera-ready
|
||||
Line = "240",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0",
|
||||
Before = "0"
|
||||
},
|
||||
// First-line indent: 0.125in = 180 DXA (very small, suits narrow columns)
|
||||
new Indentation { FirstLine = "180" }
|
||||
)
|
||||
)
|
||||
));
|
||||
|
||||
// ── Normal style ──
|
||||
styles.Append(CreateParagraphStyle(
|
||||
styleId: "Normal",
|
||||
styleName: "Normal",
|
||||
isDefault: true,
|
||||
uiPriority: 0
|
||||
));
|
||||
|
||||
// ── Title style: 24pt centered, NOT bold ──
|
||||
// IEEEtran.cls \maketitle: \LARGE (24pt at 10pt base), centered, no bold
|
||||
var titleRPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "48" }, // 24pt
|
||||
new FontSizeComplexScript { Val = "48" },
|
||||
new Color { Val = "000000" }
|
||||
// No Bold — IEEEtran titles are NOT bold
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "Title" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 10 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { Before = "0", After = "240" },
|
||||
new Indentation { FirstLine = "0" } // No indent for title
|
||||
),
|
||||
titleRPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Title",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Heading 1: 10pt small caps, centered ──
|
||||
// IEEEtran \section: \centering\scshape at body size, Roman numeral prefix
|
||||
var h1RPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt — same as body
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" },
|
||||
new SmallCaps() // Small caps for section headings
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "heading 1" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { Before = "240", After = "120" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new OutlineLevel { Val = 0 }
|
||||
),
|
||||
h1RPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Heading1",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Heading 2: 10pt italic, flush left ──
|
||||
// IEEEtran \subsection: \itshape at body size, flush left
|
||||
var h2RPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt — same as body
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" },
|
||||
new Italic() // Italic for subsection headings
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "heading 2" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines { Before = "180", After = "60" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new OutlineLevel { Val = 1 }
|
||||
),
|
||||
h2RPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Heading2",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Abstract style: 9pt bold "Abstract" label convention ──
|
||||
styles.Append(CreateParagraphStyle(
|
||||
styleId: "Abstract",
|
||||
styleName: "Abstract",
|
||||
basedOn: "Normal",
|
||||
uiPriority: 11
|
||||
));
|
||||
|
||||
// ── Caption style: 8pt (sz=16) ──
|
||||
styles.Append(CreateCaptionStyle(
|
||||
fontSizeHalfPts: "16", // 8pt — IEEE standard caption size
|
||||
color: "000000",
|
||||
italic: false // IEEE captions are not italic
|
||||
));
|
||||
|
||||
// ── Page setup: US Letter, IEEE margins, two-column ──
|
||||
// IEEEtran.cls: top=0.75in, bottom=1in, left=right=0.625in
|
||||
var sectPr = new SectionProperties(
|
||||
new WpPageSize { Width = 12240U, Height = 15840U }, // US Letter
|
||||
new PageMargin
|
||||
{
|
||||
Top = 1080, // 0.75in
|
||||
Bottom = 1440, // 1in
|
||||
Left = 900U, // 0.625in
|
||||
Right = 900U, // 0.625in
|
||||
Header = 720U, Footer = 720U, Gutter = 0U
|
||||
},
|
||||
// Two-column layout: 0.25in gutter = 360 DXA
|
||||
new WpColumns { ColumnCount = 2, Space = "360" }
|
||||
);
|
||||
|
||||
// ── Page numbers: bottom center, 8pt ──
|
||||
AddPageNumberFooter(mainPart, sectPr,
|
||||
alignment: JustificationValues.Center,
|
||||
fontSizeHalfPts: "16", // 8pt
|
||||
color: "000000",
|
||||
format: PageNumberFormat.Plain
|
||||
);
|
||||
|
||||
// ── Sample content: IEEE paper structure ──
|
||||
|
||||
// Title (spans both columns via the Title style)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Title" }
|
||||
),
|
||||
new Run(new Text("Deep Learning Approaches for Automated Document Layout Analysis"))
|
||||
));
|
||||
|
||||
// Author line (centered, no indent)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { After = "120" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(new FontSize { Val = "20" }, new FontSizeComplexScript { Val = "20" }),
|
||||
new Text("Jane A. Smith, John B. Doe, and Alice C. Johnson")
|
||||
)
|
||||
));
|
||||
|
||||
// Affiliation (centered, italic, smaller)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new SpacingBetweenLines { After = "240" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new FontSize { Val = "18" }, new FontSizeComplexScript { Val = "18" },
|
||||
new Italic()
|
||||
),
|
||||
new Text("Department of Computer Science, Example University, City, Country")
|
||||
)
|
||||
));
|
||||
|
||||
// Abstract
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Abstract" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines { After = "120" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(new Bold(), new Italic(), new FontSize { Val = "18" }, new FontSizeComplexScript { Val = "18" }),
|
||||
new Text("Abstract") { Space = SpaceProcessingModeValues.Preserve }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(new FontSize { Val = "18" }, new FontSizeComplexScript { Val = "18" }),
|
||||
new Text("\u2014This paper presents a comprehensive framework for automated document "
|
||||
+ "layout analysis using deep learning. We propose a novel architecture that "
|
||||
+ "combines convolutional neural networks with transformer-based attention "
|
||||
+ "mechanisms to accurately segment and classify document regions. Experimental "
|
||||
+ "results on benchmark datasets demonstrate state-of-the-art performance.")
|
||||
{ Space = SpaceProcessingModeValues.Preserve }
|
||||
)
|
||||
));
|
||||
|
||||
// I. INTRODUCTION (Roman numeral convention rendered in text)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("I. Introduction"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Document layout analysis is a fundamental step in document "
|
||||
+ "understanding pipelines. The ability to automatically identify and classify "
|
||||
+ "regions within a document image has applications in digitization, information "
|
||||
+ "extraction, and accessibility.", "Normal");
|
||||
|
||||
AddSampleParagraph(body, "Recent advances in deep learning have significantly improved "
|
||||
+ "the accuracy of layout analysis systems. However, challenges remain in handling "
|
||||
+ "complex multi-column layouts and heterogeneous document types.", "Normal");
|
||||
|
||||
// II. RELATED WORK
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("II. Related Work"))
|
||||
));
|
||||
|
||||
// A. Subsection
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading2" }
|
||||
),
|
||||
new Run(new Text("A. Traditional Methods"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Early approaches to document layout analysis relied on "
|
||||
+ "rule-based methods and connected component analysis. These methods perform well "
|
||||
+ "on structured documents but struggle with complex layouts.", "Normal");
|
||||
|
||||
// B. Subsection
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading2" }
|
||||
),
|
||||
new Run(new Text("B. Deep Learning Methods"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Convolutional neural networks have been successfully applied "
|
||||
+ "to document layout analysis, achieving significant improvements over traditional "
|
||||
+ "methods on standard benchmarks.", "Normal");
|
||||
|
||||
// III. PROPOSED METHOD
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("III. Proposed Method"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Our proposed framework integrates a feature pyramid network "
|
||||
+ "backbone with a transformer decoder module. The architecture processes document "
|
||||
+ "images at multiple scales to capture both fine-grained character-level features "
|
||||
+ "and coarse layout structures.", "Normal");
|
||||
|
||||
// Table
|
||||
body.Append(CreateThreeLineTable(
|
||||
new[] { "Method", "Precision", "Recall", "F1" },
|
||||
new[]
|
||||
{
|
||||
new[] { "Rule-based", "0.823", "0.791", "0.807" },
|
||||
new[] { "CNN-only", "0.912", "0.887", "0.899" },
|
||||
new[] { "Ours", "0.956", "0.943", "0.949" }
|
||||
}
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "TABLE I: Comparison of layout analysis methods on PubLayNet.", "Caption");
|
||||
|
||||
// IV. CONCLUSION
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("IV. Conclusion"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "We have presented a novel deep learning framework for document "
|
||||
+ "layout analysis that achieves state-of-the-art results. Future work will explore "
|
||||
+ "extending the approach to handle more diverse document types.", "Normal");
|
||||
|
||||
// Section properties must be last child of body
|
||||
body.Append(sectPr);
|
||||
}
|
||||
|
||||
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
// RECIPE 7: ACM CONFERENCE (acmart)
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
|
||||
/// <summary>
|
||||
/// Recipe: ACM Conference Paper (acmart.cls v2.x, ACM Author Guide)
|
||||
/// Source: acmart.cls v2.x — the consolidated ACM master article template,
|
||||
/// and the ACM Author Guide for typographic specifications.
|
||||
///
|
||||
/// Feel: Clean, structured, slightly more open than IEEE.
|
||||
/// Best for: ACM conference proceedings (SIGCHI, SIGMOD, SIGGRAPH, etc.),
|
||||
/// ACM journal submissions.
|
||||
///
|
||||
/// Design rationale (all values from acmart.cls and ACM Author Guide):
|
||||
/// - US Letter, 1.25in top/bottom, 0.75in L/R: more generous vertical margins
|
||||
/// than IEEE, giving a less cramped appearance.
|
||||
/// - Two columns with 0.33in (480 DXA) gutter: slightly wider than IEEE's
|
||||
/// 0.25in, providing better visual separation between columns.
|
||||
/// - 9pt Times New Roman body (sz=18): ACM's standard body size. The original
|
||||
/// acmart uses Linux Libertine, but TNR is the accessible fallback specified
|
||||
/// in the ACM Author Guide for systems without Libertine.
|
||||
/// - 14.4pt bold title, flush left (sz=29): ACM titles are bold and left-aligned,
|
||||
/// unlike IEEE's centered unbolded titles. The 14.4pt size (1.6x body) creates
|
||||
/// strong but not overwhelming hierarchy.
|
||||
/// - H1: 10pt bold ALL CAPS, flush left, arabic numbered (sz=20). ALL CAPS at
|
||||
/// body size with bold creates definitive section breaks.
|
||||
/// - H2: 10pt bold title case, flush left (sz=20). Bold without caps is the
|
||||
/// minimal step down from H1.
|
||||
/// - H3: 10pt bold italic, flush left (sz=20). Adding italic distinguishes
|
||||
/// from H2 while maintaining the same weight.
|
||||
/// - Single spacing: required for ACM camera-ready format.
|
||||
/// - First-line indent ~10pt (200 DXA): slightly larger than IEEE's 0.125in,
|
||||
/// matching ACM's convention of a roughly 1em indent at 9pt.
|
||||
/// - Captions: 8pt (sz=16) — consistent with ACM figure/table caption style.
|
||||
/// - References: 7.5pt (sz=15) — ACM uses a smaller font for the bibliography
|
||||
/// to maximize space for content.
|
||||
/// </summary>
|
||||
public static void CreateACMConferenceDocument(string outputPath)
|
||||
{
|
||||
using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
|
||||
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
var body = mainPart.Document.Body!;
|
||||
|
||||
// ── Styles ──
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
stylesPart.Styles = new Styles();
|
||||
var styles = stylesPart.Styles;
|
||||
|
||||
// DocDefaults: Times New Roman 9pt (TNR as Libertine fallback), single spacing
|
||||
styles.Append(new DocDefaults(
|
||||
new RunPropertiesDefault(
|
||||
new RunPropertiesBaseStyle(
|
||||
new RunFonts
|
||||
{
|
||||
// ACM specifies Linux Libertine; TNR is the accessible fallback
|
||||
// per ACM Author Guide for systems without Libertine installed
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "18" }, // 9pt body (acmart standard)
|
||||
new FontSizeComplexScript { Val = "18" },
|
||||
new Color { Val = "000000" }, // Pure black
|
||||
new Languages { Val = "en-US", EastAsia = "zh-CN" }
|
||||
)
|
||||
),
|
||||
new ParagraphPropertiesDefault(
|
||||
new ParagraphPropertiesBaseStyle(
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
// Single spacing: ACM camera-ready requirement
|
||||
Line = "240",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0",
|
||||
Before = "0"
|
||||
},
|
||||
// First-line indent: ~10pt = 200 DXA (roughly 1em at 9pt)
|
||||
new Indentation { FirstLine = "200" }
|
||||
)
|
||||
)
|
||||
));
|
||||
|
||||
// ── Normal style ──
|
||||
styles.Append(CreateParagraphStyle(
|
||||
styleId: "Normal",
|
||||
styleName: "Normal",
|
||||
isDefault: true,
|
||||
uiPriority: 0
|
||||
));
|
||||
|
||||
// ── Title style: 14.4pt bold, flush left ──
|
||||
// acmart \maketitle: \LARGE\bfseries, left-aligned
|
||||
var titleRPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "29" }, // 14.4pt (≈29 half-points)
|
||||
new FontSizeComplexScript { Val = "29" },
|
||||
new Color { Val = "000000" },
|
||||
new Bold() // ACM titles ARE bold
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "Title" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 10 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
// Flush left — ACM titles are NOT centered
|
||||
new SpacingBetweenLines { Before = "0", After = "200" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
titleRPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Title",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Heading 1: 10pt bold ALL CAPS, flush left ──
|
||||
// acmart \section: \bfseries at body size, uppercase
|
||||
var h1RPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" },
|
||||
new Bold(),
|
||||
new Caps() // ALL CAPS for H1
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "heading 1" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines { Before = "240", After = "120" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new OutlineLevel { Val = 0 }
|
||||
),
|
||||
h1RPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Heading1",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Heading 2: 10pt bold title case, flush left ──
|
||||
// acmart \subsection: \bfseries, no case change
|
||||
var h2RPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" },
|
||||
new Bold() // Bold, no caps
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "heading 2" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines { Before = "200", After = "80" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new OutlineLevel { Val = 1 }
|
||||
),
|
||||
h2RPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Heading2",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Heading 3: 10pt bold italic, flush left ──
|
||||
// acmart \subsubsection: \bfseries\itshape
|
||||
var h3RPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "20" }, // 10pt
|
||||
new FontSizeComplexScript { Val = "20" },
|
||||
new Color { Val = "000000" },
|
||||
new Bold(),
|
||||
new Italic() // Bold italic for H3
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "heading 3" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines { Before = "160", After = "60" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new OutlineLevel { Val = 2 }
|
||||
),
|
||||
h3RPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "Heading3",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Caption style: 8pt (sz=16) ──
|
||||
styles.Append(CreateCaptionStyle(
|
||||
fontSizeHalfPts: "16", // 8pt — ACM standard caption size
|
||||
color: "000000",
|
||||
italic: false
|
||||
));
|
||||
|
||||
// ── References style: 7.5pt (sz=15) ──
|
||||
var refsRPr = new StyleRunProperties(
|
||||
new FontSize { Val = "15" }, // 7.5pt
|
||||
new FontSizeComplexScript { Val = "15" }
|
||||
);
|
||||
|
||||
styles.Append(new Style(
|
||||
new StyleName { Val = "References" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 37 },
|
||||
new PrimaryStyle(),
|
||||
new StyleParagraphProperties(
|
||||
new SpacingBetweenLines { After = "40" },
|
||||
new Indentation { FirstLine = "0", Left = "360", Hanging = "360" }
|
||||
),
|
||||
refsRPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "References",
|
||||
Default = false
|
||||
});
|
||||
|
||||
// ── Page setup: US Letter, ACM margins, two-column ──
|
||||
// acmart.cls: top=1.25in, bottom=1.25in, left=right=0.75in
|
||||
var sectPr = new SectionProperties(
|
||||
new WpPageSize { Width = 12240U, Height = 15840U }, // US Letter
|
||||
new PageMargin
|
||||
{
|
||||
Top = 1800, // 1.25in
|
||||
Bottom = 1800, // 1.25in
|
||||
Left = 1080U, // 0.75in
|
||||
Right = 1080U, // 0.75in
|
||||
Header = 720U, Footer = 720U, Gutter = 0U
|
||||
},
|
||||
// Two-column layout: 0.33in gutter = 480 DXA
|
||||
new WpColumns { ColumnCount = 2, Space = "480" }
|
||||
);
|
||||
|
||||
// ── Page numbers: bottom center, 8pt ──
|
||||
AddPageNumberFooter(mainPart, sectPr,
|
||||
alignment: JustificationValues.Center,
|
||||
fontSizeHalfPts: "16", // 8pt
|
||||
color: "000000",
|
||||
format: PageNumberFormat.Plain
|
||||
);
|
||||
|
||||
// ── Sample content: ACM paper structure ──
|
||||
|
||||
// Title (flush left, bold)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Title" }
|
||||
),
|
||||
new Run(new Text("Towards Scalable Graph Neural Networks for Heterogeneous Document Understanding"))
|
||||
));
|
||||
|
||||
// Author block (flush left)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new SpacingBetweenLines { After = "60" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(new FontSize { Val = "18" }, new FontSizeComplexScript { Val = "18" }),
|
||||
new Text("Maria R. Garcia")
|
||||
)
|
||||
));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new SpacingBetweenLines { After = "60" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new FontSize { Val = "16" }, new FontSizeComplexScript { Val = "16" },
|
||||
new Italic()
|
||||
),
|
||||
new Text("Example University, City, Country")
|
||||
)
|
||||
));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new SpacingBetweenLines { After = "200" },
|
||||
new Indentation { FirstLine = "0" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new FontSize { Val = "16" }, new FontSizeComplexScript { Val = "16" }
|
||||
),
|
||||
new Text("garcia@example.edu")
|
||||
)
|
||||
));
|
||||
|
||||
// Abstract section
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines { After = "80" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Bold(),
|
||||
new FontSize { Val = "18" }, new FontSizeComplexScript { Val = "18" }
|
||||
),
|
||||
new Text("ABSTRACT")
|
||||
)
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Graph neural networks (GNNs) have emerged as a powerful tool for "
|
||||
+ "document understanding tasks that require modeling relationships between document "
|
||||
+ "elements. We present a scalable GNN architecture that processes heterogeneous "
|
||||
+ "document graphs containing text, table, and figure nodes. Our approach achieves "
|
||||
+ "competitive results while reducing computational costs by 40%.", "Normal");
|
||||
|
||||
// CCS Concepts / Keywords (ACM-specific metadata)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines { Before = "120", After = "120" }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Bold(),
|
||||
new FontSize { Val = "16" }, new FontSizeComplexScript { Val = "16" }
|
||||
),
|
||||
new Text("Keywords: ") { Space = SpaceProcessingModeValues.Preserve }
|
||||
),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new FontSize { Val = "16" }, new FontSizeComplexScript { Val = "16" }
|
||||
),
|
||||
new Text("graph neural networks, document understanding, scalability")
|
||||
)
|
||||
));
|
||||
|
||||
// 1 INTRODUCTION (arabic numbered, ALL CAPS via style)
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("1 Introduction"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Document understanding encompasses a broad set of tasks including "
|
||||
+ "layout analysis, information extraction, and document classification. Recent work "
|
||||
+ "has demonstrated that modeling the structural relationships between document "
|
||||
+ "elements can significantly improve performance on these tasks.", "Normal");
|
||||
|
||||
AddSampleParagraph(body, "Graph neural networks provide a natural framework for representing "
|
||||
+ "and reasoning about document structure. However, existing GNN-based approaches face "
|
||||
+ "scalability challenges when processing large or complex documents.", "Normal");
|
||||
|
||||
// 2 RELATED WORK
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("2 Related Work"))
|
||||
));
|
||||
|
||||
// 2.1 Subsection
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading2" }
|
||||
),
|
||||
new Run(new Text("2.1 Document Representation Learning"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Pre-trained language models have been adapted for document "
|
||||
+ "understanding by incorporating layout information. LayoutLM and its successors "
|
||||
+ "demonstrate the value of multi-modal pre-training for document tasks.", "Normal");
|
||||
|
||||
// 2.1.1 Sub-subsection
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading3" }
|
||||
),
|
||||
new Run(new Text("2.1.1 Multi-Modal Approaches"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Multi-modal approaches jointly model text, layout, and visual "
|
||||
+ "features. This integration has proven critical for tasks where visual appearance "
|
||||
+ "carries semantic meaning, such as form understanding.", "Normal");
|
||||
|
||||
// 3 METHOD
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("3 Proposed Method"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "We propose HetDocGNN, a heterogeneous graph neural network "
|
||||
+ "designed specifically for document understanding. The architecture operates on "
|
||||
+ "a document graph where nodes represent text blocks, tables, and figures, and "
|
||||
+ "edges encode spatial and logical relationships.", "Normal");
|
||||
|
||||
// Results table
|
||||
body.Append(CreateThreeLineTable(
|
||||
new[] { "Model", "DocVQA", "InfoVQA", "Params" },
|
||||
new[]
|
||||
{
|
||||
new[] { "LayoutLMv3", "83.4", "45.1", "133M" },
|
||||
new[] { "UDOP", "84.7", "47.4", "770M" },
|
||||
new[] { "HetDocGNN", "85.2", "48.9", "89M" }
|
||||
}
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Table 1: Comparison on document understanding benchmarks.", "Caption");
|
||||
|
||||
// 4 CONCLUSION
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("4 Conclusion"))
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "We have presented HetDocGNN, a scalable graph neural network "
|
||||
+ "for heterogeneous document understanding. Our approach achieves state-of-the-art "
|
||||
+ "results with significantly fewer parameters than competing methods.", "Normal");
|
||||
|
||||
// REFERENCES section
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Heading1" }
|
||||
),
|
||||
new Run(new Text("References"))
|
||||
));
|
||||
|
||||
// Sample references in ACM style (7.5pt)
|
||||
AddSampleParagraph(body, "[1] Yiheng Xu, et al. 2020. LayoutLM: Pre-training of Text and "
|
||||
+ "Layout for Document Image Understanding. In KDD '20. ACM, 1192\u20131200.", "References");
|
||||
|
||||
AddSampleParagraph(body, "[2] Zhiliang Peng, et al. 2023. UDOP: Unifying Vision, Text, "
|
||||
+ "and Layout for Universal Document Processing. In CVPR '23. 19254\u201319264.", "References");
|
||||
|
||||
AddSampleParagraph(body, "[3] Zilong Wang, et al. 2022. DocFormer: End-to-End Transformer "
|
||||
+ "for Document Understanding. In ICCV '22. 993\u20131003.", "References");
|
||||
|
||||
// Section properties must be last child of body
|
||||
body.Append(sectPr);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,999 @@
|
||||
// ============================================================================
|
||||
// AestheticRecipeSamples_Batch2.cs — Academic citation style recipes (APA 7, MLA 9)
|
||||
// ============================================================================
|
||||
// Recipes 8-9: Strict compliance with academic citation style guides.
|
||||
// These are NOT aesthetic "design" choices — they are codified standards
|
||||
// mandated by publishers, universities, and professional organizations.
|
||||
//
|
||||
// UNIT REFERENCE:
|
||||
// Font size: half-points (22 = 11pt, 24 = 12pt, 32 = 16pt)
|
||||
// Spacing: DXA = twentieths of a point (1440 DXA = 1 inch)
|
||||
// Borders: eighth-points (4 = 0.5pt, 8 = 1pt, 12 = 1.5pt)
|
||||
// Line spacing "line": 240ths of single spacing (240 = 1.0x, 480 = 2.0x)
|
||||
// ============================================================================
|
||||
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
using WpPageSize = DocumentFormat.OpenXml.Wordprocessing.PageSize;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
public static partial class AestheticRecipeSamples
|
||||
{
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
// RECIPE 8: APA 7TH EDITION (PROFESSIONAL PAPER)
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
|
||||
/// <summary>
|
||||
/// Recipe: APA 7th Edition — Professional Paper
|
||||
/// Source: Publication Manual of the American Psychological Association,
|
||||
/// 7th edition (2020), Chapters 2 (Paper Elements) and 6 (Mechanics of Style).
|
||||
///
|
||||
/// Key APA 7 specifications:
|
||||
/// - Font: 12pt Times New Roman (Section 2.19). Also acceptable: 11pt Calibri,
|
||||
/// 11pt Arial, 10pt Lucida Sans Unicode, or 11pt Georgia.
|
||||
/// - Margins: 1 inch on all sides (Section 2.22).
|
||||
/// - Line spacing: Double-spaced throughout, including title page and references (Section 2.21).
|
||||
/// - Paragraph indent: 0.5 inch first-line indent for body paragraphs (Section 2.24).
|
||||
/// - Heading levels (Section 2.27):
|
||||
/// Level 1: Centered, Bold, Title Case Heading
|
||||
/// Level 2: Flush Left, Bold, Title Case Heading
|
||||
/// Level 3: Flush Left, Bold Italic, Title Case Heading
|
||||
/// Level 4: Indented, Bold, Title Case Heading, Ending With a Period. (run-in)
|
||||
/// Level 5: Indented, Bold Italic, Title Case Heading, Ending With a Period. (run-in)
|
||||
/// All headings are 12pt — hierarchy through format, NOT size.
|
||||
/// - Page numbers: top right corner on every page including title page (Section 2.18).
|
||||
/// - Running head: flush left, ALL CAPS, for professional papers only (Section 2.18).
|
||||
/// - Abstract: "Abstract" centered bold; single paragraph, not indented (Section 2.9).
|
||||
/// - No numbered headings (APA does not use section numbers).
|
||||
///
|
||||
/// Design rationale:
|
||||
/// - Every parameter is dictated by the style guide, not aesthetic preference.
|
||||
/// - Double spacing with first-line indent (no paragraph spacing) is the
|
||||
/// traditional academic convention — it provides annotation room and
|
||||
/// clear paragraph boundaries without wasting vertical space.
|
||||
/// - Uniform 12pt headings ensure the text content is primary; headings
|
||||
/// serve as navigational aids, not visual statements.
|
||||
/// </summary>
|
||||
public static void CreateAPA7Document(string outputPath)
|
||||
{
|
||||
using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
|
||||
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
var body = mainPart.Document.Body!;
|
||||
|
||||
// ── Styles ──
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
stylesPart.Styles = new Styles();
|
||||
var styles = stylesPart.Styles;
|
||||
|
||||
// DocDefaults: 12pt Times New Roman, double spacing, 0.5in first-line indent
|
||||
// NOTE: 11pt Calibri and 11pt Arial are also acceptable per APA 7 Section 2.19
|
||||
styles.Append(new DocDefaults(
|
||||
new RunPropertiesDefault(
|
||||
new RunPropertiesBaseStyle(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" }, // 12pt (half-points)
|
||||
new FontSizeComplexScript { Val = "24" },
|
||||
new Color { Val = "000000" }, // Pure black
|
||||
new Languages { Val = "en-US", EastAsia = "zh-CN" }
|
||||
)
|
||||
),
|
||||
new ParagraphPropertiesDefault(
|
||||
new ParagraphPropertiesBaseStyle(
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
// Double spacing throughout (APA 7, Section 2.21)
|
||||
// 480 = 2.0x (240 = single spacing)
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0" // No paragraph spacing — APA uses indent, not space
|
||||
},
|
||||
// First-line indent 0.5in = 720 DXA (APA 7, Section 2.24)
|
||||
new Indentation { FirstLine = "720" }
|
||||
)
|
||||
)
|
||||
));
|
||||
|
||||
// ── Normal style ──
|
||||
styles.Append(CreateParagraphStyle(
|
||||
styleId: "Normal",
|
||||
styleName: "Normal",
|
||||
isDefault: true,
|
||||
uiPriority: 0
|
||||
));
|
||||
|
||||
// ── APA Level 1: Centered, Bold, Title Case ──
|
||||
// Same 12pt as body — hierarchy via format, NOT size (APA 7, Section 2.27)
|
||||
styles.Append(CreateAcademicHeadingStyle(
|
||||
level: 1,
|
||||
sizeHalfPts: "24", // 12pt — same as body
|
||||
bold: true,
|
||||
italic: false,
|
||||
centered: true,
|
||||
spaceBefore: "480", // One double-spaced blank line before
|
||||
spaceAfter: "0"
|
||||
));
|
||||
|
||||
// ── APA Level 2: Flush Left, Bold, Title Case ──
|
||||
styles.Append(CreateAcademicHeadingStyle(
|
||||
level: 2,
|
||||
sizeHalfPts: "24", // 12pt — same as body
|
||||
bold: true,
|
||||
italic: false,
|
||||
centered: false,
|
||||
spaceBefore: "480",
|
||||
spaceAfter: "0"
|
||||
));
|
||||
|
||||
// ── APA Level 3: Flush Left, Bold Italic, Title Case ──
|
||||
styles.Append(CreateAcademicHeadingStyle(
|
||||
level: 3,
|
||||
sizeHalfPts: "24", // 12pt — same as body
|
||||
bold: true,
|
||||
italic: true,
|
||||
centered: false,
|
||||
spaceBefore: "480",
|
||||
spaceAfter: "0"
|
||||
));
|
||||
|
||||
// ── APA Level 4: Indented 0.5in, Bold, Title Case, Ending With Period. ──
|
||||
// This is a "run-in" heading in APA — the heading text runs into the paragraph.
|
||||
// In OpenXML we approximate by creating an indented bold paragraph.
|
||||
styles.Append(CreateAPA7RunInHeadingStyle(
|
||||
level: 4,
|
||||
bold: true,
|
||||
italic: false
|
||||
));
|
||||
|
||||
// ── APA Level 5: Indented 0.5in, Bold Italic, Title Case, Ending With Period. ──
|
||||
styles.Append(CreateAPA7RunInHeadingStyle(
|
||||
level: 5,
|
||||
bold: true,
|
||||
italic: true
|
||||
));
|
||||
|
||||
// ── "Abstract" label style: centered, bold, no indent ──
|
||||
styles.Append(CreateAPA7NoIndentCenteredStyle(
|
||||
styleId: "APAAbstractLabel",
|
||||
styleName: "APA Abstract Label",
|
||||
bold: true
|
||||
));
|
||||
|
||||
// ── Abstract body style: no first-line indent ──
|
||||
styles.Append(CreateAPA7NoIndentStyle(
|
||||
styleId: "APAAbstractBody",
|
||||
styleName: "APA Abstract Body"
|
||||
));
|
||||
|
||||
// ── Title page style: centered, bold, no indent ──
|
||||
styles.Append(CreateAPA7NoIndentCenteredStyle(
|
||||
styleId: "APATitlePageTitle",
|
||||
styleName: "APA Title Page Title",
|
||||
bold: true
|
||||
));
|
||||
|
||||
// ── Title page author/affiliation: centered, no indent, not bold ──
|
||||
styles.Append(CreateAPA7NoIndentCenteredStyle(
|
||||
styleId: "APATitlePageInfo",
|
||||
styleName: "APA Title Page Info",
|
||||
bold: false
|
||||
));
|
||||
|
||||
// ── Page setup: US Letter, 1in all sides (APA 7, Section 2.22) ──
|
||||
var sectPr = new SectionProperties(
|
||||
new WpPageSize { Width = 12240U, Height = 15840U }, // 8.5" x 11"
|
||||
new PageMargin
|
||||
{
|
||||
Top = 1440, Bottom = 1440,
|
||||
Left = 1440U, Right = 1440U,
|
||||
Header = 720U, Footer = 720U, Gutter = 0U
|
||||
}
|
||||
);
|
||||
|
||||
// ── Running head + page number in header ──
|
||||
// Professional papers: running head flush left (ALL CAPS), page number flush right
|
||||
// Both in the same header (APA 7, Section 2.18)
|
||||
AddAPA7Header(mainPart, sectPr, "COGNITIVE EFFECTS OF SLEEP DEPRIVATION");
|
||||
|
||||
// ══════════════════════════════════════════════════════════════════
|
||||
// SAMPLE CONTENT: Title Page, Abstract, Body with all 5 heading levels
|
||||
// ══════════════════════════════════════════════════════════════════
|
||||
|
||||
// ── Title page ──
|
||||
// Title: centered, bold, upper half of page (3-4 blank lines before)
|
||||
AddAPA7TitlePage(body,
|
||||
title: "Cognitive Effects of Sleep Deprivation on Working Memory Performance",
|
||||
authorName: "Sarah J. Mitchell",
|
||||
affiliation: "Department of Psychology, University of Washington",
|
||||
courseLine: "PSY 401: Advanced Cognitive Psychology",
|
||||
instructorLine: "Dr. Robert Chen",
|
||||
dateLine: "October 15, 2024"
|
||||
);
|
||||
|
||||
// ── Abstract page ──
|
||||
AddSampleParagraph(body, "Abstract", "APAAbstractLabel");
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "APAAbstractBody" }
|
||||
),
|
||||
new Run(new Text(
|
||||
"This study examined the effects of acute sleep deprivation on working memory "
|
||||
+ "performance in college-aged adults. Participants (N = 48) were randomly assigned "
|
||||
+ "to either a sleep deprivation condition (24 hours without sleep) or a control "
|
||||
+ "condition (normal sleep). Working memory was assessed using a dual n-back task. "
|
||||
+ "Results indicated that sleep-deprived participants showed significantly lower "
|
||||
+ "accuracy (M = 72.3%, SD = 8.1) compared to controls (M = 89.7%, SD = 5.4), "
|
||||
+ "t(46) = 9.12, p < .001, d = 2.52. These findings suggest that even a single "
|
||||
+ "night of sleep deprivation substantially impairs working memory capacity."
|
||||
))
|
||||
));
|
||||
|
||||
// ── Body: Level 1 heading ──
|
||||
AddSampleParagraph(body, "Cognitive Effects of Sleep Deprivation on Working Memory Performance", "Heading1");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Sleep deprivation is increasingly prevalent among college students, with approximately "
|
||||
+ "50% reporting insufficient sleep on a regular basis (Hershner & Chervin, 2014). The "
|
||||
+ "consequences of inadequate sleep extend beyond daytime drowsiness, affecting core "
|
||||
+ "cognitive processes including attention, executive function, and working memory.",
|
||||
"Normal");
|
||||
|
||||
// ── Level 2 heading ──
|
||||
AddSampleParagraph(body, "Theoretical Framework", "Heading2");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Working memory, as conceptualized by Baddeley and Hitch (1974), comprises a central "
|
||||
+ "executive system supported by the phonological loop and visuospatial sketchpad. Sleep "
|
||||
+ "deprivation has been hypothesized to primarily affect the central executive component, "
|
||||
+ "which governs attentional control and task coordination.",
|
||||
"Normal");
|
||||
|
||||
// ── Level 3 heading ──
|
||||
AddSampleParagraph(body, "Neural Mechanisms of Sleep-Related Cognitive Decline", "Heading3");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Neuroimaging studies have demonstrated that sleep deprivation is associated with "
|
||||
+ "reduced activation in the prefrontal cortex, the neural substrate most closely linked "
|
||||
+ "to working memory function (Chee & Chuah, 2007). Additionally, thalamic deactivation "
|
||||
+ "may impair the relay of sensory information necessary for memory encoding.",
|
||||
"Normal");
|
||||
|
||||
// ── Level 4 heading (run-in, bold, ends with period) ──
|
||||
// APA Level 4 is a run-in heading: the heading text and paragraph text
|
||||
// share the same line. We approximate with a bold indented paragraph.
|
||||
body.Append(CreateAPA7RunInParagraph(
|
||||
headingText: "Prefrontal Cortex Involvement.",
|
||||
bodyText: " The dorsolateral prefrontal cortex (DLPFC) shows the greatest "
|
||||
+ "susceptibility to sleep loss. Functional MRI studies reveal a dose-dependent "
|
||||
+ "relationship between hours of wakefulness and DLPFC activation levels during "
|
||||
+ "working memory tasks.",
|
||||
bold: true,
|
||||
italic: false
|
||||
));
|
||||
|
||||
// ── Level 5 heading (run-in, bold italic, ends with period) ──
|
||||
body.Append(CreateAPA7RunInParagraph(
|
||||
headingText: "Glutamatergic Pathways.",
|
||||
bodyText: " Recent research has identified glutamatergic signaling in the "
|
||||
+ "prefrontal cortex as a key mediator of sleep deprivation effects on working "
|
||||
+ "memory. Antagonism of NMDA receptors produces cognitive deficits similar to "
|
||||
+ "those observed following 24 hours of sleep loss.",
|
||||
bold: true,
|
||||
italic: true
|
||||
));
|
||||
|
||||
// ── Level 2: Method section ──
|
||||
AddSampleParagraph(body, "Method", "Heading2");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"This experiment used a between-subjects design with sleep condition (deprived vs. "
|
||||
+ "control) as the independent variable and working memory accuracy as the dependent "
|
||||
+ "variable. All procedures were approved by the University of Washington Institutional "
|
||||
+ "Review Board (Protocol #2024-0847).",
|
||||
"Normal");
|
||||
|
||||
// ── Level 2: Results ──
|
||||
AddSampleParagraph(body, "Results", "Heading2");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"An independent-samples t test revealed a statistically significant difference in "
|
||||
+ "working memory accuracy between the sleep-deprived group (M = 72.3%, SD = 8.1) "
|
||||
+ "and the control group (M = 89.7%, SD = 5.4), t(46) = 9.12, p < .001. The effect "
|
||||
+ "size was large (Cohen's d = 2.52), indicating a substantial practical difference.",
|
||||
"Normal");
|
||||
|
||||
// ── Level 2: Discussion ──
|
||||
AddSampleParagraph(body, "Discussion", "Heading2");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"The findings of this study are consistent with previous research demonstrating the "
|
||||
+ "deleterious effects of sleep deprivation on cognitive performance. The magnitude of "
|
||||
+ "the effect observed here exceeds that reported in meta-analytic reviews, possibly "
|
||||
+ "due to the use of a more demanding dual n-back paradigm that places greater demands "
|
||||
+ "on executive control processes.",
|
||||
"Normal");
|
||||
|
||||
// Section properties must be last child of body
|
||||
body.Append(sectPr);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates an APA 7 "run-in" heading style (Levels 4 and 5).
|
||||
/// These headings are indented 0.5in and end with a period;
|
||||
/// the paragraph text runs in on the same line as the heading.
|
||||
/// In OpenXML, we create a paragraph style with the appropriate formatting.
|
||||
/// </summary>
|
||||
private static Style CreateAPA7RunInHeadingStyle(int level, bool bold, bool italic)
|
||||
{
|
||||
var rPr = new StyleRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" }, // 12pt — same as body
|
||||
new FontSizeComplexScript { Val = "24" },
|
||||
new Color { Val = "000000" }
|
||||
);
|
||||
|
||||
if (bold)
|
||||
rPr.Append(new Bold());
|
||||
if (italic)
|
||||
rPr.Append(new Italic());
|
||||
|
||||
var pPr = new StyleParagraphProperties(
|
||||
new KeepNext(),
|
||||
new KeepLines(),
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Before = "480",
|
||||
After = "0",
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto
|
||||
},
|
||||
// Indented 0.5in = 720 DXA (APA 7 Levels 4-5)
|
||||
new Indentation { FirstLine = "720" },
|
||||
new OutlineLevel { Val = level - 1 }
|
||||
);
|
||||
|
||||
return new Style(
|
||||
new StyleName { Val = $"heading {level}" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new NextParagraphStyle { Val = "Normal" },
|
||||
new UIPriority { Val = 9 },
|
||||
new PrimaryStyle(),
|
||||
pPr,
|
||||
rPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = $"Heading{level}",
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a centered, optionally bold paragraph style with no first-line indent.
|
||||
/// Used for APA title page elements and the "Abstract" label.
|
||||
/// </summary>
|
||||
private static Style CreateAPA7NoIndentCenteredStyle(string styleId, string styleName, bool bold)
|
||||
{
|
||||
var rPr = new StyleRunProperties(
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
);
|
||||
|
||||
if (bold)
|
||||
rPr.Append(new Bold());
|
||||
|
||||
return new Style(
|
||||
new StyleName { Val = styleName },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
),
|
||||
rPr
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = styleId,
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a left-aligned paragraph style with no first-line indent.
|
||||
/// Used for the abstract body text (APA 7 specifies no indent for abstract).
|
||||
/// </summary>
|
||||
private static Style CreateAPA7NoIndentStyle(string styleId, string styleName)
|
||||
{
|
||||
return new Style(
|
||||
new StyleName { Val = styleName },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
)
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = styleId,
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds the APA 7 professional paper header: running head flush left (ALL CAPS)
|
||||
/// and page number flush right, both in the same header line.
|
||||
/// Per APA 7, Section 2.18: the running head appears on every page.
|
||||
/// </summary>
|
||||
private static void AddAPA7Header(MainDocumentPart mainPart, SectionProperties sectPr, string runningHeadText)
|
||||
{
|
||||
// Use a tab stop at the right margin to position the page number flush right
|
||||
// Right margin position: page width (12240) - left margin (1440) - right margin (1440) = 9360 DXA
|
||||
var headerParagraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "Normal" },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines { Line = "240", LineRule = LineSpacingRuleValues.Auto, After = "0" },
|
||||
new Tabs(
|
||||
new TabStop
|
||||
{
|
||||
Val = TabStopValues.Right,
|
||||
Position = 9360 // Flush right at the text area edge
|
||||
}
|
||||
)
|
||||
),
|
||||
// Running head text (flush left, ALL CAPS)
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new Text(runningHeadText) { Space = SpaceProcessingModeValues.Preserve }
|
||||
),
|
||||
// Tab to move to right-aligned position
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new TabChar()
|
||||
),
|
||||
// Page number (flush right)
|
||||
new SimpleField(
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new Text("1")
|
||||
)
|
||||
)
|
||||
{ Instruction = " PAGE " }
|
||||
);
|
||||
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
headerPart.Header = new Header(headerParagraph);
|
||||
headerPart.Header.Save();
|
||||
|
||||
string headerPartId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerPartId
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds the APA 7 title page content: title, author, affiliation,
|
||||
/// course, instructor, and date — all centered and double-spaced.
|
||||
/// Per APA 7, Section 2.3: title should be bold, centered, in upper half of page.
|
||||
/// </summary>
|
||||
private static void AddAPA7TitlePage(Body body,
|
||||
string title, string authorName, string affiliation,
|
||||
string courseLine, string instructorLine, string dateLine)
|
||||
{
|
||||
// Add some blank lines to position title in upper half of page
|
||||
for (int i = 0; i < 3; i++)
|
||||
{
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "APATitlePageInfo" }
|
||||
)
|
||||
));
|
||||
}
|
||||
|
||||
// Title: centered, bold
|
||||
AddSampleParagraph(body, title, "APATitlePageTitle");
|
||||
|
||||
// Author name
|
||||
AddSampleParagraph(body, authorName, "APATitlePageInfo");
|
||||
|
||||
// Affiliation
|
||||
AddSampleParagraph(body, affiliation, "APATitlePageInfo");
|
||||
|
||||
// Course
|
||||
AddSampleParagraph(body, courseLine, "APATitlePageInfo");
|
||||
|
||||
// Instructor
|
||||
AddSampleParagraph(body, instructorLine, "APATitlePageInfo");
|
||||
|
||||
// Date
|
||||
AddSampleParagraph(body, dateLine, "APATitlePageInfo");
|
||||
|
||||
// Page break after title page
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "APATitlePageInfo" }
|
||||
),
|
||||
new Run(new Break { Type = BreakValues.Page })
|
||||
));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates an APA Level 4 or 5 "run-in" paragraph where the heading text
|
||||
/// (bold or bold italic) is followed by the body text on the same line.
|
||||
/// The heading ends with a period per APA 7 convention.
|
||||
/// </summary>
|
||||
private static Paragraph CreateAPA7RunInParagraph(
|
||||
string headingText, string bodyText, bool bold, bool italic)
|
||||
{
|
||||
var headingRunProps = new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
);
|
||||
|
||||
if (bold)
|
||||
headingRunProps.Append(new Bold());
|
||||
if (italic)
|
||||
headingRunProps.Append(new Italic());
|
||||
|
||||
return new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Indentation { FirstLine = "720" }, // 0.5in indent
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
),
|
||||
// Heading run (bold / bold italic)
|
||||
new Run(
|
||||
headingRunProps,
|
||||
new Text(headingText) { Space = SpaceProcessingModeValues.Preserve }
|
||||
),
|
||||
// Body text run (regular)
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new Text(bodyText) { Space = SpaceProcessingModeValues.Preserve }
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
// RECIPE 9: MLA 9TH EDITION
|
||||
// ════════════════════════════════════════════════════════════════════════
|
||||
|
||||
/// <summary>
|
||||
/// Recipe: MLA 9th Edition
|
||||
/// Source: MLA Handbook, 9th edition (2021), Part 1 (Principles of Scholarship)
|
||||
/// and Part 2 (Details of MLA Style).
|
||||
///
|
||||
/// Key MLA 9 specifications:
|
||||
/// - Font: 12pt Times New Roman (or other readable font; Times New Roman is standard).
|
||||
/// - Margins: 1 inch on all sides.
|
||||
/// - Line spacing: Double-spaced throughout, including block quotes and Works Cited.
|
||||
/// - Paragraph indent: 0.5 inch first-line indent for body paragraphs.
|
||||
/// - Title: Centered, same size as body text (12pt), NOT bold, italic, or underlined.
|
||||
/// MLA eschews visual hierarchy — the title is distinguished only by centering.
|
||||
/// - No mandatory heading system. If headings are used, they should be simple and
|
||||
/// consistent. MLA does not prescribe heading levels like APA does.
|
||||
/// - Running header: Author's last name and page number, flush right, 0.5 inch from top.
|
||||
/// - First-page header block: Student's name, instructor's name, course title, and
|
||||
/// date — upper left, double-spaced, NO extra spacing.
|
||||
/// - Works Cited: title "Works Cited" centered (not bold), entries have hanging indent
|
||||
/// of 0.5 inch (first line flush left, subsequent lines indented).
|
||||
/// - No title page required (unless specifically requested by instructor).
|
||||
///
|
||||
/// Design rationale:
|
||||
/// - MLA's aesthetic is deliberately plain — the writing is the content.
|
||||
/// - No bold headings, no size variation, no decorative elements.
|
||||
/// - The only structural markers are centering (title, Works Cited label)
|
||||
/// and indentation (paragraphs, hanging indent for citations).
|
||||
/// - This uniformity reflects MLA's roots in literary studies, where the
|
||||
/// text itself is paramount and formatting should be invisible.
|
||||
/// </summary>
|
||||
public static void CreateMLA9Document(string outputPath)
|
||||
{
|
||||
using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
|
||||
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document(new Body());
|
||||
var body = mainPart.Document.Body!;
|
||||
|
||||
// ── Styles ──
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
stylesPart.Styles = new Styles();
|
||||
var styles = stylesPart.Styles;
|
||||
|
||||
// DocDefaults: 12pt Times New Roman, double spacing, 0.5in first-line indent
|
||||
styles.Append(new DocDefaults(
|
||||
new RunPropertiesDefault(
|
||||
new RunPropertiesBaseStyle(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" }, // 12pt
|
||||
new FontSizeComplexScript { Val = "24" },
|
||||
new Color { Val = "000000" },
|
||||
new Languages { Val = "en-US", EastAsia = "zh-CN" }
|
||||
)
|
||||
),
|
||||
new ParagraphPropertiesDefault(
|
||||
new ParagraphPropertiesBaseStyle(
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480", // Double spacing throughout
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
},
|
||||
new Indentation { FirstLine = "720" } // 0.5in first-line indent
|
||||
)
|
||||
)
|
||||
));
|
||||
|
||||
// ── Normal style ──
|
||||
styles.Append(CreateParagraphStyle(
|
||||
styleId: "Normal",
|
||||
styleName: "Normal",
|
||||
isDefault: true,
|
||||
uiPriority: 0
|
||||
));
|
||||
|
||||
// ── MLA Title style: centered, NOT bold/italic/underlined ──
|
||||
// MLA is distinctive: the title has NO special formatting beyond centering.
|
||||
styles.Append(CreateMLA9TitleStyle());
|
||||
|
||||
// ── MLA Header Block style: flush left, no indent ──
|
||||
styles.Append(CreateMLA9HeaderBlockStyle());
|
||||
|
||||
// ── MLA Works Cited label style: centered, not bold ──
|
||||
styles.Append(CreateMLA9WorksCitedLabelStyle());
|
||||
|
||||
// ── MLA Works Cited entry style: hanging indent 0.5in ──
|
||||
styles.Append(CreateMLA9WorksCitedEntryStyle());
|
||||
|
||||
// ── Page setup: US Letter, 1in all sides ──
|
||||
var sectPr = new SectionProperties(
|
||||
new WpPageSize { Width = 12240U, Height = 15840U },
|
||||
new PageMargin
|
||||
{
|
||||
Top = 1440, Bottom = 1440,
|
||||
Left = 1440U, Right = 1440U,
|
||||
Header = 720U, Footer = 720U, Gutter = 0U
|
||||
}
|
||||
);
|
||||
|
||||
// ── Running header: "LastName PageNumber" flush right ──
|
||||
AddMLA9Header(mainPart, sectPr, "Mitchell");
|
||||
|
||||
// ══════════════════════════════════════════════════════════════════
|
||||
// SAMPLE CONTENT: MLA header block, title, body, Works Cited
|
||||
// ══════════════════════════════════════════════════════════════════
|
||||
|
||||
// ── First-page header block (upper left, double-spaced) ──
|
||||
AddSampleParagraph(body, "Sarah Mitchell", "MLAHeaderBlock");
|
||||
AddSampleParagraph(body, "Professor Johnson", "MLAHeaderBlock");
|
||||
AddSampleParagraph(body, "English 201: American Literature", "MLAHeaderBlock");
|
||||
AddSampleParagraph(body, "15 October 2024", "MLAHeaderBlock");
|
||||
|
||||
// ── Title: centered, 12pt, plain (not bold) ──
|
||||
AddSampleParagraph(body, "The Function of the Unreliable Narrator in Nabokov's Lolita", "MLATitle");
|
||||
|
||||
// ── Body paragraphs ──
|
||||
AddSampleParagraph(body,
|
||||
"Vladimir Nabokov's Lolita (1955) remains one of the most studied examples of "
|
||||
+ "unreliable narration in twentieth-century fiction. Humbert Humbert's elaborate, "
|
||||
+ "self-justifying prose has been analyzed through numerous critical lenses, yet the "
|
||||
+ "question of how the novel's narrative structure shapes reader complicity continues "
|
||||
+ "to generate scholarly debate.",
|
||||
"Normal");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"The concept of the unreliable narrator, first articulated by Wayne C. Booth in "
|
||||
+ "The Rhetoric of Fiction (1961), provides a foundational framework for understanding "
|
||||
+ "Humbert's discourse. Booth argues that unreliable narrators are those whose values "
|
||||
+ "diverge from those of the implied author (158-59). In Lolita, this divergence is "
|
||||
+ "particularly complex because Nabokov layers multiple forms of unreliability: "
|
||||
+ "factual, evaluative, and interpretive.",
|
||||
"Normal");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Michael Wood has observed that \"Nabokov's genius lies in making us forget, "
|
||||
+ "momentarily, that Humbert is a monster\" (127). This temporary forgetting is not "
|
||||
+ "a failure of reading but a designed effect of the narrative voice. The luxurious "
|
||||
+ "prose, the literary allusions, the self-deprecating wit \u2014 all serve to create what "
|
||||
+ "Nomi Tamir-Ghez calls \"rhetorical seduction\" (42), in which readers find "
|
||||
+ "themselves sympathizing with a narrator whose actions they would condemn.",
|
||||
"Normal");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"The structural implications of Humbert's unreliability extend beyond mere "
|
||||
+ "factual distortion. As Eric Naiman demonstrates, the novel's famous opening "
|
||||
+ "paragraph \u2014 with its incantatory repetition of \"Lolita\" \u2014 establishes a "
|
||||
+ "pattern of linguistic possession that mirrors Humbert's physical possession of "
|
||||
+ "Dolores Haze (85). The language itself becomes an instrument of control, one "
|
||||
+ "that operates on the reader as well as on the characters within the narrative.",
|
||||
"Normal");
|
||||
|
||||
// ── Works Cited ──
|
||||
// Page break before Works Cited
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphStyleId { Val = "MLAHeaderBlock" }
|
||||
),
|
||||
new Run(new Break { Type = BreakValues.Page })
|
||||
));
|
||||
|
||||
AddSampleParagraph(body, "Works Cited", "MLAWorksCitedLabel");
|
||||
|
||||
// Works Cited entries with hanging indent
|
||||
AddSampleParagraph(body,
|
||||
"Booth, Wayne C. The Rhetoric of Fiction. 2nd ed., U of Chicago P, 1983.",
|
||||
"MLAWorksCitedEntry");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Nabokov, Vladimir. Lolita. 1955. Vintage International, 1989.",
|
||||
"MLAWorksCitedEntry");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Naiman, Eric. Nabokov, Perversely. Cornell UP, 2010.",
|
||||
"MLAWorksCitedEntry");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Tamir-Ghez, Nomi. \"The Art of Persuasion in Nabokov's Lolita.\" Poetics Today, "
|
||||
+ "vol. 1, no. 1-2, 1979, pp. 65-83.",
|
||||
"MLAWorksCitedEntry");
|
||||
|
||||
AddSampleParagraph(body,
|
||||
"Wood, Michael. The Magician's Doubts: Nabokov and the Risks of Fiction. "
|
||||
+ "Princeton UP, 1995.",
|
||||
"MLAWorksCitedEntry");
|
||||
|
||||
// Section properties must be last child of body
|
||||
body.Append(sectPr);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// MLA title style: centered, 12pt, NO bold/italic/underline.
|
||||
/// MLA's radical plainness — the title is distinguished only by position.
|
||||
/// </summary>
|
||||
private static Style CreateMLA9TitleStyle()
|
||||
{
|
||||
return new Style(
|
||||
new StyleName { Val = "MLA Title" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
)
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "MLATitle",
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// MLA first-page header block style: flush left, no first-line indent, double-spaced.
|
||||
/// Used for the student name, instructor, course, and date lines.
|
||||
/// </summary>
|
||||
private static Style CreateMLA9HeaderBlockStyle()
|
||||
{
|
||||
return new Style(
|
||||
new StyleName { Val = "MLA Header Block" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
)
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "MLAHeaderBlock",
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// MLA Works Cited label style: centered, 12pt, NOT bold.
|
||||
/// Like the title, the label is plain — only centering distinguishes it.
|
||||
/// </summary>
|
||||
private static Style CreateMLA9WorksCitedLabelStyle()
|
||||
{
|
||||
return new Style(
|
||||
new StyleName { Val = "MLA Works Cited Label" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
)
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "MLAWorksCitedLabel",
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// MLA Works Cited entry style: hanging indent of 0.5 inch (720 DXA).
|
||||
/// First line is flush left; subsequent lines indent 0.5 inch.
|
||||
/// This is the standard format for bibliography entries in MLA style.
|
||||
/// </summary>
|
||||
private static Style CreateMLA9WorksCitedEntryStyle()
|
||||
{
|
||||
return new Style(
|
||||
new StyleName { Val = "MLA Works Cited Entry" },
|
||||
new BasedOn { Val = "Normal" },
|
||||
new UIPriority { Val = 1 },
|
||||
new StyleParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left },
|
||||
// Hanging indent: Left = 720, FirstLine is negative (Hanging = 720)
|
||||
new Indentation { Left = "720", Hanging = "720" },
|
||||
new SpacingBetweenLines
|
||||
{
|
||||
Line = "480",
|
||||
LineRule = LineSpacingRuleValues.Auto,
|
||||
After = "0"
|
||||
}
|
||||
)
|
||||
)
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = "MLAWorksCitedEntry",
|
||||
Default = false
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds the MLA 9 running header: author last name and page number, flush right,
|
||||
/// 0.5 inch from top of page. Per MLA convention, this appears on every page.
|
||||
/// </summary>
|
||||
private static void AddMLA9Header(MainDocumentPart mainPart, SectionProperties sectPr, string authorLastName)
|
||||
{
|
||||
var headerParagraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Right },
|
||||
new Indentation { FirstLine = "0" },
|
||||
new SpacingBetweenLines { Line = "240", LineRule = LineSpacingRuleValues.Auto, After = "0" }
|
||||
),
|
||||
// Author last name
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new Text(authorLastName + " ") { Space = SpaceProcessingModeValues.Preserve }
|
||||
),
|
||||
// Page number
|
||||
new SimpleField(
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "Times New Roman",
|
||||
HighAnsi = "Times New Roman"
|
||||
},
|
||||
new FontSize { Val = "24" },
|
||||
new FontSizeComplexScript { Val = "24" }
|
||||
),
|
||||
new Text("1")
|
||||
)
|
||||
)
|
||||
{ Instruction = " PAGE " }
|
||||
);
|
||||
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
headerPart.Header = new Header(headerParagraph);
|
||||
headerPart.Header.Save();
|
||||
|
||||
string headerPartId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerPartId
|
||||
});
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,624 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Reference implementations for field codes and Table of Contents (TOC).
|
||||
///
|
||||
/// KEY CONCEPTS:
|
||||
/// - SimpleField: single-element shorthand, e.g. <w:fldSimple w:instr="PAGE"/>
|
||||
/// - Complex field: three FieldChar elements (Begin / Separate / End) with FieldCode between them.
|
||||
/// Word always writes complex fields; SimpleField is only used for trivial cases.
|
||||
/// - TOC is a structured document tag (SdtBlock) wrapping a complex field.
|
||||
/// - UpdateFieldsOnOpen tells Word to recalculate all fields when opening.
|
||||
/// </summary>
|
||||
public static class FieldAndTocSamples
|
||||
{
|
||||
// ──────────────────────────────────────────────
|
||||
// 1. InsertToc — TOC levels 1-3 inside SdtBlock
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a Table of Contents covering heading levels 1-3.
|
||||
/// Uses an SdtBlock wrapper with a complex field code:
|
||||
/// TOC \o "1-3" \h \z \u
|
||||
///
|
||||
/// Switches:
|
||||
/// \o "1-3" — outline levels 1-3
|
||||
/// \h — hyperlinks
|
||||
/// \z — hide tab leaders / page numbers in Web Layout
|
||||
/// \u — use applied paragraph outline level
|
||||
/// </summary>
|
||||
public static SdtBlock InsertToc(Body body)
|
||||
{
|
||||
var sdtBlock = new SdtBlock();
|
||||
|
||||
// SdtProperties — mark as TOC
|
||||
var sdtPr = new SdtProperties();
|
||||
sdtPr.Append(new SdtContentDocPartObject(
|
||||
new DocPartGallery { Val = "Table of Contents" },
|
||||
new DocPartUnique()));
|
||||
sdtBlock.Append(sdtPr);
|
||||
|
||||
// SdtContent — contains the field code paragraph(s)
|
||||
var sdtContent = new SdtContentBlock();
|
||||
|
||||
// TOC title paragraph
|
||||
var titlePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
|
||||
new Run(new Text("Table of Contents")));
|
||||
sdtContent.Append(titlePara);
|
||||
|
||||
// Complex field paragraph for TOC
|
||||
var fieldPara = new Paragraph();
|
||||
InsertComplexFieldInline(fieldPara, " TOC \\o \"1-3\" \\h \\z \\u ");
|
||||
sdtContent.Append(fieldPara);
|
||||
|
||||
sdtBlock.Append(sdtContent);
|
||||
body.Append(sdtBlock);
|
||||
return sdtBlock;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 2. InsertTocWithCustomLevels — TOC 1-4 levels
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a TOC covering heading levels 1-4.
|
||||
/// Identical structure to <see cref="InsertToc"/> but with "\o 1-4".
|
||||
/// </summary>
|
||||
public static SdtBlock InsertTocWithCustomLevels(Body body)
|
||||
{
|
||||
var sdtBlock = new SdtBlock();
|
||||
|
||||
var sdtPr = new SdtProperties();
|
||||
sdtPr.Append(new SdtContentDocPartObject(
|
||||
new DocPartGallery { Val = "Table of Contents" },
|
||||
new DocPartUnique()));
|
||||
sdtBlock.Append(sdtPr);
|
||||
|
||||
var sdtContent = new SdtContentBlock();
|
||||
|
||||
var titlePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
|
||||
new Run(new Text("Table of Contents")));
|
||||
sdtContent.Append(titlePara);
|
||||
|
||||
// 1-4 levels instead of 1-3
|
||||
var fieldPara = new Paragraph();
|
||||
InsertComplexFieldInline(fieldPara, " TOC \\o \"1-4\" \\h \\z \\u ");
|
||||
sdtContent.Append(fieldPara);
|
||||
|
||||
sdtBlock.Append(sdtContent);
|
||||
body.Append(sdtBlock);
|
||||
return sdtBlock;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 3. InsertSimpleField — PAGE, NUMPAGES, DATE, etc.
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a SimpleField element into a paragraph.
|
||||
///
|
||||
/// SimpleField is the compact form: <w:fldSimple w:instr=" PAGE "><w:r>...</w:r></w:fldSimple>
|
||||
///
|
||||
/// Common instructions: "PAGE", "NUMPAGES", "DATE", "TIME", "FILENAME".
|
||||
/// The run inside is the cached display value; Word recalculates on open.
|
||||
/// </summary>
|
||||
public static SimpleField InsertSimpleField(Paragraph para, string instruction)
|
||||
{
|
||||
var simpleField = new SimpleField { Instruction = $" {instruction} " };
|
||||
|
||||
// Cached display value — Word replaces this on recalculation
|
||||
simpleField.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text("«" + instruction + "»")));
|
||||
|
||||
para.Append(simpleField);
|
||||
return simpleField;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 4. InsertComplexField — Begin/Separate/End
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a complex field into a paragraph using the FieldChar Begin/Separate/End pattern.
|
||||
///
|
||||
/// Structure:
|
||||
/// Run1: FieldChar(Begin) + FieldCode(" PAGE ")
|
||||
/// Run2: FieldChar(Separate)
|
||||
/// Run3: Text("1") ← cached display value
|
||||
/// Run4: FieldChar(End)
|
||||
///
|
||||
/// Use complex fields when you need dirty flags, lock, or nested fields.
|
||||
/// </summary>
|
||||
public static void InsertComplexField(Paragraph para, string instruction)
|
||||
{
|
||||
InsertComplexFieldInline(para, $" {instruction} ");
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 5. InsertDateField — DATE with format switch
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a DATE field with a format switch: DATE \@ "yyyy-MM-dd"
|
||||
///
|
||||
/// The \@ switch specifies the date/time picture.
|
||||
/// Common formats:
|
||||
/// \@ "yyyy-MM-dd" → 2026-03-22
|
||||
/// \@ "MMMM d, yyyy" → March 22, 2026
|
||||
/// \@ "M/d/yyyy h:mm am/pm" → 3/22/2026 2:30 PM
|
||||
/// </summary>
|
||||
public static void InsertDateField(Paragraph para, string format)
|
||||
{
|
||||
// Field instruction with date-time picture switch
|
||||
string instruction = $" DATE \\@ \"{format}\" ";
|
||||
InsertComplexFieldInline(para, instruction);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 6. InsertCrossReference — REF field
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a REF cross-reference field that refers to a bookmark.
|
||||
///
|
||||
/// Instruction: REF bookmarkName \h
|
||||
/// \h — creates a hyperlink to the bookmark
|
||||
/// \p — inserts "above" or "below" relative position
|
||||
/// \n — inserts paragraph number of the bookmark
|
||||
/// </summary>
|
||||
public static void InsertCrossReference(Paragraph para, string bookmarkName)
|
||||
{
|
||||
string instruction = $" REF {bookmarkName} \\h ";
|
||||
InsertComplexFieldInline(para, instruction);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 7. InsertSequenceField — SEQ for numbering
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a SEQ (sequence) field for auto-numbering figures, tables, etc.
|
||||
///
|
||||
/// Usage pattern for "Figure 1":
|
||||
/// 1. Append a run with text "Figure " to the paragraph
|
||||
/// 2. Call InsertSequenceField(para, "Figure")
|
||||
///
|
||||
/// Usage pattern for "Table 1":
|
||||
/// 1. Append a run with text "Table " to the paragraph
|
||||
/// 2. Call InsertSequenceField(para, "Table")
|
||||
///
|
||||
/// Each unique seqName maintains its own counter across the document.
|
||||
/// </summary>
|
||||
public static void InsertSequenceField(Paragraph para, string seqName)
|
||||
{
|
||||
string instruction = $" SEQ {seqName} \\* ARABIC ";
|
||||
InsertComplexFieldInline(para, instruction);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 8. InsertMergeField — MERGEFIELD for mail merge
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a MERGEFIELD for mail merge scenarios.
|
||||
///
|
||||
/// Instruction: MERGEFIELD fieldName \* MERGEFORMAT
|
||||
/// \* MERGEFORMAT — preserves formatting applied to the field result
|
||||
/// \b "text" — text before if field is non-empty
|
||||
/// \f "text" — text after if field is non-empty
|
||||
///
|
||||
/// The cached display shows «fieldName» as a placeholder.
|
||||
/// </summary>
|
||||
public static void InsertMergeField(Paragraph para, string fieldName)
|
||||
{
|
||||
string instruction = $" MERGEFIELD {fieldName} \\* MERGEFORMAT ";
|
||||
|
||||
// Begin
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
|
||||
// Field code
|
||||
para.Append(new Run(
|
||||
new FieldCode(instruction) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Separate
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
|
||||
// Cached value — shows merge field placeholder
|
||||
para.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text($"\u00AB{fieldName}\u00BB") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// End
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 9. InsertConditionalField — IF field
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an IF conditional field.
|
||||
///
|
||||
/// Syntax: IF expression1 operator expression2 "true-text" "false-text"
|
||||
/// Example: IF { MERGEFIELD Gender } = "Male" "Mr." "Ms."
|
||||
///
|
||||
/// This example checks if MERGEFIELD Amount > 1000 and displays different text.
|
||||
/// Nested fields (MERGEFIELD inside IF) require nested Begin/End pairs.
|
||||
/// </summary>
|
||||
public static void InsertConditionalField(Paragraph para)
|
||||
{
|
||||
// Outer IF field Begin
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
|
||||
para.Append(new Run(
|
||||
new FieldCode(" IF ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Nested MERGEFIELD inside the IF condition
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
para.Append(new Run(
|
||||
new FieldCode(" MERGEFIELD Amount ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
para.Append(new Run(
|
||||
new Text("0") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
// Continuation of IF instruction
|
||||
para.Append(new Run(
|
||||
new FieldCode(" > \"1000\" \"High Value\" \"Standard\" ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Separate — cached result
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
para.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text("Standard") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// End
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 10. InsertStyleRef — STYLEREF for running headers
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a STYLEREF field, commonly used in headers/footers
|
||||
/// to display the current chapter or section title.
|
||||
///
|
||||
/// Instruction: STYLEREF "Heading 1"
|
||||
/// Displays the text of the nearest paragraph with style "Heading 1".
|
||||
/// \l — search from bottom of page up (for last instance on page)
|
||||
/// \n — insert the paragraph number, not text
|
||||
/// </summary>
|
||||
public static void InsertStyleRef(Paragraph para)
|
||||
{
|
||||
string instruction = " STYLEREF \"Heading 1\" ";
|
||||
InsertComplexFieldInline(para, instruction);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 11. EnableUpdateFieldsOnOpen
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Sets the UpdateFieldsOnOpen property so Word recalculates
|
||||
/// all fields (PAGE, TOC, SEQ, etc.) when the document is opened.
|
||||
///
|
||||
/// Without this, TOC and cross-references show stale cached values
|
||||
/// until the user manually presses Ctrl+A, F9 to update.
|
||||
/// </summary>
|
||||
public static void EnableUpdateFieldsOnOpen(DocumentSettingsPart settingsPart)
|
||||
{
|
||||
settingsPart.Settings ??= new Settings();
|
||||
var existing = settingsPart.Settings.GetFirstChild<UpdateFieldsOnOpen>();
|
||||
if (existing != null)
|
||||
{
|
||||
existing.Val = true;
|
||||
}
|
||||
else
|
||||
{
|
||||
settingsPart.Settings.Append(new UpdateFieldsOnOpen { Val = true });
|
||||
}
|
||||
settingsPart.Settings.Save();
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 12. CreateTocStyles — TOC1/2/3 with tab leaders
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates TOC1, TOC2, TOC3 paragraph styles with right-aligned tab stops
|
||||
/// and dot leaders (the "....." between entry text and page number).
|
||||
///
|
||||
/// Each TOC level is indented further:
|
||||
/// TOC1 — 0 indent
|
||||
/// TOC2 — 240 twips (1/6 inch)
|
||||
/// TOC3 — 480 twips (1/3 inch)
|
||||
///
|
||||
/// Tab leader: dot-filled right tab at 9360 twips (6.5 inches for letter paper).
|
||||
/// </summary>
|
||||
public static void CreateTocStyles(StyleDefinitionsPart stylesPart)
|
||||
{
|
||||
stylesPart.Styles ??= new Styles();
|
||||
|
||||
string[] tocStyleIds = ["TOC1", "TOC2", "TOC3"];
|
||||
string[] tocStyleNames = ["toc 1", "toc 2", "toc 3"];
|
||||
int[] indents = [0, 240, 480]; // twips
|
||||
|
||||
// Right tab position: 6.5 inches = 9360 twips (standard for US Letter)
|
||||
const int tabPosition = 9360;
|
||||
|
||||
for (int i = 0; i < tocStyleIds.Length; i++)
|
||||
{
|
||||
var style = new Style
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = tocStyleIds[i],
|
||||
CustomStyle = false
|
||||
};
|
||||
|
||||
style.Append(new StyleName { Val = tocStyleNames[i] });
|
||||
style.Append(new BasedOn { Val = "Normal" });
|
||||
style.Append(new NextParagraphStyle { Val = "Normal" });
|
||||
style.Append(new UIPriority { Val = 39 });
|
||||
|
||||
var pPr = new StyleParagraphProperties();
|
||||
|
||||
// Indentation for nested levels
|
||||
if (indents[i] > 0)
|
||||
{
|
||||
pPr.Append(new Indentation { Left = indents[i].ToString() });
|
||||
}
|
||||
|
||||
// Spacing: no space after for compact TOC
|
||||
pPr.Append(new SpacingBetweenLines { After = "0", Line = "276", LineRule = LineSpacingRuleValues.Auto });
|
||||
|
||||
// Right-aligned tab with dot leader
|
||||
var tabs = new Tabs();
|
||||
tabs.Append(new TabStop
|
||||
{
|
||||
Val = TabStopValues.Right,
|
||||
Leader = TabStopLeaderCharValues.Dot,
|
||||
Position = tabPosition
|
||||
});
|
||||
pPr.Append(tabs);
|
||||
|
||||
style.Append(pPr);
|
||||
stylesPart.Styles.Append(style);
|
||||
}
|
||||
|
||||
stylesPart.Styles.Save();
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 13. CreateMixedTocStructure — Real-world TOC
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Real-world TOC structure: Mixed SDT block + static entries + field code.
|
||||
///
|
||||
/// IMPORTANT: Most templates do NOT have a clean TOC field code alone.
|
||||
/// Instead, they contain:
|
||||
/// 1. An SDT (Structured Document Tag) wrapper with alias "TOC"
|
||||
/// 2. Inside the SDT: a field code BEGIN + SEPARATE + static example entries + END
|
||||
/// 3. The static entries are placeholder text (e.g., "第1章 绪论...........1")
|
||||
/// that Word replaces when user presses "Update Fields"
|
||||
///
|
||||
/// When applying a template (Scenario C), you should:
|
||||
/// - KEEP the entire SDT block from the template (don't rebuild it)
|
||||
/// - DO NOT replace static entries with programmatic content
|
||||
/// - The entries will auto-update when the user opens in Word and updates fields
|
||||
/// - If you must update entries programmatically, replace the content INSIDE
|
||||
/// the SDT between fldChar separate and fldChar end
|
||||
///
|
||||
/// Common mistake: Treating TOC as pure field code and rebuilding it from scratch,
|
||||
/// which destroys the SDT wrapper and breaks Word's "Update Table" functionality.
|
||||
/// </summary>
|
||||
public static void CreateMixedTocStructure(string outputPath)
|
||||
{
|
||||
using var doc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
|
||||
var mainPart = doc.AddMainDocumentPart();
|
||||
mainPart.Document = new Document();
|
||||
var body = new Body();
|
||||
mainPart.Document.Append(body);
|
||||
|
||||
// Add styles part with TOC styles
|
||||
var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
|
||||
CreateTocStyles(stylesPart);
|
||||
|
||||
// ─── SDT Block wrapping the entire TOC ───
|
||||
var sdtBlock = new SdtBlock();
|
||||
|
||||
// SDT Properties: alias "TOC", tag, and DocPartGallery
|
||||
var sdtPr = new SdtProperties();
|
||||
sdtPr.Append(new SdtAlias { Val = "TOC" });
|
||||
sdtPr.Append(new Tag { Val = "TOC" });
|
||||
sdtPr.Append(new SdtContentDocPartObject(
|
||||
new DocPartGallery { Val = "Table of Contents" },
|
||||
new DocPartUnique()));
|
||||
sdtBlock.Append(sdtPr);
|
||||
|
||||
// SDT Content: field code + static entries
|
||||
var sdtContent = new SdtContentBlock();
|
||||
|
||||
// ─── TOC title paragraph ───
|
||||
var titlePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "TOCHeading" }),
|
||||
new Run(new Text("目 录")));
|
||||
sdtContent.Append(titlePara);
|
||||
|
||||
// ─── Field code BEGIN paragraph ───
|
||||
var fieldBeginPara = new Paragraph();
|
||||
|
||||
// fldChar Begin
|
||||
fieldBeginPara.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
|
||||
// instrText: TOC \o "1-3" \h \z \u
|
||||
fieldBeginPara.Append(new Run(
|
||||
new FieldCode(" TOC \\o \"1-3\" \\h \\z \\u ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// fldChar Separate
|
||||
fieldBeginPara.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
|
||||
sdtContent.Append(fieldBeginPara);
|
||||
|
||||
// ─── Static placeholder entries (TOC1/TOC2/TOC3) ───
|
||||
// These are the example entries that Word will replace when user clicks "Update Table".
|
||||
// In real templates, these show example chapter titles with dot leaders and page numbers.
|
||||
|
||||
// TOC level 1 entry: "第1章 绪论...........1"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC1", "第1章 绪论", "1"));
|
||||
|
||||
// TOC level 2 entry: "1.1 研究背景...........1"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC2", "1.1 研究背景", "1"));
|
||||
|
||||
// TOC level 2 entry: "1.2 研究目的...........2"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC2", "1.2 研究目的", "2"));
|
||||
|
||||
// TOC level 1 entry: "第2章 文献综述...........3"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC1", "第2章 文献综述", "3"));
|
||||
|
||||
// TOC level 2 entry: "2.1 国内研究现状...........3"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC2", "2.1 国内研究现状", "3"));
|
||||
|
||||
// TOC level 3 entry: "2.1.1 早期研究...........4"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC3", "2.1.1 早期研究", "4"));
|
||||
|
||||
// TOC level 1 entry: "第3章 研究方法...........5"
|
||||
sdtContent.Append(CreateStaticTocEntry("TOC1", "第3章 研究方法", "5"));
|
||||
|
||||
// ─── Field code END paragraph ───
|
||||
var fieldEndPara = new Paragraph();
|
||||
fieldEndPara.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
sdtContent.Append(fieldEndPara);
|
||||
|
||||
sdtBlock.Append(sdtContent);
|
||||
body.Append(sdtBlock);
|
||||
|
||||
// ─── Actual heading paragraphs (what the TOC references) ───
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
|
||||
new Run(new Text("第1章 绪论"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
|
||||
new Run(new Text("1.1 研究背景"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("本研究旨在探讨……"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
|
||||
new Run(new Text("1.2 研究目的"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("研究目的包括……"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
|
||||
new Run(new Text("第2章 文献综述"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading2" }),
|
||||
new Run(new Text("2.1 国内研究现状"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading3" }),
|
||||
new Run(new Text("2.1.1 早期研究"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("早期研究表明……"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
|
||||
new Run(new Text("第3章 研究方法"))));
|
||||
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("本章介绍研究方法……"))));
|
||||
|
||||
// ─── Enable UpdateFieldsOnOpen so TOC auto-refreshes ───
|
||||
var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
|
||||
EnableUpdateFieldsOnOpen(settingsPart);
|
||||
|
||||
mainPart.Document.Save();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Helper: creates a single static TOC entry paragraph with style, text, tab leader, and page number.
|
||||
/// This mirrors what Word generates inside a TOC SDT block.
|
||||
/// </summary>
|
||||
private static Paragraph CreateStaticTocEntry(string tocStyleId, string entryText, string pageNumber)
|
||||
{
|
||||
var para = new Paragraph();
|
||||
|
||||
// Paragraph properties: TOC style + right-aligned tab with dot leader
|
||||
var pPr = new ParagraphProperties();
|
||||
pPr.Append(new ParagraphStyleId { Val = tocStyleId });
|
||||
para.Append(pPr);
|
||||
|
||||
// Run with entry text
|
||||
para.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text(entryText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Tab character (creates the dot leader between text and page number)
|
||||
para.Append(new Run(new TabChar()));
|
||||
|
||||
// Page number
|
||||
para.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text(pageNumber)));
|
||||
|
||||
return para;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// Private helper: insert complex field inline
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Shared helper that appends Begin / FieldCode / Separate / CachedValue / End
|
||||
/// runs to a paragraph.
|
||||
/// </summary>
|
||||
private static void InsertComplexFieldInline(Paragraph para, string instruction)
|
||||
{
|
||||
// Run 1: FieldChar Begin
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
|
||||
// Run 2: FieldCode (the instruction text)
|
||||
para.Append(new Run(
|
||||
new FieldCode(instruction) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Run 3: FieldChar Separate
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.Separate }));
|
||||
|
||||
// Run 4: Cached display value (placeholder until Word recalculates)
|
||||
para.Append(new Run(
|
||||
new RunProperties(new NoProof()),
|
||||
new Text("1") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Run 5: FieldChar End
|
||||
para.Append(new Run(
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,675 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
// W15 types for people.xml (Office 2013+ comment author tracking)
|
||||
using W15Person = DocumentFormat.OpenXml.Office2013.Word.Person;
|
||||
using W15People = DocumentFormat.OpenXml.Office2013.Word.People;
|
||||
using W15PresenceInfo = DocumentFormat.OpenXml.Office2013.Word.PresenceInfo;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Reference implementations for footnotes, endnotes, comments, bookmarks, and hyperlinks.
|
||||
///
|
||||
/// KEY CONCEPTS:
|
||||
/// - FootnotesPart must contain separator (id=-1) and continuationSeparator (id=0) footnotes.
|
||||
/// - Comments require up to 4 parts: comments.xml, commentsExtended.xml, commentsIds.xml, people.xml.
|
||||
/// - CommentRangeStart/CommentRangeEnd wrap the commented text; CommentReference goes in a run after CommentRangeEnd.
|
||||
/// - Bookmarks use BookmarkStart/BookmarkEnd pairs with matching Id attributes.
|
||||
/// - External hyperlinks require a HyperlinkRelationship in the part's relationships.
|
||||
/// </summary>
|
||||
public static class FootnoteAndCommentSamples
|
||||
{
|
||||
// ──────────────────────────────────────────────
|
||||
// 1. SetupFootnotesPart — required separator footnotes
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Initializes the FootnotesPart with the two REQUIRED special footnotes:
|
||||
/// - id=-1: separator (the short horizontal line between body text and footnotes)
|
||||
/// - id=0: continuationSeparator (line shown when a footnote spans pages)
|
||||
///
|
||||
/// Word will refuse to render footnotes correctly without these.
|
||||
/// Call this once before adding any footnotes.
|
||||
/// </summary>
|
||||
public static FootnotesPart SetupFootnotesPart(MainDocumentPart mainPart)
|
||||
{
|
||||
var footnotesPart = mainPart.FootnotesPart
|
||||
?? mainPart.AddNewPart<FootnotesPart>();
|
||||
|
||||
footnotesPart.Footnotes = new Footnotes();
|
||||
|
||||
// Separator footnote (id = -1): renders as a short horizontal rule
|
||||
var separator = new Footnote { Type = FootnoteEndnoteValues.Separator, Id = -1 };
|
||||
separator.Append(new Paragraph(
|
||||
new ParagraphProperties(new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }),
|
||||
new Run(new SeparatorMark())));
|
||||
footnotesPart.Footnotes.Append(separator);
|
||||
|
||||
// Continuation separator footnote (id = 0): renders as a full-width rule
|
||||
var contSeparator = new Footnote { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 0 };
|
||||
contSeparator.Append(new Paragraph(
|
||||
new ParagraphProperties(new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }),
|
||||
new Run(new ContinuationSeparatorMark())));
|
||||
footnotesPart.Footnotes.Append(contSeparator);
|
||||
|
||||
footnotesPart.Footnotes.Save();
|
||||
return footnotesPart;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 2. AddFootnote — reference in body + content in part
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a footnote with two coordinated pieces:
|
||||
/// 1. A FootnoteReference in the body paragraph (superscript number in the text)
|
||||
/// 2. A Footnote element in the FootnotesPart (the actual footnote content)
|
||||
///
|
||||
/// The footnote id links the two together. IDs must be unique and > 0
|
||||
/// (ids -1 and 0 are reserved for separator and continuationSeparator).
|
||||
/// </summary>
|
||||
public static int AddFootnote(MainDocumentPart mainPart, Paragraph para, string footnoteText)
|
||||
{
|
||||
// Ensure footnotes part exists with separators
|
||||
if (mainPart.FootnotesPart == null)
|
||||
{
|
||||
SetupFootnotesPart(mainPart);
|
||||
}
|
||||
|
||||
int footnoteId = GetNextFootnoteId(mainPart.FootnotesPart!);
|
||||
|
||||
// 1. Add the footnote reference in the body paragraph
|
||||
// This renders the superscript number (e.g., "1") in the text
|
||||
var refRun = new Run(
|
||||
new RunProperties(new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }),
|
||||
new FootnoteReference { Id = footnoteId });
|
||||
para.Append(refRun);
|
||||
|
||||
// 2. Add the footnote content in the FootnotesPart
|
||||
var footnote = new Footnote { Id = footnoteId };
|
||||
|
||||
// Footnote paragraph starts with a self-referencing FootnoteReference
|
||||
var footnotePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "FootnoteText" }),
|
||||
new Run(
|
||||
new RunProperties(new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }),
|
||||
new FootnoteReferenceMark()),
|
||||
new Run(
|
||||
new Text(" " + footnoteText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
footnote.Append(footnotePara);
|
||||
mainPart.FootnotesPart!.Footnotes!.Append(footnote);
|
||||
mainPart.FootnotesPart.Footnotes.Save();
|
||||
|
||||
return footnoteId;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 3. AddEndnote — same pattern for endnotes
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds an endnote. Same two-part pattern as footnotes:
|
||||
/// 1. EndnoteReference in body paragraph
|
||||
/// 2. Endnote element in EndnotesPart
|
||||
///
|
||||
/// EndnotesPart also requires separator (id=-1) and continuationSeparator (id=0).
|
||||
/// Endnotes appear at the end of the document (or section) rather than page bottom.
|
||||
/// </summary>
|
||||
public static int AddEndnote(MainDocumentPart mainPart, Paragraph para, string endnoteText)
|
||||
{
|
||||
// Ensure endnotes part exists with separators
|
||||
if (mainPart.EndnotesPart == null)
|
||||
{
|
||||
SetupEndnotesPart(mainPart);
|
||||
}
|
||||
|
||||
int endnoteId = GetNextEndnoteId(mainPart.EndnotesPart!);
|
||||
|
||||
// 1. Endnote reference in body text
|
||||
var refRun = new Run(
|
||||
new RunProperties(new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }),
|
||||
new EndnoteReference { Id = endnoteId });
|
||||
para.Append(refRun);
|
||||
|
||||
// 2. Endnote content in EndnotesPart
|
||||
var endnote = new Endnote { Id = endnoteId };
|
||||
var endnotePara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "EndnoteText" }),
|
||||
new Run(
|
||||
new RunProperties(new VerticalTextAlignment { Val = VerticalPositionValues.Superscript }),
|
||||
new EndnoteReferenceMark()),
|
||||
new Run(
|
||||
new Text(" " + endnoteText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
endnote.Append(endnotePara);
|
||||
mainPart.EndnotesPart!.Endnotes!.Append(endnote);
|
||||
mainPart.EndnotesPart.Endnotes.Save();
|
||||
|
||||
return endnoteId;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 4. SetFootnoteProperties — position, numbering restart
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Configures footnote properties on a section:
|
||||
/// - Position: page bottom (default) vs. beneath text
|
||||
/// - Numbering format: decimal, lowerRoman, symbol, etc.
|
||||
/// - Numbering restart: continuous, eachSection, eachPage
|
||||
///
|
||||
/// These go inside SectionProperties as w:footnotePr.
|
||||
/// </summary>
|
||||
public static void SetFootnoteProperties(SectionProperties sectPr)
|
||||
{
|
||||
var footnotePr = new FootnoteProperties();
|
||||
|
||||
// Position: PageBottom is default; BeneathText puts them right after text
|
||||
footnotePr.Append(new FootnotePosition { Val = FootnotePositionValues.PageBottom });
|
||||
|
||||
// Numbering format: decimal (1, 2, 3...)
|
||||
footnotePr.Append(new NumberingFormat { Val = NumberFormatValues.Decimal });
|
||||
|
||||
// Restart numbering each section (alternatives: Continuous, EachPage)
|
||||
footnotePr.Append(new NumberingRestart { Val = RestartNumberValues.EachSection });
|
||||
|
||||
// Starting number
|
||||
footnotePr.Append(new NumberingStart { Val = 1 });
|
||||
|
||||
sectPr.Append(footnotePr);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 5. SetupCommentSystem — all 4 parts
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Initializes the complete comment system with all required parts:
|
||||
/// 1. WordprocessingCommentsPart — comments.xml (the Comment elements)
|
||||
/// 2. WordprocessingCommentsExPart — commentsExtended.xml (reply threading, done state)
|
||||
/// 3. WordprocessingCommentsIdsPart — commentsIds.xml (durable GUID-based comment IDs)
|
||||
/// 4. WordprocessingPeoplePart — people.xml (author identities)
|
||||
///
|
||||
/// All four parts must be present and consistent for modern Word to
|
||||
/// display comments correctly without repair prompts.
|
||||
/// </summary>
|
||||
public static void SetupCommentSystem(MainDocumentPart mainPart)
|
||||
{
|
||||
// Part 1: comments.xml
|
||||
if (mainPart.WordprocessingCommentsPart == null)
|
||||
{
|
||||
var commentsPart = mainPart.AddNewPart<WordprocessingCommentsPart>();
|
||||
commentsPart.Comments = new Comments();
|
||||
commentsPart.Comments.Save();
|
||||
}
|
||||
|
||||
// Part 2: commentsExtended.xml — for reply threading and done/resolved state
|
||||
// Uses W15 namespace (word/2012/wordml)
|
||||
if (mainPart.WordprocessingCommentsExPart == null)
|
||||
{
|
||||
var commentsExPart = mainPart.AddNewPart<WordprocessingCommentsExPart>();
|
||||
// Initialize with root element via raw XML since the typed API is limited
|
||||
using var writer = new System.IO.StreamWriter(commentsExPart.GetStream(System.IO.FileMode.Create));
|
||||
writer.Write("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
|
||||
+ "<w15:commentsEx xmlns:w15=\"http://schemas.microsoft.com/office/word/2012/wordml\""
|
||||
+ " xmlns:mc=\"http://schemas.openxmlformats.org/markup-compatibility/2006\""
|
||||
+ " mc:Ignorable=\"w15\"/>");
|
||||
}
|
||||
|
||||
// Part 3: commentsIds.xml — durable comment identifiers (W16CID namespace)
|
||||
if (mainPart.WordprocessingCommentsIdsPart == null)
|
||||
{
|
||||
var commentsIdsPart = mainPart.AddNewPart<WordprocessingCommentsIdsPart>();
|
||||
using var writer = new System.IO.StreamWriter(commentsIdsPart.GetStream(System.IO.FileMode.Create));
|
||||
writer.Write("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
|
||||
+ "<w16cid:commentsIds xmlns:w16cid=\"http://schemas.microsoft.com/office/word/2016/wordml/cid\"/>");
|
||||
}
|
||||
|
||||
// Part 4: people.xml — author info for comments
|
||||
if (mainPart.WordprocessingPeoplePart == null)
|
||||
{
|
||||
var peoplePart = mainPart.AddNewPart<WordprocessingPeoplePart>();
|
||||
peoplePart.People = new W15People();
|
||||
peoplePart.People.Save();
|
||||
}
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 6. AddComment — full comment with range markers
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a comment anchored to an entire paragraph with three coordinated elements:
|
||||
///
|
||||
/// In the document body (inside the paragraph):
|
||||
/// 1. CommentRangeStart { Id = commentId } — before commented content
|
||||
/// 2. CommentRangeEnd { Id = commentId } — after commented content
|
||||
/// 3. Run containing CommentReference { Id = commentId } — immediately after RangeEnd
|
||||
///
|
||||
/// In comments.xml:
|
||||
/// 4. Comment { Id = commentId } with paragraph content
|
||||
///
|
||||
/// The CommentReference run is what makes the comment indicator appear in the margin.
|
||||
/// </summary>
|
||||
public static int AddComment(MainDocumentPart mainPart, Paragraph para, string author, string text)
|
||||
{
|
||||
SetupCommentSystem(mainPart);
|
||||
|
||||
var commentsPart = mainPart.WordprocessingCommentsPart!;
|
||||
int commentId = GetNextCommentId(commentsPart);
|
||||
string idStr = commentId.ToString();
|
||||
|
||||
// Add comment range markers to the paragraph
|
||||
// Insert CommentRangeStart before existing content
|
||||
para.InsertAt(new CommentRangeStart { Id = idStr }, 0);
|
||||
|
||||
// Append CommentRangeEnd + CommentReference after content
|
||||
para.Append(new CommentRangeEnd { Id = idStr });
|
||||
para.Append(new Run(
|
||||
new RunProperties(
|
||||
new RunStyle { Val = "CommentReference" }),
|
||||
new CommentReference { Id = idStr }));
|
||||
|
||||
// Create the comment content in comments.xml
|
||||
var comment = new Comment
|
||||
{
|
||||
Id = idStr,
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Initials = GetInitials(author)
|
||||
};
|
||||
comment.Append(new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "CommentText" }),
|
||||
new Run(
|
||||
new RunProperties(new RunStyle { Val = "CommentReference" }),
|
||||
new AnnotationReferenceMark()),
|
||||
new Run(new Text(text) { Space = SpaceProcessingModeValues.Preserve })));
|
||||
|
||||
commentsPart.Comments!.Append(comment);
|
||||
commentsPart.Comments.Save();
|
||||
|
||||
// Register author in people.xml
|
||||
EnsurePersonEntry(mainPart, author);
|
||||
|
||||
return commentId;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 7. AddCommentReply — reply via commentsExtended
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a reply to an existing comment. Replies are threaded via commentsExtended.xml
|
||||
/// which links the reply's paraId to the parent comment's paraId using w15:paraIdParent.
|
||||
///
|
||||
/// The reply is a separate Comment element in comments.xml (with its own unique id),
|
||||
/// but it does NOT get CommentRangeStart/End markers in the document body.
|
||||
/// The threading relationship is purely in commentsExtended.xml.
|
||||
/// </summary>
|
||||
public static int AddCommentReply(MainDocumentPart mainPart, int parentCommentId, string author, string replyText)
|
||||
{
|
||||
SetupCommentSystem(mainPart);
|
||||
|
||||
var commentsPart = mainPart.WordprocessingCommentsPart!;
|
||||
int replyId = GetNextCommentId(commentsPart);
|
||||
string replyIdStr = replyId.ToString();
|
||||
|
||||
// Generate a unique paraId for the reply paragraph (w14:paraId)
|
||||
string replyParaId = GenerateParaId();
|
||||
|
||||
// Create reply as a Comment in comments.xml
|
||||
var reply = new Comment
|
||||
{
|
||||
Id = replyIdStr,
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Initials = GetInitials(author)
|
||||
};
|
||||
|
||||
var replyPara = new Paragraph(
|
||||
new ParagraphProperties(new ParagraphStyleId { Val = "CommentText" }),
|
||||
new Run(new Text(replyText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// Set paraId on the paragraph via extended attributes (W14 namespace)
|
||||
replyPara.SetAttribute(new OpenXmlAttribute("w14", "paraId", "http://schemas.microsoft.com/office/word/2010/wordml", replyParaId));
|
||||
|
||||
reply.Append(replyPara);
|
||||
commentsPart.Comments!.Append(reply);
|
||||
commentsPart.Comments.Save();
|
||||
|
||||
// Link the reply to the parent in commentsExtended.xml
|
||||
// Find the parent comment's paraId, then create a commentEx element
|
||||
var parentComment = commentsPart.Comments.Elements<Comment>()
|
||||
.FirstOrDefault(c => c.Id?.Value == parentCommentId.ToString());
|
||||
|
||||
string parentParaId = "00000000";
|
||||
if (parentComment != null)
|
||||
{
|
||||
var firstPara = parentComment.GetFirstChild<Paragraph>();
|
||||
if (firstPara != null)
|
||||
{
|
||||
var attr = firstPara.GetAttributes().FirstOrDefault(a => a.LocalName == "paraId");
|
||||
if (attr.Value != null) parentParaId = attr.Value;
|
||||
}
|
||||
}
|
||||
|
||||
// Write commentEx entry to commentsExtended.xml
|
||||
// This links replyParaId -> parentParaId
|
||||
if (mainPart.WordprocessingCommentsExPart != null)
|
||||
{
|
||||
var stream = mainPart.WordprocessingCommentsExPart.GetStream(System.IO.FileMode.Open);
|
||||
var doc = System.Xml.Linq.XDocument.Load(stream);
|
||||
stream.Dispose();
|
||||
|
||||
System.Xml.Linq.XNamespace w15 = "http://schemas.microsoft.com/office/word/2012/wordml";
|
||||
doc.Root!.Add(new System.Xml.Linq.XElement(w15 + "commentEx",
|
||||
new System.Xml.Linq.XAttribute(w15 + "paraId", replyParaId),
|
||||
new System.Xml.Linq.XAttribute(w15 + "paraIdParent", parentParaId)));
|
||||
|
||||
using var writeStream = mainPart.WordprocessingCommentsExPart.GetStream(System.IO.FileMode.Create);
|
||||
doc.Save(writeStream);
|
||||
}
|
||||
|
||||
EnsurePersonEntry(mainPart, author);
|
||||
|
||||
return replyId;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 8. DeleteComment — remove from all parts + markers
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Completely removes a comment from the document by cleaning up all four locations:
|
||||
/// 1. CommentRangeStart/End from document body
|
||||
/// 2. CommentReference run from document body
|
||||
/// 3. Comment element from comments.xml
|
||||
/// 4. CommentEx entry from commentsExtended.xml
|
||||
///
|
||||
/// Failing to remove from all locations causes Word to show repair prompts.
|
||||
/// </summary>
|
||||
public static void DeleteComment(MainDocumentPart mainPart, int commentId)
|
||||
{
|
||||
string idStr = commentId.ToString();
|
||||
|
||||
// 1. Remove markers from document body
|
||||
var body = mainPart.Document?.Body;
|
||||
if (body != null)
|
||||
{
|
||||
// Remove all CommentRangeStart with matching id
|
||||
foreach (var start in body.Descendants<CommentRangeStart>()
|
||||
.Where(s => s.Id?.Value == idStr).ToList())
|
||||
{
|
||||
start.Remove();
|
||||
}
|
||||
|
||||
// Remove all CommentRangeEnd with matching id
|
||||
foreach (var end in body.Descendants<CommentRangeEnd>()
|
||||
.Where(e => e.Id?.Value == idStr).ToList())
|
||||
{
|
||||
end.Remove();
|
||||
}
|
||||
|
||||
// Remove runs containing CommentReference with matching id
|
||||
foreach (var reference in body.Descendants<CommentReference>()
|
||||
.Where(r => r.Id?.Value == idStr).ToList())
|
||||
{
|
||||
// Remove the parent Run, not just the CommentReference
|
||||
reference.Parent?.Remove();
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Remove from comments.xml
|
||||
var commentsPart = mainPart.WordprocessingCommentsPart;
|
||||
if (commentsPart?.Comments != null)
|
||||
{
|
||||
var comment = commentsPart.Comments.Elements<Comment>()
|
||||
.FirstOrDefault(c => c.Id?.Value == idStr);
|
||||
comment?.Remove();
|
||||
commentsPart.Comments.Save();
|
||||
}
|
||||
|
||||
// 3. Remove from commentsExtended.xml (reply threading)
|
||||
if (mainPart.WordprocessingCommentsExPart != null)
|
||||
{
|
||||
var stream = mainPart.WordprocessingCommentsExPart.GetStream(System.IO.FileMode.Open);
|
||||
var doc = System.Xml.Linq.XDocument.Load(stream);
|
||||
stream.Dispose();
|
||||
|
||||
System.Xml.Linq.XNamespace w15 = "http://schemas.microsoft.com/office/word/2012/wordml";
|
||||
// Find and remove commentEx entries that reference this comment's paraId
|
||||
// We need to find the paraId from the comment first, but since we already removed it,
|
||||
// we remove by matching — in practice you would track paraIds before deletion
|
||||
var toRemove = doc.Root!.Elements(w15 + "commentEx").ToList();
|
||||
// Remove entries whose paraId matches any paragraph in the deleted comment
|
||||
foreach (var elem in toRemove)
|
||||
{
|
||||
// In a full implementation, match by paraId correlation
|
||||
// For safety, this removes entries that are no longer referenced
|
||||
_ = elem; // kept for reference
|
||||
}
|
||||
|
||||
using var writeStream = mainPart.WordprocessingCommentsExPart.GetStream(System.IO.FileMode.Create);
|
||||
doc.Save(writeStream);
|
||||
}
|
||||
|
||||
// 4. Remove from commentsIds.xml if present
|
||||
if (mainPart.WordprocessingCommentsIdsPart != null)
|
||||
{
|
||||
var stream = mainPart.WordprocessingCommentsIdsPart.GetStream(System.IO.FileMode.Open);
|
||||
var doc = System.Xml.Linq.XDocument.Load(stream);
|
||||
stream.Dispose();
|
||||
|
||||
System.Xml.Linq.XNamespace w16cid = "http://schemas.microsoft.com/office/word/2016/wordml/cid";
|
||||
var toRemove = doc.Root!.Elements(w16cid + "commentId")
|
||||
.Where(e => (string?)e.Attribute(w16cid + "paraId") == idStr)
|
||||
.ToList();
|
||||
foreach (var elem in toRemove)
|
||||
{
|
||||
elem.Remove();
|
||||
}
|
||||
|
||||
using var writeStream = mainPart.WordprocessingCommentsIdsPart.GetStream(System.IO.FileMode.Create);
|
||||
doc.Save(writeStream);
|
||||
}
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 9. AddBookmark — BookmarkStart + BookmarkEnd
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a bookmark spanning the entire paragraph content.
|
||||
///
|
||||
/// Structure:
|
||||
/// <w:bookmarkStart w:id="1" w:name="my_bookmark"/>
|
||||
/// ... paragraph content ...
|
||||
/// <w:bookmarkEnd w:id="1"/>
|
||||
///
|
||||
/// The id must be unique across all bookmarks in the document.
|
||||
/// The name is used to reference the bookmark in REF fields and hyperlinks.
|
||||
/// Bookmark names are case-insensitive and cannot contain spaces.
|
||||
/// </summary>
|
||||
public static void AddBookmark(Paragraph para, string bookmarkName, int bookmarkId)
|
||||
{
|
||||
string idStr = bookmarkId.ToString();
|
||||
|
||||
// Insert BookmarkStart at the beginning of the paragraph
|
||||
para.InsertAt(new BookmarkStart { Id = idStr, Name = bookmarkName }, 0);
|
||||
|
||||
// Append BookmarkEnd at the end of the paragraph
|
||||
para.Append(new BookmarkEnd { Id = idStr });
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 10. AddInternalHyperlink — Hyperlink with Anchor
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a hyperlink that jumps to a bookmark within the same document.
|
||||
///
|
||||
/// Uses the Anchor property (NOT a relationship) to reference the bookmark name.
|
||||
/// The run inside the Hyperlink should have "Hyperlink" character style for blue underline.
|
||||
///
|
||||
/// Structure:
|
||||
/// <w:hyperlink w:anchor="bookmarkName">
|
||||
/// <w:r><w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr><w:t>Click here</w:t></w:r>
|
||||
/// </w:hyperlink>
|
||||
/// </summary>
|
||||
public static Hyperlink AddInternalHyperlink(Paragraph para, string bookmarkName)
|
||||
{
|
||||
var hyperlink = new Hyperlink { Anchor = bookmarkName };
|
||||
|
||||
hyperlink.Append(new Run(
|
||||
new RunProperties(
|
||||
new RunStyle { Val = "Hyperlink" },
|
||||
new Color { Val = "0563C1", ThemeColor = ThemeColorValues.Hyperlink }),
|
||||
new Text(bookmarkName) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
para.Append(hyperlink);
|
||||
return hyperlink;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 11. AddExternalHyperlink — Hyperlink with relationship
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Adds a hyperlink to an external URL.
|
||||
///
|
||||
/// Unlike internal hyperlinks, external ones require a HyperlinkRelationship
|
||||
/// in the part's .rels file. The Hyperlink element references the relationship Id.
|
||||
///
|
||||
/// Steps:
|
||||
/// 1. Create a HyperlinkRelationship with the URL (isExternal: true)
|
||||
/// 2. Create a Hyperlink element with Id = relationship Id
|
||||
/// 3. Style the run with "Hyperlink" character style
|
||||
/// </summary>
|
||||
public static Hyperlink AddExternalHyperlink(MainDocumentPart mainPart, Paragraph para, string url, string displayText)
|
||||
{
|
||||
// Step 1: Create the relationship (external = true)
|
||||
var relationship = mainPart.AddHyperlinkRelationship(new Uri(url, UriKind.Absolute), isExternal: true);
|
||||
|
||||
// Step 2: Create the Hyperlink element referencing the relationship
|
||||
var hyperlink = new Hyperlink { Id = relationship.Id };
|
||||
|
||||
// Step 3: Styled run inside the hyperlink
|
||||
hyperlink.Append(new Run(
|
||||
new RunProperties(
|
||||
new RunStyle { Val = "Hyperlink" },
|
||||
new Color { Val = "0563C1", ThemeColor = ThemeColorValues.Hyperlink },
|
||||
new Underline { Val = UnderlineValues.Single }),
|
||||
new Text(displayText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
para.Append(hyperlink);
|
||||
return hyperlink;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// Private helpers
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
private static EndnotesPart SetupEndnotesPart(MainDocumentPart mainPart)
|
||||
{
|
||||
var endnotesPart = mainPart.EndnotesPart
|
||||
?? mainPart.AddNewPart<EndnotesPart>();
|
||||
|
||||
endnotesPart.Endnotes = new Endnotes();
|
||||
|
||||
var separator = new Endnote { Type = FootnoteEndnoteValues.Separator, Id = -1 };
|
||||
separator.Append(new Paragraph(
|
||||
new ParagraphProperties(new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }),
|
||||
new Run(new SeparatorMark())));
|
||||
endnotesPart.Endnotes.Append(separator);
|
||||
|
||||
var contSeparator = new Endnote { Type = FootnoteEndnoteValues.ContinuationSeparator, Id = 0 };
|
||||
contSeparator.Append(new Paragraph(
|
||||
new ParagraphProperties(new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }),
|
||||
new Run(new ContinuationSeparatorMark())));
|
||||
endnotesPart.Endnotes.Append(contSeparator);
|
||||
|
||||
endnotesPart.Endnotes.Save();
|
||||
return endnotesPart;
|
||||
}
|
||||
|
||||
private static int GetNextFootnoteId(FootnotesPart footnotesPart)
|
||||
{
|
||||
int maxId = 0;
|
||||
if (footnotesPart.Footnotes != null)
|
||||
{
|
||||
foreach (var fn in footnotesPart.Footnotes.Elements<Footnote>())
|
||||
{
|
||||
if (fn.Id?.Value != null && fn.Id.Value > maxId)
|
||||
maxId = (int)fn.Id.Value;
|
||||
}
|
||||
}
|
||||
return maxId + 1;
|
||||
}
|
||||
|
||||
private static int GetNextEndnoteId(EndnotesPart endnotesPart)
|
||||
{
|
||||
int maxId = 0;
|
||||
if (endnotesPart.Endnotes != null)
|
||||
{
|
||||
foreach (var en in endnotesPart.Endnotes.Elements<Endnote>())
|
||||
{
|
||||
if (en.Id?.Value != null && en.Id.Value > maxId)
|
||||
maxId = (int)en.Id.Value;
|
||||
}
|
||||
}
|
||||
return maxId + 1;
|
||||
}
|
||||
|
||||
private static int GetNextCommentId(WordprocessingCommentsPart commentsPart)
|
||||
{
|
||||
int maxId = 0;
|
||||
if (commentsPart.Comments != null)
|
||||
{
|
||||
foreach (var c in commentsPart.Comments.Elements<Comment>())
|
||||
{
|
||||
if (c.Id?.Value != null && int.TryParse(c.Id.Value, out int id) && id > maxId)
|
||||
maxId = id;
|
||||
}
|
||||
}
|
||||
return maxId + 1;
|
||||
}
|
||||
|
||||
private static string GetInitials(string author)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(author)) return "A";
|
||||
var parts = author.Split(' ', StringSplitOptions.RemoveEmptyEntries);
|
||||
return string.Concat(parts.Select(p => p[..1].ToUpperInvariant()));
|
||||
}
|
||||
|
||||
private static string GenerateParaId()
|
||||
{
|
||||
// paraId is an 8-character hex string (32-bit unsigned integer)
|
||||
return Random.Shared.Next(0x10000000, int.MaxValue).ToString("X8");
|
||||
}
|
||||
|
||||
private static void EnsurePersonEntry(MainDocumentPart mainPart, string author)
|
||||
{
|
||||
var peoplePart = mainPart.WordprocessingPeoplePart;
|
||||
if (peoplePart?.People == null) return;
|
||||
|
||||
// Check if this author already has an entry
|
||||
bool exists = peoplePart.People.Elements<W15Person>()
|
||||
.Any(p => p.Author?.Value == author);
|
||||
|
||||
if (!exists)
|
||||
{
|
||||
var person = new W15Person { Author = author };
|
||||
// PresenceInfo — the provider/userId for the author's identity
|
||||
person.Append(new W15PresenceInfo
|
||||
{
|
||||
ProviderId = "None",
|
||||
UserId = author
|
||||
});
|
||||
peoplePart.People.Append(person);
|
||||
peoplePart.People.Save();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,838 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
using A = DocumentFormat.OpenXml.Drawing;
|
||||
using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
|
||||
using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Comprehensive reference for OpenXML headers, footers, and page numbers.
|
||||
///
|
||||
/// Architecture:
|
||||
/// - Headers/footers live in separate HeaderPart/FooterPart containers.
|
||||
/// - They are linked to sections via HeaderReference/FooterReference in SectionProperties.
|
||||
/// - Each reference has a Type: Default, First, Even.
|
||||
/// - The relationship ID (r:id) connects the reference to the part.
|
||||
///
|
||||
/// XML structure in SectionProperties:
|
||||
/// <w:sectPr>
|
||||
/// <w:headerReference w:type="default" r:id="rId7"/>
|
||||
/// <w:footerReference w:type="default" r:id="rId8"/>
|
||||
/// <w:headerReference w:type="first" r:id="rId9"/>
|
||||
/// <w:titlePg/> <!-- needed to activate first-page header/footer -->
|
||||
/// </w:sectPr>
|
||||
///
|
||||
/// Header/Footer XML (in separate part):
|
||||
/// <w:hdr> (or <w:ftr>)
|
||||
/// <w:p>
|
||||
/// <w:pPr>...</w:pPr>
|
||||
/// <w:r><w:t>Header text</w:t></w:r>
|
||||
/// </w:p>
|
||||
/// </w:hdr>
|
||||
///
|
||||
/// Page number fields use complex field codes:
|
||||
/// PAGE — current page number
|
||||
/// NUMPAGES — total page count
|
||||
/// </summary>
|
||||
public static class HeaderFooterSamples
|
||||
{
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 1. AddSimpleHeader — basic text header
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a simple text header to the default header slot.
|
||||
///
|
||||
/// Steps:
|
||||
/// 1. Create a HeaderPart on the MainDocumentPart
|
||||
/// 2. Set its Header content (must contain at least one Paragraph)
|
||||
/// 3. Get the relationship ID
|
||||
/// 4. Add HeaderReference to SectionProperties with type="default"
|
||||
///
|
||||
/// XML in header part:
|
||||
/// <w:hdr>
|
||||
/// <w:p>
|
||||
/// <w:pPr><w:jc w:val="right"/></w:pPr>
|
||||
/// <w:r>
|
||||
/// <w:rPr><w:color w:val="808080"/><w:sz w:val="18"/></w:rPr>
|
||||
/// <w:t>My Document Header</w:t>
|
||||
/// </w:r>
|
||||
/// </w:p>
|
||||
/// </w:hdr>
|
||||
///
|
||||
/// XML in sectPr:
|
||||
/// <w:headerReference w:type="default" r:id="rIdXX"/>
|
||||
/// </summary>
|
||||
public static void AddSimpleHeader(MainDocumentPart mainPart, SectionProperties sectPr, string text)
|
||||
{
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
|
||||
headerPart.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Right }),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Color { Val = "808080" },
|
||||
new FontSize { Val = "18" }), // 9pt (half-points)
|
||||
new Text(text) { Space = SpaceProcessingModeValues.Preserve })));
|
||||
headerPart.Header.Save();
|
||||
|
||||
var headerRefId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 2. AddSimpleFooter — basic text footer
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a simple text footer to the default footer slot.
|
||||
///
|
||||
/// XML in footer part:
|
||||
/// <w:ftr>
|
||||
/// <w:p>
|
||||
/// <w:pPr><w:jc w:val="center"/></w:pPr>
|
||||
/// <w:r><w:t>Confidential</w:t></w:r>
|
||||
/// </w:p>
|
||||
/// </w:ftr>
|
||||
///
|
||||
/// XML in sectPr:
|
||||
/// <w:footerReference w:type="default" r:id="rIdXX"/>
|
||||
/// </summary>
|
||||
public static void AddSimpleFooter(MainDocumentPart mainPart, SectionProperties sectPr, string text)
|
||||
{
|
||||
var footerPart = mainPart.AddNewPart<FooterPart>();
|
||||
|
||||
footerPart.Footer = new Footer(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Color { Val = "808080" },
|
||||
new FontSize { Val = "18" }),
|
||||
new Text(text) { Space = SpaceProcessingModeValues.Preserve })));
|
||||
footerPart.Footer.Save();
|
||||
|
||||
var footerRefId = mainPart.GetIdOfPart(footerPart);
|
||||
sectPr.Append(new FooterReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = footerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 3. AddPageNumberFooter — centered page number
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a centered page number footer using the PAGE field code.
|
||||
///
|
||||
/// Field code pattern (3 runs):
|
||||
/// Run 1: FieldChar Begin
|
||||
/// Run 2: FieldCode " PAGE "
|
||||
/// Run 3: FieldChar End
|
||||
///
|
||||
/// XML:
|
||||
/// <w:ftr>
|
||||
/// <w:p>
|
||||
/// <w:pPr><w:jc w:val="center"/></w:pPr>
|
||||
/// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
|
||||
/// <w:r><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
|
||||
/// <w:r><w:fldChar w:fldCharType="end"/></w:r>
|
||||
/// </w:p>
|
||||
/// </w:ftr>
|
||||
///
|
||||
/// GOTCHA: FieldCode text MUST have leading/trailing spaces: " PAGE ", not "PAGE".
|
||||
/// GOTCHA: Use Space = SpaceProcessingModeValues.Preserve on FieldCode to keep spaces.
|
||||
/// </summary>
|
||||
public static void AddPageNumberFooter(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
var footerPart = mainPart.AddNewPart<FooterPart>();
|
||||
|
||||
var paragraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }));
|
||||
|
||||
// PAGE field: Begin → InstrText → End
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
paragraph.Append(new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
footerPart.Footer = new Footer(paragraph);
|
||||
footerPart.Footer.Save();
|
||||
|
||||
var footerRefId = mainPart.GetIdOfPart(footerPart);
|
||||
sectPr.Append(new FooterReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = footerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 4. AddPageXofYFooter — "Page X of Y"
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a footer with "Page X of Y" format using PAGE and NUMPAGES field codes.
|
||||
///
|
||||
/// XML:
|
||||
/// <w:ftr>
|
||||
/// <w:p>
|
||||
/// <w:pPr><w:jc w:val="center"/></w:pPr>
|
||||
/// <w:r><w:t xml:space="preserve">Page </w:t></w:r>
|
||||
/// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
|
||||
/// <w:r><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
|
||||
/// <w:r><w:fldChar w:fldCharType="end"/></w:r>
|
||||
/// <w:r><w:t xml:space="preserve"> of </w:t></w:r>
|
||||
/// <w:r><w:fldChar w:fldCharType="begin"/></w:r>
|
||||
/// <w:r><w:instrText xml:space="preserve"> NUMPAGES </w:instrText></w:r>
|
||||
/// <w:r><w:fldChar w:fldCharType="end"/></w:r>
|
||||
/// </w:p>
|
||||
/// </w:ftr>
|
||||
/// </summary>
|
||||
public static void AddPageXofYFooter(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
var footerPart = mainPart.AddNewPart<FooterPart>();
|
||||
|
||||
var paragraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }));
|
||||
|
||||
// "Page "
|
||||
paragraph.Append(new Run(new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// PAGE field
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
paragraph.Append(new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
// " of "
|
||||
paragraph.Append(new Run(new Text(" of ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// NUMPAGES field
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
paragraph.Append(new Run(new FieldCode(" NUMPAGES ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
paragraph.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
footerPart.Footer = new Footer(paragraph);
|
||||
footerPart.Footer.Save();
|
||||
|
||||
var footerRefId = mainPart.GetIdOfPart(footerPart);
|
||||
sectPr.Append(new FooterReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = footerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 5. AddDifferentFirstPageHeader — TitlePage element
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a different header for the first page vs. subsequent pages.
|
||||
///
|
||||
/// Requires:
|
||||
/// 1. <w:titlePg/> in SectionProperties to enable first-page header/footer
|
||||
/// 2. HeaderReference with Type="first" for the first page header
|
||||
/// 3. HeaderReference with Type="default" for subsequent pages
|
||||
///
|
||||
/// XML in sectPr:
|
||||
/// <w:sectPr>
|
||||
/// <w:headerReference w:type="first" r:id="rIdFirst"/>
|
||||
/// <w:headerReference w:type="default" r:id="rIdDefault"/>
|
||||
/// <w:titlePg/> <!-- CRITICAL: without this, first-page header is ignored -->
|
||||
/// </w:sectPr>
|
||||
///
|
||||
/// GOTCHA: Without <w:titlePg/>, the "first" type header is completely ignored.
|
||||
/// GOTCHA: If you want a blank first-page header, you still need a HeaderPart
|
||||
/// with an empty Paragraph — just don't add text to it.
|
||||
/// </summary>
|
||||
public static void AddDifferentFirstPageHeader(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
// First page header: e.g., cover page with large title
|
||||
var firstHeaderPart = mainPart.AddNewPart<HeaderPart>();
|
||||
firstHeaderPart.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Bold(),
|
||||
new FontSize { Val = "32" }), // 16pt
|
||||
new Text("COMPANY CONFIDENTIAL"))));
|
||||
firstHeaderPart.Header.Save();
|
||||
|
||||
// Default header for subsequent pages
|
||||
var defaultHeaderPart = mainPart.AddNewPart<HeaderPart>();
|
||||
defaultHeaderPart.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Right }),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new FontSize { Val = "18" }), // 9pt
|
||||
new Text("Internal Document"))));
|
||||
defaultHeaderPart.Header.Save();
|
||||
|
||||
// Link both headers to section
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.First,
|
||||
Id = mainPart.GetIdOfPart(firstHeaderPart)
|
||||
});
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = mainPart.GetIdOfPart(defaultHeaderPart)
|
||||
});
|
||||
|
||||
// CRITICAL: Enable first page header/footer
|
||||
sectPr.Append(new TitlePage());
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 6. AddEvenOddHeaders — EvenAndOddHeaders in Settings
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Creates different headers for even and odd pages (e.g., for book-style printing).
|
||||
///
|
||||
/// Requires:
|
||||
/// 1. <w:evenAndOddHeaders/> in document Settings (DocumentSettingsPart)
|
||||
/// 2. HeaderReference with Type="default" for odd pages
|
||||
/// 3. HeaderReference with Type="even" for even pages
|
||||
///
|
||||
/// XML in settings.xml:
|
||||
/// <w:settings>
|
||||
/// <w:evenAndOddHeaders/>
|
||||
/// </w:settings>
|
||||
///
|
||||
/// XML in sectPr:
|
||||
/// <w:sectPr>
|
||||
/// <w:headerReference w:type="default" r:id="rIdOdd"/>
|
||||
/// <w:headerReference w:type="even" r:id="rIdEven"/>
|
||||
/// </w:sectPr>
|
||||
///
|
||||
/// GOTCHA: "default" means ODD pages when evenAndOddHeaders is enabled.
|
||||
/// GOTCHA: Without the Settings flag, the "even" header is ignored entirely.
|
||||
/// </summary>
|
||||
public static void AddEvenOddHeaders(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
// Enable even/odd header distinction in document settings
|
||||
var settingsPart = mainPart.DocumentSettingsPart
|
||||
?? mainPart.AddNewPart<DocumentSettingsPart>();
|
||||
if (settingsPart.Settings == null)
|
||||
settingsPart.Settings = new Settings();
|
||||
|
||||
// Add EvenAndOddHeaders if not already present
|
||||
if (settingsPart.Settings.GetFirstChild<EvenAndOddHeaders>() == null)
|
||||
{
|
||||
settingsPart.Settings.Append(new EvenAndOddHeaders());
|
||||
}
|
||||
settingsPart.Settings.Save();
|
||||
|
||||
// Odd page header (Type="default" means odd when even/odd is enabled)
|
||||
var oddHeaderPart = mainPart.AddNewPart<HeaderPart>();
|
||||
oddHeaderPart.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Right }),
|
||||
new Run(new Text("Chapter Title — Odd Page"))));
|
||||
oddHeaderPart.Header.Save();
|
||||
|
||||
// Even page header
|
||||
var evenHeaderPart = mainPart.AddNewPart<HeaderPart>();
|
||||
evenHeaderPart.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left }),
|
||||
new Run(new Text("Book Title — Even Page"))));
|
||||
evenHeaderPart.Header.Save();
|
||||
|
||||
// Link to section
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default, // = odd pages
|
||||
Id = mainPart.GetIdOfPart(oddHeaderPart)
|
||||
});
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Even,
|
||||
Id = mainPart.GetIdOfPart(evenHeaderPart)
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 7. AddHeaderWithLogo — image in header
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a header containing an image (logo).
|
||||
///
|
||||
/// Steps:
|
||||
/// 1. Create HeaderPart
|
||||
/// 2. Add ImagePart to the HeaderPart (NOT to MainDocumentPart)
|
||||
/// 3. Feed the image stream
|
||||
/// 4. Build Drawing element with inline image
|
||||
/// 5. Link HeaderPart to sectPr
|
||||
///
|
||||
/// Image sizing uses EMU (English Metric Units):
|
||||
/// 914400 EMU = 1 inch
|
||||
/// 360000 EMU = 1 cm
|
||||
///
|
||||
/// XML for inline image:
|
||||
/// <w:drawing>
|
||||
/// <wp:inline distT="0" distB="0" distL="0" distR="0">
|
||||
/// <wp:extent cx="914400" cy="457200"/>
|
||||
/// <wp:docPr id="1" name="Logo"/>
|
||||
/// <a:graphic>
|
||||
/// <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
|
||||
/// <pic:pic>
|
||||
/// <pic:nvPicPr>...</pic:nvPicPr>
|
||||
/// <pic:blipFill><a:blip r:embed="rIdImg"/></pic:blipFill>
|
||||
/// <pic:spPr>...</pic:spPr>
|
||||
/// </pic:pic>
|
||||
/// </a:graphicData>
|
||||
/// </a:graphic>
|
||||
/// </wp:inline>
|
||||
/// </w:drawing>
|
||||
///
|
||||
/// GOTCHA: The ImagePart must be added to the HeaderPart, not the MainDocumentPart.
|
||||
/// If you add it to MainDocumentPart, the relationship ID won't resolve in the header.
|
||||
/// </summary>
|
||||
public static void AddHeaderWithLogo(MainDocumentPart mainPart, SectionProperties sectPr, string imagePath)
|
||||
{
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
|
||||
// Add image part to the HEADER part (not main document part)
|
||||
var imagePart = headerPart.AddImagePart(ImagePartType.Png);
|
||||
using (var stream = new FileStream(imagePath, FileMode.Open, FileAccess.Read))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
var imageRelId = headerPart.GetIdOfPart(imagePart);
|
||||
|
||||
// Image dimensions in EMU: 1 inch wide x 0.5 inch tall
|
||||
long widthEmu = 914400; // 1 inch
|
||||
long heightEmu = 457200; // 0.5 inch
|
||||
|
||||
// Build the Drawing element with inline image
|
||||
var drawing = new Drawing(
|
||||
new DW.Inline(
|
||||
new DW.Extent { Cx = widthEmu, Cy = heightEmu },
|
||||
new DW.EffectExtent { LeftEdge = 0, TopEdge = 0, RightEdge = 0, BottomEdge = 0 },
|
||||
new DW.DocProperties { Id = 1U, Name = "Logo" },
|
||||
new A.Graphic(
|
||||
new A.GraphicData(
|
||||
new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties { Id = 0U, Name = "logo.png" },
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
new A.Blip { Embed = imageRelId },
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0, Y = 0 },
|
||||
new A.Extents { Cx = widthEmu, Cy = heightEmu }),
|
||||
new A.PresetGeometry(
|
||||
new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle }))
|
||||
) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" })
|
||||
)
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 0U,
|
||||
DistanceFromRight = 0U
|
||||
});
|
||||
|
||||
headerPart.Header = new Header(
|
||||
new Paragraph(new Run(drawing)));
|
||||
headerPart.Header.Save();
|
||||
|
||||
var headerRefId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 8. AddTableLayoutHeader — 3-column invisible table
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Creates a header with a 3-column invisible table for precise layout:
|
||||
/// Left cell: Logo placeholder text
|
||||
/// Center cell: Document title (centered)
|
||||
/// Right cell: Page number (right-aligned)
|
||||
///
|
||||
/// The table has no borders, so it's invisible but provides column alignment.
|
||||
///
|
||||
/// XML structure:
|
||||
/// <w:hdr>
|
||||
/// <w:tbl>
|
||||
/// <w:tblPr>
|
||||
/// <w:tblW w:w="5000" w:type="pct"/>
|
||||
/// <w:tblBorders>
|
||||
/// <w:top w:val="none"/> <w:left w:val="none"/> ...
|
||||
/// </w:tblBorders>
|
||||
/// </w:tblPr>
|
||||
/// <w:tblGrid>
|
||||
/// <w:gridCol w:w="3120"/> <w:gridCol w:w="3120"/> <w:gridCol w:w="3120"/>
|
||||
/// </w:tblGrid>
|
||||
/// <w:tr>
|
||||
/// <w:tc> <!-- left: logo text --> </w:tc>
|
||||
/// <w:tc> <!-- center: title --> </w:tc>
|
||||
/// <w:tc> <!-- right: page num --> </w:tc>
|
||||
/// </w:tr>
|
||||
/// </w:tbl>
|
||||
/// </w:hdr>
|
||||
/// </summary>
|
||||
public static void AddTableLayoutHeader(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
|
||||
// Invisible table (no borders)
|
||||
var table = new Table();
|
||||
var tblPr = new TableProperties(
|
||||
new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
|
||||
new TableBorders(
|
||||
new TopBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" },
|
||||
new LeftBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" },
|
||||
new BottomBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" },
|
||||
new RightBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" },
|
||||
new InsideHorizontalBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" },
|
||||
new InsideVerticalBorder { Val = BorderValues.None, Size = 0, Space = 0, Color = "auto" }
|
||||
),
|
||||
// Fixed layout so columns don't shift
|
||||
new TableLayout { Type = TableLayoutValues.Fixed });
|
||||
table.Append(tblPr);
|
||||
|
||||
var grid = new TableGrid(
|
||||
new GridColumn { Width = "3120" },
|
||||
new GridColumn { Width = "3120" },
|
||||
new GridColumn { Width = "3120" });
|
||||
table.Append(grid);
|
||||
|
||||
var row = new TableRow();
|
||||
|
||||
// Left cell: logo/company name
|
||||
var leftCell = new TableCell(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left }),
|
||||
new Run(
|
||||
new RunProperties(new Bold(), new FontSize { Val = "18" }),
|
||||
new Text("ACME Corp"))));
|
||||
row.Append(leftCell);
|
||||
|
||||
// Center cell: document title
|
||||
var centerCell = new TableCell(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }),
|
||||
new Run(
|
||||
new RunProperties(new FontSize { Val = "18" }),
|
||||
new Text("Technical Report"))));
|
||||
row.Append(centerCell);
|
||||
|
||||
// Right cell: page number
|
||||
var pageNumPara = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Right }));
|
||||
pageNumPara.Append(new Run(
|
||||
new RunProperties(new FontSize { Val = "18" }),
|
||||
new Text("Page ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
pageNumPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
pageNumPara.Append(new Run(new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
pageNumPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
var rightCell = new TableCell(pageNumPara);
|
||||
row.Append(rightCell);
|
||||
|
||||
table.Append(row);
|
||||
|
||||
headerPart.Header = new Header(table);
|
||||
headerPart.Header.Save();
|
||||
|
||||
var headerRefId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 9. AddChineseGongWenFooter — "-X-" format, SimSun 14pt
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a Chinese government document (公文) style footer:
|
||||
/// - Page number in "-X-" format (e.g., "- 1 -")
|
||||
/// - Centered at bottom
|
||||
/// - SimSun (宋体) font, 14pt (Chinese 四号)
|
||||
///
|
||||
/// XML:
|
||||
/// <w:ftr>
|
||||
/// <w:p>
|
||||
/// <w:pPr><w:jc w:val="center"/></w:pPr>
|
||||
/// <w:r>
|
||||
/// <w:rPr>
|
||||
/// <w:rFonts w:ascii="SimSun" w:eastAsia="SimSun"/>
|
||||
/// <w:sz w:val="28"/>
|
||||
/// </w:rPr>
|
||||
/// <w:t xml:space="preserve">- </w:t>
|
||||
/// </w:r>
|
||||
/// <w:r>..PAGE field..</w:r>
|
||||
/// <w:r>
|
||||
/// <w:rPr>...</w:rPr>
|
||||
/// <w:t xml:space="preserve"> -</w:t>
|
||||
/// </w:r>
|
||||
/// </w:p>
|
||||
/// </w:ftr>
|
||||
///
|
||||
/// Chinese font size reference:
|
||||
/// 四号 = 14pt = sz val="28" (half-points)
|
||||
/// 小四 = 12pt = sz val="24"
|
||||
/// 五号 = 10.5pt = sz val="21"
|
||||
/// </summary>
|
||||
public static void AddChineseGongWenFooter(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
var footerPart = mainPart.AddNewPart<FooterPart>();
|
||||
|
||||
// Common run properties for the footer: SimSun 14pt (四号)
|
||||
// 14pt = 28 half-points
|
||||
RunProperties MakeGongWenRunProps() => new RunProperties(
|
||||
new RunFonts { Ascii = "SimSun", EastAsia = "SimSun", HighAnsi = "SimSun" },
|
||||
new FontSize { Val = "28" },
|
||||
new FontSizeComplexScript { Val = "28" });
|
||||
|
||||
var paragraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }));
|
||||
|
||||
// "- " prefix
|
||||
paragraph.Append(new Run(
|
||||
MakeGongWenRunProps(),
|
||||
new Text("- ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
// PAGE field with same formatting
|
||||
paragraph.Append(new Run(
|
||||
MakeGongWenRunProps(),
|
||||
new FieldChar { FieldCharType = FieldCharValues.Begin }));
|
||||
paragraph.Append(new Run(
|
||||
MakeGongWenRunProps(),
|
||||
new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
paragraph.Append(new Run(
|
||||
MakeGongWenRunProps(),
|
||||
new FieldChar { FieldCharType = FieldCharValues.End }));
|
||||
|
||||
// " -" suffix
|
||||
paragraph.Append(new Run(
|
||||
MakeGongWenRunProps(),
|
||||
new Text(" -") { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
footerPart.Footer = new Footer(paragraph);
|
||||
footerPart.Footer.Save();
|
||||
|
||||
var footerRefId = mainPart.GetIdOfPart(footerPart);
|
||||
sectPr.Append(new FooterReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = footerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 10. AddHeaderWithHorizontalLine — bottom border line
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Adds a header with a horizontal line (bottom border) beneath the text.
|
||||
/// This is a common style: header text with a line separating it from content.
|
||||
///
|
||||
/// The line is achieved via a paragraph bottom border in the header, NOT a
|
||||
/// separate drawing element.
|
||||
///
|
||||
/// XML:
|
||||
/// <w:hdr>
|
||||
/// <w:p>
|
||||
/// <w:pPr>
|
||||
/// <w:pBdr>
|
||||
/// <w:bottom w:val="single" w:sz="6" w:space="1" w:color="000000"/>
|
||||
/// </w:pBdr>
|
||||
/// <w:jc w:val="center"/>
|
||||
/// </w:pPr>
|
||||
/// <w:r><w:t>Document Header</w:t></w:r>
|
||||
/// </w:p>
|
||||
/// </w:hdr>
|
||||
///
|
||||
/// Border space attribute: space between text and border line, in points.
|
||||
/// Border size: in eighth-points (6 = 0.75pt).
|
||||
/// </summary>
|
||||
public static void AddHeaderWithHorizontalLine(MainDocumentPart mainPart, SectionProperties sectPr)
|
||||
{
|
||||
var headerPart = mainPart.AddNewPart<HeaderPart>();
|
||||
|
||||
var paragraph = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new ParagraphBorders(
|
||||
new BottomBorder
|
||||
{
|
||||
Val = BorderValues.Single,
|
||||
Size = 6, // 0.75pt line (in eighth-points)
|
||||
Space = 1, // 1pt spacing between text and line
|
||||
Color = "000000"
|
||||
}),
|
||||
new Justification { Val = JustificationValues.Center }),
|
||||
new Run(
|
||||
new RunProperties(
|
||||
new Bold(),
|
||||
new FontSize { Val = "20" }), // 10pt
|
||||
new Text("Document Header")));
|
||||
|
||||
headerPart.Header = new Header(paragraph);
|
||||
headerPart.Header.Save();
|
||||
|
||||
var headerRefId = mainPart.GetIdOfPart(headerPart);
|
||||
sectPr.Append(new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = headerRefId
|
||||
});
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
// 11. ChangeHeaderPerSection — different headers per section
|
||||
// ──────────────────────────────────────────────────────────────
|
||||
/// <summary>
|
||||
/// Creates a document with multiple sections, each having its own header.
|
||||
///
|
||||
/// In OOXML, sections are delimited by SectionProperties:
|
||||
/// - Inner sections: sectPr inside a Paragraph's ParagraphProperties (section break)
|
||||
/// - Last section: sectPr as direct child of Body
|
||||
///
|
||||
/// Each sectPr can reference different HeaderPart/FooterPart via its own
|
||||
/// HeaderReference/FooterReference elements.
|
||||
///
|
||||
/// XML structure for multi-section document:
|
||||
/// <w:body>
|
||||
/// <!-- Section 1 content -->
|
||||
/// <w:p><w:r><w:t>Section 1 content</w:t></w:r></w:p>
|
||||
/// <w:p>
|
||||
/// <w:pPr>
|
||||
/// <w:sectPr> <!-- Section 1 break -->
|
||||
/// <w:headerReference w:type="default" r:id="rId_hdr1"/>
|
||||
/// <w:type w:val="nextPage"/>
|
||||
/// </w:sectPr>
|
||||
/// </w:pPr>
|
||||
/// </w:p>
|
||||
///
|
||||
/// <!-- Section 2 content -->
|
||||
/// <w:p><w:r><w:t>Section 2 content</w:t></w:r></w:p>
|
||||
///
|
||||
/// <!-- Final section properties (last child of body) -->
|
||||
/// <w:sectPr>
|
||||
/// <w:headerReference w:type="default" r:id="rId_hdr2"/>
|
||||
/// </w:sectPr>
|
||||
/// </w:body>
|
||||
///
|
||||
/// GOTCHA: A section break sectPr is placed inside a paragraph's ParagraphProperties.
|
||||
/// The paragraph that contains the sectPr is the LAST paragraph of that section.
|
||||
///
|
||||
/// GOTCHA: If a section does not have its own HeaderReference, it inherits
|
||||
/// the header from the previous section. To have NO header in a section,
|
||||
/// you must explicitly link to an empty HeaderPart.
|
||||
/// </summary>
|
||||
public static void ChangeHeaderPerSection(MainDocumentPart mainPart, Body body)
|
||||
{
|
||||
// --- Create two different header parts ---
|
||||
|
||||
// Header for Section 1
|
||||
var header1Part = mainPart.AddNewPart<HeaderPart>();
|
||||
header1Part.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left }),
|
||||
new Run(new Text("Section 1 — Introduction"))));
|
||||
header1Part.Header.Save();
|
||||
|
||||
// Header for Section 2
|
||||
var header2Part = mainPart.AddNewPart<HeaderPart>();
|
||||
header2Part.Header = new Header(
|
||||
new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Left }),
|
||||
new Run(new Text("Section 2 — Analysis"))));
|
||||
header2Part.Header.Save();
|
||||
|
||||
// --- Section 1 content ---
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("This is content in Section 1."))));
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("More Section 1 content..."))));
|
||||
|
||||
// --- Section 1 break: sectPr inside a paragraph's pPr ---
|
||||
// This paragraph is the LAST paragraph of Section 1.
|
||||
var sect1Pr = new SectionProperties(
|
||||
new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = mainPart.GetIdOfPart(header1Part)
|
||||
},
|
||||
// Section break type: start next section on a new page
|
||||
new SectionType { Val = SectionMarkValues.NextPage });
|
||||
|
||||
// Page size and margins for section 1 (required for valid sectPr)
|
||||
sect1Pr.Append(new DocumentFormat.OpenXml.Wordprocessing.PageSize
|
||||
{
|
||||
Width = (UInt32Value)12240U, // Letter width: 8.5" = 12240 DXA
|
||||
Height = (UInt32Value)15840U // Letter height: 11" = 15840 DXA
|
||||
});
|
||||
sect1Pr.Append(new PageMargin
|
||||
{
|
||||
Top = 1440,
|
||||
Bottom = 1440,
|
||||
Left = (UInt32Value)1440U,
|
||||
Right = (UInt32Value)1440U
|
||||
});
|
||||
|
||||
// Wrap the sectPr in a paragraph's ParagraphProperties
|
||||
var sectionBreakPara = new Paragraph(
|
||||
new ParagraphProperties(sect1Pr));
|
||||
body.Append(sectionBreakPara);
|
||||
|
||||
// --- Section 2 content ---
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("This is content in Section 2."))));
|
||||
body.Append(new Paragraph(
|
||||
new Run(new Text("More Section 2 content..."))));
|
||||
|
||||
// --- Final section: sectPr as last child of Body ---
|
||||
// This is the sectPr for the LAST section of the document.
|
||||
var finalSectPr = new SectionProperties(
|
||||
new HeaderReference
|
||||
{
|
||||
Type = HeaderFooterValues.Default,
|
||||
Id = mainPart.GetIdOfPart(header2Part)
|
||||
});
|
||||
finalSectPr.Append(new DocumentFormat.OpenXml.Wordprocessing.PageSize
|
||||
{
|
||||
Width = (UInt32Value)12240U,
|
||||
Height = (UInt32Value)15840U
|
||||
});
|
||||
finalSectPr.Append(new PageMargin
|
||||
{
|
||||
Top = 1440,
|
||||
Bottom = 1440,
|
||||
Left = (UInt32Value)1440U,
|
||||
Right = (UInt32Value)1440U
|
||||
});
|
||||
body.Append(finalSectPr);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,917 @@
|
||||
// ============================================================================
|
||||
// ImageSamples.cs — Comprehensive OpenXML image handling reference
|
||||
// ============================================================================
|
||||
// EMU (English Metric Unit) is the universal measurement in DrawingML:
|
||||
// 1 inch = 914400 EMU
|
||||
// 1 cm = 360000 EMU
|
||||
// 1 px@96dpi = 9525 EMU (914400 / 96 = 9525)
|
||||
//
|
||||
// Image architecture in OpenXML:
|
||||
// Paragraph → Run → Drawing → DW.Inline (or DW.Anchor)
|
||||
// → A.Graphic → A.GraphicData → PIC.Picture
|
||||
// → PIC.BlipFill → A.Blip (references the image part via r:embed)
|
||||
// → PIC.ShapeProperties → A.Transform2D → A.Extents (cx, cy)
|
||||
//
|
||||
// CRITICAL RULES:
|
||||
// 1. Extent.Cx/Cy on DW.Inline/DW.Anchor MUST match A.Extents.Cx/Cy
|
||||
// on PIC.ShapeProperties. Mismatch causes rendering issues.
|
||||
// 2. Each Drawing element needs a unique DocProperties.Id within the document.
|
||||
// 3. ImagePart must be added to the PART that references it:
|
||||
// - MainDocumentPart for images in body
|
||||
// - HeaderPart for images in headers
|
||||
// - FooterPart for images in footers
|
||||
// 4. Blip.Embed contains the relationship ID (rId) linking to the ImagePart.
|
||||
// ============================================================================
|
||||
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
using A = DocumentFormat.OpenXml.Drawing;
|
||||
using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
|
||||
using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Reference implementations for every common image operation in OpenXML.
|
||||
/// All methods produce valid, Word-renderable markup.
|
||||
/// </summary>
|
||||
public static class ImageSamples
|
||||
{
|
||||
// ── Constants ──────────────────────────────────────────────────────
|
||||
private const long EmuPerInch = 914400L;
|
||||
private const long EmuPerCm = 360000L;
|
||||
private const long EmuPerPixel96Dpi = 9525L; // 914400 / 96
|
||||
|
||||
// GraphicData URI that tells Word "this is a picture"
|
||||
private const string PicGraphicDataUri = "http://schemas.openxmlformats.org/drawingml/2006/picture";
|
||||
|
||||
// ── 1. Inline Image (most common) ──────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an inline image into the body. Inline images flow with text
|
||||
/// and do not float. This is the most common image insertion pattern.
|
||||
/// </summary>
|
||||
/// <param name="mainPart">The MainDocumentPart to add the image relationship to.</param>
|
||||
/// <param name="body">The Body element to append the paragraph to.</param>
|
||||
/// <param name="imagePath">Filesystem path to the image file (png, jpg, etc.).</param>
|
||||
/// <param name="widthPx">Desired display width in pixels (at 96 dpi).</param>
|
||||
/// <param name="heightPx">Desired display height in pixels (at 96 dpi).</param>
|
||||
public static void InsertInlineImage(
|
||||
MainDocumentPart mainPart, Body body,
|
||||
string imagePath, int widthPx, int heightPx)
|
||||
{
|
||||
// Step 1: Add the image file as a part. The ImagePartType must match
|
||||
// the actual file format. AddImagePart returns the ImagePart; we then
|
||||
// feed data into it.
|
||||
var imageType = GetImagePartType(imagePath);
|
||||
ImagePart imagePart = mainPart.AddImagePart(imageType);
|
||||
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
|
||||
// Step 2: Get the relationship ID that links the Blip to this ImagePart.
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
// Step 3: Convert pixel dimensions to EMU.
|
||||
// Formula: pixels * 9525 = EMU (at 96 dpi, which is Word's assumption)
|
||||
long cx = widthPx * EmuPerPixel96Dpi;
|
||||
long cy = heightPx * EmuPerPixel96Dpi;
|
||||
|
||||
// Step 4: Build the Drawing element using the reusable helper.
|
||||
// docPropId must be unique across the entire document.
|
||||
Drawing drawing = BuildDrawingElement(
|
||||
relId, cx, cy,
|
||||
docPropId: 1U,
|
||||
name: "Image1",
|
||||
description: null);
|
||||
|
||||
// Step 5: Wrap in Paragraph → Run → Drawing
|
||||
Paragraph para = new Paragraph(
|
||||
new Run(drawing));
|
||||
|
||||
body.AppendChild(para);
|
||||
}
|
||||
|
||||
// ── 2. Floating Image (Anchor) ─────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts a floating image with absolute positioning using DW.Anchor.
|
||||
/// Floating images are positioned relative to a reference point (page,
|
||||
/// column, paragraph, etc.) and text wraps around them.
|
||||
/// </summary>
|
||||
public static void InsertFloatingImage(
|
||||
MainDocumentPart mainPart, Body body, string imagePath)
|
||||
{
|
||||
ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
long cx = (long)(3.0 * EmuPerInch); // 3 inches wide
|
||||
long cy = (long)(2.0 * EmuPerInch); // 2 inches tall
|
||||
|
||||
// DW.Anchor is used instead of DW.Inline for floating images.
|
||||
// Key differences from Inline:
|
||||
// - Has positioning (SimplePos, HorizontalPosition, VerticalPosition)
|
||||
// - Has wrapping mode (WrapSquare, WrapTight, WrapNone, etc.)
|
||||
// - Has BehindDoc and LayoutInCell flags
|
||||
DW.Anchor anchor = new DW.Anchor(
|
||||
// SimplePosition: when SimplePos=true, uses SimplePosition x/y directly.
|
||||
// Normally false; we use HorizontalPosition/VerticalPosition instead.
|
||||
new DW.SimplePosition { X = 0L, Y = 0L },
|
||||
|
||||
// HorizontalPosition: where the image sits horizontally.
|
||||
// RelativeFrom can be: Column, Page, Margin, Character, LeftMargin, etc.
|
||||
new DW.HorizontalPosition(
|
||||
new DW.PositionOffset("914400") // 1 inch from reference
|
||||
)
|
||||
{ RelativeFrom = DW.HorizontalRelativePositionValues.Column },
|
||||
|
||||
// VerticalPosition: where the image sits vertically.
|
||||
new DW.VerticalPosition(
|
||||
new DW.PositionOffset("457200") // 0.5 inch from reference
|
||||
)
|
||||
{ RelativeFrom = DW.VerticalRelativePositionValues.Paragraph },
|
||||
|
||||
// Extent: overall size of the drawing object
|
||||
new DW.Extent { Cx = cx, Cy = cy },
|
||||
|
||||
// EffectExtent: extra space for shadows, glow, etc. (0 if none)
|
||||
new DW.EffectExtent
|
||||
{
|
||||
LeftEdge = 0L,
|
||||
TopEdge = 0L,
|
||||
RightEdge = 0L,
|
||||
BottomEdge = 0L
|
||||
},
|
||||
|
||||
// WrapSquare: text wraps in a square around the image bounding box.
|
||||
new DW.WrapSquare { WrapText = DW.WrapTextValues.BothSides },
|
||||
|
||||
// DocProperties: unique ID + name for the drawing object
|
||||
new DW.DocProperties { Id = 2U, Name = "FloatingImage1" },
|
||||
|
||||
// Non-visual graphic frame properties (required but usually empty)
|
||||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||||
|
||||
// The actual graphic content
|
||||
new A.Graphic(
|
||||
new A.GraphicData(
|
||||
new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties
|
||||
{
|
||||
Id = 0U,
|
||||
Name = "FloatingImage1.png"
|
||||
},
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
new A.Blip { Embed = relId },
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0L, Y = 0L },
|
||||
// CRITICAL: These cx/cy MUST match the Extent above
|
||||
new A.Extents { Cx = cx, Cy = cy }),
|
||||
new A.PresetGeometry(
|
||||
new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle }))
|
||||
)
|
||||
{ Uri = PicGraphicDataUri })
|
||||
)
|
||||
{
|
||||
// Anchor attributes
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 114300U, // ~0.125 inch gap between text and image
|
||||
DistanceFromRight = 114300U,
|
||||
SimplePos = false,
|
||||
RelativeHeight = 251658240U, // z-order; higher = in front
|
||||
BehindDoc = false, // true = behind text (like a watermark)
|
||||
Locked = false,
|
||||
LayoutInCell = true,
|
||||
AllowOverlap = true
|
||||
};
|
||||
|
||||
Paragraph para = new Paragraph(new Run(new Drawing(anchor)));
|
||||
body.AppendChild(para);
|
||||
}
|
||||
|
||||
// ── 3. Image with Various Text Wrapping ────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Demonstrates the four main text wrapping modes for floating images.
|
||||
/// Each wrapping mode controls how body text flows around the image.
|
||||
/// </summary>
|
||||
public static void InsertImageWithTextWrapping(
|
||||
MainDocumentPart mainPart, Body body, string imagePath)
|
||||
{
|
||||
// All wrapping modes require DW.Anchor (not DW.Inline).
|
||||
// The wrapping element is a direct child of the Anchor element.
|
||||
|
||||
ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
long cx = (long)(2.5 * EmuPerInch);
|
||||
long cy = (long)(2.0 * EmuPerInch);
|
||||
|
||||
// ── WrapSquare ──
|
||||
// Text wraps in a rectangular bounding box around the image.
|
||||
// WrapText controls which sides text appears on.
|
||||
var wrapSquare = new DW.WrapSquare
|
||||
{
|
||||
WrapText = DW.WrapTextValues.BothSides
|
||||
// Other options: Left, Right, Largest
|
||||
};
|
||||
|
||||
// ── WrapTight ──
|
||||
// Text wraps tightly around the actual contour of the image.
|
||||
// Uses a WrapPolygon to define the outline; Word can auto-generate this.
|
||||
// The coordinates are in EMU relative to the image's top-left.
|
||||
var wrapTight = new DW.WrapTight(
|
||||
new DW.WrapPolygon(
|
||||
new DW.StartPoint { X = 0L, Y = 0L },
|
||||
new DW.LineTo { X = 0L, Y = 21600L },
|
||||
new DW.LineTo { X = 21600L, Y = 21600L },
|
||||
new DW.LineTo { X = 21600L, Y = 0L },
|
||||
new DW.LineTo { X = 0L, Y = 0L }
|
||||
)
|
||||
{ Edited = false }
|
||||
)
|
||||
{
|
||||
WrapText = DW.WrapTextValues.BothSides
|
||||
};
|
||||
|
||||
// ── WrapTopAndBottom ──
|
||||
// No text appears beside the image. Text only above and below.
|
||||
// This effectively makes the image act as a block-level element
|
||||
// but still floating (not inline).
|
||||
var wrapTopAndBottom = new DW.WrapTopBottom
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U
|
||||
};
|
||||
|
||||
// ── WrapNone ──
|
||||
// No text wrapping at all. Image floats over or behind text.
|
||||
// Combined with BehindDoc=true, this creates a watermark effect.
|
||||
var wrapNone = new DW.WrapNone();
|
||||
|
||||
// Example: build anchor with WrapSquare (swap in any wrapping element above)
|
||||
DW.Anchor anchor = BuildAnchorElement(
|
||||
relId, cx, cy,
|
||||
docPropId: 3U,
|
||||
name: "WrappedImage",
|
||||
wrapElement: wrapSquare,
|
||||
behindDoc: false);
|
||||
|
||||
body.AppendChild(new Paragraph(new Run(new Drawing(anchor))));
|
||||
}
|
||||
|
||||
// ── 4. Image with Border ───────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an image with a visible outline/border. The border is applied
|
||||
/// via A.Outline on the PIC.ShapeProperties element.
|
||||
/// </summary>
|
||||
public static void InsertImageWithBorder(
|
||||
MainDocumentPart mainPart, Body body, string imagePath)
|
||||
{
|
||||
ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
long cx = (long)(3.0 * EmuPerInch);
|
||||
long cy = (long)(2.0 * EmuPerInch);
|
||||
|
||||
// Build PIC.ShapeProperties with an Outline element for the border.
|
||||
// Outline width is in EMU. 1pt = 12700 EMU.
|
||||
var shapeProperties = new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0L, Y = 0L },
|
||||
new A.Extents { Cx = cx, Cy = cy }),
|
||||
new A.PresetGeometry(
|
||||
new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle },
|
||||
// The Outline element defines the border
|
||||
new A.Outline(
|
||||
// SolidFill sets the border color
|
||||
new A.SolidFill(
|
||||
new A.RgbColorModelHex { Val = "2F5496" }), // Dark blue
|
||||
// PresetDash sets the line style (solid, dash, dot, etc.)
|
||||
new A.PresetDash { Val = A.PresetLineDashValues.Solid }
|
||||
)
|
||||
{
|
||||
Width = 25400, // 2pt border (12700 EMU per pt)
|
||||
CompoundLineType = A.CompoundLineValues.Single
|
||||
}
|
||||
);
|
||||
|
||||
var picture = new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties { Id = 0U, Name = "BorderedImage.png" },
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
new A.Blip { Embed = relId },
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
shapeProperties);
|
||||
|
||||
var drawing = new Drawing(
|
||||
new DW.Inline(
|
||||
new DW.Extent { Cx = cx, Cy = cy },
|
||||
new DW.EffectExtent
|
||||
{
|
||||
// Must account for border width in effect extent so it is not clipped
|
||||
LeftEdge = 25400L,
|
||||
TopEdge = 25400L,
|
||||
RightEdge = 25400L,
|
||||
BottomEdge = 25400L
|
||||
},
|
||||
new DW.DocProperties { Id = 4U, Name = "BorderedImage" },
|
||||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||||
new A.Graphic(
|
||||
new A.GraphicData(picture)
|
||||
{ Uri = PicGraphicDataUri })
|
||||
)
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 0U,
|
||||
DistanceFromRight = 0U
|
||||
});
|
||||
|
||||
body.AppendChild(new Paragraph(new Run(drawing)));
|
||||
}
|
||||
|
||||
// ── 5. Image with Alt Text ─────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an image with alt text for accessibility. The alt text is set
|
||||
/// on the DocProperties.Description attribute. Screen readers use this.
|
||||
/// Word also shows it in the "Alt Text" pane.
|
||||
/// </summary>
|
||||
public static void InsertImageWithAltText(
|
||||
MainDocumentPart mainPart, Body body, string imagePath)
|
||||
{
|
||||
ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
long cx = (long)(3.0 * EmuPerInch);
|
||||
long cy = (long)(2.0 * EmuPerInch);
|
||||
|
||||
// DocProperties.Description is the standard alt text field.
|
||||
// DocProperties.Title is an optional short title shown in some UIs.
|
||||
Drawing drawing = BuildDrawingElement(
|
||||
relId, cx, cy,
|
||||
docPropId: 5U,
|
||||
name: "AccessibleImage",
|
||||
description: "A chart showing quarterly revenue growth from Q1 to Q4 2025");
|
||||
|
||||
body.AppendChild(new Paragraph(new Run(drawing)));
|
||||
}
|
||||
|
||||
// ── 6. Image in Header ─────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an image into a header part. The image relationship MUST be
|
||||
/// added to the HeaderPart, NOT the MainDocumentPart. If you add it
|
||||
/// to MainDocumentPart, Word will show a broken image in the header
|
||||
/// because relationship IDs are scoped to their containing part.
|
||||
/// </summary>
|
||||
public static void InsertImageInHeader(HeaderPart headerPart, string imagePath)
|
||||
{
|
||||
// CRITICAL: AddImagePart to headerPart, not mainDocumentPart!
|
||||
// Each OpenXML part has its own relationship namespace.
|
||||
// An rId in the header must point to a relationship in the header's .rels file.
|
||||
ImagePart imagePart = headerPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
|
||||
// GetIdOfPart must also be called on headerPart
|
||||
string relId = headerPart.GetIdOfPart(imagePart);
|
||||
|
||||
long cx = (long)(1.5 * EmuPerInch); // Company logo, typically small
|
||||
long cy = (long)(0.5 * EmuPerInch);
|
||||
|
||||
Drawing drawing = BuildDrawingElement(
|
||||
relId, cx, cy,
|
||||
docPropId: 6U,
|
||||
name: "HeaderLogo",
|
||||
description: "Company logo");
|
||||
|
||||
// Headers use the Header element with Paragraph children (same as Body)
|
||||
Header header = headerPart.Header;
|
||||
Paragraph para = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new Justification { Val = JustificationValues.Center }),
|
||||
new Run(drawing));
|
||||
|
||||
header.AppendChild(para);
|
||||
}
|
||||
|
||||
// ── 7. Image in Table Cell ─────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an image into a table cell, sized to fit. Table cells constrain
|
||||
/// content width, so we calculate appropriate dimensions to avoid overflow.
|
||||
/// The image part is still added to MainDocumentPart (the cell is in the body).
|
||||
/// </summary>
|
||||
/// <param name="mainPart">MainDocumentPart (owns the relationship).</param>
|
||||
/// <param name="cell">The TableCell to insert the image into.</param>
|
||||
/// <param name="imagePath">Path to the image file.</param>
|
||||
public static void InsertImageInTableCell(
|
||||
MainDocumentPart mainPart, TableCell cell, string imagePath)
|
||||
{
|
||||
ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
|
||||
using (FileStream stream = new FileStream(imagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
string relId = mainPart.GetIdOfPart(imagePart);
|
||||
|
||||
// Determine cell width from TableCellWidth if available.
|
||||
// TableCellWidth.Width is in DXA (twentieths of a point).
|
||||
// If not set, use a reasonable default (e.g., 2 inches).
|
||||
long maxWidthEmu = (long)(2.0 * EmuPerInch); // default
|
||||
|
||||
TableCellProperties? tcPr = cell.GetFirstChild<TableCellProperties>();
|
||||
TableCellWidth? tcWidth = tcPr?.GetFirstChild<TableCellWidth>();
|
||||
if (tcWidth?.Width is not null && tcWidth.Type?.Value == TableWidthUnitValues.Dxa)
|
||||
{
|
||||
// Convert DXA to EMU: 1 DXA = 1/20 pt = 1/1440 inch = 914400/1440 EMU
|
||||
int dxa = int.Parse(tcWidth.Width);
|
||||
maxWidthEmu = (long)(dxa * (EmuPerInch / 1440.0));
|
||||
}
|
||||
|
||||
// Calculate image dimensions to fit within the cell width
|
||||
(long cx, long cy) = CalculateImageDimensions(imagePath, maxWidthEmu / (double)EmuPerInch);
|
||||
|
||||
Drawing drawing = BuildDrawingElement(
|
||||
relId, cx, cy,
|
||||
docPropId: 7U,
|
||||
name: "CellImage",
|
||||
description: null);
|
||||
|
||||
// A TableCell MUST contain at least one Paragraph.
|
||||
// We add the image inside that paragraph.
|
||||
Paragraph para = cell.GetFirstChild<Paragraph>() ?? cell.AppendChild(new Paragraph());
|
||||
para.AppendChild(new Run(drawing));
|
||||
}
|
||||
|
||||
// ── 8. Replace Existing Image ──────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Replaces an existing image by updating the ImagePart data behind a
|
||||
/// known relationship ID. The Blip.Embed attribute (rId) stays the same;
|
||||
/// only the binary content changes. This avoids needing to rebuild the
|
||||
/// entire Drawing XML tree.
|
||||
/// </summary>
|
||||
/// <param name="mainPart">The MainDocumentPart containing the image relationship.</param>
|
||||
/// <param name="oldRelId">The existing relationship ID (e.g., "rId5") of the image to replace.</param>
|
||||
/// <param name="newImagePath">Path to the replacement image file.</param>
|
||||
public static void ReplaceExistingImage(
|
||||
MainDocumentPart mainPart, string oldRelId, string newImagePath)
|
||||
{
|
||||
// Look up the existing ImagePart by its relationship ID
|
||||
OpenXmlPart part = mainPart.GetPartById(oldRelId);
|
||||
if (part is not ImagePart imagePart)
|
||||
{
|
||||
throw new InvalidOperationException(
|
||||
$"Relationship {oldRelId} does not point to an ImagePart.");
|
||||
}
|
||||
|
||||
// Feed new image data into the existing part.
|
||||
// This replaces the binary content while keeping the same rId.
|
||||
using (FileStream stream = new FileStream(newImagePath, FileMode.Open))
|
||||
{
|
||||
imagePart.FeedData(stream);
|
||||
}
|
||||
|
||||
// NOTE: If the new image has different dimensions, you should also
|
||||
// update the Extent.Cx/Cy and A.Extents.Cx/Cy in the Drawing element.
|
||||
// Find all Blip elements referencing this relId:
|
||||
//
|
||||
// var blips = mainPart.Document.Descendants<A.Blip>()
|
||||
// .Where(b => b.Embed == oldRelId);
|
||||
// foreach (var blip in blips)
|
||||
// {
|
||||
// // Navigate up to find the Extent and A.Extents to update dimensions
|
||||
// }
|
||||
}
|
||||
|
||||
// ── 9. SVG with PNG Fallback ───────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts an SVG image with a PNG fallback for compatibility.
|
||||
/// Word 2019+ supports SVG natively; older versions show the PNG.
|
||||
/// The SVG is referenced via an extension element (SvgBlip) inside the Blip,
|
||||
/// while the Blip.Embed itself points to the PNG fallback.
|
||||
/// </summary>
|
||||
public static void InsertSvgWithPngFallback(
|
||||
MainDocumentPart mainPart, Body body,
|
||||
string svgPath, string pngFallbackPath)
|
||||
{
|
||||
// Add PNG fallback as the primary image part
|
||||
ImagePart pngPart = mainPart.AddImagePart(ImagePartType.Png);
|
||||
using (FileStream pngStream = new FileStream(pngFallbackPath, FileMode.Open))
|
||||
{
|
||||
pngPart.FeedData(pngStream);
|
||||
}
|
||||
string pngRelId = mainPart.GetIdOfPart(pngPart);
|
||||
|
||||
// Add SVG as a separate image part
|
||||
ImagePart svgPart = mainPart.AddImagePart(ImagePartType.Svg);
|
||||
using (FileStream svgStream = new FileStream(svgPath, FileMode.Open))
|
||||
{
|
||||
svgPart.FeedData(svgStream);
|
||||
}
|
||||
string svgRelId = mainPart.GetIdOfPart(svgPart);
|
||||
|
||||
long cx = (long)(3.0 * EmuPerInch);
|
||||
long cy = (long)(3.0 * EmuPerInch);
|
||||
|
||||
// The Blip.Embed points to the PNG fallback.
|
||||
// The SVG is added as an extension element (asvg:svgBlip) inside the Blip.
|
||||
// Namespace: http://schemas.microsoft.com/office/drawing/2016/SVG/main
|
||||
var blip = new A.Blip { Embed = pngRelId };
|
||||
|
||||
// Add SVG extension to the Blip using BlipExtensionList
|
||||
var svgExtension = new A.BlipExtensionList(
|
||||
new A.BlipExtension(
|
||||
// The SVG blip element references the SVG image part
|
||||
new OpenXmlUnknownElement(
|
||||
"asvg", "svgBlip",
|
||||
"http://schemas.microsoft.com/office/drawing/2016/SVG/main")
|
||||
// NOTE: In production, set the r:embed attribute on this element
|
||||
// to svgRelId. OpenXmlUnknownElement requires manual attribute setting.
|
||||
)
|
||||
{ Uri = "{96DAC541-7B7A-43D3-8B79-37D633B846F1}" }
|
||||
);
|
||||
blip.Append(svgExtension);
|
||||
|
||||
var picture = new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties { Id = 0U, Name = "SvgImage.svg" },
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
blip,
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0L, Y = 0L },
|
||||
new A.Extents { Cx = cx, Cy = cy }),
|
||||
new A.PresetGeometry(new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle }));
|
||||
|
||||
var drawing = new Drawing(
|
||||
new DW.Inline(
|
||||
new DW.Extent { Cx = cx, Cy = cy },
|
||||
new DW.EffectExtent
|
||||
{
|
||||
LeftEdge = 0L, TopEdge = 0L,
|
||||
RightEdge = 0L, BottomEdge = 0L
|
||||
},
|
||||
new DW.DocProperties { Id = 9U, Name = "SvgImage" },
|
||||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||||
new A.Graphic(
|
||||
new A.GraphicData(picture)
|
||||
{ Uri = PicGraphicDataUri })
|
||||
)
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 0U,
|
||||
DistanceFromRight = 0U
|
||||
});
|
||||
|
||||
body.AppendChild(new Paragraph(new Run(drawing)));
|
||||
}
|
||||
|
||||
// ── 10. Calculate Image Dimensions ─────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Reads the actual pixel dimensions of an image file (PNG or JPEG) and
|
||||
/// calculates EMU values that fit within a maximum width while maintaining
|
||||
/// the original aspect ratio. Uses raw byte reading to avoid a dependency
|
||||
/// on System.Drawing (which is Windows-only on modern .NET).
|
||||
/// </summary>
|
||||
/// <param name="imagePath">Path to a PNG or JPEG image file.</param>
|
||||
/// <param name="maxWidthInches">Maximum allowed width in inches.</param>
|
||||
/// <returns>Tuple of (cx, cy) in EMU, scaled to fit maxWidthInches.</returns>
|
||||
/// <remarks>
|
||||
/// For production use, consider SkiaSharp or SixLabors.ImageSharp for
|
||||
/// cross-platform image metadata reading with broader format support.
|
||||
/// This implementation handles PNG and JPEG only.
|
||||
/// </remarks>
|
||||
public static (long cx, long cy) CalculateImageDimensions(
|
||||
string imagePath, double maxWidthInches)
|
||||
{
|
||||
// Read pixel dimensions from the image file header.
|
||||
// We parse PNG IHDR or JPEG SOF0 markers directly to avoid
|
||||
// pulling in System.Drawing.Common (Windows-only on .NET 6+).
|
||||
(int widthPx, int heightPx, double dpiX, double dpiY) = ReadImageMetadata(imagePath);
|
||||
|
||||
// Calculate actual size in inches based on pixel count and DPI
|
||||
double widthInches = widthPx / dpiX;
|
||||
double heightInches = heightPx / dpiY;
|
||||
|
||||
// Scale down if wider than maxWidthInches, preserving aspect ratio
|
||||
if (widthInches > maxWidthInches)
|
||||
{
|
||||
double scale = maxWidthInches / widthInches;
|
||||
widthInches = maxWidthInches;
|
||||
heightInches *= scale;
|
||||
}
|
||||
|
||||
long cx = (long)(widthInches * EmuPerInch);
|
||||
long cy = (long)(heightInches * EmuPerInch);
|
||||
|
||||
return (cx, cy);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Reads width, height, and DPI from a PNG or JPEG file header.
|
||||
/// Returns 96 DPI as default if DPI metadata is not found.
|
||||
/// </summary>
|
||||
private static (int widthPx, int heightPx, double dpiX, double dpiY) ReadImageMetadata(
|
||||
string imagePath)
|
||||
{
|
||||
const double DefaultDpi = 96.0;
|
||||
byte[] header = new byte[32];
|
||||
|
||||
using var fs = new FileStream(imagePath, FileMode.Open, FileAccess.Read);
|
||||
int bytesRead = fs.Read(header, 0, header.Length);
|
||||
|
||||
// PNG: starts with 0x89 0x50 0x4E 0x47 (‰PNG)
|
||||
// IHDR chunk is always first; width and height are at bytes 16-23 (big-endian)
|
||||
if (bytesRead >= 24 &&
|
||||
header[0] == 0x89 && header[1] == 0x50 &&
|
||||
header[2] == 0x4E && header[3] == 0x47)
|
||||
{
|
||||
int width = (header[16] << 24) | (header[17] << 16) |
|
||||
(header[18] << 8) | header[19];
|
||||
int height = (header[20] << 24) | (header[21] << 16) |
|
||||
(header[22] << 8) | header[23];
|
||||
// PNG DPI is in the pHYs chunk (not in IHDR); use default for simplicity
|
||||
return (width, height, DefaultDpi, DefaultDpi);
|
||||
}
|
||||
|
||||
// JPEG: starts with 0xFF 0xD8
|
||||
// Scan for SOF0 (0xFF 0xC0) marker to find dimensions
|
||||
if (bytesRead >= 2 && header[0] == 0xFF && header[1] == 0xD8)
|
||||
{
|
||||
fs.Position = 2;
|
||||
while (fs.Position < fs.Length - 1)
|
||||
{
|
||||
int b = fs.ReadByte();
|
||||
if (b != 0xFF) continue;
|
||||
|
||||
int marker = fs.ReadByte();
|
||||
if (marker == -1) break;
|
||||
|
||||
// SOF0 (0xC0) or SOF2 (0xC2, progressive)
|
||||
if (marker == 0xC0 || marker == 0xC2)
|
||||
{
|
||||
byte[] sof = new byte[7];
|
||||
if (fs.Read(sof, 0, 7) == 7)
|
||||
{
|
||||
// SOF structure: length(2) + precision(1) + height(2) + width(2)
|
||||
int height = (sof[3] << 8) | sof[4];
|
||||
int width = (sof[5] << 8) | sof[6];
|
||||
return (width, height, DefaultDpi, DefaultDpi);
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
// Skip other markers: read 2-byte length and advance
|
||||
if (marker is not (0xD0 or 0xD1 or 0xD2 or 0xD3 or 0xD4 or
|
||||
0xD5 or 0xD6 or 0xD7 or 0xD8 or 0xD9 or 0x01))
|
||||
{
|
||||
byte[] lenBytes = new byte[2];
|
||||
if (fs.Read(lenBytes, 0, 2) < 2) break;
|
||||
int len = (lenBytes[0] << 8) | lenBytes[1];
|
||||
if (len < 2) break;
|
||||
fs.Position += len - 2;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: cannot determine dimensions; return a reasonable default
|
||||
// Caller should handle this gracefully.
|
||||
return (300, 200, DefaultDpi, DefaultDpi);
|
||||
}
|
||||
|
||||
// ── 11. Reusable Drawing Builder (Inline) ──────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Builds a complete Drawing element for an inline image. This is the
|
||||
/// reusable core that most insertion methods delegate to.
|
||||
/// </summary>
|
||||
/// <param name="relId">Relationship ID pointing to the ImagePart (e.g., "rId4").</param>
|
||||
/// <param name="cx">Image width in EMU. Must be positive.</param>
|
||||
/// <param name="cy">Image height in EMU. Must be positive.</param>
|
||||
/// <param name="docPropId">Unique ID for DocProperties within the document.
|
||||
/// Each Drawing in a document must have a distinct DocProperties.Id.</param>
|
||||
/// <param name="name">Name for DocProperties (shows in Word selection pane).</param>
|
||||
/// <param name="description">Alt text for accessibility. Null if not needed.</param>
|
||||
/// <returns>A fully constructed Drawing element ready to append to a Run.</returns>
|
||||
public static Drawing BuildDrawingElement(
|
||||
string relId, long cx, long cy,
|
||||
uint docPropId, string name, string? description)
|
||||
{
|
||||
// ── Complete element hierarchy ──
|
||||
// Drawing
|
||||
// └─ DW.Inline
|
||||
// ├─ DW.Extent (cx, cy) ← bounding box size
|
||||
// ├─ DW.EffectExtent ← extra space for effects
|
||||
// ├─ DW.DocProperties (id, name, descr) ← identity + alt text
|
||||
// ├─ DW.NonVisualGraphicFrameDrawingProperties
|
||||
// │ └─ A.GraphicFrameLocks ← lock aspect ratio
|
||||
// └─ A.Graphic
|
||||
// └─ A.GraphicData (uri = picture namespace)
|
||||
// └─ PIC.Picture
|
||||
// ├─ PIC.NonVisualPictureProperties
|
||||
// │ ├─ PIC.NonVisualDrawingProperties
|
||||
// │ └─ PIC.NonVisualPictureDrawingProperties
|
||||
// ├─ PIC.BlipFill
|
||||
// │ ├─ A.Blip (embed = relId)
|
||||
// │ └─ A.Stretch → A.FillRectangle
|
||||
// └─ PIC.ShapeProperties
|
||||
// ├─ A.Transform2D
|
||||
// │ ├─ A.Offset (0, 0)
|
||||
// │ └─ A.Extents (cx, cy) ← MUST match DW.Extent!
|
||||
// └─ A.PresetGeometry (rect)
|
||||
|
||||
var docProps = new DW.DocProperties
|
||||
{
|
||||
Id = docPropId,
|
||||
Name = name
|
||||
};
|
||||
if (description is not null)
|
||||
{
|
||||
docProps.Description = description;
|
||||
}
|
||||
|
||||
var picture = new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties
|
||||
{
|
||||
Id = 0U,
|
||||
Name = name
|
||||
},
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
new A.Blip
|
||||
{
|
||||
Embed = relId,
|
||||
// CompressionState controls image quality vs file size.
|
||||
// Print = high quality, Screen = medium, Email = low, None = original
|
||||
CompressionState = A.BlipCompressionValues.Print
|
||||
},
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0L, Y = 0L },
|
||||
new A.Extents { Cx = cx, Cy = cy }), // MUST match DW.Extent
|
||||
new A.PresetGeometry(
|
||||
new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle }));
|
||||
|
||||
var inline = new DW.Inline(
|
||||
new DW.Extent { Cx = cx, Cy = cy }, // MUST match A.Extents
|
||||
new DW.EffectExtent
|
||||
{
|
||||
LeftEdge = 0L,
|
||||
TopEdge = 0L,
|
||||
RightEdge = 0L,
|
||||
BottomEdge = 0L
|
||||
},
|
||||
docProps,
|
||||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||||
new A.Graphic(
|
||||
new A.GraphicData(picture)
|
||||
{ Uri = PicGraphicDataUri }))
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 0U,
|
||||
DistanceFromRight = 0U
|
||||
};
|
||||
|
||||
return new Drawing(inline);
|
||||
}
|
||||
|
||||
// ── Private Helpers ────────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Builds a DW.Anchor element for floating images with configurable wrapping.
|
||||
/// </summary>
|
||||
private static DW.Anchor BuildAnchorElement(
|
||||
string relId, long cx, long cy,
|
||||
uint docPropId, string name,
|
||||
OpenXmlElement wrapElement,
|
||||
bool behindDoc)
|
||||
{
|
||||
return new DW.Anchor(
|
||||
new DW.SimplePosition { X = 0L, Y = 0L },
|
||||
new DW.HorizontalPosition(
|
||||
new DW.PositionOffset("0"))
|
||||
{ RelativeFrom = DW.HorizontalRelativePositionValues.Column },
|
||||
new DW.VerticalPosition(
|
||||
new DW.PositionOffset("0"))
|
||||
{ RelativeFrom = DW.VerticalRelativePositionValues.Paragraph },
|
||||
new DW.Extent { Cx = cx, Cy = cy },
|
||||
new DW.EffectExtent
|
||||
{
|
||||
LeftEdge = 0L,
|
||||
TopEdge = 0L,
|
||||
RightEdge = 0L,
|
||||
BottomEdge = 0L
|
||||
},
|
||||
wrapElement,
|
||||
new DW.DocProperties { Id = docPropId, Name = name },
|
||||
new DW.NonVisualGraphicFrameDrawingProperties(
|
||||
new A.GraphicFrameLocks { NoChangeAspect = true }),
|
||||
new A.Graphic(
|
||||
new A.GraphicData(
|
||||
new PIC.Picture(
|
||||
new PIC.NonVisualPictureProperties(
|
||||
new PIC.NonVisualDrawingProperties
|
||||
{
|
||||
Id = 0U,
|
||||
Name = name
|
||||
},
|
||||
new PIC.NonVisualPictureDrawingProperties()),
|
||||
new PIC.BlipFill(
|
||||
new A.Blip { Embed = relId },
|
||||
new A.Stretch(new A.FillRectangle())),
|
||||
new PIC.ShapeProperties(
|
||||
new A.Transform2D(
|
||||
new A.Offset { X = 0L, Y = 0L },
|
||||
new A.Extents { Cx = cx, Cy = cy }),
|
||||
new A.PresetGeometry(
|
||||
new A.AdjustValueList())
|
||||
{ Preset = A.ShapeTypeValues.Rectangle }))
|
||||
)
|
||||
{ Uri = PicGraphicDataUri })
|
||||
)
|
||||
{
|
||||
DistanceFromTop = 0U,
|
||||
DistanceFromBottom = 0U,
|
||||
DistanceFromLeft = 114300U,
|
||||
DistanceFromRight = 114300U,
|
||||
SimplePos = false,
|
||||
RelativeHeight = 251658240U,
|
||||
BehindDoc = behindDoc,
|
||||
Locked = false,
|
||||
LayoutInCell = true,
|
||||
AllowOverlap = true
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Maps file extensions to OpenXML PartTypeInfo values via ImagePartType.
|
||||
/// In SDK 3.x, ImagePartType is a static class whose members return PartTypeInfo.
|
||||
/// </summary>
|
||||
private static PartTypeInfo GetImagePartType(string imagePath)
|
||||
{
|
||||
string ext = Path.GetExtension(imagePath).ToLowerInvariant();
|
||||
return ext switch
|
||||
{
|
||||
".png" => ImagePartType.Png,
|
||||
".jpg" or ".jpeg" => ImagePartType.Jpeg,
|
||||
".gif" => ImagePartType.Gif,
|
||||
".bmp" => ImagePartType.Bmp,
|
||||
".tif" or ".tiff" => ImagePartType.Tiff,
|
||||
".svg" => ImagePartType.Svg,
|
||||
".emf" => ImagePartType.Emf,
|
||||
".wmf" => ImagePartType.Wmf,
|
||||
".ico" => ImagePartType.Icon,
|
||||
_ => throw new NotSupportedException(
|
||||
$"Image format '{ext}' is not supported by OpenXML.")
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,826 @@
|
||||
// ============================================================================
|
||||
// ListAndNumberingSamples.cs — OpenXML numbering system deep dive
|
||||
// ============================================================================
|
||||
// OpenXML list/numbering architecture (3 layers):
|
||||
//
|
||||
// 1. AbstractNum — defines the numbering FORMAT (bullet chars, number formats,
|
||||
// indentation, fonts). Contains Level elements (0-8) for multi-level lists.
|
||||
//
|
||||
// 2. NumberingInstance (Num) — a concrete "instance" that references an
|
||||
// AbstractNum. Multiple paragraphs share the same NumId to form one list.
|
||||
// LevelOverride on a NumberingInstance can restart numbering.
|
||||
//
|
||||
// 3. NumberingProperties on Paragraph — links a paragraph to a NumberingInstance
|
||||
// via NumId + Level (ilvl). This is what makes a paragraph a list item.
|
||||
//
|
||||
// CRITICAL RULES:
|
||||
// - In the Numbering root element, ALL AbstractNum elements MUST appear
|
||||
// BEFORE any NumberingInstance (Num) elements. Violating this order causes
|
||||
// Word to report corruption.
|
||||
// - LevelText uses %1, %2, %3 etc. as placeholders for the current value
|
||||
// at each level. %1 = level 0's value, %2 = level 1's value, etc.
|
||||
// - NumberingSymbolRunProperties (rPr inside Level) sets the font for the
|
||||
// bullet character or number. Without it, the bullet may render in the
|
||||
// paragraph's font, which can produce wrong glyphs.
|
||||
// - IsLegalNumberingStyle on a Level forces "legal" flat numbering
|
||||
// (e.g., "1.1.1" instead of outline style) regardless of heading level.
|
||||
//
|
||||
// Storage: Numbering definitions live in numbering.xml, accessed via
|
||||
// NumberingDefinitionsPart on the MainDocumentPart.
|
||||
// ============================================================================
|
||||
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
using A = DocumentFormat.OpenXml.Drawing;
|
||||
using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
|
||||
using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Reference implementations for bullet lists, numbered lists, custom numbering,
|
||||
/// and all related numbering infrastructure in OpenXML.
|
||||
/// </summary>
|
||||
public static class ListAndNumberingSamples
|
||||
{
|
||||
// ── 1. Bullet List (3 levels) ──────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a 3-level bullet list: bullet (•) → circle (○) → square (■).
|
||||
/// Uses Symbol font for standard bullet characters.
|
||||
/// </summary>
|
||||
public static void CreateBulletList(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 0;
|
||||
int numId = 1;
|
||||
|
||||
// Level 0: solid bullet • (Unicode F0B7 in Symbol font)
|
||||
// Level 1: open circle ○ (Unicode F06F in Symbol font = ○, or "o" in Courier New)
|
||||
// Level 2: solid square ■ (Unicode F0A7 in Wingdings)
|
||||
var levels = new Level[]
|
||||
{
|
||||
CreateBulletLevel(
|
||||
levelIndex: 0,
|
||||
bulletChar: "\xF0B7", // • in Symbol
|
||||
font: "Symbol",
|
||||
indentLeftDxa: 720, // 0.5 inch
|
||||
hangingDxa: 360), // bullet hangs 0.25 inch
|
||||
|
||||
CreateBulletLevel(
|
||||
levelIndex: 1,
|
||||
bulletChar: "o", // ○ in Courier New
|
||||
font: "Courier New",
|
||||
indentLeftDxa: 1440, // 1.0 inch
|
||||
hangingDxa: 360),
|
||||
|
||||
CreateBulletLevel(
|
||||
levelIndex: 2,
|
||||
bulletChar: "\xF0A7", // ■ in Wingdings
|
||||
font: "Wingdings",
|
||||
indentLeftDxa: 2160, // 1.5 inch
|
||||
hangingDxa: 360)
|
||||
};
|
||||
|
||||
// Build the abstract numbering definition and instance
|
||||
SetupAbstractNum(numPart, abstractNumId, levels);
|
||||
SetupNumberingInstance(numPart, numId, abstractNumId);
|
||||
|
||||
// Create sample list items at each level
|
||||
string[] level0Items = ["First item", "Second item", "Third item"];
|
||||
string[] level1Items = ["Sub-item A", "Sub-item B"];
|
||||
string[] level2Items = ["Detail 1", "Detail 2"];
|
||||
|
||||
foreach (string text in level0Items)
|
||||
{
|
||||
Paragraph para = CreateListParagraph(text, numId, level: 0);
|
||||
body.AppendChild(para);
|
||||
}
|
||||
foreach (string text in level1Items)
|
||||
{
|
||||
Paragraph para = CreateListParagraph(text, numId, level: 1);
|
||||
body.AppendChild(para);
|
||||
}
|
||||
foreach (string text in level2Items)
|
||||
{
|
||||
Paragraph para = CreateListParagraph(text, numId, level: 2);
|
||||
body.AppendChild(para);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 2. Numbered List (3 levels) ────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a 3-level numbered list: 1. → 1.1. → 1.1.1.
|
||||
/// Uses NumberFormatValues.Decimal with compound LevelText patterns.
|
||||
/// </summary>
|
||||
public static void CreateNumberedList(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 1;
|
||||
int numId = 2;
|
||||
|
||||
// LevelText explanation:
|
||||
// "%1" → just the level-0 counter: 1, 2, 3...
|
||||
// "%1.%2" → level-0.level-1: 1.1, 1.2, 2.1...
|
||||
// "%1.%2.%3" → level-0.level-1.level-2: 1.1.1, 1.1.2...
|
||||
var levels = new Level[]
|
||||
{
|
||||
CreateNumberLevel(
|
||||
levelIndex: 0,
|
||||
format: NumberFormatValues.Decimal,
|
||||
levelText: "%1.", // "1.", "2.", "3."
|
||||
indentLeftDxa: 720,
|
||||
hangingDxa: 360,
|
||||
start: 1),
|
||||
|
||||
CreateNumberLevel(
|
||||
levelIndex: 1,
|
||||
format: NumberFormatValues.Decimal,
|
||||
levelText: "%1.%2.", // "1.1.", "1.2.", "2.1."
|
||||
indentLeftDxa: 1440,
|
||||
hangingDxa: 720, // wider hanging for "1.1."
|
||||
start: 1),
|
||||
|
||||
CreateNumberLevel(
|
||||
levelIndex: 2,
|
||||
format: NumberFormatValues.Decimal,
|
||||
levelText: "%1.%2.%3.", // "1.1.1.", "1.1.2."
|
||||
indentLeftDxa: 2160,
|
||||
hangingDxa: 1080,
|
||||
start: 1)
|
||||
};
|
||||
|
||||
SetupAbstractNum(numPart, abstractNumId, levels);
|
||||
SetupNumberingInstance(numPart, numId, abstractNumId);
|
||||
|
||||
// Sample items
|
||||
body.AppendChild(CreateListParagraph("Chapter One", numId, level: 0));
|
||||
body.AppendChild(CreateListParagraph("Section One", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("Detail A", numId, level: 2));
|
||||
body.AppendChild(CreateListParagraph("Detail B", numId, level: 2));
|
||||
body.AppendChild(CreateListParagraph("Section Two", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("Chapter Two", numId, level: 0));
|
||||
}
|
||||
|
||||
// ── 3. Custom Bullet Characters ────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates bullets with custom Unicode characters: ✓ (check), ➢ (arrow), ★ (star).
|
||||
/// Uses specific fonts that contain these glyphs.
|
||||
/// </summary>
|
||||
public static void CreateCustomBullets(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 2;
|
||||
int numId = 3;
|
||||
|
||||
// For custom Unicode bullets, the font in NumberingSymbolRunProperties
|
||||
// MUST contain the glyph. Common choices:
|
||||
// - "Segoe UI Symbol" — broad Unicode coverage on Windows
|
||||
// - "Arial Unicode MS" — wide coverage
|
||||
// - "Wingdings" / "Webdings" — symbol fonts (use their private codepoints)
|
||||
var levels = new Level[]
|
||||
{
|
||||
CreateBulletLevel(
|
||||
levelIndex: 0,
|
||||
bulletChar: "\u2713", // ✓ CHECK MARK
|
||||
font: "Segoe UI Symbol",
|
||||
indentLeftDxa: 720,
|
||||
hangingDxa: 360),
|
||||
|
||||
CreateBulletLevel(
|
||||
levelIndex: 1,
|
||||
bulletChar: "\u27A2", // ➢ THREE-D TOP-LIGHTED RIGHTWARDS ARROWHEAD
|
||||
font: "Segoe UI Symbol",
|
||||
indentLeftDxa: 1440,
|
||||
hangingDxa: 360),
|
||||
|
||||
CreateBulletLevel(
|
||||
levelIndex: 2,
|
||||
bulletChar: "\u2605", // ★ BLACK STAR
|
||||
font: "Segoe UI Symbol",
|
||||
indentLeftDxa: 2160,
|
||||
hangingDxa: 360)
|
||||
};
|
||||
|
||||
SetupAbstractNum(numPart, abstractNumId, levels);
|
||||
SetupNumberingInstance(numPart, numId, abstractNumId);
|
||||
|
||||
body.AppendChild(CreateListParagraph("Completed task", numId, level: 0));
|
||||
body.AppendChild(CreateListParagraph("Action item", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("Starred note", numId, level: 2));
|
||||
}
|
||||
|
||||
// ── 4. Outline Numbering Linked to Heading Styles ──────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates outline numbering (Article 1, Section 1.1, etc.) linked to
|
||||
/// Heading1, Heading2, Heading3 styles. This is how Word's built-in
|
||||
/// "List Number" styles work for legal/technical documents.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// When a Level has ParagraphStyleIdInLevel, any paragraph with that
|
||||
/// style ID automatically gets numbered. The numbering is "linked" to
|
||||
/// the style — you don't need NumberingProperties on each paragraph
|
||||
/// (though it's also valid to add them explicitly).
|
||||
/// </remarks>
|
||||
public static void CreateOutlineNumbering(
|
||||
NumberingDefinitionsPart numPart,
|
||||
StyleDefinitionsPart stylesPart)
|
||||
{
|
||||
int abstractNumId = 3;
|
||||
int numId = 4;
|
||||
|
||||
var abstractNum = new AbstractNum(
|
||||
// Level 0: "1" — linked to Heading1
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "%1" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new ParagraphStyleIdInLevel { Val = "Heading1" },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "432", Hanging = "432" })
|
||||
)
|
||||
{ LevelIndex = 0 },
|
||||
|
||||
// Level 1: "1.1" — linked to Heading2
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "%1.%2" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new ParagraphStyleIdInLevel { Val = "Heading2" },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "576", Hanging = "576" })
|
||||
)
|
||||
{ LevelIndex = 1 },
|
||||
|
||||
// Level 2: "1.1.1" — linked to Heading3
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "%1.%2.%3" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new ParagraphStyleIdInLevel { Val = "Heading3" },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "720", Hanging = "720" })
|
||||
)
|
||||
{ LevelIndex = 2 }
|
||||
)
|
||||
{
|
||||
AbstractNumberId = abstractNumId,
|
||||
// MultiLevelType controls how Word treats level transitions:
|
||||
// - HybridMultilevel: each level is somewhat independent (most common)
|
||||
// - Multilevel: true outline numbering where sub-levels nest under parents
|
||||
// - SingleLevel: only one level
|
||||
MultiLevelType = new MultiLevelType
|
||||
{
|
||||
Val = MultiLevelValues.Multilevel
|
||||
}
|
||||
};
|
||||
|
||||
// Ensure AbstractNum appears first, then NumberingInstance
|
||||
EnsureNumberingRoot(numPart);
|
||||
numPart.Numbering.Append(abstractNum);
|
||||
|
||||
var numInstance = new NumberingInstance(
|
||||
new AbstractNumId { Val = abstractNumId })
|
||||
{ NumberID = numId };
|
||||
numPart.Numbering.Append(numInstance);
|
||||
|
||||
// Link the styles to the numbering definition.
|
||||
// Each heading style gets a NumberingProperties pointing to this numId.
|
||||
Styles styles = stylesPart.Styles ?? (stylesPart.Styles = new Styles());
|
||||
|
||||
LinkStyleToNumbering(styles, "Heading1", numId, level: 0);
|
||||
LinkStyleToNumbering(styles, "Heading2", numId, level: 1);
|
||||
LinkStyleToNumbering(styles, "Heading3", numId, level: 2);
|
||||
}
|
||||
|
||||
// ── 5. Legal Numbering ─────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a legal document numbering pattern:
|
||||
/// Article I, Article II (Roman numerals)
|
||||
/// Section 1, Section 2 (Decimal)
|
||||
/// (a), (b), (c) (Lowercase letters)
|
||||
/// </summary>
|
||||
public static void CreateLegalNumbering(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 4;
|
||||
int numId = 5;
|
||||
|
||||
var abstractNum = new AbstractNum(
|
||||
// Level 0: "Article I" — Upper Roman
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.UpperRoman },
|
||||
new LevelText { Val = "Article %1" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "720", Hanging = "720" }),
|
||||
new NumberingSymbolRunProperties(
|
||||
new Bold(),
|
||||
new RunFonts { Ascii = "Times New Roman", HighAnsi = "Times New Roman" })
|
||||
)
|
||||
{ LevelIndex = 0 },
|
||||
|
||||
// Level 1: "Section 1" — Decimal
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "Section %2" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "1440", Hanging = "720" })
|
||||
)
|
||||
{ LevelIndex = 1 },
|
||||
|
||||
// Level 2: "(a)" — Lowercase letter
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.LowerLetter },
|
||||
new LevelText { Val = "(%3)" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "2160", Hanging = "720" })
|
||||
)
|
||||
{ LevelIndex = 2 }
|
||||
)
|
||||
{
|
||||
AbstractNumberId = abstractNumId,
|
||||
MultiLevelType = new MultiLevelType { Val = MultiLevelValues.Multilevel }
|
||||
};
|
||||
|
||||
EnsureNumberingRoot(numPart);
|
||||
numPart.Numbering.Append(abstractNum);
|
||||
SetupNumberingInstance(numPart, numId, abstractNumId);
|
||||
|
||||
// Sample legal document structure
|
||||
body.AppendChild(CreateListParagraph("Definitions", numId, level: 0));
|
||||
body.AppendChild(CreateListParagraph("General Terms", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph(
|
||||
"\"Agreement\" means this document and all exhibits.", numId, level: 2));
|
||||
body.AppendChild(CreateListParagraph(
|
||||
"\"Party\" means any signatory to this Agreement.", numId, level: 2));
|
||||
body.AppendChild(CreateListParagraph("Scope of Work", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("Obligations", numId, level: 0));
|
||||
}
|
||||
|
||||
// ── 6. Chinese Numbering ───────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a Chinese document numbering hierarchy:
|
||||
/// Level 0: 一、二、三、 (Chinese ideographic, followed by 、)
|
||||
/// Level 1: （一）（二）（三） (Chinese ideographic in parentheses)
|
||||
/// Level 2: 1. 2. 3. (Decimal, Arabic numerals)
|
||||
/// Level 3: (1) (2) (3) (Decimal in parentheses)
|
||||
///
|
||||
/// Chinese numbering uses NumberFormatValues.ChineseCounting or
|
||||
/// ChineseCountingThousand for 一二三 style characters.
|
||||
/// The font for Chinese number characters should be a CJK font like SimSun or SimHei.
|
||||
/// </summary>
|
||||
public static void CreateChineseNumbering(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 5;
|
||||
int numId = 6;
|
||||
|
||||
var abstractNum = new AbstractNum(
|
||||
// Level 0: 一、 二、 三、
|
||||
// ChineseCountingThousand produces 一 二 三 四 五 六 七 八 九 十
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.ChineseCountingThousand },
|
||||
new LevelText { Val = "%1\u3001" }, // 、 is the Chinese enumeration comma
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "840", Hanging = "420" }),
|
||||
// NumberingSymbolRunProperties MUST specify a CJK font
|
||||
// so the Chinese number renders correctly
|
||||
new NumberingSymbolRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "SimSun",
|
||||
HighAnsi = "SimSun",
|
||||
EastAsia = "SimSun", // Critical for CJK rendering
|
||||
ComplexScript = "SimSun"
|
||||
})
|
||||
)
|
||||
{ LevelIndex = 0 },
|
||||
|
||||
// Level 1: （一）（二）（三）
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.ChineseCountingThousand },
|
||||
new LevelText { Val = "\uFF08%2\uFF09" }, // （ and ） are fullwidth parens
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "1260", Hanging = "420" }),
|
||||
new NumberingSymbolRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = "SimSun",
|
||||
HighAnsi = "SimSun",
|
||||
EastAsia = "SimSun",
|
||||
ComplexScript = "SimSun"
|
||||
})
|
||||
)
|
||||
{ LevelIndex = 1 },
|
||||
|
||||
// Level 2: 1. 2. 3.
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "%3." },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "1680", Hanging = "420" })
|
||||
)
|
||||
{ LevelIndex = 2 },
|
||||
|
||||
// Level 3: (1) (2) (3)
|
||||
new Level(
|
||||
new StartNumberingValue { Val = 1 },
|
||||
new NumberingFormat { Val = NumberFormatValues.Decimal },
|
||||
new LevelText { Val = "(%4)" },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation { Left = "2100", Hanging = "420" })
|
||||
)
|
||||
{ LevelIndex = 3 }
|
||||
)
|
||||
{
|
||||
AbstractNumberId = abstractNumId,
|
||||
MultiLevelType = new MultiLevelType { Val = MultiLevelValues.Multilevel }
|
||||
};
|
||||
|
||||
EnsureNumberingRoot(numPart);
|
||||
numPart.Numbering.Append(abstractNum);
|
||||
SetupNumberingInstance(numPart, numId, abstractNumId);
|
||||
|
||||
body.AppendChild(CreateListParagraph("总则", numId, level: 0));
|
||||
body.AppendChild(CreateListParagraph("目的和依据", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("本办法适用于全体员工。", numId, level: 2));
|
||||
body.AppendChild(CreateListParagraph("自发布之日起施行。", numId, level: 3));
|
||||
body.AppendChild(CreateListParagraph("适用范围", numId, level: 1));
|
||||
body.AppendChild(CreateListParagraph("职责与权限", numId, level: 0));
|
||||
}
|
||||
|
||||
// ── 7. Restart Numbering ───────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Demonstrates how to restart a numbered list at 1 using LevelOverride
|
||||
/// with StartOverride. This creates a new NumberingInstance that shares
|
||||
/// the same AbstractNum but overrides the start value.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Scenario: You have items 1-5 in one list, then want a separate list
|
||||
/// that starts again at 1 with the same formatting. You need a new
|
||||
/// NumberingInstance (new NumId) with LevelOverride.
|
||||
/// </remarks>
|
||||
public static void RestartNumbering(
|
||||
NumberingDefinitionsPart numPart, Body body)
|
||||
{
|
||||
int abstractNumId = 6;
|
||||
int numId1 = 7;
|
||||
int numId2 = 8; // Second instance for restarted list
|
||||
|
||||
// Simple single-level numbered list
|
||||
var levels = new Level[]
|
||||
{
|
||||
CreateNumberLevel(
|
||||
levelIndex: 0,
|
||||
format: NumberFormatValues.Decimal,
|
||||
levelText: "%1.",
|
||||
indentLeftDxa: 720,
|
||||
hangingDxa: 360,
|
||||
start: 1)
|
||||
};
|
||||
|
||||
SetupAbstractNum(numPart, abstractNumId, levels);
|
||||
SetupNumberingInstance(numPart, numId1, abstractNumId);
|
||||
|
||||
// First list: 1, 2, 3
|
||||
body.AppendChild(CreateListParagraph("First list item 1", numId1, level: 0));
|
||||
body.AppendChild(CreateListParagraph("First list item 2", numId1, level: 0));
|
||||
body.AppendChild(CreateListParagraph("First list item 3", numId1, level: 0));
|
||||
|
||||
// Non-list paragraph between the lists
|
||||
body.AppendChild(new Paragraph(
|
||||
new Run(new Text("Some text between lists."))));
|
||||
|
||||
// Create a NEW NumberingInstance with LevelOverride to restart at 1.
|
||||
// LevelOverride on a NumberingInstance overrides a specific level's
|
||||
// start value WITHOUT creating a new AbstractNum.
|
||||
var restartedInstance = new NumberingInstance(
|
||||
new AbstractNumId { Val = abstractNumId },
|
||||
// LevelOverride resets level 0 to start at 1
|
||||
new LevelOverride(
|
||||
new StartOverrideNumberingValue { Val = 1 }
|
||||
)
|
||||
{ LevelIndex = 0 }
|
||||
)
|
||||
{ NumberID = numId2 };
|
||||
|
||||
numPart.Numbering.Append(restartedInstance);
|
||||
|
||||
// Second list uses numId2: starts at 1 again
|
||||
body.AppendChild(CreateListParagraph("Restarted item 1", numId2, level: 0));
|
||||
body.AppendChild(CreateListParagraph("Restarted item 2", numId2, level: 0));
|
||||
body.AppendChild(CreateListParagraph("Restarted item 3", numId2, level: 0));
|
||||
}
|
||||
|
||||
// ── 8. Continue Numbering ──────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Continues numbering from a previous list by using the same NumId.
|
||||
/// All paragraphs sharing a NumId form a single continuous sequence.
|
||||
/// Inserting non-list paragraphs between them does NOT break the sequence.
|
||||
/// </summary>
|
||||
/// <param name="body">The Body to append paragraphs to.</param>
|
||||
/// <param name="existingNumId">The NumId of the list to continue.</param>
|
||||
public static void ContinueNumbering(Body body, int existingNumId)
|
||||
{
|
||||
// Simply use the SAME numId as the existing list.
|
||||
// Word automatically continues the counter from wherever it left off.
|
||||
// Even if there are non-list paragraphs in between, the numbering
|
||||
// picks up seamlessly.
|
||||
|
||||
body.AppendChild(new Paragraph(
|
||||
new Run(new Text("(Non-list paragraph — numbering continues after this.)"))));
|
||||
|
||||
// These will be numbered 4, 5 (assuming previous list ended at 3)
|
||||
body.AppendChild(CreateListParagraph(
|
||||
"Continued item", existingNumId, level: 0));
|
||||
body.AppendChild(CreateListParagraph(
|
||||
"Another continued item", existingNumId, level: 0));
|
||||
}
|
||||
|
||||
// ── 9. Setup AbstractNum (Helper) ──────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Builds an AbstractNum from an array of Level definitions and appends
|
||||
/// it to the Numbering root. AbstractNum defines the *format* of a list
|
||||
/// (bullet characters, number format, indentation, fonts).
|
||||
/// </summary>
|
||||
/// <param name="numPart">The NumberingDefinitionsPart to append to.</param>
|
||||
/// <param name="abstractNumId">Unique ID for this abstract definition.</param>
|
||||
/// <param name="levels">Array of Level elements (one per nesting level, max 9).</param>
|
||||
public static void SetupAbstractNum(
|
||||
NumberingDefinitionsPart numPart, int abstractNumId, Level[] levels)
|
||||
{
|
||||
EnsureNumberingRoot(numPart);
|
||||
|
||||
var abstractNum = new AbstractNum
|
||||
{
|
||||
AbstractNumberId = abstractNumId,
|
||||
// MultiLevelType:
|
||||
// HybridMultilevel — most common; each level can have independent formatting
|
||||
// Multilevel — true outline; sub-levels inherit parent context
|
||||
// SingleLevel — only level 0 is used
|
||||
MultiLevelType = new MultiLevelType
|
||||
{
|
||||
Val = levels.Length > 1
|
||||
? MultiLevelValues.HybridMultilevel
|
||||
: MultiLevelValues.SingleLevel
|
||||
}
|
||||
};
|
||||
|
||||
foreach (Level level in levels)
|
||||
{
|
||||
abstractNum.Append(level.CloneNode(true));
|
||||
}
|
||||
|
||||
// IMPORTANT: AbstractNum must be inserted BEFORE any NumberingInstance
|
||||
// elements in the Numbering root. Find the right position.
|
||||
NumberingInstance? firstNumInstance =
|
||||
numPart.Numbering.GetFirstChild<NumberingInstance>();
|
||||
|
||||
if (firstNumInstance is not null)
|
||||
{
|
||||
numPart.Numbering.InsertBefore(abstractNum, firstNumInstance);
|
||||
}
|
||||
else
|
||||
{
|
||||
numPart.Numbering.Append(abstractNum);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 10. Setup NumberingInstance (Helper) ────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a NumberingInstance (Num element) that references an AbstractNum.
|
||||
/// The NumberingInstance is what paragraphs actually point to via NumId.
|
||||
/// Multiple paragraphs with the same NumId form one continuous list.
|
||||
/// </summary>
|
||||
/// <param name="numPart">The NumberingDefinitionsPart to append to.</param>
|
||||
/// <param name="numId">Unique instance ID (referenced by paragraphs).
|
||||
/// Must be >= 1; value 0 is reserved for "no numbering".</param>
|
||||
/// <param name="abstractNumId">The AbstractNum this instance uses.</param>
|
||||
public static void SetupNumberingInstance(
|
||||
NumberingDefinitionsPart numPart, int numId, int abstractNumId)
|
||||
{
|
||||
EnsureNumberingRoot(numPart);
|
||||
|
||||
// NumberingInstance (w:num) links to AbstractNum via AbstractNumId child
|
||||
var numInstance = new NumberingInstance(
|
||||
new AbstractNumId { Val = abstractNumId })
|
||||
{
|
||||
// NumberID is the w:numId attribute; this is what paragraphs reference
|
||||
NumberID = numId
|
||||
};
|
||||
|
||||
// NumberingInstance MUST come after all AbstractNum elements
|
||||
numPart.Numbering.Append(numInstance);
|
||||
}
|
||||
|
||||
// ── 11. Apply Numbering to Paragraph (Helper) ──────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Applies numbering to an existing paragraph by setting NumberingProperties
|
||||
/// in the ParagraphProperties. This is the final link that makes a
|
||||
/// paragraph display as a list item.
|
||||
/// </summary>
|
||||
/// <param name="para">The paragraph to make into a list item.</param>
|
||||
/// <param name="numId">The NumberingInstance ID to use.</param>
|
||||
/// <param name="level">The indentation level (0 = top level, max 8).</param>
|
||||
public static void ApplyNumberingToParagraph(Paragraph para, int numId, int level)
|
||||
{
|
||||
// NumberingProperties contains:
|
||||
// - NumberingLevelReference (w:ilvl) — which level (0-8)
|
||||
// - NumberingId (w:numId) — which NumberingInstance to use
|
||||
var numberingProperties = new NumberingProperties(
|
||||
new NumberingLevelReference { Val = level },
|
||||
new NumberingId { Val = numId });
|
||||
|
||||
// Ensure ParagraphProperties exists
|
||||
ParagraphProperties pPr = para.GetFirstChild<ParagraphProperties>()
|
||||
?? para.PrependChild(new ParagraphProperties());
|
||||
|
||||
// Replace existing NumberingProperties if present
|
||||
NumberingProperties? existing = pPr.GetFirstChild<NumberingProperties>();
|
||||
if (existing is not null)
|
||||
{
|
||||
pPr.ReplaceChild(numberingProperties, existing);
|
||||
}
|
||||
else
|
||||
{
|
||||
// NumberingProperties should appear early in ParagraphProperties
|
||||
// (after ParagraphStyleId if present)
|
||||
ParagraphStyleId? styleId = pPr.GetFirstChild<ParagraphStyleId>();
|
||||
if (styleId is not null)
|
||||
{
|
||||
pPr.InsertAfter(numberingProperties, styleId);
|
||||
}
|
||||
else
|
||||
{
|
||||
pPr.PrependChild(numberingProperties);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Private Helper Methods ─────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a bullet-type Level definition.
|
||||
/// </summary>
|
||||
private static Level CreateBulletLevel(
|
||||
int levelIndex,
|
||||
string bulletChar,
|
||||
string font,
|
||||
int indentLeftDxa,
|
||||
int hangingDxa)
|
||||
{
|
||||
return new Level(
|
||||
// Bullets don't increment, but StartNumberingValue is still required
|
||||
new StartNumberingValue { Val = 1 },
|
||||
// NumberFormatValues.Bullet tells Word this is a bullet, not a number
|
||||
new NumberingFormat { Val = NumberFormatValues.Bullet },
|
||||
// LevelText.Val is the actual bullet character
|
||||
new LevelText { Val = bulletChar },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
// PreviousParagraphProperties controls indentation of the text
|
||||
// (confusingly named; it's the paragraph indent for THIS level)
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation
|
||||
{
|
||||
Left = indentLeftDxa.ToString(),
|
||||
Hanging = hangingDxa.ToString()
|
||||
}),
|
||||
// NumberingSymbolRunProperties sets the font for the bullet character.
|
||||
// Without this, the bullet renders in the paragraph's body font,
|
||||
// which may not contain the glyph (e.g., Symbol characters).
|
||||
new NumberingSymbolRunProperties(
|
||||
new RunFonts
|
||||
{
|
||||
Ascii = font,
|
||||
HighAnsi = font,
|
||||
Hint = FontTypeHintValues.Default
|
||||
})
|
||||
)
|
||||
{ LevelIndex = levelIndex };
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a number-type Level definition.
|
||||
/// </summary>
|
||||
private static Level CreateNumberLevel(
|
||||
int levelIndex,
|
||||
NumberFormatValues format,
|
||||
string levelText,
|
||||
int indentLeftDxa,
|
||||
int hangingDxa,
|
||||
int start)
|
||||
{
|
||||
return new Level(
|
||||
new StartNumberingValue { Val = start },
|
||||
new NumberingFormat { Val = format },
|
||||
new LevelText { Val = levelText },
|
||||
new LevelJustification { Val = LevelJustificationValues.Left },
|
||||
new PreviousParagraphProperties(
|
||||
new Indentation
|
||||
{
|
||||
Left = indentLeftDxa.ToString(),
|
||||
Hanging = hangingDxa.ToString()
|
||||
})
|
||||
)
|
||||
{ LevelIndex = levelIndex };
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a paragraph with text and numbering properties applied.
|
||||
/// </summary>
|
||||
private static Paragraph CreateListParagraph(string text, int numId, int level)
|
||||
{
|
||||
var para = new Paragraph(
|
||||
new ParagraphProperties(
|
||||
new NumberingProperties(
|
||||
new NumberingLevelReference { Val = level },
|
||||
new NumberingId { Val = numId })),
|
||||
new Run(new Text(text)));
|
||||
return para;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ensures the Numbering root element exists on the NumberingDefinitionsPart.
|
||||
/// </summary>
|
||||
private static void EnsureNumberingRoot(NumberingDefinitionsPart numPart)
|
||||
{
|
||||
if (numPart.Numbering is null)
|
||||
{
|
||||
numPart.Numbering = new Numbering();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Links a named style to a numbering definition by adding NumberingProperties
|
||||
/// to the style's ParagraphProperties.
|
||||
/// </summary>
|
||||
private static void LinkStyleToNumbering(
|
||||
Styles styles, string styleId, int numId, int level)
|
||||
{
|
||||
// Find existing style or create it
|
||||
Style? style = styles.Elements<Style>()
|
||||
.FirstOrDefault(s => s.StyleId?.Value == styleId);
|
||||
|
||||
if (style is null)
|
||||
{
|
||||
style = new Style
|
||||
{
|
||||
Type = StyleValues.Paragraph,
|
||||
StyleId = styleId,
|
||||
StyleName = new StyleName { Val = styleId }
|
||||
};
|
||||
styles.Append(style);
|
||||
}
|
||||
|
||||
// Ensure StyleParagraphProperties exists
|
||||
StyleParagraphProperties? spPr = style.GetFirstChild<StyleParagraphProperties>();
|
||||
if (spPr is null)
|
||||
{
|
||||
spPr = new StyleParagraphProperties();
|
||||
style.Append(spPr);
|
||||
}
|
||||
|
||||
// Set NumberingProperties on the style
|
||||
NumberingProperties? existingNumPr = spPr.GetFirstChild<NumberingProperties>();
|
||||
var newNumPr = new NumberingProperties(
|
||||
new NumberingLevelReference { Val = level },
|
||||
new NumberingId { Val = numId });
|
||||
|
||||
if (existingNumPr is not null)
|
||||
{
|
||||
spPr.ReplaceChild(newNumPr, existingNumPr);
|
||||
}
|
||||
else
|
||||
{
|
||||
spPr.Append(newNumPr);
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,595 @@
|
||||
using DocumentFormat.OpenXml;
|
||||
using DocumentFormat.OpenXml.Packaging;
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.Samples;
|
||||
|
||||
/// <summary>
|
||||
/// Reference implementations for revision tracking (Track Changes).
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════════════════╗
|
||||
/// ║ CRITICAL: w:del uses w:delText, NEVER w:t ║
|
||||
/// ║ w:ins uses w:t, NEVER w:delText ║
|
||||
/// ║ Getting this wrong silently corrupts the document. ║
|
||||
/// ║ Word will open without error but display garbled text or ║
|
||||
/// ║ lose content when accepting/rejecting changes. ║
|
||||
/// ╚══════════════════════════════════════════════════════════════════╝
|
||||
///
|
||||
/// KEY CONCEPTS:
|
||||
/// - Every revision element (ins, del, rPrChange, pPrChange) needs:
|
||||
/// w:id — unique revision ID (string, must be unique across all revisions)
|
||||
/// w:author — who made the change
|
||||
/// w:date — ISO 8601 timestamp
|
||||
/// - InsertedRun (w:ins) wraps normal Run elements with w:t text
|
||||
/// - DeletedRun (w:del) wraps Run elements that use DeletedText (w:delText) instead of Text (w:t)
|
||||
/// - MoveFrom/MoveTo track text that was moved (not just deleted+inserted)
|
||||
/// </summary>
|
||||
public static class TrackChangesSamples
|
||||
{
|
||||
/// <summary>
|
||||
/// Thread-safe counter for generating unique revision IDs.
|
||||
/// In production, scan the document for the max existing ID first.
|
||||
/// </summary>
|
||||
private static int s_revisionCounter;
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 1. EnableTrackChanges
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Enables revision tracking in the document settings.
|
||||
/// This makes Word record all subsequent edits as tracked changes.
|
||||
///
|
||||
/// Maps to: <w:trackChanges/> in settings.xml
|
||||
///
|
||||
/// Note: This only controls whether NEW edits are tracked.
|
||||
/// Existing revision marks are always preserved regardless of this setting.
|
||||
/// </summary>
|
||||
public static void EnableTrackChanges(DocumentSettingsPart settingsPart)
|
||||
{
|
||||
settingsPart.Settings ??= new Settings();
|
||||
|
||||
var existing = settingsPart.Settings.GetFirstChild<TrackRevisions>();
|
||||
if (existing == null)
|
||||
{
|
||||
settingsPart.Settings.Append(new TrackRevisions());
|
||||
}
|
||||
|
||||
settingsPart.Settings.Save();
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 2. InsertTrackedInsertion — w:ins with w:t
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts text as a tracked insertion (w:ins).
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════╗
|
||||
/// ║ w:ins uses w:t (Text), NOT w:delText. ║
|
||||
/// ║ The text appears with green underline in Word. ║
|
||||
/// ╚══════════════════════════════════════════════════════╝
|
||||
///
|
||||
/// XML structure:
|
||||
/// <w:ins w:id="1" w:author="John" w:date="2026-03-22T00:00:00Z">
|
||||
/// <w:r>
|
||||
/// <w:t>inserted text</w:t> <!-- w:t, NOT w:delText -->
|
||||
/// </w:r>
|
||||
/// </w:ins>
|
||||
/// </summary>
|
||||
public static InsertedRun InsertTrackedInsertion(Paragraph para, string text, string author)
|
||||
{
|
||||
var ins = new InsertedRun
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// CORRECT: w:ins contains w:r with w:t (normal Text element)
|
||||
ins.Append(new Run(
|
||||
new Text(text) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
para.Append(ins);
|
||||
return ins;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 3. InsertTrackedDeletion — w:del with w:delText
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Inserts text as a tracked deletion (w:del).
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════╗
|
||||
/// ║ w:del uses w:delText (DeletedText), NOT w:t. ║
|
||||
/// ║ Using w:t inside w:del SILENTLY CORRUPTS the file. ║
|
||||
/// ║ The text appears with red strikethrough in Word. ║
|
||||
/// ╚══════════════════════════════════════════════════════╝
|
||||
///
|
||||
/// XML structure:
|
||||
/// <w:del w:id="2" w:author="John" w:date="2026-03-22T00:00:00Z">
|
||||
/// <w:r>
|
||||
/// <w:delText xml:space="preserve">deleted text</w:delText> <!-- w:delText, NOT w:t -->
|
||||
/// </w:r>
|
||||
/// </w:del>
|
||||
/// </summary>
|
||||
public static DeletedRun InsertTrackedDeletion(Paragraph para, string deletedText, string author)
|
||||
{
|
||||
var del = new DeletedRun
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// CORRECT: w:del contains w:r with w:delText (DeletedText element)
|
||||
// WRONG would be: new Text(deletedText) — this creates w:t which corrupts the document
|
||||
del.Append(new Run(
|
||||
new DeletedText(deletedText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
para.Append(del);
|
||||
return del;
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 4. InsertFormattingChange — RunPropertiesChange
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Records a formatting change on a run (e.g., text was made bold).
|
||||
///
|
||||
/// RunPropertiesChange (w:rPrChange) stores the PREVIOUS formatting.
|
||||
/// The current RunProperties on the run reflects the NEW formatting.
|
||||
///
|
||||
/// Example: text changed from normal to bold:
|
||||
/// <w:rPr>
|
||||
/// <w:b/> <!-- current: bold -->
|
||||
/// <w:rPrChange w:id="3" w:author="John" w:date="...">
|
||||
/// <w:rPr/> <!-- previous: no bold -->
|
||||
/// </w:rPrChange>
|
||||
/// </w:rPr>
|
||||
/// </summary>
|
||||
public static void InsertFormattingChange(Run run, string author)
|
||||
{
|
||||
// Ensure RunProperties exists
|
||||
run.RunProperties ??= new RunProperties();
|
||||
|
||||
// Store the previous (empty/normal) formatting as the "before" state
|
||||
var rPrChange = new RunPropertiesChange
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// The child RunProperties inside rPrChange is the OLD formatting (before the change).
|
||||
// An empty RunProperties means "was default/normal formatting."
|
||||
rPrChange.Append(new PreviousRunProperties());
|
||||
|
||||
run.RunProperties.Append(rPrChange);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 5. InsertParagraphFormatChange — ParagraphPropertiesChange
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Records a paragraph formatting change (e.g., alignment changed).
|
||||
///
|
||||
/// ParagraphPropertiesChange (w:pPrChange) stores the PREVIOUS paragraph properties.
|
||||
/// The current ParagraphProperties reflects the NEW formatting.
|
||||
///
|
||||
/// Example: paragraph changed from left-aligned to centered:
|
||||
/// <w:pPr>
|
||||
/// <w:jc w:val="center"/> <!-- current: centered -->
|
||||
/// <w:pPrChange w:id="4" w:author="John" w:date="...">
|
||||
/// <w:pPr>
|
||||
/// <w:jc w:val="left"/> <!-- previous: left -->
|
||||
/// </w:pPr>
|
||||
/// </w:pPrChange>
|
||||
/// </w:pPr>
|
||||
/// </summary>
|
||||
public static void InsertParagraphFormatChange(Paragraph para, string author)
|
||||
{
|
||||
para.ParagraphProperties ??= new ParagraphProperties();
|
||||
|
||||
var pPrChange = new ParagraphPropertiesChange
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// Store previous paragraph properties (before the change)
|
||||
// Example: was left-aligned before changing to whatever the current alignment is
|
||||
var previousPPr = new ParagraphPropertiesExtended();
|
||||
previousPPr.Append(new Justification { Val = JustificationValues.Left });
|
||||
pPrChange.Append(previousPPr);
|
||||
|
||||
para.ParagraphProperties.Append(pPrChange);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 6. InsertTableRowInsertion — table revision marks
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Marks a table row as a tracked insertion.
|
||||
///
|
||||
/// Table-level track changes use TableRowProperties with InsertedMathControl
|
||||
/// mapped from w:trPr/w:ins — indicating the entire row was inserted.
|
||||
///
|
||||
/// Structure:
|
||||
/// <w:tr>
|
||||
/// <w:trPr>
|
||||
/// <w:ins w:id="5" w:author="John" w:date="..."/>
|
||||
/// </w:trPr>
|
||||
/// <w:tc>...</w:tc>
|
||||
/// </w:tr>
|
||||
/// </summary>
|
||||
public static void InsertTableRowInsertion(TableRow row, string author)
|
||||
{
|
||||
row.TableRowProperties ??= new TableRowProperties();
|
||||
|
||||
var inserted = new Inserted
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
row.TableRowProperties.Append(inserted);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 7. AcceptAllRevisions — accept all tracked changes
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Programmatically accepts all tracked changes in the document body.
|
||||
///
|
||||
/// For insertions (w:ins): unwrap the content (keep the runs, remove the w:ins wrapper)
|
||||
/// For deletions (w:del): remove the entire element (the deleted text disappears)
|
||||
/// For formatting changes: remove the rPrChange/pPrChange (keep new formatting)
|
||||
/// For table row insertions: remove the w:ins from trPr
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════════════╗
|
||||
/// ║ Process deletions before insertions to avoid invalidating ║
|
||||
/// ║ element references. Always call .ToList() before ║
|
||||
/// ║ iterating to avoid modifying the collection during ║
|
||||
/// ║ enumeration. ║
|
||||
/// ╚══════════════════════════════════════════════════════════════╝
|
||||
/// </summary>
|
||||
public static void AcceptAllRevisions(Body body)
|
||||
{
|
||||
// 1. Accept deletions — remove the w:del and all its content
|
||||
foreach (var del in body.Descendants<DeletedRun>().ToList())
|
||||
{
|
||||
del.Remove();
|
||||
}
|
||||
|
||||
// 2. Accept insertions — unwrap w:ins, keeping child runs in place
|
||||
foreach (var ins in body.Descendants<InsertedRun>().ToList())
|
||||
{
|
||||
var parent = ins.Parent;
|
||||
if (parent == null) continue;
|
||||
|
||||
// Move all child elements before the ins element, then remove ins
|
||||
var children = ins.ChildElements.ToList();
|
||||
foreach (var child in children)
|
||||
{
|
||||
child.Remove();
|
||||
ins.InsertBeforeSelf(child);
|
||||
}
|
||||
ins.Remove();
|
||||
}
|
||||
|
||||
// 3. Accept formatting changes — remove rPrChange (keep new formatting)
|
||||
foreach (var rPrChange in body.Descendants<RunPropertiesChange>().ToList())
|
||||
{
|
||||
rPrChange.Remove();
|
||||
}
|
||||
|
||||
// 4. Accept paragraph formatting changes
|
||||
foreach (var pPrChange in body.Descendants<ParagraphPropertiesChange>().ToList())
|
||||
{
|
||||
pPrChange.Remove();
|
||||
}
|
||||
|
||||
// 5. Accept table row insertions — remove w:ins from trPr
|
||||
foreach (var inserted in body.Descendants<TableRowProperties>()
|
||||
.SelectMany(trPr => trPr.Elements<Inserted>()).ToList())
|
||||
{
|
||||
inserted.Remove();
|
||||
}
|
||||
|
||||
// 6. Accept MoveFrom/MoveTo — keep MoveTo content, remove MoveFrom
|
||||
foreach (var moveFrom in body.Descendants<MoveFromRun>().ToList())
|
||||
{
|
||||
moveFrom.Remove();
|
||||
}
|
||||
foreach (var moveTo in body.Descendants<MoveToRun>().ToList())
|
||||
{
|
||||
var parent = moveTo.Parent;
|
||||
if (parent == null) continue;
|
||||
var children = moveTo.ChildElements.ToList();
|
||||
foreach (var child in children)
|
||||
{
|
||||
child.Remove();
|
||||
moveTo.InsertBeforeSelf(child);
|
||||
}
|
||||
moveTo.Remove();
|
||||
}
|
||||
|
||||
// 7. Remove move range markers
|
||||
foreach (var marker in body.Descendants<MoveFromRangeStart>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveFromRangeEnd>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveToRangeStart>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveToRangeEnd>().ToList()) marker.Remove();
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 8. RejectAllRevisions — reject all tracked changes
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Programmatically rejects all tracked changes in the document body.
|
||||
///
|
||||
/// For insertions (w:ins): remove the entire element (the inserted text disappears)
|
||||
/// For deletions (w:del): unwrap the content and convert w:delText back to w:t
|
||||
/// (the "deleted" text is restored)
|
||||
/// For formatting changes: restore old formatting from rPrChange/pPrChange
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════════════╗
|
||||
/// ║ When rejecting deletions, you MUST convert w:delText back ║
|
||||
/// ║ to w:t. Leaving w:delText in a non-deleted run causes ║
|
||||
/// ║ the text to be invisible in Word. ║
|
||||
/// ╚══════════════════════════════════════════════════════════════╝
|
||||
/// </summary>
|
||||
public static void RejectAllRevisions(Body body)
|
||||
{
|
||||
// 1. Reject insertions — remove the entire w:ins and its content
|
||||
foreach (var ins in body.Descendants<InsertedRun>().ToList())
|
||||
{
|
||||
ins.Remove();
|
||||
}
|
||||
|
||||
// 2. Reject deletions — restore deleted text by unwrapping w:del
|
||||
// and converting w:delText back to w:t
|
||||
foreach (var del in body.Descendants<DeletedRun>().ToList())
|
||||
{
|
||||
var parent = del.Parent;
|
||||
if (parent == null) continue;
|
||||
|
||||
// Convert DeletedText -> Text in each run inside the deletion
|
||||
foreach (var run in del.Elements<Run>().ToList())
|
||||
{
|
||||
foreach (var delText in run.Elements<DeletedText>().ToList())
|
||||
{
|
||||
// IMPORTANT: convert w:delText back to w:t
|
||||
var text = new Text(delText.Text ?? "") { Space = SpaceProcessingModeValues.Preserve };
|
||||
delText.InsertAfterSelf(text);
|
||||
delText.Remove();
|
||||
}
|
||||
}
|
||||
|
||||
// Unwrap — move children before the del element
|
||||
var children = del.ChildElements.ToList();
|
||||
foreach (var child in children)
|
||||
{
|
||||
child.Remove();
|
||||
del.InsertBeforeSelf(child);
|
||||
}
|
||||
del.Remove();
|
||||
}
|
||||
|
||||
// 3. Reject formatting changes — restore old RunProperties
|
||||
foreach (var rPrChange in body.Descendants<RunPropertiesChange>().ToList())
|
||||
{
|
||||
var runProperties = rPrChange.Parent as RunProperties;
|
||||
if (runProperties == null) continue;
|
||||
|
||||
// Get the previous (old) formatting
|
||||
var previousRPr = rPrChange.GetFirstChild<PreviousRunProperties>();
|
||||
if (previousRPr != null)
|
||||
{
|
||||
// Remove current formatting (except the rPrChange itself)
|
||||
var currentProps = runProperties.ChildElements
|
||||
.Where(c => c is not RunPropertiesChange).ToList();
|
||||
foreach (var prop in currentProps)
|
||||
{
|
||||
prop.Remove();
|
||||
}
|
||||
|
||||
// Restore old formatting from PreviousRunProperties
|
||||
foreach (var oldProp in previousRPr.ChildElements.ToList())
|
||||
{
|
||||
oldProp.Remove();
|
||||
runProperties.Append(oldProp);
|
||||
}
|
||||
}
|
||||
rPrChange.Remove();
|
||||
}
|
||||
|
||||
// 4. Reject paragraph formatting changes — restore old ParagraphProperties
|
||||
foreach (var pPrChange in body.Descendants<ParagraphPropertiesChange>().ToList())
|
||||
{
|
||||
var paragraphProperties = pPrChange.Parent as ParagraphProperties;
|
||||
if (paragraphProperties == null) continue;
|
||||
|
||||
var previousPPr = pPrChange.GetFirstChild<ParagraphPropertiesExtended>();
|
||||
if (previousPPr != null)
|
||||
{
|
||||
var currentProps = paragraphProperties.ChildElements
|
||||
.Where(c => c is not ParagraphPropertiesChange).ToList();
|
||||
foreach (var prop in currentProps)
|
||||
{
|
||||
prop.Remove();
|
||||
}
|
||||
foreach (var oldProp in previousPPr.ChildElements.ToList())
|
||||
{
|
||||
oldProp.Remove();
|
||||
paragraphProperties.Append(oldProp);
|
||||
}
|
||||
}
|
||||
pPrChange.Remove();
|
||||
}
|
||||
|
||||
// 5. Reject table row insertions — remove the entire row
|
||||
foreach (var row in body.Descendants<TableRow>().ToList())
|
||||
{
|
||||
var trPr = row.TableRowProperties;
|
||||
if (trPr?.GetFirstChild<Inserted>() != null)
|
||||
{
|
||||
row.Remove();
|
||||
}
|
||||
}
|
||||
|
||||
// 6. Reject MoveFrom/MoveTo — keep MoveFrom content (original position), remove MoveTo
|
||||
foreach (var moveTo in body.Descendants<MoveToRun>().ToList())
|
||||
{
|
||||
moveTo.Remove();
|
||||
}
|
||||
foreach (var moveFrom in body.Descendants<MoveFromRun>().ToList())
|
||||
{
|
||||
var parent = moveFrom.Parent;
|
||||
if (parent == null) continue;
|
||||
|
||||
// Convert any DeletedText back to Text in MoveFrom runs
|
||||
foreach (var run in moveFrom.Elements<Run>().ToList())
|
||||
{
|
||||
foreach (var delText in run.Elements<DeletedText>().ToList())
|
||||
{
|
||||
var text = new Text(delText.Text ?? "") { Space = SpaceProcessingModeValues.Preserve };
|
||||
delText.InsertAfterSelf(text);
|
||||
delText.Remove();
|
||||
}
|
||||
}
|
||||
|
||||
var children = moveFrom.ChildElements.ToList();
|
||||
foreach (var child in children)
|
||||
{
|
||||
child.Remove();
|
||||
moveFrom.InsertBeforeSelf(child);
|
||||
}
|
||||
moveFrom.Remove();
|
||||
}
|
||||
|
||||
// 7. Remove move range markers
|
||||
foreach (var marker in body.Descendants<MoveFromRangeStart>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveFromRangeEnd>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveToRangeStart>().ToList()) marker.Remove();
|
||||
foreach (var marker in body.Descendants<MoveToRangeEnd>().ToList()) marker.Remove();
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 9. InsertMoveFromTo — MoveFrom + MoveTo blocks
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Creates a tracked move operation (text moved from one location to another).
|
||||
///
|
||||
/// A move consists of:
|
||||
/// - MoveFromRangeStart/End markers around the original location
|
||||
/// - MoveFrom (w:moveFrom) containing the original text with w:delText
|
||||
/// - MoveToRangeStart/End markers around the new location
|
||||
/// - MoveTo (w:moveTo) containing the moved text with w:t
|
||||
/// - Both share the same name attribute to link them
|
||||
///
|
||||
/// ╔══════════════════════════════════════════════════════════════╗
|
||||
/// ║ MoveFrom uses w:delText (like w:del — text is "leaving") ║
|
||||
/// ║ MoveTo uses w:t (like w:ins — text is "arriving") ║
|
||||
/// ╚══════════════════════════════════════════════════════════════╝
|
||||
/// </summary>
|
||||
public static void InsertMoveFromTo(Body body, string movedText, string author)
|
||||
{
|
||||
string moveId = GenerateRevisionId();
|
||||
string moveId2 = GenerateRevisionId();
|
||||
string moveName = "move" + moveId;
|
||||
|
||||
// ── MoveFrom paragraph (original location — text shown with strikethrough) ──
|
||||
var moveFromPara = new Paragraph();
|
||||
|
||||
moveFromPara.Append(new MoveFromRangeStart
|
||||
{
|
||||
Id = moveId,
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Name = moveName
|
||||
});
|
||||
|
||||
var moveFrom = new MoveFromRun
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// MoveFrom uses DeletedText (w:delText), NOT Text (w:t)
|
||||
// The text is visually struck through in Word
|
||||
moveFrom.Append(new Run(
|
||||
new DeletedText(movedText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
moveFromPara.Append(moveFrom);
|
||||
moveFromPara.Append(new MoveFromRangeEnd { Id = moveId });
|
||||
|
||||
body.Append(moveFromPara);
|
||||
|
||||
// ── MoveTo paragraph (destination — text shown with double underline) ──
|
||||
var moveToPara = new Paragraph();
|
||||
|
||||
moveToPara.Append(new MoveToRangeStart
|
||||
{
|
||||
Id = moveId2,
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow,
|
||||
Name = moveName
|
||||
});
|
||||
|
||||
var moveTo = new MoveToRun
|
||||
{
|
||||
Id = GenerateRevisionId(),
|
||||
Author = author,
|
||||
Date = DateTime.UtcNow
|
||||
};
|
||||
|
||||
// MoveTo uses Text (w:t), NOT DeletedText (w:delText)
|
||||
// The text is visually double-underlined in green in Word
|
||||
moveTo.Append(new Run(
|
||||
new Text(movedText) { Space = SpaceProcessingModeValues.Preserve }));
|
||||
|
||||
moveToPara.Append(moveTo);
|
||||
moveToPara.Append(new MoveToRangeEnd { Id = moveId2 });
|
||||
|
||||
body.Append(moveToPara);
|
||||
}
|
||||
|
||||
// ──────────────────────────────────────────────
|
||||
// 10. GenerateRevisionId — unique ID pattern
|
||||
// ──────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Generates a unique revision ID string.
|
||||
///
|
||||
/// Revision IDs (w:id) must be unique across ALL revision elements in the document:
|
||||
/// ins, del, rPrChange, pPrChange, moveFrom, moveTo, table row ins/del, etc.
|
||||
///
|
||||
/// Word uses simple incrementing integers starting from 0.
|
||||
/// When programmatically adding revisions to an existing document,
|
||||
/// first scan for the maximum existing ID and start from there.
|
||||
///
|
||||
/// For new documents, a simple counter suffices.
|
||||
/// For existing documents, use:
|
||||
/// int maxId = body.Descendants()
|
||||
/// .SelectMany(e => e.GetAttributes())
|
||||
/// .Where(a => a.LocalName == "id")
|
||||
/// .Select(a => int.TryParse(a.Value, out int v) ? v : 0)
|
||||
/// .DefaultIfEmpty(0)
|
||||
/// .Max();
|
||||
/// </summary>
|
||||
public static string GenerateRevisionId()
|
||||
{
|
||||
return Interlocked.Increment(ref s_revisionCounter).ToString();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
using DocumentFormat.OpenXml.Wordprocessing;
|
||||
|
||||
namespace DocxToolkit.Core.Typography;
|
||||
|
||||
/// <summary>
|
||||
/// CJK mixed typography helpers for East Asian font and paragraph configuration.
|
||||
/// </summary>
|
||||
public static class CjkHelper
|
||||
{
|
||||
public const string DefaultSimplifiedChinese = "SimSun";
|
||||
public const string DefaultJapanese = "MS Mincho";
|
||||
public const string DefaultKorean = "Batang";
|
||||
|
||||
/// <summary>
|
||||
/// Sets the East Asia font on run properties.
|
||||
/// </summary>
|
||||
public static void SetEastAsiaFont(RunProperties rPr, string fontName)
|
||||
{
|
||||
var fonts = rPr.RunFonts;
|
||||
if (fonts == null)
|
||||
{
|
||||
fonts = new RunFonts();
|
||||
rPr.RunFonts = fonts;
|
||||
}
|
||||
fonts.EastAsia = fontName;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Configures CJK-appropriate paragraph properties.
|
||||
/// </summary>
|
||||
public static void ConfigureCjkParagraph(ParagraphProperties pPr)
|
||||
{
|
||||
// Enable word wrap for CJK
|
||||
pPr.WordWrap = new WordWrap { Val = true };
|
||||
// Allow auto space between CJK and Latin/numbers
|
||||
pPr.AutoSpaceDE = new AutoSpaceDE { Val = true };
|
||||
pPr.AutoSpaceDN = new AutoSpaceDN { Val = true };
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
namespace DocxToolkit.Core.Typography;
|
||||
|
||||
public record FontConfig(
|
||||
string BodyFont,
|
||||
string HeadingFont,
|
||||
double BodySize,
|
||||
double Heading1Size,
|
||||
double Heading2Size,
|
||||
double Heading3Size,
|
||||
double Heading4Size,
|
||||
double Heading5Size,
|
||||
double Heading6Size,
|
||||
double LineSpacing);
|
||||
|
||||
/// <summary>
|
||||
/// Default font configurations by document type.
|
||||
/// </summary>
|
||||
public static class FontDefaults
|
||||
{
|
||||
public static FontConfig Report => new("Calibri", "Calibri Light", 11.0, 26.0, 20.0, 16.0, 14.0, 12.0, 11.0, 1.15);
|
||||
public static FontConfig Letter => new("Calibri", "Calibri", 11.0, 16.0, 14.0, 12.0, 11.0, 11.0, 11.0, 1.0);
|
||||
public static FontConfig Memo => new("Arial", "Arial", 11.0, 16.0, 14.0, 12.0, 11.0, 11.0, 11.0, 1.15);
|
||||
public static FontConfig Academic => new("Times New Roman", "Times New Roman", 12.0, 16.0, 14.0, 13.0, 12.0, 12.0, 12.0, 2.0);
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
namespace DocxToolkit.Core.Typography;
|
||||
|
||||
public record PageSize(int WidthDxa, int HeightDxa);
|
||||
public record MarginConfig(int TopDxa, int BottomDxa, int LeftDxa, int RightDxa);
|
||||
|
||||
/// <summary>
|
||||
/// Standard page sizes and margin presets in DXA units.
|
||||
/// </summary>
|
||||
public static class PageSizes
|
||||
{
|
||||
public static PageSize Letter => new(12240, 15840); // 8.5 x 11 inches
|
||||
public static PageSize A4 => new(11906, 16838); // 210 x 297 mm
|
||||
public static PageSize Legal => new(12240, 20160); // 8.5 x 14 inches
|
||||
public static PageSize A3 => new(16838, 23811); // 297 x 420 mm
|
||||
public static PageSize A5 => new(8391, 11906); // 148 x 210 mm
|
||||
|
||||
public static MarginConfig StandardMargins => new(1440, 1440, 1440, 1440); // 1 inch all
|
||||
public static MarginConfig NarrowMargins => new(720, 720, 720, 720); // 0.5 inch all
|
||||
public static MarginConfig WideMargins => new(1440, 1440, 2160, 2160); // 1" top/bottom, 1.5" left/right
|
||||
}
|
||||
@@ -0,0 +1,224 @@
|
||||
using System.IO.Compression;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Validation;
|
||||
|
||||
public class BusinessRuleValidator
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
private static readonly XNamespace R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
|
||||
private static readonly XNamespace WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
|
||||
private static readonly XNamespace A = "http://schemas.openxmlformats.org/drawingml/2006/main";
|
||||
|
||||
private const int MinMarginDxa = 360; // 0.25 inch
|
||||
private const int MaxMarginDxa = 4320; // 3 inches
|
||||
private const int MinBodyFontHps = 16; // 8pt
|
||||
private const int MaxBodyFontHps = 144; // 72pt
|
||||
private const int MinHeadingFontHps = 20; // 10pt
|
||||
private const int MaxHeadingFontHps = 192; // 96pt
|
||||
|
||||
public ValidationResult Validate(string docxPath)
|
||||
{
|
||||
var result = new ValidationResult();
|
||||
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var docEntry = zip.GetEntry("word/document.xml")
|
||||
?? throw new InvalidOperationException("Missing word/document.xml");
|
||||
|
||||
var doc = LoadXml(docEntry);
|
||||
var body = doc.Root?.Element(W + "body");
|
||||
if (body == null)
|
||||
{
|
||||
result.Errors.Add(Error("Document has no body element"));
|
||||
return result;
|
||||
}
|
||||
|
||||
ValidateMargins(body, result);
|
||||
ValidateFontSizes(body, result);
|
||||
ValidateHeadingHierarchy(body, result);
|
||||
ValidateTableColumnWidths(body, result);
|
||||
ValidateRelationships(zip, doc, result);
|
||||
ValidateComments(zip, result);
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
private void ValidateMargins(XElement body, ValidationResult result)
|
||||
{
|
||||
foreach (var sectPr in body.Descendants(W + "sectPr"))
|
||||
{
|
||||
var pgMar = sectPr.Element(W + "pgMar");
|
||||
if (pgMar == null) continue;
|
||||
|
||||
foreach (var attr in new[] { "top", "bottom", "left", "right" })
|
||||
{
|
||||
var val = (string?)pgMar.Attribute(W + attr);
|
||||
if (val != null && int.TryParse(val, out var dxa))
|
||||
{
|
||||
var absDxa = Math.Abs(dxa);
|
||||
if (absDxa < MinMarginDxa)
|
||||
result.Errors.Add(Error($"Margin '{attr}' is {absDxa} DXA ({absDxa / 1440.0:F2}\"), below minimum {MinMarginDxa} DXA"));
|
||||
if (absDxa > MaxMarginDxa)
|
||||
result.Warnings.Add(Warning($"Margin '{attr}' is {absDxa} DXA ({absDxa / 1440.0:F2}\"), above maximum {MaxMarginDxa} DXA"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void ValidateFontSizes(XElement body, ValidationResult result)
|
||||
{
|
||||
foreach (var p in body.Descendants(W + "p"))
|
||||
{
|
||||
var pStyle = p.Element(W + "pPr")?.Element(W + "pStyle")?.Attribute(W + "val")?.Value;
|
||||
bool isHeading = pStyle?.StartsWith("Heading", StringComparison.OrdinalIgnoreCase) == true;
|
||||
|
||||
foreach (var rPr in p.Descendants(W + "rPr"))
|
||||
{
|
||||
var szEl = rPr.Element(W + "sz");
|
||||
var val = (string?)szEl?.Attribute(W + "val");
|
||||
if (val != null && int.TryParse(val, out var hps))
|
||||
{
|
||||
int min = isHeading ? MinHeadingFontHps : MinBodyFontHps;
|
||||
int max = isHeading ? MaxHeadingFontHps : MaxBodyFontHps;
|
||||
if (hps < min || hps > max)
|
||||
result.Warnings.Add(Warning($"Font size {hps / 2.0}pt is outside {(isHeading ? "heading" : "body")} range ({min / 2}-{max / 2}pt)"));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void ValidateHeadingHierarchy(XElement body, ValidationResult result)
|
||||
{
|
||||
int lastLevel = 0;
|
||||
foreach (var p in body.Descendants(W + "p"))
|
||||
{
|
||||
var pStyle = p.Element(W + "pPr")?.Element(W + "pStyle")?.Attribute(W + "val")?.Value;
|
||||
if (pStyle == null) continue;
|
||||
|
||||
int level = 0;
|
||||
if (pStyle.StartsWith("Heading", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
var numPart = pStyle.AsSpan(7);
|
||||
if (int.TryParse(numPart, out var parsed)) level = parsed;
|
||||
}
|
||||
|
||||
if (level > 0)
|
||||
{
|
||||
if (lastLevel > 0 && level > lastLevel + 1)
|
||||
result.Warnings.Add(Warning($"Heading level skips from {lastLevel} to {level} (missing Heading{lastLevel + 1})"));
|
||||
lastLevel = level;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void ValidateTableColumnWidths(XElement body, ValidationResult result)
|
||||
{
|
||||
var sectPr = body.Element(W + "sectPr");
|
||||
if (sectPr == null) return;
|
||||
|
||||
var pgSz = sectPr.Element(W + "pgSz");
|
||||
var pgMar = sectPr.Element(W + "pgMar");
|
||||
if (pgSz == null || pgMar == null) return;
|
||||
|
||||
if (!int.TryParse((string?)pgSz.Attribute(W + "w"), out var pageWidth)) return;
|
||||
int.TryParse((string?)pgMar.Attribute(W + "left"), out var marginLeft);
|
||||
int.TryParse((string?)pgMar.Attribute(W + "right"), out var marginRight);
|
||||
var contentWidth = pageWidth - marginLeft - marginRight;
|
||||
|
||||
int tableIndex = 0;
|
||||
foreach (var tbl in body.Descendants(W + "tbl"))
|
||||
{
|
||||
tableIndex++;
|
||||
var firstRow = tbl.Element(W + "tr");
|
||||
if (firstRow == null) continue;
|
||||
|
||||
int totalWidth = 0;
|
||||
foreach (var tc in firstRow.Elements(W + "tc"))
|
||||
{
|
||||
var tcW = tc.Element(W + "tcPr")?.Element(W + "tcW");
|
||||
var w = (string?)tcW?.Attribute(W + "w");
|
||||
if (w != null && int.TryParse(w, out var cellWidth))
|
||||
totalWidth += cellWidth;
|
||||
}
|
||||
|
||||
if (totalWidth > 0)
|
||||
{
|
||||
var tolerance = contentWidth * 0.02;
|
||||
if (Math.Abs(totalWidth - contentWidth) > tolerance)
|
||||
result.Warnings.Add(Warning($"Table {tableIndex}: column widths sum to {totalWidth} DXA but content width is {contentWidth} DXA"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void ValidateRelationships(ZipArchive zip, XDocument doc, ValidationResult result)
|
||||
{
|
||||
var relsEntry = zip.GetEntry("word/_rels/document.xml.rels");
|
||||
if (relsEntry == null) return;
|
||||
|
||||
var relDoc = LoadXml(relsEntry);
|
||||
var ns = relDoc.Root?.Name.Namespace ?? XNamespace.None;
|
||||
var definedIds = new HashSet<string>();
|
||||
|
||||
foreach (var rel in relDoc.Descendants(ns + "Relationship"))
|
||||
{
|
||||
var id = (string?)rel.Attribute("Id");
|
||||
if (id != null) definedIds.Add(id);
|
||||
}
|
||||
|
||||
var referencedIds = new HashSet<string>();
|
||||
foreach (var el in doc.Descendants())
|
||||
{
|
||||
var rid = (string?)el.Attribute(R + "id") ?? (string?)el.Attribute(R + "embed");
|
||||
if (rid != null) referencedIds.Add(rid);
|
||||
}
|
||||
|
||||
foreach (var id in referencedIds.Except(definedIds))
|
||||
result.Errors.Add(Error($"Reference r:id='{id}' has no matching relationship"));
|
||||
|
||||
foreach (var id in definedIds.Except(referencedIds))
|
||||
result.Warnings.Add(Warning($"Orphaned relationship: Id='{id}' is defined but never referenced"));
|
||||
}
|
||||
|
||||
private void ValidateComments(ZipArchive zip, ValidationResult result)
|
||||
{
|
||||
var commentFiles = new[] { "word/comments.xml", "word/commentsExtended.xml", "word/commentsIds.xml", "word/commentsExtensible.xml" };
|
||||
var existing = commentFiles.Where(f => zip.GetEntry(f) != null).ToList();
|
||||
|
||||
if (existing.Count > 0 && existing.Count < 4)
|
||||
{
|
||||
var missing = commentFiles.Except(existing);
|
||||
result.Warnings.Add(Warning($"Comments partially present. Missing: {string.Join(", ", missing)}"));
|
||||
}
|
||||
|
||||
if (zip.GetEntry("word/comments.xml") is { } commentsEntry)
|
||||
{
|
||||
var commentsDoc = LoadXml(commentsEntry);
|
||||
var commentIds = commentsDoc.Descendants(W + "comment")
|
||||
.Select(c => (string?)c.Attribute(W + "id"))
|
||||
.Where(id => id != null)
|
||||
.ToHashSet();
|
||||
|
||||
if (zip.GetEntry("word/commentsExtended.xml") is { } extEntry)
|
||||
{
|
||||
var W15 = XNamespace.Get("http://schemas.microsoft.com/office/word/2012/wordml");
|
||||
var extDoc = LoadXml(extEntry);
|
||||
var extIds = extDoc.Descendants(W15 + "commentEx")
|
||||
.Select(c => (string?)c.Attribute(W15 + "paraId"))
|
||||
.Where(id => id != null)
|
||||
.ToHashSet();
|
||||
|
||||
if (commentIds.Count > 0 && extIds.Count == 0)
|
||||
result.Warnings.Add(Warning("comments.xml has entries but commentsExtended.xml has none"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private static XDocument LoadXml(ZipArchiveEntry entry)
|
||||
{
|
||||
using var stream = entry.Open();
|
||||
return XDocument.Load(stream);
|
||||
}
|
||||
|
||||
private static ValidationError Error(string msg) => new() { Message = msg, Severity = "Error" };
|
||||
private static ValidationError Warning(string msg) => new() { Message = msg, Severity = "Warning" };
|
||||
}
|
||||
@@ -0,0 +1,148 @@
|
||||
using System.IO.Compression;
|
||||
using System.Xml.Linq;
|
||||
|
||||
namespace DocxToolkit.Core.Validation;
|
||||
|
||||
public class GateCheckResult
|
||||
{
|
||||
public bool Passed => Violations.Count == 0;
|
||||
public List<string> Violations { get; set; } = new();
|
||||
}
|
||||
|
||||
public class GateCheckValidator
|
||||
{
|
||||
private static readonly XNamespace W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||
|
||||
public GateCheckResult Validate(string outputDocxPath, string templateDocxPath)
|
||||
{
|
||||
var result = new GateCheckResult();
|
||||
|
||||
var templateStyles = ExtractStyles(templateDocxPath);
|
||||
var outputStyles = ExtractStyles(outputDocxPath);
|
||||
var templateSectPr = ExtractSectionProperties(templateDocxPath);
|
||||
var outputSectPr = ExtractSectionProperties(outputDocxPath);
|
||||
|
||||
// All template styles must exist in output
|
||||
foreach (var style in templateStyles)
|
||||
{
|
||||
if (!outputStyles.Contains(style))
|
||||
result.Violations.Add($"Missing style: '{style}' defined in template but absent from output");
|
||||
}
|
||||
|
||||
// Page margins must match
|
||||
if (templateSectPr.Margins != null && outputSectPr.Margins != null)
|
||||
{
|
||||
var tm = templateSectPr.Margins;
|
||||
var om = outputSectPr.Margins;
|
||||
if (tm.Top != om.Top || tm.Bottom != om.Bottom || tm.Left != om.Left || tm.Right != om.Right)
|
||||
result.Violations.Add($"Page margins mismatch: template=({tm.Top},{tm.Bottom},{tm.Left},{tm.Right}) output=({om.Top},{om.Bottom},{om.Left},{om.Right})");
|
||||
}
|
||||
|
||||
// Page size must match
|
||||
if (templateSectPr.PageWidth != outputSectPr.PageWidth || templateSectPr.PageHeight != outputSectPr.PageHeight)
|
||||
result.Violations.Add($"Page size mismatch: template=({templateSectPr.PageWidth}x{templateSectPr.PageHeight}) output=({outputSectPr.PageWidth}x{outputSectPr.PageHeight})");
|
||||
|
||||
// Default font must match
|
||||
var templateFont = ExtractDefaultFont(templateDocxPath);
|
||||
var outputFont = ExtractDefaultFont(outputDocxPath);
|
||||
if (templateFont != null && outputFont != null && templateFont != outputFont)
|
||||
result.Violations.Add($"Default font mismatch: template='{templateFont}' output='{outputFont}'");
|
||||
|
||||
// Heading font hierarchy consistency
|
||||
ValidateHeadingFontHierarchy(outputDocxPath, result);
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
private HashSet<string> ExtractStyles(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/styles.xml");
|
||||
if (entry == null) return new();
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
return doc.Descendants(W + "style")
|
||||
.Select(s => (string?)s.Attribute(W + "styleId"))
|
||||
.Where(id => id != null)
|
||||
.ToHashSet()!;
|
||||
}
|
||||
|
||||
private record SectionProps(int PageWidth, int PageHeight, MarginInfo? Margins);
|
||||
private record MarginInfo(int Top, int Bottom, int Left, int Right);
|
||||
|
||||
private SectionProps ExtractSectionProperties(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/document.xml")!;
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
|
||||
var sectPr = doc.Descendants(W + "sectPr").LastOrDefault();
|
||||
if (sectPr == null) return new(0, 0, null);
|
||||
|
||||
int.TryParse((string?)sectPr.Element(W + "pgSz")?.Attribute(W + "w"), out var pw);
|
||||
int.TryParse((string?)sectPr.Element(W + "pgSz")?.Attribute(W + "h"), out var ph);
|
||||
|
||||
var pgMar = sectPr.Element(W + "pgMar");
|
||||
MarginInfo? margins = null;
|
||||
if (pgMar != null)
|
||||
{
|
||||
int.TryParse((string?)pgMar.Attribute(W + "top"), out var t);
|
||||
int.TryParse((string?)pgMar.Attribute(W + "bottom"), out var b);
|
||||
int.TryParse((string?)pgMar.Attribute(W + "left"), out var l);
|
||||
int.TryParse((string?)pgMar.Attribute(W + "right"), out var r);
|
||||
margins = new(t, b, l, r);
|
||||
}
|
||||
|
||||
return new(pw, ph, margins);
|
||||
}
|
||||
|
||||
private string? ExtractDefaultFont(string docxPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/styles.xml");
|
||||
if (entry == null) return null;
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
|
||||
var defaultStyle = doc.Descendants(W + "style")
|
||||
.FirstOrDefault(s => (string?)s.Attribute(W + "type") == "paragraph"
|
||||
&& (string?)s.Attribute(W + "default") == "1");
|
||||
|
||||
return (string?)defaultStyle?.Descendants(W + "rFonts").FirstOrDefault()?.Attribute(W + "ascii");
|
||||
}
|
||||
|
||||
private void ValidateHeadingFontHierarchy(string docxPath, GateCheckResult result)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/styles.xml");
|
||||
if (entry == null) return;
|
||||
|
||||
using var stream = entry.Open();
|
||||
var doc = XDocument.Load(stream);
|
||||
|
||||
var headingSizes = new SortedDictionary<int, int>();
|
||||
foreach (var style in doc.Descendants(W + "style"))
|
||||
{
|
||||
var id = (string?)style.Attribute(W + "styleId");
|
||||
if (id == null || !id.StartsWith("Heading", StringComparison.OrdinalIgnoreCase)) continue;
|
||||
|
||||
var numPart = id.AsSpan(7);
|
||||
if (!int.TryParse(numPart, out var level)) continue;
|
||||
|
||||
var sz = (string?)style.Descendants(W + "sz").FirstOrDefault()?.Attribute(W + "val");
|
||||
if (sz != null && int.TryParse(sz, out var hps))
|
||||
headingSizes[level] = hps;
|
||||
}
|
||||
|
||||
int prevSize = int.MaxValue;
|
||||
foreach (var (level, size) in headingSizes)
|
||||
{
|
||||
if (size > prevSize)
|
||||
result.Violations.Add($"Heading{level} ({size / 2}pt) is larger than a higher-level heading ({prevSize / 2}pt)");
|
||||
prevSize = size;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
namespace DocxToolkit.Core.Validation;
|
||||
|
||||
public class ValidationResult
|
||||
{
|
||||
public bool IsValid => Errors.Count == 0;
|
||||
public List<ValidationError> Errors { get; set; } = new();
|
||||
public List<ValidationError> Warnings { get; set; } = new();
|
||||
|
||||
public void Merge(ValidationResult other)
|
||||
{
|
||||
Errors.AddRange(other.Errors);
|
||||
Warnings.AddRange(other.Warnings);
|
||||
}
|
||||
}
|
||||
|
||||
public class ValidationError
|
||||
{
|
||||
public int LineNumber { get; set; }
|
||||
public int LinePosition { get; set; }
|
||||
public string Element { get; set; } = "";
|
||||
public string Message { get; set; } = "";
|
||||
public string Severity { get; set; } = "Error";
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
using System.IO.Compression;
|
||||
using System.Xml;
|
||||
using System.Xml.Schema;
|
||||
|
||||
namespace DocxToolkit.Core.Validation;
|
||||
|
||||
public class XsdValidator
|
||||
{
|
||||
public ValidationResult Validate(string docxPath, string xsdPath)
|
||||
{
|
||||
using var zip = ZipFile.OpenRead(docxPath);
|
||||
var entry = zip.GetEntry("word/document.xml")
|
||||
?? throw new InvalidOperationException("DOCX does not contain word/document.xml");
|
||||
|
||||
using var stream = entry.Open();
|
||||
using var reader = new StreamReader(stream);
|
||||
var xmlContent = reader.ReadToEnd();
|
||||
|
||||
return ValidateXml(xmlContent, xsdPath);
|
||||
}
|
||||
|
||||
public ValidationResult ValidateXml(string xmlContent, string xsdPath)
|
||||
{
|
||||
var result = new ValidationResult();
|
||||
var settings = new XmlReaderSettings();
|
||||
|
||||
var schemaSet = new XmlSchemaSet();
|
||||
schemaSet.Add(null, xsdPath);
|
||||
settings.Schemas = schemaSet;
|
||||
settings.ValidationType = ValidationType.Schema;
|
||||
settings.ValidationFlags |= XmlSchemaValidationFlags.ReportValidationWarnings;
|
||||
|
||||
settings.ValidationEventHandler += (sender, e) =>
|
||||
{
|
||||
var error = new ValidationError
|
||||
{
|
||||
LineNumber = e.Exception?.LineNumber ?? 0,
|
||||
LinePosition = e.Exception?.LinePosition ?? 0,
|
||||
Message = e.Message,
|
||||
Severity = e.Severity == XmlSeverityType.Warning ? "Warning" : "Error"
|
||||
};
|
||||
|
||||
if (e.Severity == XmlSeverityType.Warning)
|
||||
result.Warnings.Add(error);
|
||||
else
|
||||
result.Errors.Add(error);
|
||||
};
|
||||
|
||||
using var stringReader = new StringReader(xmlContent);
|
||||
using var xmlReader = XmlReader.Create(stringReader, settings);
|
||||
|
||||
try
|
||||
{
|
||||
while (xmlReader.Read()) { }
|
||||
}
|
||||
catch (XmlException ex)
|
||||
{
|
||||
result.Errors.Add(new ValidationError
|
||||
{
|
||||
LineNumber = ex.LineNumber,
|
||||
LinePosition = ex.LinePosition,
|
||||
Message = $"XML parse error: {ex.Message}",
|
||||
Severity = "Error"
|
||||
});
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
<Solution>
|
||||
<Project Path="DocxToolkit.Cli/DocxToolkit.Cli.csproj" />
|
||||
<Project Path="DocxToolkit.Core/DocxToolkit.Core.csproj" />
|
||||
</Solution>
|
||||
197
agent/skills-disabled/SoftwareCopyright-Skill/software-copyright-materials/vendor/docx-toolkit/scripts/env_check.sh
vendored
Executable file
197
agent/skills-disabled/SoftwareCopyright-Skill/software-copyright-materials/vendor/docx-toolkit/scripts/env_check.sh
vendored
Executable file
@@ -0,0 +1,197 @@
|
||||
#!/usr/bin/env bash
|
||||
# docx-toolkit Quick Environment Check
|
||||
# Cross-platform: macOS, Linux, WSL, Git Bash
|
||||
# Run this BEFORE any docx-toolkit operation. Use setup.sh for initial installation.
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
DOTNET_DIR="$SCRIPT_DIR/dotnet"
|
||||
CLI_PROJECT="$DOTNET_DIR/DocxToolkit.Cli/DocxToolkit.Cli.csproj"
|
||||
|
||||
# Force English output for dotnet CLI
|
||||
export DOTNET_CLI_UI_LANGUAGE=en
|
||||
|
||||
echo "=== DOCX Environment Check ==="
|
||||
echo ""
|
||||
|
||||
STATUS="READY"
|
||||
WARNINGS=0
|
||||
|
||||
# --- Detect platform ---
|
||||
OS="unknown"
|
||||
case "$(uname -s)" in
|
||||
Darwin) OS="macos" ;;
|
||||
Linux)
|
||||
OS="linux"
|
||||
grep -qi microsoft /proc/version 2>/dev/null && OS="wsl"
|
||||
;;
|
||||
MINGW*|MSYS*|CYGWIN*) OS="windows-shell" ;;
|
||||
esac
|
||||
|
||||
# --- Critical: .NET SDK ---
|
||||
if ! command -v dotnet &>/dev/null; then
|
||||
printf "[FAIL] %-14s not found\n" "dotnet"
|
||||
echo ""
|
||||
echo " .NET SDK is REQUIRED. Install it:"
|
||||
case "$OS" in
|
||||
macos) echo " brew install --cask dotnet-sdk" ;;
|
||||
linux|wsl)
|
||||
echo " # Option 1: Microsoft install script"
|
||||
echo " wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh"
|
||||
echo " chmod +x /tmp/dotnet-install.sh && /tmp/dotnet-install.sh --channel 8.0"
|
||||
echo " # Option 2 (Ubuntu/Debian): sudo apt-get install -y dotnet-sdk-8.0"
|
||||
;;
|
||||
windows-shell) echo " winget install Microsoft.DotNet.SDK.8" ;;
|
||||
*) echo " https://dotnet.microsoft.com/download" ;;
|
||||
esac
|
||||
echo ""
|
||||
echo " Or run the full setup: bash scripts/setup.sh"
|
||||
echo ""
|
||||
STATUS="NOT READY"
|
||||
else
|
||||
local_ver=$(dotnet --version 2>/dev/null || echo "0.0.0")
|
||||
local_major="${local_ver%%.*}"
|
||||
if [ "$local_major" -ge 8 ] 2>/dev/null; then
|
||||
printf "[OK] %-14s %s (>= 8.0)\n" "dotnet" "$local_ver"
|
||||
else
|
||||
printf "[FAIL] %-14s %s (requires >= 8.0)\n" "dotnet" "$local_ver"
|
||||
STATUS="NOT READY"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Critical: NuGet packages ---
|
||||
if [ -f "$CLI_PROJECT" ]; then
|
||||
if [ -f "$DOTNET_DIR/DocxToolkit.Cli/bin/Debug/net10.0/DocxToolkit.Cli.dll" ] || \
|
||||
[ -f "$DOTNET_DIR/DocxToolkit.Cli/bin/Debug/net8.0/DocxToolkit.Cli.dll" ]; then
|
||||
printf "[OK] %-14s built\n" "project"
|
||||
else
|
||||
# Try restore + build
|
||||
if dotnet restore "$CLI_PROJECT" --verbosity quiet &>/dev/null; then
|
||||
printf "[OK] %-14s packages restored\n" "nuget"
|
||||
if dotnet build "$CLI_PROJECT" --verbosity quiet --no-restore &>/dev/null; then
|
||||
printf "[OK] %-14s build succeeded\n" "project"
|
||||
else
|
||||
printf "[FAIL] %-14s build failed (run: dotnet build %s)\n" "project" "$CLI_PROJECT"
|
||||
STATUS="NOT READY"
|
||||
fi
|
||||
else
|
||||
printf "[FAIL] %-14s restore failed\n" "nuget"
|
||||
echo ""
|
||||
echo " Common causes:"
|
||||
echo " - No internet access (NuGet needs to download packages)"
|
||||
echo " - Corporate proxy blocking nuget.org"
|
||||
echo " - SSL certificate issues (try: dotnet nuget list source)"
|
||||
echo ""
|
||||
STATUS="NOT READY"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
printf "[FAIL] %-14s project not found: %s\n" "project" "$CLI_PROJECT"
|
||||
STATUS="NOT READY"
|
||||
fi
|
||||
|
||||
# --- Optional: pandoc ---
|
||||
if command -v pandoc &>/dev/null; then
|
||||
pandoc_ver=$(pandoc --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 || echo "?")
|
||||
printf "[OK] %-14s %s (content preview)\n" "pandoc" "$pandoc_ver"
|
||||
else
|
||||
printf "[WARN] %-14s not found — docx_preview.sh will use fallback\n" "pandoc"
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
case "$OS" in
|
||||
macos) echo " Install: brew install pandoc" ;;
|
||||
linux|wsl) echo " Install: sudo apt-get install pandoc # or dnf/pacman" ;;
|
||||
windows-shell) echo " Install: winget install JohnMacFarlane.Pandoc" ;;
|
||||
esac
|
||||
fi
|
||||
|
||||
# --- Optional: LibreOffice ---
|
||||
if command -v soffice &>/dev/null; then
|
||||
soffice_ver=$(soffice --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 || echo "?")
|
||||
printf "[OK] %-14s %s (.doc conversion)\n" "soffice" "$soffice_ver"
|
||||
else
|
||||
# Check common paths
|
||||
soffice_found=false
|
||||
for p in \
|
||||
"/Applications/LibreOffice.app/Contents/MacOS/soffice" \
|
||||
"/usr/lib/libreoffice/program/soffice" \
|
||||
"/snap/bin/libreoffice" \
|
||||
"/opt/libreoffice/program/soffice"; do
|
||||
if [ -x "$p" ]; then
|
||||
printf "[OK] %-14s found at %s (.doc conversion)\n" "soffice" "$p"
|
||||
soffice_found=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
if ! $soffice_found; then
|
||||
printf "[WARN] %-14s not found — .doc files cannot be converted\n" "soffice"
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
case "$OS" in
|
||||
macos) echo " Install: brew install --cask libreoffice" ;;
|
||||
linux|wsl) echo " Install: sudo apt-get install libreoffice-core" ;;
|
||||
windows-shell) echo " Install: winget install TheDocumentFoundation.LibreOffice" ;;
|
||||
esac
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Optional: zip/unzip ---
|
||||
zip_ok=true
|
||||
if ! command -v zip &>/dev/null; then
|
||||
printf "[WARN] %-14s not found (optional, .NET handles DOCX natively)\n" "zip"
|
||||
zip_ok=false
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
fi
|
||||
if ! command -v unzip &>/dev/null; then
|
||||
printf "[WARN] %-14s not found (optional, .NET handles DOCX natively)\n" "unzip"
|
||||
zip_ok=false
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
fi
|
||||
if $zip_ok; then
|
||||
printf "[OK] %-14s available\n" "zip/unzip"
|
||||
fi
|
||||
|
||||
# --- Encoding check ---
|
||||
current_lang="${LANG:-}"
|
||||
if [ -n "$current_lang" ] && echo "$current_lang" | grep -qi "utf-8\|utf8"; then
|
||||
printf "[OK] %-14s %s\n" "locale" "$current_lang"
|
||||
else
|
||||
if [ -z "$current_lang" ]; then
|
||||
printf "[WARN] %-14s LANG not set (CJK text may have issues)\n" "locale"
|
||||
else
|
||||
printf "[WARN] %-14s %s (not UTF-8, CJK text may have issues)\n" "locale" "$current_lang"
|
||||
fi
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
echo " Fix: export LANG=en_US.UTF-8"
|
||||
fi
|
||||
|
||||
# --- Shell script permissions ---
|
||||
perm_issues=0
|
||||
for s in "$SCRIPT_DIR"/*.sh; do
|
||||
if [ -f "$s" ] && [ ! -x "$s" ]; then
|
||||
perm_issues=$((perm_issues + 1))
|
||||
fi
|
||||
done
|
||||
if [ "$perm_issues" -gt 0 ]; then
|
||||
printf "[WARN] %-14s %d script(s) not executable\n" "permissions" "$perm_issues"
|
||||
echo " Fix: chmod +x scripts/*.sh"
|
||||
WARNINGS=$((WARNINGS + 1))
|
||||
else
|
||||
printf "[OK] %-14s all scripts executable\n" "permissions"
|
||||
fi
|
||||
|
||||
# --- Result ---
|
||||
echo ""
|
||||
if [ "$STATUS" = "READY" ]; then
|
||||
if [ "$WARNINGS" -gt 0 ]; then
|
||||
echo "Status: READY (with $WARNINGS warning(s) — optional features may be limited)"
|
||||
else
|
||||
echo "Status: READY"
|
||||
fi
|
||||
else
|
||||
echo "Status: NOT READY"
|
||||
echo ""
|
||||
echo "Critical dependencies missing. Run the full setup:"
|
||||
echo " bash scripts/setup.sh # macOS / Linux / WSL"
|
||||
echo " powershell scripts/setup.ps1 # Windows PowerShell"
|
||||
exit 1
|
||||
fi
|
||||
@@ -0,0 +1,275 @@
|
||||
# docx-toolkit Environment Setup & Initialization Script (Windows PowerShell)
|
||||
# Supports: Windows 10/11, Windows Server 2019+
|
||||
# License: MIT
|
||||
#Requires -Version 5.1
|
||||
|
||||
param(
|
||||
[switch]$Minimal,
|
||||
[switch]$SkipVerify,
|
||||
[switch]$Help
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$ProjectDir = Split-Path -Parent $ScriptDir
|
||||
$DotnetDir = Join-Path $ScriptDir "dotnet"
|
||||
$CliProject = Join-Path $DotnetDir "DocxToolkit.Cli/DocxToolkit.Cli.csproj"
|
||||
$LogFile = Join-Path $ProjectDir ".setup.log"
|
||||
|
||||
# --- Output Helpers ---
|
||||
function Log { Write-Host "[OK] $args" -ForegroundColor Green }
|
||||
function Warn { Write-Host "[WARN] $args" -ForegroundColor Yellow }
|
||||
function Fail { Write-Host "[FAIL] $args" -ForegroundColor Red }
|
||||
function Info { Write-Host "[INFO] $args" -ForegroundColor Cyan }
|
||||
function Step { Write-Host "`n=== $args ===" -ForegroundColor Blue }
|
||||
|
||||
if ($Help) {
|
||||
Write-Host @"
|
||||
Usage: setup.ps1 [options]
|
||||
-Minimal Only install critical dependencies (skip pandoc, soffice, fonts)
|
||||
-SkipVerify Skip the verification test at the end
|
||||
-Help Show this help
|
||||
"@
|
||||
exit 0
|
||||
}
|
||||
|
||||
Write-Host "============================================"
|
||||
Write-Host " docx-toolkit Setup & Initialization (Windows)"
|
||||
Write-Host " $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
|
||||
Write-Host "============================================"
|
||||
|
||||
"" | Set-Content $LogFile
|
||||
|
||||
# --- Detect Package Manager ---
|
||||
$HasWinget = $null -ne (Get-Command winget -ErrorAction SilentlyContinue)
|
||||
$HasChoco = $null -ne (Get-Command choco -ErrorAction SilentlyContinue)
|
||||
$HasScoop = $null -ne (Get-Command scoop -ErrorAction SilentlyContinue)
|
||||
|
||||
if ($HasWinget) { Info "Package manager: winget" }
|
||||
elseif ($HasChoco) { Info "Package manager: chocolatey" }
|
||||
elseif ($HasScoop) { Info "Package manager: scoop" }
|
||||
else { Warn "No package manager found (winget/choco/scoop). Manual install may be needed." }
|
||||
|
||||
# --- .NET SDK ---
|
||||
Step "Checking .NET SDK"
|
||||
|
||||
$dotnetCmd = Get-Command dotnet -ErrorAction SilentlyContinue
|
||||
if ($dotnetCmd) {
|
||||
$dotnetVer = & dotnet --version 2>$null
|
||||
$majorVer = [int]($dotnetVer -split '\.')[0]
|
||||
if ($majorVer -ge 8) {
|
||||
Log "dotnet $dotnetVer already installed (>= 8.0 OK)"
|
||||
} else {
|
||||
Warn "dotnet $dotnetVer found but < 8.0, upgrading..."
|
||||
$dotnetCmd = $null
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $dotnetCmd -or $majorVer -lt 8) {
|
||||
Info "Installing .NET SDK..."
|
||||
if ($HasWinget) {
|
||||
winget install Microsoft.DotNet.SDK.8 --accept-source-agreements --accept-package-agreements 2>>$LogFile
|
||||
} elseif ($HasChoco) {
|
||||
choco install dotnet-sdk -y 2>>$LogFile
|
||||
} elseif ($HasScoop) {
|
||||
scoop install dotnet-sdk 2>>$LogFile
|
||||
} else {
|
||||
Fail "Cannot auto-install .NET SDK. Download from: https://dotnet.microsoft.com/download"
|
||||
Fail "After installing, restart PowerShell and re-run this script."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Refresh PATH
|
||||
$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
|
||||
|
||||
if (Get-Command dotnet -ErrorAction SilentlyContinue) {
|
||||
Log "dotnet $(dotnet --version) installed"
|
||||
} else {
|
||||
Fail "dotnet installation failed. Restart PowerShell and retry, or install manually."
|
||||
exit 1
|
||||
}
|
||||
}
|
||||
|
||||
# --- Pandoc (Optional) ---
|
||||
if (-not $Minimal) {
|
||||
Step "Checking pandoc (optional: content preview)"
|
||||
|
||||
if (Get-Command pandoc -ErrorAction SilentlyContinue) {
|
||||
$pandocVer = (pandoc --version | Select-Object -First 1) -replace '.*?(\d+\.\d+(\.\d+)?)', '$1'
|
||||
Log "pandoc $pandocVer already installed"
|
||||
} else {
|
||||
Info "Installing pandoc..."
|
||||
if ($HasWinget) { winget install JohnMacFarlane.Pandoc --accept-source-agreements 2>>$LogFile }
|
||||
elseif ($HasChoco) { choco install pandoc -y 2>>$LogFile }
|
||||
elseif ($HasScoop) { scoop install pandoc 2>>$LogFile }
|
||||
else { Warn "Install pandoc manually: https://pandoc.org/installing.html" }
|
||||
|
||||
$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
|
||||
|
||||
if (Get-Command pandoc -ErrorAction SilentlyContinue) {
|
||||
Log "pandoc installed"
|
||||
} else {
|
||||
Warn "pandoc not found after install (optional, will degrade gracefully)"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# --- LibreOffice (Optional) ---
|
||||
if (-not $Minimal) {
|
||||
Step "Checking LibreOffice/soffice (optional: .doc conversion)"
|
||||
|
||||
$sofficeFound = $false
|
||||
|
||||
# Check common Windows install paths
|
||||
$sofficePaths = @(
|
||||
"C:\Program Files\LibreOffice\program\soffice.exe",
|
||||
"C:\Program Files (x86)\LibreOffice\program\soffice.exe",
|
||||
"${env:LOCALAPPDATA}\Programs\LibreOffice\program\soffice.exe"
|
||||
)
|
||||
|
||||
if (Get-Command soffice -ErrorAction SilentlyContinue) {
|
||||
Log "soffice found in PATH"
|
||||
$sofficeFound = $true
|
||||
} else {
|
||||
foreach ($p in $sofficePaths) {
|
||||
if (Test-Path $p) {
|
||||
Log "soffice found at: $p"
|
||||
Info "Tip: Add to PATH: `$env:Path += ';$(Split-Path $p)'"
|
||||
$sofficeFound = $true
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $sofficeFound) {
|
||||
Info "Installing LibreOffice (this may take a while)..."
|
||||
if ($HasWinget) { winget install TheDocumentFoundation.LibreOffice --accept-source-agreements 2>>$LogFile }
|
||||
elseif ($HasChoco) { choco install libreoffice-fresh -y 2>>$LogFile }
|
||||
else { Warn "Install LibreOffice manually: https://www.libreoffice.org/download/" }
|
||||
}
|
||||
}
|
||||
|
||||
# --- NuGet Configuration ---
|
||||
Step "Checking NuGet configuration"
|
||||
|
||||
$nugetSources = & dotnet nuget list source 2>$null
|
||||
if ($nugetSources -match "nuget.org") {
|
||||
Log "nuget.org source is configured"
|
||||
} else {
|
||||
Warn "nuget.org not in sources. Adding..."
|
||||
& dotnet nuget add source "https://api.nuget.org/v3/index.json" --name "nuget.org" 2>>$LogFile
|
||||
}
|
||||
|
||||
# --- Encoding Check ---
|
||||
Step "Checking console encoding"
|
||||
|
||||
$currentEncoding = [Console]::OutputEncoding.EncodingName
|
||||
if ($currentEncoding -match "UTF-8|Unicode") {
|
||||
Log "Console encoding: $currentEncoding (UTF-8 compatible)"
|
||||
} else {
|
||||
Warn "Console encoding: $currentEncoding (may cause issues with CJK text)"
|
||||
Info "To fix: [Console]::OutputEncoding = [System.Text.Encoding]::UTF8"
|
||||
Info "Or set system-wide: Settings > Time & Language > Language > Administrative > Change system locale > Beta: UTF-8"
|
||||
# Apply for this session
|
||||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||||
Log "Set UTF-8 encoding for this session"
|
||||
}
|
||||
|
||||
# --- Font Check ---
|
||||
if (-not $Minimal) {
|
||||
Step "Checking fonts"
|
||||
|
||||
$fonts = [System.Drawing.FontFamily]::Families 2>$null
|
||||
if ($fonts) {
|
||||
$fontNames = $fonts | ForEach-Object { $_.Name }
|
||||
$hasCalibri = $fontNames -contains "Calibri"
|
||||
$hasTimes = $fontNames -contains "Times New Roman"
|
||||
$hasCJK = ($fontNames | Where-Object { $_ -match "SimSun|Microsoft YaHei|MS Mincho|Malgun Gothic" }).Count -gt 0
|
||||
|
||||
if ($hasCalibri) { Log "Western fonts: Calibri found" } else { Warn "Calibri not found (install Microsoft Office or fonts)" }
|
||||
if ($hasTimes) { Log "Western fonts: Times New Roman found" } else { Warn "Times New Roman not found" }
|
||||
if ($hasCJK) { Log "CJK fonts: available" } else { Warn "CJK fonts not found (install language packs for Chinese/Japanese/Korean)" }
|
||||
} else {
|
||||
Info "Cannot enumerate fonts (System.Drawing not loaded). Skipping font check."
|
||||
}
|
||||
}
|
||||
|
||||
# --- Build Project ---
|
||||
Step "Building docx-toolkit .NET project"
|
||||
|
||||
if (-not (Test-Path $CliProject)) {
|
||||
Fail "CLI project file not found: $CliProject"
|
||||
exit 1
|
||||
}
|
||||
|
||||
Push-Location $DotnetDir
|
||||
|
||||
Info "Restoring NuGet packages..."
|
||||
$restoreResult = & dotnet restore $CliProject --verbosity quiet 2>&1
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
Fail "NuGet restore failed:"
|
||||
$restoreResult | ForEach-Object { Fail " $_" }
|
||||
Fail "Common causes:"
|
||||
Fail " - No internet (NuGet needs to download packages)"
|
||||
Fail " - Corporate proxy/firewall blocking nuget.org"
|
||||
Fail " - Insufficient disk space"
|
||||
Fail "Try: dotnet restore $CliProject --verbosity detailed"
|
||||
Pop-Location
|
||||
exit 1
|
||||
}
|
||||
Log "NuGet packages restored"
|
||||
|
||||
Info "Building project..."
|
||||
$buildResult = & dotnet build $CliProject --verbosity quiet --no-restore 2>&1
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
Fail "Build failed:"
|
||||
$buildResult | ForEach-Object { Fail " $_" }
|
||||
Pop-Location
|
||||
exit 1
|
||||
}
|
||||
Log "Project built successfully"
|
||||
|
||||
Pop-Location
|
||||
|
||||
# --- Verification ---
|
||||
if (-not $SkipVerify) {
|
||||
Step "Verification Test"
|
||||
|
||||
$testOutput = Join-Path $env:TEMP "docx-toolkit-setup-test-$PID.docx"
|
||||
|
||||
Info "Creating a test document..."
|
||||
Push-Location $DotnetDir
|
||||
$testResult = & dotnet run --project DocxToolkit.Cli -- create --type report --output $testOutput --title "Setup Test" 2>&1
|
||||
$testExitCode = $LASTEXITCODE
|
||||
Pop-Location
|
||||
|
||||
if ($testExitCode -eq 0 -and (Test-Path $testOutput)) {
|
||||
Log "Test document created: $testOutput"
|
||||
|
||||
if (Get-Command pandoc -ErrorAction SilentlyContinue) {
|
||||
$preview = & pandoc -f docx -t plain $testOutput 2>$null | Select-Object -First 3
|
||||
if ($preview) { Log "Preview working: `"$($preview -join ' ')`"" }
|
||||
}
|
||||
|
||||
Remove-Item $testOutput -Force
|
||||
Log "Test passed - docx-toolkit is ready to use!"
|
||||
} else {
|
||||
Fail "Test document creation failed. Output:"
|
||||
$testResult | ForEach-Object { Fail " $_" }
|
||||
}
|
||||
}
|
||||
|
||||
# --- Summary ---
|
||||
Step "Setup Complete"
|
||||
|
||||
Write-Host ""
|
||||
Write-Host " Environment: Windows $([System.Environment]::OSVersion.Version)"
|
||||
Write-Host " .NET SDK: $(dotnet --version 2>$null)"
|
||||
$pandocInfo = if (Get-Command pandoc -ErrorAction SilentlyContinue) { pandoc --version | Select-Object -First 1 } else { "not installed (optional)" }
|
||||
Write-Host " pandoc: $pandocInfo"
|
||||
Write-Host " Project: $DotnetDir"
|
||||
Write-Host ""
|
||||
Write-Host " Usage:"
|
||||
Write-Host " dotnet run --project $DotnetDir\DocxToolkit.Cli -- create --type report --output my_report.docx"
|
||||
Write-Host ""
|
||||
Write-Host " Log file: $LogFile"
|
||||
505
agent/skills-disabled/SoftwareCopyright-Skill/software-copyright-materials/vendor/docx-toolkit/scripts/setup.sh
vendored
Executable file
505
agent/skills-disabled/SoftwareCopyright-Skill/software-copyright-materials/vendor/docx-toolkit/scripts/setup.sh
vendored
Executable file
@@ -0,0 +1,505 @@
|
||||
#!/usr/bin/env bash
|
||||
# docx-toolkit Environment Setup & Initialization Script
|
||||
# Supports: macOS (Homebrew), Linux (apt/dnf/pacman), WSL
|
||||
# License: MIT
|
||||
set -euo pipefail
|
||||
|
||||
# Force English output for dotnet CLI
|
||||
export DOTNET_CLI_UI_LANGUAGE=en
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
DOTNET_DIR="$SCRIPT_DIR/dotnet"
|
||||
CLI_PROJECT="$DOTNET_DIR/DocxToolkit.Cli/DocxToolkit.Cli.csproj"
|
||||
LOG_FILE="$PROJECT_DIR/.setup.log"
|
||||
|
||||
# --- Colors ---
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m'
|
||||
|
||||
log() { echo -e "${GREEN}[OK]${NC} $*"; }
|
||||
warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
|
||||
fail() { echo -e "${RED}[FAIL]${NC} $*"; }
|
||||
info() { echo -e "${BLUE}[INFO]${NC} $*"; }
|
||||
step() { echo -e "\n${BLUE}=== $* ===${NC}"; }
|
||||
|
||||
# --- Detect OS & Package Manager ---
|
||||
detect_platform() {
|
||||
OS="unknown"
|
||||
PKG_MGR="unknown"
|
||||
ARCH="$(uname -m)"
|
||||
|
||||
case "$(uname -s)" in
|
||||
Darwin)
|
||||
OS="macos"
|
||||
if command -v brew &>/dev/null; then
|
||||
PKG_MGR="brew"
|
||||
else
|
||||
PKG_MGR="none"
|
||||
fi
|
||||
;;
|
||||
Linux)
|
||||
OS="linux"
|
||||
if [ -f /etc/os-release ]; then
|
||||
. /etc/os-release
|
||||
case "$ID" in
|
||||
ubuntu|debian|linuxmint|pop)
|
||||
PKG_MGR="apt"
|
||||
;;
|
||||
fedora|rhel|centos|rocky|alma)
|
||||
PKG_MGR="dnf"
|
||||
;;
|
||||
arch|manjaro|endeavouros)
|
||||
PKG_MGR="pacman"
|
||||
;;
|
||||
opensuse*|sles)
|
||||
PKG_MGR="zypper"
|
||||
;;
|
||||
alpine)
|
||||
PKG_MGR="apk"
|
||||
;;
|
||||
*)
|
||||
PKG_MGR="unknown"
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
# Detect WSL
|
||||
if grep -qi microsoft /proc/version 2>/dev/null; then
|
||||
OS="wsl"
|
||||
fi
|
||||
;;
|
||||
MINGW*|MSYS*|CYGWIN*)
|
||||
OS="windows-git-bash"
|
||||
PKG_MGR="none"
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Platform: $OS ($ARCH), Package Manager: $PKG_MGR"
|
||||
}
|
||||
|
||||
# --- .NET SDK Installation ---
|
||||
install_dotnet() {
|
||||
step "Checking .NET SDK"
|
||||
|
||||
if command -v dotnet &>/dev/null; then
|
||||
local ver
|
||||
ver=$(dotnet --version 2>/dev/null || echo "0")
|
||||
local major="${ver%%.*}"
|
||||
if [ "$major" -ge 8 ] 2>/dev/null; then
|
||||
log "dotnet $ver already installed (>= 8.0 OK)"
|
||||
return 0
|
||||
else
|
||||
warn "dotnet $ver found but < 8.0, upgrading..."
|
||||
fi
|
||||
fi
|
||||
|
||||
info "Installing .NET SDK..."
|
||||
case "$PKG_MGR" in
|
||||
brew)
|
||||
brew install --cask dotnet-sdk
|
||||
;;
|
||||
apt)
|
||||
# Microsoft package repo for Ubuntu/Debian
|
||||
if ! dpkg -l dotnet-sdk-8.0 &>/dev/null 2>&1; then
|
||||
info "Adding Microsoft package repository..."
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y -qq wget apt-transport-https
|
||||
wget -q "https://dot.net/v1/dotnet-install.sh" -O /tmp/dotnet-install.sh
|
||||
chmod +x /tmp/dotnet-install.sh
|
||||
/tmp/dotnet-install.sh --channel 8.0 --install-dir "$HOME/.dotnet"
|
||||
export PATH="$HOME/.dotnet:$PATH"
|
||||
echo 'export PATH="$HOME/.dotnet:$PATH"' >> "$HOME/.bashrc"
|
||||
fi
|
||||
;;
|
||||
dnf)
|
||||
sudo dnf install -y dotnet-sdk-8.0
|
||||
;;
|
||||
pacman)
|
||||
sudo pacman -S --noconfirm dotnet-sdk
|
||||
;;
|
||||
zypper)
|
||||
sudo zypper install -y dotnet-sdk-8.0
|
||||
;;
|
||||
apk)
|
||||
apk add --no-cache dotnet8-sdk
|
||||
;;
|
||||
none)
|
||||
if [ "$OS" = "windows-git-bash" ]; then
|
||||
fail "On Windows, install .NET SDK from: https://dotnet.microsoft.com/download"
|
||||
fail "Then restart your terminal and re-run this script."
|
||||
return 1
|
||||
fi
|
||||
# Fallback: use Microsoft install script
|
||||
info "Using Microsoft install script..."
|
||||
wget -q "https://dot.net/v1/dotnet-install.sh" -O /tmp/dotnet-install.sh || \
|
||||
curl -sSL "https://dot.net/v1/dotnet-install.sh" -o /tmp/dotnet-install.sh
|
||||
chmod +x /tmp/dotnet-install.sh
|
||||
/tmp/dotnet-install.sh --channel 8.0 --install-dir "$HOME/.dotnet"
|
||||
export PATH="$HOME/.dotnet:$PATH"
|
||||
echo 'export PATH="$HOME/.dotnet:$PATH"' >> "$HOME/.bashrc"
|
||||
;;
|
||||
*)
|
||||
warn "Unknown package manager. Install .NET SDK manually: https://dotnet.microsoft.com/download"
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
|
||||
# Verify
|
||||
if command -v dotnet &>/dev/null; then
|
||||
log "dotnet $(dotnet --version) installed"
|
||||
else
|
||||
fail "dotnet installation failed. Install manually: https://dotnet.microsoft.com/download"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# --- Pandoc Installation (Optional) ---
|
||||
install_pandoc() {
|
||||
step "Checking pandoc (optional: content preview)"
|
||||
|
||||
if command -v pandoc &>/dev/null; then
|
||||
log "pandoc $(pandoc --version | head -1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?') already installed"
|
||||
return 0
|
||||
fi
|
||||
|
||||
info "Installing pandoc..."
|
||||
case "$PKG_MGR" in
|
||||
brew) brew install pandoc ;;
|
||||
apt) sudo apt-get install -y -qq pandoc ;;
|
||||
dnf) sudo dnf install -y pandoc ;;
|
||||
pacman) sudo pacman -S --noconfirm pandoc ;;
|
||||
zypper) sudo zypper install -y pandoc ;;
|
||||
apk) apk add --no-cache pandoc ;;
|
||||
*)
|
||||
warn "Cannot auto-install pandoc. Install manually: https://pandoc.org/installing.html"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
|
||||
if command -v pandoc &>/dev/null; then
|
||||
log "pandoc installed"
|
||||
else
|
||||
warn "pandoc installation failed (optional, will degrade gracefully)"
|
||||
fi
|
||||
}
|
||||
|
||||
# --- LibreOffice Installation (Optional) ---
|
||||
install_soffice() {
|
||||
step "Checking LibreOffice/soffice (optional: .doc conversion)"
|
||||
|
||||
if command -v soffice &>/dev/null; then
|
||||
log "soffice already installed"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# Also check common install paths
|
||||
local soffice_paths=(
|
||||
"/usr/bin/soffice"
|
||||
"/usr/local/bin/soffice"
|
||||
"/opt/libreoffice/program/soffice"
|
||||
"/snap/bin/libreoffice"
|
||||
"/Applications/LibreOffice.app/Contents/MacOS/soffice"
|
||||
)
|
||||
for p in "${soffice_paths[@]}"; do
|
||||
if [ -x "$p" ]; then
|
||||
log "soffice found at $p"
|
||||
if [ "$OS" = "macos" ] && [ "$p" = "/Applications/LibreOffice.app/Contents/MacOS/soffice" ]; then
|
||||
info "Tip: Add to PATH: ln -s '$p' /usr/local/bin/soffice"
|
||||
fi
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
|
||||
info "Installing LibreOffice (this may take a while)..."
|
||||
case "$PKG_MGR" in
|
||||
brew) brew install --cask libreoffice ;;
|
||||
apt) sudo apt-get install -y -qq libreoffice-core ;;
|
||||
dnf) sudo dnf install -y libreoffice-core ;;
|
||||
pacman) sudo pacman -S --noconfirm libreoffice-still ;;
|
||||
zypper) sudo zypper install -y libreoffice ;;
|
||||
apk) apk add --no-cache libreoffice ;;
|
||||
*)
|
||||
warn "Cannot auto-install LibreOffice. Install manually: https://www.libreoffice.org/download/"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
|
||||
if command -v soffice &>/dev/null; then
|
||||
log "soffice installed"
|
||||
else
|
||||
warn "soffice not found after install (optional, .doc conversion unavailable)"
|
||||
fi
|
||||
}
|
||||
|
||||
# --- zip/unzip ---
|
||||
install_zip_tools() {
|
||||
step "Checking zip/unzip"
|
||||
|
||||
local need_zip=false need_unzip=false
|
||||
command -v zip &>/dev/null && log "zip already installed" || need_zip=true
|
||||
command -v unzip &>/dev/null && log "unzip already installed" || need_unzip=true
|
||||
|
||||
if ! $need_zip && ! $need_unzip; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
info "Installing zip/unzip..."
|
||||
case "$PKG_MGR" in
|
||||
brew) brew install zip unzip 2>/dev/null || true ;;
|
||||
apt) sudo apt-get install -y -qq zip unzip ;;
|
||||
dnf) sudo dnf install -y zip unzip ;;
|
||||
pacman) sudo pacman -S --noconfirm zip unzip ;;
|
||||
zypper) sudo zypper install -y zip unzip ;;
|
||||
apk) apk add --no-cache zip unzip ;;
|
||||
*) warn "Install zip/unzip manually (optional, .NET handles DOCX natively)" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# --- .NET Project Build ---
|
||||
build_project() {
|
||||
step "Building docx-toolkit .NET project"
|
||||
|
||||
if [ ! -f "$CLI_PROJECT" ]; then
|
||||
fail "CLI project file not found: $CLI_PROJECT"
|
||||
return 1
|
||||
fi
|
||||
|
||||
cd "$DOTNET_DIR"
|
||||
|
||||
info "Restoring NuGet packages..."
|
||||
if ! dotnet restore "$CLI_PROJECT" --verbosity quiet 2>>"$LOG_FILE"; then
|
||||
fail "NuGet restore failed. Check network and $LOG_FILE for details."
|
||||
fail "Common causes:"
|
||||
fail " - No internet access (NuGet needs to download packages)"
|
||||
fail " - Corporate proxy blocking nuget.org"
|
||||
fail " - Disk space insufficient"
|
||||
echo ""
|
||||
fail "Try manually: dotnet restore $CLI_PROJECT --verbosity detailed"
|
||||
return 1
|
||||
fi
|
||||
log "NuGet packages restored"
|
||||
|
||||
info "Building project..."
|
||||
if ! dotnet build "$CLI_PROJECT" --verbosity quiet --no-restore 2>>"$LOG_FILE"; then
|
||||
fail "Build failed. Check $LOG_FILE for details."
|
||||
fail "Try manually: dotnet build $CLI_PROJECT --verbosity normal"
|
||||
return 1
|
||||
fi
|
||||
log "Project built successfully"
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
}
|
||||
|
||||
# --- Shell Script Permissions ---
|
||||
fix_permissions() {
|
||||
step "Setting script permissions"
|
||||
|
||||
local scripts=(
|
||||
"$SCRIPT_DIR/env_check.sh"
|
||||
"$SCRIPT_DIR/docx_preview.sh"
|
||||
"$SCRIPT_DIR/doc_to_docx.sh"
|
||||
"$SCRIPT_DIR/setup.sh"
|
||||
)
|
||||
|
||||
for s in "${scripts[@]}"; do
|
||||
if [ -f "$s" ]; then
|
||||
chmod +x "$s"
|
||||
log "chmod +x $(basename "$s")"
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
# --- NuGet Proxy / Certificate Issues (Corporate Environments) ---
|
||||
check_nuget_config() {
|
||||
step "Checking NuGet configuration"
|
||||
|
||||
local nuget_config="$HOME/.nuget/NuGet/NuGet.Config"
|
||||
if [ -f "$nuget_config" ]; then
|
||||
log "NuGet config exists: $nuget_config"
|
||||
else
|
||||
info "No custom NuGet config found (using defaults)"
|
||||
fi
|
||||
|
||||
# Test NuGet connectivity
|
||||
if dotnet nuget list source 2>/dev/null | grep -q "nuget.org"; then
|
||||
log "nuget.org source is configured"
|
||||
else
|
||||
warn "nuget.org not in sources. Adding..."
|
||||
dotnet nuget add source "https://api.nuget.org/v3/index.json" --name "nuget.org" 2>/dev/null || true
|
||||
fi
|
||||
}
|
||||
|
||||
# --- Locale / Encoding Check ---
|
||||
check_locale() {
|
||||
step "Checking locale and encoding"
|
||||
|
||||
local current_lang="${LANG:-not set}"
|
||||
local current_lc="${LC_ALL:-not set}"
|
||||
|
||||
if echo "$current_lang" | grep -qi "utf-8\|utf8"; then
|
||||
log "Locale supports UTF-8: LANG=$current_lang"
|
||||
else
|
||||
warn "Locale may not support UTF-8: LANG=$current_lang"
|
||||
warn "CJK document processing requires UTF-8. Set: export LANG=en_US.UTF-8"
|
||||
if [ "$OS" = "linux" ] || [ "$OS" = "wsl" ]; then
|
||||
info "To fix permanently: sudo locale-gen en_US.UTF-8 && sudo update-locale LANG=en_US.UTF-8"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# --- Font Check (for CJK and professional documents) ---
|
||||
check_fonts() {
|
||||
step "Checking fonts for document rendering"
|
||||
|
||||
if [ "$OS" = "macos" ]; then
|
||||
# macOS has good CJK support built-in
|
||||
log "macOS: built-in CJK font support (PingFang, Hiragino, Apple SD Gothic)"
|
||||
log "macOS: built-in Western fonts (Helvetica, Times, Calibri via Office)"
|
||||
if [ -d "/Applications/Microsoft Word.app" ] || [ -d "/Applications/Microsoft Office" ]; then
|
||||
log "Microsoft Office fonts available (Calibri, Cambria, etc.)"
|
||||
else
|
||||
warn "Microsoft Office not installed — Calibri/Cambria fonts may be missing"
|
||||
info "Documents will render with fallback fonts on this machine"
|
||||
info "Recipients with Office installed will see correct fonts"
|
||||
fi
|
||||
elif [ "$OS" = "linux" ] || [ "$OS" = "wsl" ]; then
|
||||
# Check for key font packages
|
||||
local missing_fonts=()
|
||||
|
||||
if ! fc-list 2>/dev/null | grep -qi "liberation\|times new roman\|calibri"; then
|
||||
missing_fonts+=("Western: liberation-fonts or msttcorefonts")
|
||||
fi
|
||||
|
||||
if ! fc-list 2>/dev/null | grep -qi "noto.*cjk\|wqy\|simsun\|pingfang"; then
|
||||
missing_fonts+=("CJK: noto-fonts-cjk or wqy-microhei")
|
||||
fi
|
||||
|
||||
if [ ${#missing_fonts[@]} -eq 0 ]; then
|
||||
log "Font support looks good"
|
||||
else
|
||||
warn "Missing fonts may affect document rendering:"
|
||||
for f in "${missing_fonts[@]}"; do
|
||||
warn " - $f"
|
||||
done
|
||||
info "Install fonts:"
|
||||
case "$PKG_MGR" in
|
||||
apt)
|
||||
info " sudo apt-get install -y fonts-liberation fonts-noto-cjk"
|
||||
info " # For MS core fonts: sudo apt-get install -y ttf-mscorefonts-installer"
|
||||
;;
|
||||
dnf)
|
||||
info " sudo dnf install -y liberation-fonts google-noto-sans-cjk-fonts"
|
||||
;;
|
||||
pacman)
|
||||
info " sudo pacman -S ttf-liberation noto-fonts-cjk"
|
||||
;;
|
||||
*)
|
||||
info " Install Liberation Fonts and Noto CJK fonts for your distribution"
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# --- Verification Run ---
|
||||
verify_installation() {
|
||||
step "Verification Test"
|
||||
|
||||
local test_output="/tmp/docx-toolkit-setup-test-$$.docx"
|
||||
|
||||
info "Creating a test document..."
|
||||
if cd "$DOTNET_DIR" && dotnet run --project DocxToolkit.Cli -- create \
|
||||
--type report --output "$test_output" --title "Setup Test" 2>>"$LOG_FILE"; then
|
||||
log "Test document created: $test_output"
|
||||
|
||||
# Try preview
|
||||
if command -v pandoc &>/dev/null; then
|
||||
local preview
|
||||
preview=$(pandoc -f docx -t plain "$test_output" 2>/dev/null | head -5)
|
||||
if [ -n "$preview" ]; then
|
||||
log "Preview working: \"$preview\""
|
||||
fi
|
||||
fi
|
||||
|
||||
# Cleanup
|
||||
rm -f "$test_output"
|
||||
log "Test passed — docx-toolkit is ready to use!"
|
||||
else
|
||||
fail "Test document creation failed. Check $LOG_FILE for details."
|
||||
return 1
|
||||
fi
|
||||
|
||||
cd "$PROJECT_DIR"
|
||||
}
|
||||
|
||||
# --- Summary ---
|
||||
print_summary() {
|
||||
step "Setup Complete"
|
||||
|
||||
echo ""
|
||||
echo " Environment: $OS ($ARCH)"
|
||||
echo " .NET SDK: $(dotnet --version 2>/dev/null || echo 'NOT FOUND')"
|
||||
echo " pandoc: $(pandoc --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' || echo 'not installed (optional)')"
|
||||
echo " soffice: $(soffice --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' || echo 'not installed (optional)')"
|
||||
echo " Project: $DOTNET_DIR"
|
||||
echo ""
|
||||
echo " Usage:"
|
||||
echo " dotnet run --project $DOTNET_DIR/DocxToolkit.Cli -- create --type report --output my_report.docx"
|
||||
echo " bash $SCRIPT_DIR/env_check.sh # Quick environment check"
|
||||
echo ""
|
||||
echo " Log file: $LOG_FILE"
|
||||
}
|
||||
|
||||
# --- Main ---
|
||||
main() {
|
||||
echo "============================================"
|
||||
echo " docx-toolkit Setup & Initialization"
|
||||
echo " $(date '+%Y-%m-%d %H:%M:%S')"
|
||||
echo "============================================"
|
||||
|
||||
: > "$LOG_FILE" # Clear log
|
||||
|
||||
detect_platform
|
||||
|
||||
# Parse arguments
|
||||
local SKIP_OPTIONAL=false
|
||||
local SKIP_VERIFY=false
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--minimal) SKIP_OPTIONAL=true ;;
|
||||
--skip-verify) SKIP_VERIFY=true ;;
|
||||
--help|-h)
|
||||
echo "Usage: setup.sh [options]"
|
||||
echo " --minimal Only install critical dependencies (skip pandoc, soffice, fonts)"
|
||||
echo " --skip-verify Skip the verification test at the end"
|
||||
echo " --help Show this help"
|
||||
exit 0
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
install_dotnet
|
||||
install_zip_tools
|
||||
|
||||
if ! $SKIP_OPTIONAL; then
|
||||
install_pandoc
|
||||
install_soffice
|
||||
check_fonts
|
||||
fi
|
||||
|
||||
check_locale
|
||||
check_nuget_config
|
||||
fix_permissions
|
||||
build_project
|
||||
|
||||
if ! $SKIP_VERIFY; then
|
||||
verify_installation
|
||||
fi
|
||||
|
||||
print_summary
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Reference in New Issue
Block a user