Docbook写作指南

1. 概述

DocBook提供了一个使用SGML/XML撰写结构化文档的系统。这个系统非常适合于计算机类的文章、书籍、论文等的出版，当然并不仅仅限于计算机类。DocBook已经被Linux、FreeBSD等众多的项目制定作为文档撰写格式，并且有越来越多的组织和个人开始使用。

本文只是一个简要指南。收集了一些DocBook的学习资料，和我自己的一些心得。

如果想快速了解DocBook，可以看这里：DocBook的HelloWorld起步。
2. DocBook语法

学习DocBook，基本的语法是一定要掌握的，即便你使用所见即所得编辑器。下面是学习DocBook语法的一些资源：

    *

      Writing Documentation Using DocBook

      一个非常好的英文Docbook语法教程。也可以作为常备的速查手册。

    *

      DocBook 助你完成传世之作

      中文的教程。入门必看。有助于了解DocBook的全貌。
    *

      DocBook学习

      中文语法教程。也提到了DocBook格式转换的内容，特别是XSLT部分，是比较好的中文资料。

3. DocBook编辑器

DocBook可以用任何文本编辑器来编辑。但是为了提高生产力，我们可以使用一些更方便的工具。

    *

      DocBookAuthoringTools

      这是一个DocBook书写工具的列表。比较全面。

但上述列表还并不能大全。至少还遗漏了Kate，Quanta Plus和OpenOffice（当然还有其他一些形形色色的XML编辑器）。前面两个都是KDE的项目，只能在KDE环境下运行。OpenOffice编辑DocBook我还没有用过。

    *

      Kate编辑DocBook XML文档

      这是我2002年翻译的一篇文章。
    *

      Quanta as a Docbook Editor

      Quanta Plus是一个不错的Html/XML编辑器，用来编辑DocBook也非常好。

我推荐的编辑器：

    *

      XMLMind XML Editor

      这是我现在用的DocBook编辑器。所见即所得方式。基于Java，标准版免费，可以跨平台使用。不过我是在Linux环境用。

      我用过不少的DocBook编辑器，这是我看见过最好用的。
    *

      Quanta Plus

      非所见即所得方式。基于KDE。

4. 转换DocBook

DocBook格式的文件可以转换成很多文件格式来发布。比如：Html,Rtf,Pdf,甚至Word。

在 DocBook学习 和 DocBook助你完成传世之作 两篇文章中，介绍了 OpenJade和Saxon两种转换工具和它们的使用方法。

按照我很早以前的印象，使用OpenJade将DocBook转换成RTF和Html，中文是正常的。使用其他工具，基本上多少会遇到一点中文方面的麻烦。

如果你使用XMLMind XML Editor标准版，那么在DocBook菜单下面已经内置了转换成Html的工具（标准版不能将DocBook转换成其他格式）。不过XMLMind转换出来的html文件编码都是iso-8859-1的。

另外，你还可以关注一下在Windows下使用的Chinese DocBook Environment（CDBE） 。

下面介绍我自己使用的转换方法。环境是Ubuntu Linux。

4.1. DocBook->Html

4.1.1. 环境准备

    *

      安装xsltproc

    *

      安装docbook-xsl

    *

      建立合适的xsl

      找到我们刚才安装的docbook-xsl中的docbook.xsl，把它copy成docbook_utf8.xsl(因为我的系统语言设定是utf 。

cp /path/html/docbook.xsl /path/html/docbook_utf8.xsl

      编辑这个docbook_utf8.xsl，找到：

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

      替换为：

<xsl: output method="html"
            encoding="utf8"
            indent="yes"/>

      在这段话之后，我们添加：

<xsl: param name="html.stylesheet" select="'style.css'"></xsl:param>
<xsl: param name="table.borders.with.css" select="1"></xsl:param>
<xsl: param name="l10n.gentext.language" select="'zh_cn'"></xsl:param>
<xsl: param name="admon.graphics" select="1"></xsl:param>
<xsl: param name="section.autolabel" select="1"></xsl:param>
<xsl: param name="section.label.includes.component.label" select="1"></xsl:param>
<xsl: param name="ulink.target" select="'_blank'"></xsl:param>

      这些是样式表参数，它的具体意义请参考HTML Parameter Reference，这是DocBook Xsl文档的一部分。
    *

      建立转换脚本

      创建新文件/usr/bin/docbook2html,内容如下：

#/bin/sh
xsltproc /path/html/docbook_utf8.xsl $*

      将其设置为可执行文件。

4.1.2. 转换步骤

docbook2html YourDocBook.xml>YourDocBook.html

这样，我们就得到了html结果。

这个Html可以使用同级目录下的style.css来美化输出。

你可以去网上找那些docbook转化出来的html（根据docbook的风格是很容易识别的），然后把它们使用的css下载下来使用就可以了。

比如：

    *

       http://www.sagehill.net/docbookxsl/
    *

       http://worldhello.net/doc/docbook_howto/index.html
    *

       http://pyrecord.freezope.org/docbook/index.html

我使用的是XMLMind XML Editor转换出来的html所带的css。