一个简单的Docbook 5.0例子
来源:互联网 发布:国外二维码扫描软件 编辑:程序博客网 时间:2024/04/30 04:21
一个简单的Docbook 5.0例子
我使用Docbook写文档大约才一两个月的时间,但关注Docbook已经很久了,在网上也阅读了很多中文及英文的Docbook文档。一直没用Docbook的主要原因是Docbook 4.2的编译环境配置看起来很繁琐。我曾经尝试配置过一次,但看到一大堆catalog配置、SGML配置、OpenJade配置,最终放弃了。
直到有一天,我看到benr写的Playing With DocBook 5.0,才第一次真正书写Docbook文档。Docbook 5.0不再使用旧的SGML DTD,转而使用XML,编译环境配置简单多了。
下面我先介绍Windows下如何搭建Docbook 5.0编译环境,然后再以一个简单的Docbook 5.0文档为例,讲一下如何把Docbook文档转换成其它格式。
[ Windows下Docbook编译环境的搭建 ]
- 下载Docbook XSL样式表
首先下载Docbook XSL转换样式表。我们只需要下载docbook-xsl-ns即可,目前的最新版本是1.74.3。下载后,把它解压到一个目录中,我这里假设解压到C:\docbook目录,也就是说,Docbook XSL所在的目录是: C:\docbook\docbook-xsl-ns-1.74.3\。
在Docbook介绍一文中我讲过Docbook是”内容与格式分离”的,我们写Docbook文档时只关注文档的内容,而Docbook如何转换成其它文档类型,则由Docbook XSL转换样式表来定义。我们最常用的是转换到HTML格式的样式表,以及转换到FO格式的样式表。
- 下载xsltproc转换程序
接下来,需要下载XML语言转换工具。我喜欢用的转换工具是xsltproc,这是一个由C语言写成的XML转换工具,它的特点是转换速度很快,并且同时支持Windows和Linux。除了这个转换工具外,还有很多Java写的转换工具,例如Saxon, Xalan。
我们到这里下载Windows版本的xsltproc,需要下载下面几个包:
- iconv-1.9.2.win32.zip – 编码转换工具
- zlib-1.2.3.win32.zip – 压缩工具
- libxslt-1.1.24.win32.zip – XSL和EXSL转换工具,xsltproc程序就在此包中
- libxml2-2.7.3.win32.zip – XML解析工具和处理工具,同时提供了验证工具xmllint和xmlcatalog
其实windows下配置docbook是相当的容易,以上四个工具缺一不可
下载后,把这些包解压到同一个目录里,假设解压到C:\docbook\xsltproc目录,解压后,你可以看到在C:\docbook\xsltproc\下多了三个目录:bin,include和lib。现在需要在环境变量PATH中增加C:\docbook\xsltproc\bin,设置后,再打开一个DOS窗口,可以直接输入xsltproc命令,不需要输入使用全路径了。
- 安装FOP
安装了上面的两个工具,你就可以把Docbook文档转换成HTML格式了。如果你需要把Docbook文档转换成PDF格式,还需要安装把XSL-FO格式转换为PDF格式的转换工具,Apache FOP是一个不错的选择。不过我现在没有这方面的需求,暂时没有安装。据说配置Apache FOP支持中文比较繁琐,改天我试过再把经过写出来。(2009/04/11更新,关于Apache FOP的配置,参见文章使用Apache FOP将Docbook文档转换成PDF (一)
现在,Docbook的编译环境就建好了。相比Docbook 4.2,编译环境的搭建容易了很多,你不必再去配置catalog这些东西,因为Docbook 5.0已经不再需要文档类型定义了。
接下来,我们写一个简单的Docbook文档。
[ 编写Docbook文档 ]
你可以在这里下载本例中用到的文件,包括docbook.xml、docbook_easwy.xsl和Easwy的Makefile。
下面是一个简单的Docbook 5.0文档,把这段内容保存一下,例如,存为文件docbook.xml。
<?xml version='1.0' encoding="utf-8"?><article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN" xmlns:xlink='http://www.w3.org/1999/xlink'> <articleinfo> <title>我的第一篇Docbook 5.0文档</title> <author> <firstname>Easwy</firstname> <surname>Yang</surname> </author> </articleinfo> <section> <title>文档介绍</title> <para> 这是我的第一篇Docbook 5.0文档,欢迎你来到<link xlink:href='http://easwy.com/blog/'>Easwy的博客</link>。 </para> </section></article>
[ 将文档转换成HTML格式 ]
在转换之前,要先把输出编码设置为UTF-8。docbook-xsl-ns的缺省输出编码是ISO-8859-1,但对于中文字符,我们应该把输出编码设置为UTF-8,否则输出的文件会显示为乱码。
更改输出编码很简单,你可以直接修改你的C:\docbook\docbook-xsl-ns-1.74.3\html\docbook.xsl文件,在文件中找到
<xsl:output method="html" encoding="ISO-8859-1" indent="no"/>
把它改成
<xsl:output method="html" encoding="UTF-8" indent="no"/>
我一般是另外写一个xsl文件,在这个文件中包含标准的docbook-xsl,然后重新定义自己的编码为UTF-8。把下面的文件保存为docbook_easwy.xsl:
<?xml version='1.0'?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'><xsl:include href="C:/docbook/docbook-xsl-ns-1.74.3/html/docbook.xsl"/><xsl:output method="html" encoding="UTF-8" indent="no"/></xsl:stylesheet>
接下来,我们把上面的Docbook文档转换成HTML格式,使用下面的命令:
xsltproc -o docbook.html docbook_easwy.xsl docbook.xml
如果你看到类似下面的提示,那么你的xsl不是docbook-xsl-ns,而是docbook-xsl。如果不想下载docbook-xsl-ns的话,忽略告警即可,这些告警并不影响使用。
1: Note: namesp. cut : stripped namespace before processing 我的第一篇Docbook 5.0文档
2: WARNING: cannot add @xml:base to node set root element. Relative paths may not work.
3: Note: namesp. cut : processing stripped document 我的第一篇Docbook 5.0文档
如果嫌每次输入转换命令太麻烦,可以把上面的命令保存为一个批处理文件。我在Windows里安装了Cygwin (参考这篇文章安装cygwin),所以一般用Makefile来转换Docbook源文件。我的Makefile内容如下:
# Docbook Makefile# Easwy YangXSLFILE=docbook_easwy.xslXML_FILE=$(wildcard *.xml)HTML_FILE=$(XML_FILE:.xml=.html).PHONY: html cleanhtml : $(HTML_FILE)%.html : %.xmlxsltproc -o $(@F) $(XSLFILE) $<clean:rm *.html
现在,我在vim里可以直接使用:make命令转换我的Docbook源文档了。
- 一个简单的Docbook 5.0例子
- 一个简单的Docbook 5.0例子
- 学习 Docbook 创作一个标准化的文档
- 一个简单的例子
- 简单介绍 DocBook
- 简单介绍 DocBook
- openmp 例子:一个简单的OpenMP例子
- 一个简单的Struts例子
- 一个简单的Hibernate例子!
- auto_ptr的一个简单例子
- 一个简单的Struts例子
- 一个简单的JSF例子
- 一个简单的EJB例子!!
- 一个简单的serverclick 例子
- 一个简单易懂的例子
- 一个GMF的简单例子
- 一个简单的GUI例子
- 一个简单的Hibernate例子
- 真正成功的theos环境配置
- #include <cctype>
- limiter Gem使用记录一
- 知道为什么需要htons(), ntohl(), ntohs(),htons() 函数吗? (转)
- depend工具监测程序
- 一个简单的Docbook 5.0例子
- 创建弹出菜单
- Ruby on Rails 入门之:(23) Ruby 中文件,目录的操作
- Winsock 的初始化
- 常用正则表达式
- dede 内容页获取当前栏目的链接
- Android SDK更新缓慢或无法更新的解决方法
- jQuery获取iframe内的DOM对象并提交iframe的表单
- hibernate自己使用视图