couchbase java 手册_使用 DITA-OT 发布一份 CouchBase Server 手册

最近需要学习 CouchBase Server。而 CouchBase Server 官方网站访问速度非常慢，所以尝试使用 DITA-OT 发布一份本地文档。(其实 CouchBase Server 官网上的文档也是用 DITA-OT 发布的。)

DITA Open Toolkit 简称 DITA-OT，是一款基于 DITA 标准的文档的发布工具。DITA-OT的官方文档参见这里。

我在下载 DITA-OT 的时候，下载了好几次都没有下载成功。所以只能先本地一个编译 DITA-OT，再发布 CouchBase Server 文档。如果你能顺利下载 DITA-OT，可以直接跳过编译 DITA-OT 的步骤。

步骤1、安装 JDK 及 JRE

点击这里，访问 Oracle 官网下载。如果只是运行 DITA-OT 这种 JAVA 程序，那么安装 JDK 即可。而对于要编译 DITA-OT 源码的情况，则必须安装 JRE。(JRE 是 JAVA 的开发环境，而 DITA-OT 是 JAVA 语言编写的。好吧，其实 JAVA 我不懂……)

步骤2、配置 Windows 下 JAVA 环境变量

网上这种教程有很多，比如这个。但要注意一点，JAVAHOME 的变量值应设置为 JDK 的安装路径，不要大意设置成 JRE 的安装路径。否则，发布手册时会报找不到 tools.jar 的错误。如果已设置为 JRE 的安装路径，那么即使后续改成 JDK 的安装路径，也依然会报错。这种情况，只能把 JDK 和 JRE 卸载重装，重新配置JAVA环境变量。

步骤3、编译 DITA-OT 工具

克隆源代码，github 地址：https://github.com/dita-ot/dita-ot。

根据 README.md 完成本地编译。(如果后续有 update 源码，记得要重新编译)

步骤4、发布 CouchBase Server 文档

克隆 CouchBase Server 文档源代码，github 地址：https://github.com/couchbase/docs-cb4。

进入克隆到本地的 DITA-OT 源码所在目录(比如我的是“cd /d/work/DITA-OT/dita-ot”)，执行发布命令：

src/main/bin/dita -f html5 -i /d/work/doc/docs-cb4.6/docs-cb4/content/cb-docs.ditamap -o ~/tmp/output/date

其中-f表示发布文档保存格式，-i表示待发布的文档的顶级 ditamap 文件，-o 表示发布结果保存路径。详细命令及参数可参考 DITA-OT 文档。

过程如下图：

发布过程中会有告警，这个我暂时没有研究原因。不过不影响结果。

步骤5、查看结果

资源管理器中打开发布结果目录(比如我的是“C:\Users\lifc\tmp\outout”)，使用浏览器打开 index.html 即可查看刚刚发布出的本地 CouchBase Server 文档，如下图。如果想发布成 PDF 格式的文档，将发布命令中的“html5”改为“pdf”即可。

----------------补充内容------------------

修改 dita-ot 构建手册默认语言的方法：

D:\Work\DITA-OT\dita-ot\src\main\plugins\org.dita.base\build_init.xml

第53行，“en” 改为 “zh”，默认语言就从英文变为了中文。

这个有什么用呢？就是对模板中的固定短语进行自动转换语言。

比如 note 标签，从 dita 发布为 html 时，对于中文该标签内容前面要加“注：”，对于英文文该标签内容前面要加“Note:”。

中文 dita 文件：

发布成 html 文件后：

英文 dita 文件：

发布成 html 文件后：

(完)