使用 Apache FOP 2.3 + docbook-xsl-ns-1.79.1 转换 Docbook 5.1 格式的 XML 文档成 PDF/RTF 文件

使用 Docbook 编写折桂打印平台系统、折桂上传平台系统的产品文档，原因基于如下两点:

第一，文档的不同章节，可使用不同的 .xml 文件，由不同人员分别撰写，图片文件在XML文章中用相对目录方式指定，最后用一个 DOS 命令即可组装生成大 PDF 文件。
第二，文章内容分散在 .xml 文件中，解决 SVN 可跟踪各次修改的内容。
第三，各章节的格式，使用一个 .xsl 文件，即可统一文档风格。章节编号在组装时自动生成(这个功能貌似 word 也有，只是不同大章节里的小章节顺序号有时错误需要人工调整)。

大的 Word 文件难改，痛点大家都知道:

在大文件里改几行字，打开慢、保存慢；

如果要保留修改前的备份，文件也很大。

Docbook 格式的文档，使用 XML 格式，各个 XML node 的名字也很语义化，基本上看上去就懂。几个主要 XML node 从大到小为:

book(书), chapter(章), section(节), para (段落) 。

section(节)可以有多个层次，比如 sect1, sect2, sect3, sect4,sect5 。

环境搭建:
a. 下载 docbook 转换所用样式 xsl:
    https://sourceforge.net/projects/docbook/files/docbook-xsl-ns/1.79.1/ 里的文件: docbook-xsl-ns-1.79.1.zip

b. 解压缩 docbook-xsl-ns-1.79.1.zip 到 c:\my_apps\docbook-xsl-ns-1.79.1 ，目录结构为:
    C:\my_apps\docbook-xsl-ns-1.79.1\README
    C:\my_apps\docbook-xsl-ns-1.79.1\fo\docbook.xsl
    ...

c. 下载 docbook 转换所用工具 Apache FOP:
    https://xmlgraphics.apache.org/fop/download.html 里的 fop-2.3-bin.tar.gz 或 fop-2.3-bin.zip

d. 解压缩 fop-2.3-bin.tar.gz 到 c:\my_apps\fop-2.3 ，目录结构为:
    C:\my_apps\fop-2.3\README
    c:\my_apps\fop-2.3\fop\fop.bat

    ...

    将 c:\my_apps\fop-2.3\fop\ 设置到 windows path 路径中(控制面板\系统和安全\系统, 高级系统设置, 高级，环境变量，系统变量，path, )，后续可方便使用：C:\my_apps\fop-2.3\fop\fop.bat

e. 如果 C: 盘空间不足，可将上述文件放在 D:\my_apps，然后开一个管理员权限的 DOS 窗口，进行映射目录:
    mklink /d c:\my_apps D:\my_apps

f. 下载并安装 Java 运行支持库(JRE, 或 JDK).
    Apache FOP 运行需要 Java.

g. 在某个文件目录，比如 C:\projects\zhegui_print_upload\050-Deploy-docs，新建 xlst 文件 installation-zg_prt_uld-book.xsl，引用已有的 docbook.xsl，并加上一些定制化参数，比如中英文使用不同的字体。

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                xmlns:ng="http://docbook.org/docbook-ng"
                xmlns:db="http://docbook.org/ns/docbook"
                exclude-result-prefixes="db ng exsl"
                version='1.0'>

