从 MS Word 迁移到 Asciidoctor

Pandoc

Pandoc 是一个用于将一种标记格式转换为另一种格式的瑞士军刀。它在将简单的 docx 文件转换为 AsciiDoc 方面做得非常出色。

通常，我们不太推荐 pandoc，因为它生成的 AsciiDoc 格式不是我们偏好的。但在这种情况下，它是一个不错的选择。

要执行从 MS Word docx 到 AsciiDoc 的转换，您需要执行以下命令：

pandoc < 2.11.2

$ pandoc -f docx -t asciidoctor --wrap=none --atx-headers \
  --extract-media=extracted-media -o output.adoc

pandoc (2.11.2 或更高版本)

$ pandoc input.docx -f docx -t asciidoc --wrap=none --markdown-headings=atx \
  --extract-media=extracted-media -o output.adoc

pandoc (2.11.2 或更高版本) 和 docker

如果您使用 docker，也可以使用最新版本的 pandoc 通过 docker 来运行，而无需安装它。

$ docker run --rm --volume "$PWD:/data" --user `id -u`:`id -g` pandoc/core input.docx -f docx \
  -t asciidoc --wrap=none --markdown-headings=atx --extract-media=extracted-media -o output.adoc

然后，编辑输出文件以进行清理。

您可以期望的转换如以下表格所示（使用 MS Word 2010 和 2013 + Pandoc 2.0 和 2.5（Windows）进行测试）

Pandoc MS Word 到 AsciiDoc 的转换
MS Word 功能	转换
标题（使用 MS Word 标题样式 1-5）	是
表格	是。合并单元格将被取消合并。列宽将被忽略。
无序列表和有序列表	是
脚注	是
图表标题	普通段落
其他 MS Word 样式的段落	普通段落
嵌入式图像	是
字符格式（粗体、下划线和斜体）	是
URL 链接	否。请参阅如何移除超链接来修复它。
电子邮件链接	是
文档自动化（字段、自动生成的图表编号）	已忽略
内部引用（例如，“参见图 3”）	纯文本
绘图画布	已忽略
文本框	已忽略
链接（非嵌入式）图像	已忽略
矢量图形（MS Word “插入形状”）	已忽略

为 Pandoc 优化

上面记录的基本用法对于一次性导入来说已经足够。如果您有很多内容需要处理，那么最好先清理输入文档，然后自动化转换后的清理工作。

清理 MS Word 文档
- 删除非必需内容（封面页、页眉页脚、目录等）；通常最简单的方法是将正文复制到一个新的空白文档中。
- 关闭修订模式并接受所有更改
- 确保您已为标题使用了标题样式
- 确保表格标题位于表格的正上方
- 确保图形标题位于图形的正上方
- 确保图像是作为嵌入文件插入的，而不是作为链接
- 删除画布，并将其中包含的任何图像作为段落图像放入主流程（此限制可能在 pandoc 的下一个版本中被移除）。
- 移除超链接，并将所有内部引用和自动生成的序号替换为其字面值（Ctrl+A，Ctrl+Shift+F9）
- 删除文本框，并将其文本放入主流程
- 替换特殊字符：将智能引号替换为普通引号，将不间断连字符替换为普通连字符。
- 删除所有字符格式（Ctrl+A，Ctrl+B，Ctrl+B，Ctrl+I，Ctrl+I，Ctrl+U，Ctrl+U）
- 可选：使用 AsciiDoc 符号插入 ID 和交叉引用（您可能会发现现在执行比之后在 AsciiDoc 文档中执行更容易。）
- 另存为“严格的 Open XML 文档 (docx)”
如上所示使用 pandoc 进行转换。

检查输出文档是否正常，以及所有图像是否已提取。

如果由于某种原因 pandoc 未能提取图像，您始终可以使用 unzip 工具提取它们。Docx 本质上是一个带有 docx 文件扩展名的 zip 文件。嵌入式图像位于 word/media 目录中。

$ unzip input.docx -d input-docx
  ls input-docx/word/media/

修复输出，最好使用支持正则表达式的编辑器。
- 删除自动生成的 ID（以_开头的那些）
- 用短分隔符替换长表分隔符。
- 插入换行符，使每行一个句子。
- 重新插入图像并将标题段落转换回 Asciidoctor 标题。
- 将硬性交叉引用替换为 AsciiDoc 引用。
- 修复表格：合并的单元格将被取消合并，需要恢复列宽。
尝试进行转换，并修复出现的任何错误。

以下是用于自动化其中一些步骤的 POSIX shell 单行命令（调整正则表达式以匹配您的特定文档）。

删除自动插入的 ID

$ perl -W -pe  's!\[\[_.*]]!!g' -i output.adoc

缩短表格分隔符

$ perl -W -pe  's!\|==*!|====!g' -i output.adoc

每行一个句子。请注意不要匹配列表。它会因缩写而感到困惑，但对此别无他法。
```
$ perl -W -pe 's!(\w\w+)\.\s+(\w)!$1.\n$2!g' -i output.adoc
```

用 ID 和标题替换图形标题

$ perl -W -pe 's!^Figure (\d+)\s?(.*)![[fig-$1]]\n.$2\n!g' -i output.adoc

用 AsciiDoc xref 替换对图形的引用

$ perl -W -pe 's!Figure (\d+)!<<fig-$1>>!g' -i output.adoc

Google Docs

Google Docs 已经可以上传和编辑 MS Word docx 文件。使用 AsciiDoc Processor 插件，由 Guillaume Grossetie 开发，您可以将文档的全部或部分内容从 Google Docs 复制并粘贴为 AsciiDoc 文本。它支持的功能似乎比 pandoc 少很多，但可以期待进一步的开发。该插件的源代码可以在其仓库中找到。

纯文本

此方法仅适用于非常小的文件，或者当其他方法不可用时。

它会保留文本，并修复像自动编号列表和交叉引用之类的字段。
它会丢失表格（转换为纯段落）、图像、符号、表单字段和文本框。

在 MS Word 中，使用 另存为 纯文本，然后在“文件转换”对话框出现时，设置：

其他编码：UTF-8
不插入换行符
允许字符替换

保存文件，然后手动应用 AsciiDoc 标记。

尝试不同的编码。首先尝试 UTF-8，但如果遇到问题，您总是可以回退到 US-ASCII。