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

2019-05-17 10:31

 

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

 

第一,文档的不同章节,可使用不同的 .xml 文件,由不同人员分别撰写,图片文件在XML文章中用相对目录方式指定,最后用一个 DOS 命令即可组装生成大 PDF 文件。

第二,文章内容分散在 .xml 文件中,解决 SVN(或其它版本管理软件,比如 git) 可跟踪各次修改的内容。

第三,各章节的格式,使用一个 .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,并加上一些定制化参数,比如中英文使用不同的字体。








  Arial,Sans Serif,Verdana,SimHei,Source Han Sans CN,Arial Unicode MS
  Arial,Sans Serif,Verdana,KaiTi,Source Han Sans CN,Arial Unicode MS
  Consolas,Source Code Pro,Lucida Console,Liberation Mono,DejaVu Sans Mono,Courier New,SimSun,Source Han Serif SC,Arial Unicode MS
  Cambria Math,Arial,Sans Serif,Verdana,Source Han Serif SC,SimSun,Arial Unicode MS
  
  9pt
  
  
  

  ./
  
  
  


    wrap
     7pt






		

 

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




    电动自行车CCLC上传的配置与验证
    本章讲述了电动自行车CCLC上传的安装配置步骤。


    
配置上传参数 修改 C:\zg_prt_uld\apps\plugin_upload_veh_coc\plugin_upload_coc.exe.config 文件,在 ]]> 行之上,增加如下几行配置,填写其中的用户名及密码: ]]> 此处上传用户账号查找匹配的原则是: 先基于完整的生产线编号,比如 1101-T05 ,进行查找; 如果找不到,再基于生产线编号的前半部分工厂编号,比如 1101 ,进行查找; 如果找不到,不基于生产线编号,查找默认的上传账号 plugin.upload.coc.cclc.user; 如果找不到,则报错:无法找到对应的上传账号; 此配置支持不同的产线、工厂,对应到不同的上传账号。 请注意 以上配置仅用于电动自行车CCLC上传,不用于电动自行车的CQC上传。
配置上传网址 修改 C:\zg_prt_uld\apps\plugin_upload_veh_coc\plugin_upload_coc.exe.config 文件,在 ]]> 行之上,增加如下几行配置(如已有,则忽略): http://app.cclc.cn/SynchronousService.asmx ]]> 此步骤可在系统正常运行期间进行。不会影响到打印平台系统在运行的各个打印程序,比如车辆合格证打印、车辆一致性证书打印。 如果复制文件时,遇到 Windows 提示报错:文件正在使用中。说明当前车辆一致性证书程序 plugin_upload_coc 正在运行。可待其运行结束后再复制替换文件。
验证上传功能 准备上传数据文件,放在对应的目录,比如: C:\zg_prt_uld\sample_data_files\upload_electric_bicycle_certificate-yadi134cclc-request.xml 。 DOS 窗口下,依次运行测试 CQC 电动自行车的上传、CQC 电动摩托的上传、CCLC 电动自行车的上传: 等待程序运行结束,检查 C:\zg_prt_uld\sample_data_files 目录下的新出现的 .xml 文件(可按文件日期倒排序),其中有运行结果。逐个打开这些 .xml 文件,检查其中是否有报错。

 

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




 
    雅迪科技 CPS 系统升级(电动自行车CCLC上传)

    
        准备工作
        本章讲述了电动自行车CCLC上传的安装配置前的准备工作
        
复制新版本的安装文件 复制新版本的安装文件 20190516_09-yadi-cclc-upload 目录到 CPS 服务器的 D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload 目录里。
创建旧版本的备份目录 创建旧版本的备份目录,比如: D:\zg_prt_uld-backup\20190516_11, 此处目录名建议包含当前日期、时间。 复制 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目录到上述旧版本备份目录。
升级/替换应用软件文件 将 D:\zg_prt_uld-deploy\20190516_09-yadi-cclc-upload\plugin_upload_coc 目录下的所有文件,复制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc ,替换原有文件。 此步骤可在系统正常运行期间进行。不会影响到打印平台系统在运行的各个打印程序,比如车辆合格证打印、车辆一致性证书打印。 如果复制文件时,遇到 Windows 提示报错:文件正在使用中。说明当前车辆一致性证书程序 plugin_upload_coc 正在运行。可待其运行结束后再复制替换文件。
电动自行车CCLC上传安装对应的数据库变更 本章讲述了电动自行车CCLC上传的安装配置的数据库变更工作
执行变更的数据库改动脚本 在数据库中,运行如下 SQL 文件: 20190425-config-cclc_coc-upload.sql
失败回退步骤 本章讲述了电动自行车CCLC上传安装失败后的回退步骤
失败回退步骤 将 D:\zg_prt_uld-backup\20190516_11\plugin_upload_veh_coc 中的所有文件,复制到 C:\zg_prt_uld\apps\plugin_upload_veh_coc 目录,替换原有文件。 数据库变更不用回退,不会影响到其它打印模块、上传模块。
安装文档 陈平 1.00.00 1.00.00 2019/05/15 陈平 创建文档 2007-2019 上海折桂软件有限公司

 

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 文件部分截图:

pdf preview, part 1

-----

pdf preview, part 2

-----

pdf preview, part 3

-----

pdf preview, part 4

-----

pdf preview, part 5

 

以下是生成后的 RTF 文件部分截图,使用 wordpad (写字板)软件打开文件:

pdf preview

 

以下是不生成文件,直接查看文档的截图:

preview only

 

 

欢迎转载,转载请注明出处: https://www.zheguisoft.com/staff_blogs/jacklondon_chen/2019, 及 https://www.cnblogs.com/jacklondon/p/generate_dookbook_pdf_rtf_using_apache_fop2_3_docbook-xsl-ns-1_79_1.html