<!-- 引用官方样式表 -->
<xsl:include href="c:\my_apps\docbook-xsl-ns-1.79.1\fo/docbook.xsl"/>

  <xsl:param name="title.font.family">Arial,Sans Serif,Verdana,SimHei,Source Han Sans CN,Arial Unicode MS</xsl:param>
  <xsl:param name="body.font.family">Arial,Sans Serif,Verdana,KaiTi,Source Han Sans CN,Arial Unicode MS</xsl:param>
  <xsl:param name="monospace.font.family">Consolas,Source Code Pro,Lucida Console,Liberation Mono,DejaVu Sans Mono,Courier New,SimSun,Source Han Serif SC,Arial Unicode MS</xsl:param>
  <xsl:param name="symbol.font.family">Cambria Math,Arial,Sans Serif,Verdana,Source Han Serif SC,SimSun,Arial Unicode MS</xsl:param>
  
  <xsl:param name="body.font.size">9pt</xsl:param>
  
  <xsl:param name="paper.type" select="'A4'"/>
  <xsl:param name="l10n.gentext.language" select="'zh_cn'"/>

  <xsl:param name="img.src.path">./</xsl:param>
  <xsl:param name="keep.relative.image.uris" select="1"></xsl:param>
  <xsl:param name="section.autolabel" select="1"></xsl:param>
  <xsl:param name="section.label.includes.component.label" select="1"></xsl:param>

<xsl:attribute-set name="monospace.verbatim.properties">
    <xsl:attribute name="wrap-option">wrap</xsl:attribute>
     <xsl:attribute name="font-size">7pt</xsl:attribute>
</xsl:attribute-set>

<!-- 更改输出选项，使用 UTF-8 编码 -->
<xsl:output method="html" encoding="UTF-8" indent="no"/>

</xsl:stylesheet>

h. 在某个文件目录，比如 C:\projects\zhegui_print_upload\050-Deploy-docs，编写文章的某个章节: installation-zg_prt_uld-chapter-coc_eb-upload.xml

<?xml version='1.0' encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook">
    <title>电动自行车CCLC上传的配置与验证</title>
    <para>本章讲述了电动自行车CCLC上传的安装配置步骤。</para>


    <section>
        <title>配置上传参数</title>
        <para>修改 C:\zg_prt_uld\apps\plugin_upload_veh_coc\plugin_upload_coc.exe.config 文件，在</para>
        <para> <programlisting language="xml"><![CDATA[
</appSettings>
            ]]>
            </programlisting>
        </para>
        <para>行之上，增加如下几行配置，填写其中的用户名及密码:</para>
        <para><programlisting language="xml"><![CDATA[
<add key="plugin.upload.coc.cclc.1101-T05.user" value="Tjyadea"/>
<add key="plugin.upload.coc.cclc.1101-T05.password" value="xxx"/>
<add key="plugin.upload.coc.cclc.1101-T08.user" value="Tjyadea"/>
<add key="plugin.upload.coc.cclc.1101-T08.password" value="xxx"/>
<add key="plugin.upload.coc.cclc.1101.user" value="Tjyadea"/>
<add key="plugin.upload.coc.cclc.1101.password" value="xxx"/>

<add key="plugin.upload.coc.cclc.user" value=""/>
<add key="plugin.upload.coc.cclc.password" value=""/>
]]>
        </programlisting>
        </para>

        <para>此处上传用户账号查找匹配的原则是：</para>
        <para>
                <orderedlist numeration="arabic">
                    <listitem>先基于完整的生产线编号，比如 1101-T05 ，进行查找；</listitem>
                    <listitem>如果找不到，再基于生产线编号的前半部分工厂编号，比如 1101 ，进行查找；</listitem>
                    <listitem>如果找不到，不基于生产线编号，查找默认的上传账号 plugin.upload.coc.cclc.user；</listitem>
                    <listitem>如果找不到，则报错：无法找到对应的上传账号；</listitem>
                </orderedlist>
        </para>
        <para>此配置支持不同的产线、工厂，对应到不同的上传账号。</para>
        <caution ><title>请注意</title>
            <para>以上配置仅用于电动自行车CCLC上传，不用于电动自行车的CQC上传。</para>
        </caution>
    </section>

    <section>
        <title>配置上传网址</title>
        <para>修改 C:\zg_prt_uld\apps\plugin_upload_veh_coc\plugin_upload_coc.exe.config 文件，在</para>
        <para><programlisting language="xml"><![CDATA[
    </plugin_upload_coc.Properties.Settings>
]]></programlisting></para>
        <para>行之上，增加如下几行配置(如已有，则忽略):</para>
        <para>     <programlisting language="xml"><![CDATA[
<setting name="plugin_upload_coc_cn_cclc_app_prd20190425_SynchronousService"
    serializeAs="String">
    <value>http://app.cclc.cn/SynchronousService.asmx</value>
</setting>
        ]]>
        </programlisting>
        </para>
        <para>此步骤可在系统正常运行期间进行。不会影响到打印平台系统在运行的各个打印程序，比如车辆合格证打印、车辆一致性证书打印。</para>
        <para>如果复制文件时，遇到 Windows 提示报错：文件正在使用中。说明当前车辆一致性证书程序 plugin_upload_coc 正在运行。可待其运行结束后再复制替换文件。</para>
    </section>

        <section>
            <title>验证上传功能</title>
            <para>准备上传数据文件，放在对应的目录，比如: C:\zg_prt_uld\sample_data_files\upload_electric_bicycle_certificate-yadi134cclc-request.xml 。</para>
            <para>DOS 窗口下，依次运行测试 CQC 电动自行车的上传、CQC 电动摩托的上传、CCLC 电动自行车的上传: </para>
            <para><programlisting language="dos"><![CDATA[
cd C:\zg_prt_uld\apps\plugin_upload_veh_coc
plugin_upload_coc.exe -Dplugin_upload_coc.data.type=coc_eb file=C:\zg_prt_uld\sample_data_files\upload_electric_bicycle_certificate-yadi134cqc-request.xml
plugin_upload_coc.exe -Dplugin_upload_coc.data.type=coc_mt file=C:\zg_prt_uld\sample_data_files\upload_veh_coc-yadi134cqc-request.xml
plugin_upload_coc.exe -Dplugin_upload_coc.data.type=coc_eb file=C:\zg_prt_uld\sample_data_files\upload_electric_bicycle_certificate-yadi134cclc-request.xml
            ]]>
            </programlisting>
            </para>
            <para>等待程序运行结束，检查 C:\zg_prt_uld\sample_data_files 目录下的新出现的 .xml 文件(可按文件日期倒排序)，其中有运行结果。逐个打开这些 .xml 文件，检查其中是否有报错。</para>
        </section>


