Transition Docbook

最新推荐文章于 2024-06-04 09:07:32 发布

cxjlt

最新推荐文章于 2024-06-04 09:07:32 发布

阅读量2.6k

点赞数

文章标签： transition 文档 documentation include hibernate 下载工具

本文链接：https://blog.csdn.net/cxjlt/article/details/265716

版权

Transition Docbook

版本0.1

本文档采用docBook-xml-4.2标准书写,使用saxon6.5.3输出html和fo,用fop0.20.5把fo转换成pdf。

刚开始用docbook写文档觉得非常的不适应，毕竟比起用所见即所得的编辑工具来，要费事很多，其中文档的转换我就很费周折，最终通过查阅网上资料得以解决，希望本文能给正在为转换docbook文档而困扰的人以帮助。

开始本文之前给出网上两篇文章的链接：limodou写的<<docbook学习>>, 是我学习docbook入门的文章；曹晓纲写的<<Add Asia fonts to docbook-fop , Hibernate style>>指导我转换docbook文档。

概述 1. saxon-fop

1.1. 下载工具 1.2. 搭建环境

2. xsltproc

概述

虽然在刚开始写docbook文档的时候会有些不适，但是当看到规范清晰的文档时，我相信此刻会填补你所有的不满与牢骚。动手写过几篇文章后就会习惯docbook的语法规则，其实docbook常用的元素也不是很多。

docbook文档有sgml、xml、两种格式，转换文档样式也有相对应的两种格式dsssl、xsl 本人用的是遵循docbook-xml-dtd规则的xml文档格式。sgml也是一种标识语言，早于 xml.

通过转换工具解析docbook文档和转换样式，就可以生成规范、多样的文档。如html形式，pdf、rtf、chm javadoc等格式。本人使用过的转换工具xsltproc、saxon、fop，随后将描述其使用方法。

第 1 章 saxon-fop

1.1. 下载工具

下载转换工具时请注意对照版本号，笔者在使用中发现有些版本有bug。

docbook-dtd-4.2
docbook-xsl-1.65.1
saxon6.5.3
fop0.20.5
pdf中插入图片时需用到JAVA ADVANCED IMAGING PLUG-INS, VERSION 1.0中的jar包。
转换中文文档需要用到字体文件simsun.ttc和simhei.ttf，中文操作系统在%system%/fonts/ 下能找到

1.2. 搭建环境

建立目录如下(引用hibernate中文手册目录结构)：
|---docbook
    +---suport             
        +---lib          (1)
        +---docbook-dtd
        +---docbook-xsl
    +---zh-cn           (2)
        +---images
        +---styles
        +---fop
        +---modules
        |---master.xml
    |---build.xml       (3)

(1)	放置转换工具组件。
(2)	将文档所用的图片放置到images,转换样式及css放置styles文件夹中，fop文件中放置转换fop的所需的字体文件。待转换的docbook源文件放置在modules文件夹中，master.xml文件为docbook文档的起始文件。
(3)	ant的构建文件。

1、将下载工具中*.jar文件拷贝到lib

2、利用fop0.20.5生成中文pdf文件时，请做以下操作(摘自曹晓纲“docbook + TTF + FOP 编写中文”)

fop默认没有支持中文字体。解决办法是从windows的TTF字体中提取fontmatrix文件.
java-cpD:/works/hibernate2/doc/reference/support/lib/fop.jar;D:/works/hibernate2/doc/
reference/support/lib/avalon-framework-cvs-20020806.jar org.apache.fop.fonts.apps.TTFReader 
C:/Windows/Fonts/simhei.ttf simhei.xml
java -cp D:/works/hibernate2/doc/reference/support/lib/fop.jar;D:/works/hibernate2/doc/reference
/support/lib/avalon-framework-cvs-20020806.jar org.apache.fop.fonts.apps.TTFReader -ttcname 
"SimSun" C:/Windows/Fonts/simsun.ttc simsun.xml
得到两个xml文件：simsun.xml, sumhei.xml;然后在userconfig.xml中注册：
<fonts>
	<font metrics-file="simhei.xml" embed-file="file:///c:/windows/fonts/simhei.ttf" kerning="yes">
		<font-triplet name="simhei" style="normal" weight="normal"/> 
		<font-triplet name="simhei" style="normal" weight="bold"/> 
		<font-triplet name="simhei" style="italic" weight="normal"/> 
		<font-triplet name="simhei" style="italic" weight="bold"/> 
	</font>
	<font metrics-file="simsun.xml" embed-file="file:///c:/windows/fonts/simsun.ttc" kerning="yes">
		<font-triplet name="simsun" style="normal" weight="normal"/> 
		<font-triplet name="simsun" style="normal" weight="bold"/> 
		<font-triplet name="simsun" style="italic" weight="normal"/> 
		<font-triplet name="simsun" style="italic" weight="bold"/> 
	</font>
</fonts>
ok,字体的问题即可解决
		生成的pdf文件的中文每一行都很长，没有断开。在limodou的blog中曾经提到，如果把docbook的zh-cn强制改为zh,
