2005年10月03日

没有什么太大的变化,主要是更新了一些错误。特别感谢老康的工作。

最新版下载:docbook_step.zip

2004年04月01日

中文的确是一个很头痛的问题。在顺利将XML 写成的DocBook文档转换成HTML之后,我面临的下一个挑战就是如何将其转换为PDF。如果是英文的文档,一切都很OK。将xsl改为fop/docbook.xsl,然后执行fop -fo your.fo -pdf your.pdf即可,但在转换中文上,却不是这么简单。

我与weck朋友关于转换的问题经过了一系统的尝试。大家可以看看我俩的讨论:

reStructuredText研究

其实,让FOP支持中文字体还算容易,如何转换可以参考weck写的方法:

用FOP将DocBook输出为PDF文档

不过,转换后的pdf文档的中文断字有问题,有些行还没有结束就跳到了下一行上去了。结果为了解决中文断字的问题我查了好多地方都无功则返。weck也转成使用DocBook in ConText来转换DocBook 文档了(不过,DocBook in ConText是直接处理XML文档,而不是生成的xsl-fo文档,这样效果与标准的DocBook相差很大;而且还要用到Tex,那也是一件不小的工程。)

于是在感慨之余,我写了一篇可怜的中文!,用来表示我的感叹。不过,有位SummerRain
朋友给我留了个言,告诉我如何解决中文断字的方法:就是将fo文件中的language都设为zh即可。非常感谢他,在经过我的又一番试验之后,中文断字就算是解决了。下面就我的实验记录如下:

1. 如何从原始的xml变成xsl-fo后,使得language=”zh”生效。

SummerRain朋友的方法是在xsl-fo文件中加入language=”zh”,但这个xsl-fo文件不是我的源始文档,它是从原始的xml经过转化后生成的,因此直接修改xsl-fo的方法不适合。如果大家看过我写的《DocBook学习》教程,上面讲述了如何支持中文的方法(我使用的方法)。我简单地描述一下:

    • 使用utf-8编码,文件也要用utf-8编码保存
    • 使用<xsl:param name=”l10n.gentext.language” select=”‘zh_cn’”/>参数设置

zh_cn是docbook-xsl中定义好的中文相关的信息文件,它可以将docbook-xsl转换xml后生成的一些标准用语变成中文,如“Table of Contents”就变成“目录”了。那么在转换xsl-fo文件时也使用这一参数,一方面也起到上述作用,另一方面,你打开生成的xsl-fo文件后,会看到language=”zh_cn”。也就是说在xsl-fo中已经加入了language=”zh_cn了”。不过不是zh。那么结果就是,断字依然有问题。如果一步到位呢?没办法,我只好将docbook-xsl中的common/zh_cn.xml文件拷贝到common/zh.xml。然后在common/l10n.xml中加入了zh.xml的entity定义和它的引用。还要将common/zh.xml文件开始处的language=”zh_cn”改为language=”zh”。这样,我们把上面的select=”zh_cn”改为select=”zh”就行了。再生成xsl-fo文件,打开后会看到language的值为”zh”了。

这样断字问题基本解决。

2. 未解决的问题

但是还有一些问题没有解决,也许有好心人会帮助我。我列在下面:

  • 有些中文标点是不能在句首的,但FOP可不管这一套,因此如何避免标点符号出现在句首?
  • Bookmark中二级以后的标题看不到,但文档正文中的标题都正常。
  • 没有斜体
  • 如何使用中文Type1字体
  • 有些样式出不来,如设置bullet前面的点的样式,在生成pdf后都是圆点。

3. 要注意问题

  • 表格的宽度不能象生成HTML一样。因为HTML会自动调整表格的宽度,而FOP不行,它是很精确的,因此只能多试,宽度的比例一定要合适。
  • 如果是原样输出的话,一行太长不会自动折行,这样出伸出纸张的边缘,因此对于象程序清单、命令行之类的原样输出内容要加入换行。

下面附上我所用的转换驱动样式表内容,大家可以自行测试:

<?xml version=’1.0′?>
<xsl:stylesheet xmlns:xsl=”http://www.w3.org/1999/XSL/Transform
version=”1.0″>

<xsl:import href=”../docbook-xsl/fo/docbook.xsl”/>