</chapter>

i. 编写文章书本 installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml ，其中包含一个或多个文章章节。这里面可以写文章的部分章节，另外部分章节通过 xi:include 嵌入的方式组合进来。

<?xml version='1.0' encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
        xmlns:xi="http://www.w3.org/2001/XInclude"
        version="5.0"
        xml:lang="zh-cn">
 
    <title>雅迪科技 CPS 系统升级(电动自行车CCLC上传)</title>

    <chapter xmlns="http://docbook.org/ns/docbook">
        <title>准备工作</title>
        <para>本章讲述了电动自行车CCLC上传的安装配置前的准备工作</para>
        <section>
            <title>复制新版本的安装文件</title>
            <para>复制新版本的安装文件 20190516_09-yadi-cclc-upload 目录到 CPS 服务器的 <filename>D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload</filename> 目录里。</para>
        </section>
        <section>
            <title>创建旧版本的备份目录</title>
            <para>创建旧版本的备份目录，比如: D:\zg_prt_uld-backup\20190516_11, 此处目录名建议包含当前日期、时间。</para>
            <para>复制 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目录到上述旧版本备份目录。</para>
        </section>
        <section>
            <title>升级/替换应用软件文件</title>
            <para>将 D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload\plugin_upload_coc 目录下的所有文件，复制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc ，替换原有文件。</para>
            <para>此步骤可在系统正常运行期间进行。不会影响到打印平台系统在运行的各个打印程序，比如车辆合格证打印、车辆一致性证书打印。</para>
            <para>如果复制文件时，遇到 Windows 提示报错：文件正在使用中。说明当前车辆一致性证书程序 plugin_upload_coc 正在运行。可待其运行结束后再复制替换文件。</para>
        </section>
        
    </chapter>
    <chapter xmlns="http://docbook.org/ns/docbook">
        <title>电动自行车CCLC上传安装对应的数据库变更</title>
        <para>本章讲述了电动自行车CCLC上传的安装配置的数据库变更工作</para>

        <section>
            <title>执行变更的数据库改动脚本</title>
            <para>在数据库中，运行如下 SQL 文件：
        20190425-config-cclc_coc-upload.sql</para>
        </section>
        
    </chapter>

    <xi:include href="installation-zg_prt_uld-chapter-coc_eb-upload.xml"/>

    <chapter xmlns="http://docbook.org/ns/docbook">
        <title>失败回退步骤</title>
        <para>本章讲述了电动自行车CCLC上传安装失败后的回退步骤</para>

        <section>
            <title>失败回退步骤</title>
            <para>将 D:\zg_prt_uld-backup\20190516_11\plugin_upload_veh_coc 中的所有文件，复制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目录，替换原有文件。</para>
            <para>数据库变更不用回退，不会影响到其它打印模块、上传模块。</para>
        </section>

    </chapter>

    <info>
        <subtitle>安装文档</subtitle>
        <author>
            <personname>
                陈平
            </personname>
        </author>
        <edition>1.00.00</edition>
        <revhistory>        <!--修订记录-->
            <revision>
                <revnumber>1.00.00</revnumber>
                <date>2019/05/15</date>
                <editor><personname>陈平</personname></editor>
                <revremark>创建文档</revremark>
            </revision>
        </revhistory>
        <copyright>
            <year>2007-2019</year>
            <holder>上海折桂软件有限公司</holder>
        </copyright>
    </info>