并且做两个假的zh.xml文件即可解决这个问题。显然这是fop的一个bug.fop源代码：
org.apache.fop.layout.LineArea.java 第1407行：
String lang = hyphProps.language.toLowerCase();
if ("zh".equals(lang) || "ja".equals(lang) || "ko".equals(lang)
|| "vi".equals(lang))
ret = true;
显然问题就出在这里。作者想当然的编写了一些需要断字的case,却没有遵守RFC 3066规范。
修改为：
if (lang.startsWith("zh" || lang.startsWith("ja" || lang.startsWith("ko"
|| lang.startsWith("vi")
ret = true;
重新编译fop. 搞定。

3、建立ant的构建文件。

ant是一个非常好用的构建工具，使用和配置都很简单，这里不再对ant进行描述。本文引用hibernate汉化工作组的build.xml文档

例 1.1. build.xml

<project name="HibernateDocumentation" default="all.doc" basedir=".">
    <!-- Set build directories for all formats. -->
    <property name="build.dir"             value="${basedir}/build"/>
    <!-- Support files for build process. -->
    <property name="support.dir"           value="${basedir}/support"/>
    <!-- Set DocBook stylesheets. -->
    <property name="db.style.fopdf"        value="fopdf.xsl"/>
    <property name="db.style.html"         value="html_chunk.xsl"/>
    <property name="db.style.htmlsingle"   value="html.xsl"/>
    <!-- Classpath for the build tools. -->
    <path id="lib.classpath">
        <fileset dir="${support.dir}/lib">
            <include name="**/*.jar"/>
        </fileset>
    </path>
    <!-- ################################################################## -->
    <target name="all.doc"
            depends="clean"
            description="Compile documentation for all languages and all formats.">

        <!-- TRANSLATOR: Duplicate this line for your language -->
        <!--<antcall target="lang.all"><param name="lang" value="en"/></antcall>-->
        <antcall target="lang.all"><param name="lang" value="zh-cn"/></antcall>

    </target>

    <target name="all.revdiff"
            description="Generates a diff report for all translated versions.">

        <!-- TRANSLATOR: Duplicate this line for your language -->
        <antcall target="lang.revdiff"><param name="lang" value="de"/></antcall>

    </target>

    <!-- ################################################################## -->

    <target name="clean">

        <!-- Delete build directory. -->
        <delete dir="${build.dir}"/>

    </target>

    <target name="lang.all">
        <!-- Compile the documentation for a single language in all formats. -->
        <antcall target="lang.docpdf"/>
        <antcall target="lang.dochtml"/>
        <antcall target="lang.dochtmlsingle"/>
        <antcall target="lang.htmlmisc"/>
    </target>

    <target name="lang.docpdf.prepare">

        <!-- Copy all the images to the output location, will be removed later. -->
        <copy todir="${build.dir}/${lang}/pdf/images">
            <fileset dir="${basedir}/${lang}/images">
                <include name="**/*.png"/>
                <include name="**/*.svg"/>
                <include name="**/*.gif"/>
            </fileset>
        </copy>

        <!-- Create the XSL/FO temporary file. -->
        <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${basedir}">
            <classpath refid="lib.classpath"/>
            <arg value="-o"/>
            <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/>
            <arg value="${basedir}/${lang}/master.xml"/>
            <arg value="${basedir}/${lang}/styles/${db.style.fopdf}"/>
        </java>

		<available property="custom.fop.userconfig.present" file="userconfig.xml" 
		filepath="${basedir}/${lang}/fop"/>
    </target>

    <target name="lang.docpdf.customized" depends="lang.docpdf.prepare" if="custom.fop.userconfig.present">

        <copy todir="${build.dir}/${lang}/pdf">
            <fileset dir="${basedir}/${lang}/fop">
                <include name="*"/>
            </fileset>
        </copy>

        <!-- Create a PDF from the XSL/FO, using customized fop userconfig.xml -->
        <java classname="org.apache.fop.apps.Fop" fork="true" dir="${basedir}">
            <classpath refid="lib.classpath"/>
            <arg value="-c"/>
            <arg value="${basedir}/${lang}/fop/userconfig.xml"/>
            <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/>
            <arg value="${build.dir}/${lang}/pdf/hibernate_reference.pdf"/>
        </java>
    </target>
	
    <target name="lang.docpdf.normal" depends="lang.docpdf.prepare" unless="custom.fop.userconfig.present">
        <!-- Create a PDF from the XSL/FO. -->
        <java classname="org.apache.fop.apps.Fop" fork="true" dir="${basedir}">
            <classpath refid="lib.classpath"/>
            <arg value="${build.dir}/${lang}/pdf/docbook_fop.fo"/>
            <arg value="${build.dir}/${lang}/pdf/hibernate_reference.pdf"/>
        </java>
    </target>

    <!--<target name="lang.docpdf" depends="lang.docpdf.normal,lang.docpdf.customfop">-->
		<target name="lang.docpdf" depends="lang.docpdf.normal,lang.docpdf.customized">
        <!-- House keeping,delete temporary files. -->
  <!--
         <delete file="${build.dir}/${lang}/pdf/docbook_fop.txt"/>
        <delete  dir="${build.dir}/${lang}/pdf/images"/>
		<delete>
			<fileset dir="${build.dir}/${lang}/pdf" includes="**/*.xml"/>
		</delete>
	-->
    </target>

    <target name="lang.dochtml">

        <mkdir dir="${build.dir}/${lang}/html/"/>

        <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${build.dir}/${lang}/html">
            <classpath refid="lib.classpath"/>
            <arg value="${basedir}/${lang}/master.xml"/>
            <arg value="${basedir}/${lang}/styles/${db.style.html}"/>
        </java>
    </target>

    <target name="lang.dochtmlsingle">

        <mkdir dir="${build.dir}/${lang}/html_single/"/>

        <java classname="com.icl.saxon.StyleSheet" fork="true" dir="${basedir}">
            <classpath refid="lib.classpath"/>
            <arg value="-o"/>
            <arg value="${build.dir}/${lang}/html_single/index.html"/>
            <arg value="${basedir}/${lang}/master.xml"/>
            <arg value="${basedir}/${lang}/styles/${db.style.htmlsingle}"/>
        </java>
    </target>

    <target name="lang.htmlmisc">

        <!-- Copy images and CSS for HTML documentation, language specific. -->
        <copy todir="${build.dir}/${lang}/shared/images">
            <fileset dir="${basedir}/${lang}/images">
                <include name="**/*.png"/>
                <include name="**/*.gif"/>
            </fileset>
        </copy>
        <copy todir="${build.dir}/${lang}/shared/css">
            <fileset dir="${basedir}/${lang}/styles">
                <include name="**/*.css"/>
            </fileset>
        </copy>

    </target>

    <target name="lang.revdiff">

        <taskdef name="revdiff"
            classname="org.hibernate.docproc.revdiff.RevDiffReportTask"
            classpathref="lib.classpath">

        </taskdef>

        <revdiff original="${basedir}/en/master.xml"
                 copy="${basedir}/${lang}/master.xml"
                 report="${build.dir}/status_${lang}.html"/>
    </target>
</project>

通过上述配置之后，进入该目录运行ant,转换的文档将会放置build目录下，在转换之前请验证xml的正确性。

第 2 章 xsltproc

xsltproc有c和java两种语言的版本。本文描述的是c语言版本的。下载xlstproc。

1、建立如下目录

|---docbook
    +---bin           (1)
    +---lib           (2)
    +---source
    +---docbook-dtd
    +---docbook-xsl

(1)	将xsltproc中*.exe文件放置该文件夹下。
(2)	将xsltproc中所有lib下的文件放置该文件夹下。

2、将bin和lib实际路径设置到系统环境path路径。

以下是xsltproc常用的转换命令

--生成rtf文件 xsltproc 转换样式文件.xsl 待转换文件.xml > 输出文件.rtf 例：xsltproc C:/share/style/docbook-xsl-1.65.1/html/docbook.xsl c:/share/demo1.xml > c:/share/demo3.rtf --生成html文件（分页文件） xsltproc -o 输出目录转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:/share/src/ C:/share/style/docbook-xsl-1.65.1/html/chunk.xsl c:/share/demo1.xml --生成html文件（单页文件） xsltproc -o 输出文件.html 转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:/share/src/demo11.html C:/share/style/docbook-xsl-1.65.1/html/docbook.xsl c:/share /demo1.xml --生成htmlHelp文件 xsltproc -o 输出目录转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:/share/src/ C:/share/style/docbook-xsl-1.65.1/htmlhelp/htmlhelp.xsl c:/share/demo1.xml --生成javaHelp文件 xsltproc -o 输出目录转换样式文件.xsl 待转换文件.xml 例：xsltproc -o c:/share/src/ C:/share/style/docbook-xsl-1.65.1/javahelp/javahelp.xsl c:/share/demo1.xml --生成xml文件 xsltproc -o 输出文件.xml 转换样式文件.xsl 待转换文件.xml 例: xsltproc -o c:/share/src/demo1_xml.xml C:/share/style/docbook-xsl-1.65.1/Xhtml/docbook.xsl c:/share /demo1.xml --生成fo文件 xsltproc xsltproc 转换样式文件.xsl 待转换文件.xml > 输出文件.fo xsltproc C:/share/style/docbook-xsl-1.65.1/fo/fop.xsl c:/share/demo1.xml > c:/share/my.fo

cxjlt

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Transition Docbook

Transition Docbook版本0.1版权 © 2005 lt本文档采用docBook-xml-4.2标准书写,使用saxon6.5.3输出html和fo,用fop0.20.5把fo转换成pdf。刚开始用docbook写文档觉得非常的不适应，毕竟比起用所见即所得的编辑工具来，要费事很多，其中文档的转换我就很费周折，最终通过查阅网上
复制链接

扫一扫