<xsl:param name=”body.font.family”>simsun</xsl:param>
<xsl:param name=”monospace.font.family”>simsun</xsl:param>
<xsl:param name=”title.font.family”>simhei</xsl:param>
<xsl:param name=”saxon.character.representation” select=”‘native’”/>
<xsl:param name=”admon.graphics” select=”1″/>
<xsl:param name=”section.autolabel” select=”1″/>
<xsl:param name=”section.label.includes.component.label” select=”1″/>
<xsl:param name=”table.borders.with.css” select=”1″/>
<xsl:param name=”use.extensions” select=”1″/>
<xsl:param name=”tablecolumns.extension” select=”0″/>
<xsl:param name=”callout.unicode” select=”1″/>
<xsl:param name=”callout.unicode.start.character” select=”10102″></xsl:param>
<xsl:param name=”variablelist.as.blocks” select=”1″></xsl:param>
<xsl:param name=”callout.graphics” select=”0″/>
<xsl:param name=”fop.extensions” select=”1″/>
<xsl:param name=”hyphenate”>false</xsl:param>
<xsl:param name=”l10n.gentext.default.language” select=”‘zh’”/>
<xsl:param name=”paper.type” select=”‘A4′”/>
<xsl:param name=”draft.mode” select=”‘no’”/>
<xsl:param name=”generate.toc”>
appendix toc
article/appendix nop
article toc,title
book toc,title
chapter nop
part toc,title
preface toc,title
qandadiv toc
qandaset toc
reference toc,title
sect1 nop
sect2 nop
sect3 nop
sect4 nop
sect5 nop
section nop
set toc,title
</xsl:param>

</xsl:stylesheet>

2004年03月30日

上回写完《阅读笔记(一)》之后,再看一看,不象笔记,还是象翻译。这可能是一边读,一边写的缘故。因此,这次是把内容通读得差不多了,才开始动手写,可能效果会好一些。因此这一次的笔记只记录了我认为最有用的东西,为了更全面地现理解docbook,建议还是看一看原版的吧。如果只是想了解一下,看看这个可能也行(希望如此)吧。

2 Creating DocBook documents

这里我只关注如何生成xml的docbook,因此有关sgml的内容只好请大家自行阅读了。那么要生成xml格式的docbook,应该知道哪些东西呢?

+ 如何才是一个格式正确的xml文档
+ docbook的结构划分
+ docbook的标记使用

如何才是一个格式正确的xml文档

因为使用xml格式,因此,写出来的docbook首先应该是一个格式上正确的xml文件。关于xml语法问题只列出一些重要的地方,更具体的要参考相关的资料。

.xml文档开始必始有一个xml的声明,如<?xml version=”1.0″?>
.属性值必须用引号引起来,可以用单引号(‘),或双引号(“)
.xml是大小写敏感的。有关docbook的元素名全部用小写。
.标记必须要关闭,而且要正确的嵌套

不过要注意的是,格式正确并不等于有效。怎么叫有效,这就必须同DTD联系起来才可以。一个DTD(Document Type Declaration,文档类型声明)用来描述xml中的结构组成,每个结构的格式要求等内容。使用它的目的是对xml文档进行内容检查。因此为了保证你的xml文档是docbook的格式,应该引入DTD,以便对xml进行内容检查。DTD声明一般放在xml声明后。下面是一个例子:

<?xml version=”1.0″?>
<!DOCTYPE book PUBLIC “-//Norman Walsh//DTD DocBk XML V3.1.4//EN”
“http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd”>

从这个声明可以了解,book是文档的根元素,DTD使用了PUBLIC声明。后面是这个DTD的URI,它是放在网上的。如果使用SYSTEM声明,则说明DTD是放在本地的。要注意,一般要使用file:///地址,如一个例子:

<?xml version=”1.0″?>
<!DOCTYPE book SYSTEM “file:///d:\docbook\docbook-xml-4.2\docbookx.dtd”>

DTD中可以包含内部子集,如定义实体(entity)。这样你可以将一个XML分割成多个文件,然后在主文档中使用实体引用它们以生成一个完整的文档。如:

