歡迎大家下載試用折桂單點(diǎn)登錄系統(tǒng), https://www.zheguisoft.com

使用 Apache FOP 2.3 + docbook-xsl-ns-1.79.1 轉(zhuǎn)換 Docbook 5.1 格式的 XML 文檔成 PDF/RTF 文件

使用 Docbook 編寫折桂打印平臺系統(tǒng)、折桂上傳平臺系統(tǒng)的產(chǎn)品文檔，原因基于如下兩點(diǎn):

第一，文檔的不同章節(jié)，可使用不同的 .xml 文件，由不同人員分別撰寫，圖片文件在XML文章中用相對目錄方式指定，最后用一個 DOS 命令即可組裝生成大 PDF 文件。
第二，文章內(nèi)容分散在 .xml 文件中，解決 SVN 可跟蹤各次修改的內(nèi)容。
第三，各章節(jié)的格式，使用一個 .xsl 文件，即可統(tǒng)一文檔風(fēng)格。章節(jié)編號在組裝時自動生成(這個功能貌似 word 也有，只是不同大章節(jié)里的小章節(jié)順序號有時錯誤需要人工調(diào)整)。

大的 Word 文件難改，痛點(diǎn)大家都知道:

在大文件里改幾行字，打開慢、保存慢；

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

Docbook 格式的文檔，使用 XML 格式，各個 XML node 的名字也很語義化，基本上看上去就懂。幾個主要 XML node 從大到小為:

book(書), chapter(章), section(節(jié)), para (段落) 。

section(節(jié))可以有多個層次，比如 sect1, sect2, sect3, sect4,sect5 。

環(huán)境搭建:
a. 下載 docbook 轉(zhuǎn)換所用樣式 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 ，目錄結(jié)構(gòu)為:
    C:\my_apps\docbook-xsl-ns-1.79.1\README
    C:\my_apps\docbook-xsl-ns-1.79.1\fo\docbook.xsl
    ...

c. 下載 docbook 轉(zhuǎn)換所用工具 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 ，目錄結(jié)構(gòu)為:
    C:\my_apps\fop-2.3\README
    c:\my_apps\fop-2.3\fop\fop.bat

    ...

    將 c:\my_apps\fop-2.3\fop\ 設(shè)置到 windows path 路徑中(控制面板\系統(tǒng)和安全\系統(tǒng), 高級系統(tǒng)設(shè)置, 高級，環(huán)境變量，系統(tǒng)變量，path, )，后續(xù)可方便使用：C:\my_apps\fop-2.3\fop\fop.bat

e. 如果 C: 盤空間不足，可將上述文件放在 D:\my_apps，然后開一個管理員權(quán)限的 DOS 窗口，進(jìn)行映射目錄:
    mklink /d c:\my_apps D:\my_apps

f. 下載并安裝 Java 運(yùn)行支持庫(JRE, 或 JDK).
    Apache FOP 運(yùn)行需要 Java.

g. 在某個文件目錄，比如 C:\projects\zhegui_print_upload\050-Deploy-docs，新建 xlst 文件 installation-zg_prt_uld-book.xsl，引用已有的 docbook.xsl，并加上一些定制化參數(shù)，比如中英文使用不同的字體。

<?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>

<!-- 更改輸出選項(xiàng)，使用 UTF-8 編碼 -->
<xsl:output method="html" encoding="UTF-8" indent="no"/>

</xsl:stylesheet>

h. 在某個文件目錄，比如 C:\projects\zhegui_print_upload\050-Deploy-docs，編寫文章的某個章節(jié): 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上傳的配置與驗(yàn)證</title>
    <para>本章講述了電動自行車CCLC上傳的安裝配置步驟。</para>


    <section>
        <title>配置上傳參數(shù)</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>先基于完整的生產(chǎn)線編號，比如 1101-T05 ，進(jìn)行查找；</listitem>
                    <listitem>如果找不到，再基于生產(chǎn)線編號的前半部分工廠編號，比如 1101 ，進(jìn)行查找；</listitem>
                    <listitem>如果找不到，不基于生產(chǎn)線編號，查找默認(rèn)的上傳賬號 plugin.upload.coc.cclc.user；</listitem>
                    <listitem>如果找不到，則報錯：無法找到對應(yīng)的上傳賬號；</listitem>
                </orderedlist>
        </para>
        <para>此配置支持不同的產(chǎn)線、工廠，對應(yīng)到不同的上傳賬號。</para>
        <caution ><title>請注意</title>
            <para>以上配置僅用于電動自行車CCLC上傳，不用于電動自行車的CQC上傳。</para>
        </caution>
    </section>

    <section>
        <title>配置上傳網(wǎng)址</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>此步驟可在系統(tǒng)正常運(yùn)行期間進(jìn)行。不會影響到打印平臺系統(tǒng)在運(yùn)行的各個打印程序，比如車輛合格證打印、車輛一致性證書打印。</para>
        <para>如果復(fù)制文件時，遇到 Windows 提示報錯：文件正在使用中。說明當(dāng)前車輛一致性證書程序 plugin_upload_coc 正在運(yùn)行。可待其運(yùn)行結(jié)束后再復(fù)制替換文件。</para>
    </section>

        <section>
            <title>驗(yàn)證上傳功能</title>
            <para>準(zhǔn)備上傳數(shù)據(jù)文件，放在對應(yīng)的目錄，比如: C:\zg_prt_uld\sample_data_files\upload_electric_bicycle_certificate-yadi134cclc-request.xml 。</para>
            <para>DOS 窗口下，依次運(yùn)行測試 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>等待程序運(yùn)行結(jié)束，檢查 C:\zg_prt_uld\sample_data_files 目錄下的新出現(xiàn)的 .xml 文件(可按文件日期倒排序)，其中有運(yùn)行結(jié)果。逐個打開這些 .xml 文件，檢查其中是否有報錯。</para>
        </section>


