从MS Word迁移到Asciidoctor

潘多克

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

Note	通常，我们不建议使用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，你也可以不用安装就通过Docker使用pandoc的最新版本。

$ 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）测试）：

Table 1. Pandoc MS Word 转换为 AsciiDoc
MS Word 功能	转换情况
标题（使用 MS Word 标题样式1-5）	是
表格	是。+ 合并的单元格将被拆分。列宽被忽略。
无序和有序列表	是
脚注	是
图形和表格标题	普通段落
其他 MS Word 样式的段落	普通段落
嵌入的图片	是
字符格式化（加粗，下划线和斜体）	是
URL 链接	否。查看如何移除超链接以解决它。
电子邮件链接	是
文档自动化（字段，自动生成的图形和表格编号）	忽略
内部引用（例如，“`参见图3`”）	纯文本
绘图画布	忽略
文本框	忽略
链接的（非嵌入的）图片	忽略
矢量图形（MS Word “`插入形状`”）	忽略

为Pandoc优化

上述文件的基本用法适用于一次性导入。如果你有很多工作要做，那么首先清理输入文档，然后自动化进行转换后的整理工作是值得的。

清理MS Word文档：
- 移除非必要的内容（标题页、页眉和页脚、目录等）；通常，只复制正文到一个新的空白文档中是最简单的。
- 关闭跟踪并接受所有更改
- 确保你对标题使用了标题样式
- 确保表格的标题紧紧位于其表格的*上方*。
- 确保图形的标题紧挨着*它们的上方*。
- 确保图片作为嵌入文件插入，而不是作为链接。
- 移除画布，并将它们包含的任何图像作为段落图像放入主流程中（在下一个版本的pandoc发布时，这种限制可能会被移除）。
- 移除超链接并将所有内部引用和自动生成的序列号替换为它们的文字值（kbd:[Ctrl+A]，kbd:[Ctrl+Shift+F9]）
- 移除文本框，并将它们的文本内容放入主要内容流中
- 替换特殊字符：用普通引号替换智能引号，用普通连字符替换不间断连字符。
- 移除所有字符格式设置（kbd:[Ctrl+A], kbd:[Ctrl+B], kbd:[Ctrl+B], kbd:[Ctrl+I], kbd:[Ctrl+I], kbd:[Ctrl+U], kbd:[Ctrl+U]）
- 可选：使用AsciiDoc标记插入id和交叉引用（您可能会发现现在进行此操作比之后在AsciiDoc文档中进行更容易。）
- 将“Strict Open XML document (docx)`”保存为
如上所示使用pandoc进行转换。

检查输出文档是否看起来正常，并且所有图像都已提取出来。

Note	如果出于某种原因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已经可以上传并编辑MS Word的docx文件。使用由Guillaume Grossetie开发的[AsciiDoc Processor插件^](url-google-asciidoc)，你可以复制和粘贴部分或全部Google Docs文档为AsciiDoc文本。它能处理的功能似乎比pandoc要少得多，但预计会进一步发展。这个插件的源代码可以在[它的仓库^](url-google-asciidoc-source)中找到。

纯文本

这种方法只对非常小的文件有用，或者如果其他方法不可用。

它保留文本内容，并修复像自动编号列表和交叉引用这样的字段。
它会丢失表格（转换成普通段落）、图片、符号、表单字段和文本框。

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

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

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

尝试使用编码。首先尝试UTF-8，但如果你遇到问题，你可以随时回退到US-ASCII。