<?xml version=’1.0′?>
<!DOCTYPE book PUBLIC “-//Norman Walsh//DTD DocBk XML V3.1.4/EN”
http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd [
<!ENTITY chap1 SYSTEM "chap1.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>

Catalog 文件是用来将public声明映射到system声明的一种查找机制。这样文档中可以使用public进行声明,而通过catalog将其定义为本地内容,从而不用从网上去取相应的文档了。

docbook的结构划分

物理分割

你可以将一个xml文档分割成多个文件,然后通过一个主文件引用起来。引用的方法要使用实体。一个主文件的示例如下:

<?xml version=”1.0″?>
<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook V3.1//EN” [
<!ENTITY chap1 SYSTEM "chap1.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>
<book><title>My First Book</title>
&chap1;
&chap2;
</book>

这样每章内容和附录可以写在分离的文件中。要注意的是:这些分割的文件不能再有文档类型的声明。例如,第一章象这样开始:

<chapter id=”ch1″><title>My First Chapter</title>
<para>My first paragraph.</para>

逻辑分割

Sets
Books(书集)
Divisions(将书分成几部分)
Components(将书或divisions分成章)
Sections(Components的子分割)
Meta-information元素
Block元素
Inline元素

我个人的感觉是一级比一级包含的内容要少。

docbook的标记使用

book可以由下列元素组成:

Dedication 贡献页,出现在书的前面
Navigational Components 导航性组件,ToC (Tables of Contents,目录),LoT(Lists of Titles,标题列表,如:图表,表格,例子等的列表),Index(索引)
Divisions 是book下的第一级。他们包含Parts和References。Parts包含components。References包含RefEntrys。
Components 类似于章节的元素

Components可以包含block元素和sections。

section(节)有几种形式(只列常用):

sect1…sect5 注意标准只有5层编号的section
section 可以有任意层嵌套
simlesect 是最终结的section,在其中不能嵌套任何其它section元素
bridgehead 是一个section标题的清单
refsect1…refsect3 只在refentrys中出现

Block元素:

lists 分几种

calloutlist 插图编号列表。一般是用编号的图形
glosslist 术语表
itemizedlist 无序列表
orderdlist 有序列表
segmentdlist 一个重复的命名项的集合。如美国的州和州的首府可以用它来表示
simplelist 简单列表
variablelist 术语和其定义(或描述)的列表

Admonition (警告)

有五种:caution, important, note, tip, warning

对行有特定要求的环境

address(地址), programlisting(与程序相关的源代码,代码片段和类似的东西), screen(屏幕,以文本方式抓取), screenshot(截屏,图片), synopsis(大纲,用于命令和功能的大纲)

例子,图形,表格

example, informalexample, figure, informalfigure, table, informaltable

formal元素有标题,而informal元素没有标题。

段落

para, simpara

公式

equation, informalequation

图片

graphic 常用在figure和screenshot元素中。mediaobject可以引入其它的媒体,包括:视频、音频、图片、文本数据。

Q&A

qandaset,是一个问题question和答案answer的集合

其它block元素

blockquote 块引用
cmdsynopsis 命令的参数和选项的环境
epigraph 在文档前的一段简介,典型的是一段引用
funcsynopsis 函数的参数和返回值的环境
highlights 高亮
msgset 相关错误

Inline 元素

它一般是用来改变字体或其它小的修改,不会引起行或段的分割。

传统印刷inline

abbrev(缩写), emphasis(强调), footnote(脚注), phrase(短语), quote(引用), trademark(注册商标)

交叉引用

anchor(设置锚点), citation(用于引用外部著作的术语), citerefentry(对一个参考页的引用), citetitle(被引用著作的标题), firstterm(一个术语的第一次引用), glossterm(术语), link(链接), olink(强调是间接引用), ulink(强调是通过URL引用), xref(引用文档的其它部分)

Markup 标识

用于标识文本以获得特殊的显示。

数学

用户界面

程序语言和结构

操作系统

等不再列举。更详细地要查看docbook的参考部分,有说明,有示例。

2004年03月27日

真被中文搞死了。这不我在学了DocBook之后面临的一大问题是,在实际应用中如何支持中文。生成HTML文件还没什么关系,但生成pdf就乐不起来了。


FOP


只要加入新的字体即可支持中文,但中文的断字有问题。中文的断字是可以在任何汉字中间断开,但同时还要避免标点符号出现在句首。Fop生成的文档可能会中间断开,文档变得古怪。


Docbook in Contex(Tex)


Context中文本支持不错,但用了Docbook In Context包后,信息更乱了。中文是看得见,但效果就太差劲了。安装MikTex虽然不是太费力气,但也不容易。要下载字体包,修改ConTex的配置文件。好在有人写过中文配置说明,它装还顺利。可能定制的话会好些,但Tex可不是一个省油的灯,东西太多,太复杂了。而且ConTex是基于xml的,不是基于xsl-fo的,对于这个,我并不满意。


PassiveTex


又是一个Tex的实现。安装没什么问题,与Docbook in Contex不同,它处理的是xsl-fo文件,这个固然好,但现在还不知道如何使其支持中文。


头痛。


现在想一想,我要的其实是与HTML效果差不多就行了,那么有两种解决方案我是可以接受的:


HTML->PDF
Xsl-FO->PDF


对于第一种情况,等HTMLDOC 1.9出来再说吧


第二种情况,还没有好的方法或工具。如果能解决Fop的断字问题,我想,暂时我可以满足了。


实现不行,难道要我用Tex吗?

2004年03月23日

今天在weck的blog上看到docbook的wiki,记下来,有时间看一看。

2004年03月18日

今天试了试HTMLDOC,不支持中文,不支持多字节码。Q&A上说要1.9才支持,等等看吧。而且加入html页面时不能只加入一个起始文件,相关的文件都要加入。加入好象还有顺序。因为不支持中文就没有继续试下去。等1.9出来了再看看吧。

2004年03月17日

它是什么?它是一个可以将html转换成pdf的工具。这是我偶然在diveintopython一书中看到的。这本书是使用docbook编写的,它使用saxon将xml转换成html,然后,没有将xml转成xsl-fo,再转成pdf,而是用htmldoc将html转成pdf的。关注一下。


htmldoc 地址:http://www.easysw.com/htmldoc

2004年03月14日

关于如何在自已的程序中调用FOP,将xml文件转换成PDF文件。特别有如何实现中文化的说明。


http://www-900.ibm.com/developerWorks/cn/xml/x-fop/index.shtml