</chapter>

i. 編寫文章書本 installation-zg_prt_uld-book-CR201905-yadi-coc_eb-upload.xml ，其中包含一個或多個文章章節(jié)。這里面可以寫文章的部分章節(jié)，另外部分章節(jié)通過 xi:include 嵌入的方式組合進(jìn)來。

<?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 系統(tǒng)升級(電動自行車CCLC上傳)</title>

    <chapter xmlns="http://docbook.org/ns/docbook">
        <title>準(zhǔn)備工作</title>
        <para>本章講述了電動自行車CCLC上傳的安裝配置前的準(zhǔn)備工作</para>
        <section>
            <title>復(fù)制新版本的安裝文件</title>
            <para>復(fù)制新版本的安裝文件 20190516_09-yadi-cclc-upload 目錄到 CPS 服務(wù)器的 <filename>D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload</filename> 目錄里。</para>
        </section>
        <section>
            <title>創(chuàng)建舊版本的備份目錄</title>
            <para>創(chuàng)建舊版本的備份目錄，比如: D:\zg_prt_uld-backup\20190516_11, 此處目錄名建議包含當(dāng)前日期、時間。</para>
            <para>復(fù)制 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目錄到上述舊版本備份目錄。</para>
        </section>
        <section>
            <title>升級/替換應(yīng)用軟件文件</title>
            <para>將 D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload\plugin_upload_coc 目錄下的所有文件，復(fù)制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc ，替換原有文件。</para>
            <para>此步驟可在系統(tǒng)正常運(yùn)行期間進(jìn)行。不會影響到打印平臺系統(tǒng)在運(yùn)行的各個打印程序，比如車輛合格證打印、車輛一致性證書打印。</para>
            <para>如果復(fù)制文件時，遇到 Windows 提示報錯：文件正在使用中。說明當(dāng)前車輛一致性證書程序 plugin_upload_coc 正在運(yùn)行。可待其運(yùn)行結(jié)束后再復(fù)制替換文件。</para>
        </section>
        
    </chapter>
    <chapter xmlns="http://docbook.org/ns/docbook">
        <title>電動自行車CCLC上傳安裝對應(yīng)的數(shù)據(jù)庫變更</title>
        <para>本章講述了電動自行車CCLC上傳的安裝配置的數(shù)據(jù)庫變更工作</para>

        <section>
            <title>執(zhí)行變更的數(shù)據(jù)庫改動腳本</title>
            <para>在數(shù)據(jù)庫中，運(yùn)行如下 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 中的所有文件，復(fù)制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目錄，替換原有文件。</para>
            <para>數(shù)據(jù)庫變更不用回退，不會影響到其它打印模塊、上傳模塊。</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>創(chuàng)建文檔</revremark>
            </revision>
        </revhistory>
        <copyright>
            <year>2007-2019</year>
            <holder>上海折桂軟件有限公司</holder>
        </copyright>
    </info>

</book>

j. 運(yùn)行 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

    直接查看工具有些小問題，有時候需要上下翻頁一兩次，才能看到正確的排版結(jié)果。

k. 運(yùn)行 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. 運(yùn)行 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

    第一次運(yùn)行時，可能比較慢，Apache FOP 會掃描 C:\Windows\Fonts 目錄中的字體文件，為生成 .pdf 文件生成緩存文件。下次運(yùn)行速度就提高了。

    以上步驟生成的 .pdf 文件，字體是嵌入到PDF文件中的。可復(fù)制中英文，可搜索中英文。
    實(shí)際上，也可以生成不能復(fù)制的 PDF ，讀者可自行上網(wǎng)搜索相關(guān)開關(guān)設(shè)置資料。

    略有瑕疵的是，PDF文件中，同一行的英文單詞比中文略高，不在一個水平線上。具體原因待查。

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

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