Docbook实践记录

-------------------------------------------

本文系作者原创, 欢迎大家转载!

转载请注明出处:netwalker.blog.chinaunix.net

-------------------------------------------

在使用txt2tags时，发现对某些地方的控制无法调节，比如对图片的排版，遂重新研究了下Docbook，网上介绍Docbook文档众多，但是能够像Hello World程序一样让你快速上手的文档却太少，所以这里记下来，希望对需要的人有所帮助。

 

1. 什么是DocBook

微软的Word实现了所见即所得的编辑方式，通常情况下它可以满足需求，甚至一些庞大的项目，使用它依然可以完成。但是当你尝试编写一些需要嵌入特殊符号的文档时，比如源码，它总很难让人满意。一种非所见即所得的编辑方式是另外一种选择，它的出现甚至要早于Word。

DocBook有超出 15 年的历史了。它在 1991 年开始作为 HaL 和 O'Reilly 的合作项目。随着它的流行和成长，最后产生了自己的维护组织，Davenport 组织。在 1998 年中期，它成为结构化信息标准促进组织(OASIS)的一个技术委员会(TC)。从 DocBook V5.0 开始，DocBook使用用 RELAX NG 和图解定义的 XML 词汇表。但是DocBook 比这些技术都早。它最初是用标准 SGML 文档类型定义来描述的 SGML 词汇表，或者 DTD。 ——DocBook 5.0权威指南

总而言之，DocBook使用RELAX NG 和 XML词汇表作为标记来对文档排版和定制，并提供各种输出格式：html,pdf等。一个Linux上的简单示例只需要两个文件*.xml和*.xsl，和一个应用程序xsltproc。.xml文件使用DocBook定义的标记对内容进行封装，它的语法与html没有任何本质区别。这些标记指明了哪里是文档名，哪里是作者，哪里是文档段等等。所以我们的word文档就变成了.xml文件。它是我们编辑的结果。.xsl是.xml文件转换为其他格式时所需要的规则，比如一个article标记怎么就转换为了html文件中的html和head标记。 xsltproc则是转换的工具，它用C语言写成，它的作用就是使用.xsl作为规则，转换.xml文件到目标文件。

 

2. DocBook的安装和使用

2.1. 安装DocBook
这里是一篇在Windows环境使用DocBook的文档。 这里介绍在Linux环境中的使用，测试环境为：Linux ubuntu 10.0。 DocBook并不是一个应用程序，它可以被看作一个环境，对DocBook的安装就是对DocBook环境的配置，一个最简环境包括xsltproc和一个.xsl转换文件。默认情况下，系统上已经安装了xsltproc，如果没有，使用以下命令安装：

 

#apt-get install xsltproc

从下载docbook-xsl-ns，它里面包含了转换所用的.xsl文件。到这里，一个基本的DocBook测试环境就完成了。

2.2. 使用DocBook
文档的第27章对DocBook的标记做了非常详细的讲解和演示。这里假设编辑一个test.xml文件。注意文件中指定的encoding="utf-8"编码方式，编辑器必须使用相同的编码方式对.xml进行编辑。另外.xml文件标记是大小写不敏感的，但是，它的开始标记和对应的结束标记必须一致。

这里下载最新的docbook-xsl-ns-1.75.2.tar.bz2，解压开后，查看README：

 

fo/docbook.xsl - for XSL-FO
  fo/profile-docbook.xsl - for XSL-FO (single-pass profiled)

  html/docbook.xsl - for HTML (as a single file)
  html/chunk.xsl - for HTML (chunked into multiple files)
  html/onechunk.xsl - for HTML (chunked output in single file)
  html/profile-* - for HTML (single-pass profiled versions)

  xhtml/*.xsl - for XHTML versions of the above

  htmlhelp/htmlhelp.xsl - for HTML Help
  javahelp/javahelp.xsl - for JavaHelp
  eclipse/eclipse.xsl - for Eclipse Help

  manpages/docbook.xsl - for groff/nroff man pages[1]
  [1] more information at http://wiki.docbook.org/topic/ManPages

  roundtrip/*.xsl - for DocBook to WordML, etc., to DocBook

docbook-xsl-ns提供了转换fo，html，xhtml，manpages等对应的xsl文件。我们这里关心html文件夹，对应的.xsl是html/docbook.xsl。注意到文件中的如下规则：

<xsl:output method="html"
            encoding="ISO-8859-1"
            indent="no"/>

这里的encoding="ISO-8859-1"指明了转化后的.html文件的编码方式。显然对应含有中文的文档这种编码并不合适。需要改成encoding="UTF-8"。以下是测试的最终命令，注意./docbook-xsl-ns-1.75.2/html/docbook.xsl的路径。

xsltproc -o test.html ./docbook-xsl-ns-1.75.2/html/docbook.xsl test.xml

2.3. Makefile

即便是最精简的参数，转换.xml文件的命令依然太过冗长，没有人愿意每次都使用命令行。一个简单的Makefile将节约大量的调试时间。

XSLPATH=./docbook-xsl-ns-1.75.2/html
XSLFILE=$(XSLPATH)/docbook.xsl

XML_FILE=$(wildcard *.xml)
HTML_FILE=$(XML_FILE:.xml=.html)

all: $(HTML_FILE)

%.html : %.xml
        xsltproc -o $(@F) $(XSLFILE) $<

clean:
        rm -f *.html

2.4. 如何使用css

使用css层叠样式单，将使转化后的文档更美观，控制也更灵活。参数--stringparam html.stylesheet styles.css 将满足这个要求，把它加入到Makefile中的xsltproc行中，注意styles.css是一个示例名，它应该根据实际进行替换。

XML_FLAGS=--stringparam html.stylesheet styles.css
        xsltproc -o $(@F) $(XML_FLAGS) $(XSLFILE) $<

使用一个成熟的.css文件模板是必要的，毕竟不是所有人都是css专家，也没有人总是喜欢发明轮子。附件中提供了一个akabook使用的 styles.css文件，它基本可以满足通常的需求。

2.5. 章节自动编号

对章节自动编号，是非常强大的和基本的功能，添加参数--stringparam section.autolabel 1 ：

 

XML_FLAGS=--stringparam html.stylesheet styles.css section.autolabel 1
        xsltproc -o $(@F) $(XML_FLAGS) $(XSLFILE) $<

所有通过命令行添加的--stringparam 都可以更改.xsl来实现，这里不做深入探讨，相关的文件中有详细的介绍。还是在实践中掌握DocBook 的使用吧。

2.6. 输出多个.html文件

使用docbook-xsl-ns-1.75.2/html/dockbook.xsl将生成一个.html文件，如果一个文件比较大，那么打开它将耗费很长时间和很多的内存，一个好的方法是将一个.xml文件编译成多个.html文件，这里就需要docbook-xsl-ns-1.75.2/html/chunk.xsl这个转换模板了，只要在Makefile中将dockbook.xsl替换为chunk.xsl就可以了。

2.7. 在vim中编译

待续......

由于附件过大无法上传，遂删除掉docbook-xsl-ns-1.75.2，请自己下载并修改Docbook.xsl文档。附件： example.rar