</book>

j. 运行 DOS 命令，组装、直接查看文章书本。此处需指定书本 XML 文件、书本样式 xsl 文件、FOP 配置文件。需要明确指定配置文件fop.xconf的路径。
    cd C:\projects\zhegui_print_upload\050-Deploy-docs
    fop -xml installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml -xsl installation-zg_prt_uld-book.xsl -c c:\my_apps\fop-2.3\fop\conf\fop.xconf -awt

    直接查看工具有些小问题，有时候需要上下翻页一两次，才能看到正确的排版结果。

k. 运行 DOS 命令，组装文章书本成 .rtf 文件，可用 Windows 自带的"写字板"软件打开，也可用 Word 打开。
    fop -xml installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml -xsl installation-zg_prt_uld-book.xsl -c c:\my_apps\fop-2.3\fop\conf\fop.xconf -rtf installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.rtf

    生成的 .rtf 文件，中文字体可能与上述的 installation-zg_prt_uld-book.xsl 中字体配置略有不同，但不影响阅读。

l. 运行 DOS 命令，组装文章书本成 .pdf 文件。
    fop -noedit -xml installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml -xsl installation-zg_prt_uld-book.xsl -c c:\my_apps\fop-2.3\fop\conf\fop.xconf -pdfa1b installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.pdf
    或
    fop -noedit -xml installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml -xsl installation-zg_prt_uld-book.xsl -c c:\my_apps\fop-2.3\fop\conf\fop.xconf -pdf installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.pdf

    第一次运行时，可能比较慢，Apache FOP 会扫描 C:\Windows\Fonts 目录中的字体文件，为生成 .pdf 文件生成缓存文件。下次运行速度就提高了。

    以上步骤生成的 .pdf 文件，字体是嵌入到PDF文件中的。可复制中英文，可搜索中英文。
    实际上，也可以生成不能复制的 PDF ，读者可自行上网搜索相关开关设置资料。

    略有瑕疵的是，PDF文件中，同一行的英文单词比中文略高，不在一个水平线上。具体原因待查。

m. 参照以上步骤，使用 Apache FOP 也可生成 .pcl, .ps, .txt, .fo 等文件。

以下是生成后的 PDF 文件部分截图: