特殊:Badtitle/NS100:DocBook/zh

翻译人员:

麻辣丝瓜

{{#ifexist: :DocBook/zh/zh | | {{#ifexist: DocBook/zh/zh | | {{#ifeq: {{#titleparts:DocBook/zh|1|-1|}} | zh | | }} }} }} {{#ifeq: {{#titleparts:DocBook/zh|1|-1|}} | zh | | }}

目的

本页的目的是提供一个 DocBook 格式的概述。它介绍此格式的一些优点，提供关于此格式更多的阅读的链接，同时包含了一个简短的教程。

DocBook是什么？

DocBook是一个用于当今许多文档编制任务中的基于XML的标准。当你想要创建一个DocBook文档源码时，你需要编写XML文件来描述文档布局、段落界限和其它属性。如果你此前曾经见过HTML源码，你可能会觉得XML文件的结构很熟悉。XML更像是老式的HTML的改进，它可以用于生成完整的网页页面和其它的标记文档。

DocBook的优点是什么?

DocBook是一个OASIS标准，是大部分开源项目存储它们文档的格式。DocBook是开源应用程序。这个项目在Souce Forge主办，且在GPL下可用。DocBook可用于文档类型定义(DTD)和XML模式(XSD)。此项目有一个跨越开源和商业群体的大的开发者和支持社区。 项目使用DocBook的最重要的原因包括如下：

1. DocBook 是一个标准
2. DocBook 是开源的
3. DocBook 被用于大部分大项目
4. DocBook 有一个大的开发者和支持社区

DocBook同样是一个为文档编制团队解决了许多发布问题的XML应用程序和XML技术。解决的问题包括如下：

• Single-sourcing
• 协同创作
• 跨平台编辑
• 多通道发布
• 提升信息质量和一致性
• Enhancing functionality of electronic output
• Negating vendor lock-in

关于以上几点更多的信息请查阅 http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35 如果你已经理解了XML那么你将很轻易的开始学习DocBook。如果你还不知道XML，那么好消息是，学习DocBook将有助于你学习XML。以下是任何人开始学习DocBook必读的两本书。

进一步阅读

• Doc'Book - The Definitive Guide http://www.docbook.org/tdg/en/html/docbook.html
• Doc'Book XSL – The Complete Guide http://www.sagehill.net/docbookxsl/index.html
• Doc'Book crash course: http://opensource.bureau-cornavin.com/crash-course/index.html.
• Yelp - Gnome帮助浏览器 - 使用DocBook/XML文件路径。在http://developer.gnome.org/projects/gdp/templates.html 中可以找到模板
• 如果你想知道哪些tag用于哪里(而且太懒或查阅官方参考时感觉困惑)请阅读DocBookReference。

如果你已经安装了'docbook-defguide'包，你可以通过你的网页浏览器用如下地址获得指南:

 
http://localhost/doc/docbook-defguide/html/docbook.html (assuming that your Apache still has /doc aliased to /usr/share/doc) 

你也可以使用如下命令获得它:

 
lynx /usr/share/doc/docbook-defguide/html/docbook.html

同时阅读这些作品对实践也是有用的。想要实践的话，你需要一个XML发布工具和一个XML编辑器。DocBook网站和Wiki将为你提供关于工具和编辑器的更多信息的链接。你可以使用这些工具和编辑器来编写DocBook文档。 "[Ubuntu DocBook Interchange Protocol]"中说明了在Ubuntu文档编制项目中对DocBook的使用。

快速教程

DocBook看起来像什么？

就像HTML那样，DocBook定义了一定数量的“标签”。要设置作者名称你可以就像这样写...

<author>
Christoph Haas
</author>

如同你看到的，这和HTML非常相似。以下是一个完整的XML文档，是一个有用的例子。 用于书写这些标签的“flavor”就是XML。因此它被称为DocBook/XML。(另外的一个'flaovr'将是相差不是很大的SGML。XML比SGML要严格。HTML是SGML语言中的一种。大部分人反对SGML，所以Debian中的文档现在被转换成了XML格式的。)即使你还没有使用过XML你也应该不会有太大问题。

样式表

要创建针对你的XML输入的相应的输出文档，你同样需要一个样式表。样式表被称为“XSL转换”(XSLT)，用“可扩展样式表语言”(XSL)写成。 本质上，XSLT描述了如何将一个文档转换成另外一个。 通常你不需知道样式表的样子。 你也需要一个“处理器”来使用XML和XSLT并创建相应的输出文件。我们将使用免费的“xsltproc”程序来达到这个目的。 你可将你的文档转换成如下一些可用的样式表：

• Postscript
• PDF
• XHTML
• man
• texinfo

有些转换器可以将DocBook转换成Yelp。Yelp是Gnome帮助格式。

Hello World

首先你需要安装如下程序包：

- xsltproc (the XSL Transformations Processor)
- docbook-xsl (stylesheets for HTML, XHTML, HTML Help and others)
- docbook-defguide (The Definitive Guide to DocBook - recommended)

输入如下行到一个文件中，并命名此文件为test.xml：

 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd">
<article>
  <title>My first DocBook document</title>
  <sect1>
     <title>The greeting</title>
     <para>
       Hello world
     </para>
  </sect1>
</article>

请注意，你应该使用UTF-8来进行字符编码。 你也可以将你的终端或者编辑器转换成UTF-8模式。 运行这个命令：

xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml

你应该可以在当前路径发现一个叫“test.html”的文件。使用你最喜欢的网页浏览器来查看它。 现在你发现那一行命令干了些什么了吗？ “xsltpro”是转换程序。“-o test.html'”设置输出文件。下一个参数“.../docbook.xsl”是你用于转换的样式表 - 它将XML转换成XHTML。然后最后“test.xml”告诉xsltproc你的输入文件的位置。

定制样式表

看到DocBook输出文件，你大概会失望了。能够自动转换文档很好，可是它可能根本不符合你的网页设计或“企业形象”。然而还是有补救方法的。 样式表一般提供了一定数量的参数以供你调整。通常你可以导入“标准”样式表来写你自己的样式表。比如：

 
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
   <xsl:param name="toc.max.depth">1</xsl:param>
   <xsl:param name="html.stylesheet" select="'/ubuntu.css'"/>
   <xsl:template name="user.header.content">
     <a href="/">Back to main page</a>
   </xsl:template>
</xsl:stylesheet>

这个样式表首先导入前面提到的docbook.xsl。 它也设置了几个参数： This stylesheet first imports the docbook.xsl mentioned earlier. It also sets a few parameters: - 设置TOC(table of contents)的最大深度为“1”。这样只有<sect1>节可以被包含在TCO中。 - 最终的XHTML文档将会使用“ubuntu.css”样式表(CSS)。 - 在页面的顶端包含一个到主页的链接。 这些设置只在XHTML样式表中起作用。对于其它的输出格式你需要其它的设置。上面的设置记录在/usr/share/doc/docbook-xsl/doc/html/index.html 中 你也可以参考http://www.sagehill.net/docbookxsl/

Makefile

如果你多个XML文件或样式表，你也许要在一个Makefile中完成所有的处理。例如：

 
# Add your language file here:
TARGETS = faq.html

XSLTPROC = /usr/bin/xsltproc
XSL = ubuntu.xsl

%.html: %.xml $(XSL)
   @$(XSLTPROC) -o $@ $(XSL) $<

all: $(TARGETS)

clean:
   @rm -f *.html

DocBook to PDF

The simplest way to convert a DocBook to PDF is to install the xsl-fo stylesheet (to convert to FO format), and fop (to convert FO to PDF). For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package.

sudo aptitude install fop docbook-xsl-doc-pdf

Now to convert your docbook file to pdf run:

xsltproc -o intermediate-fo-file.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl input-docbook-file.xml
fop -pdf final-pdf-file.pdf -fo intermediate-fo-file.fo

Here's an example Makefile for a docbook named networkmanager-manual.xml:

STYLESHEETS_DIR = /usr/share/xml/docbook/stylesheet/nwalsh

all: html pdf

html:
	xsltproc -o networkmanager-manual.html $(STYLESHEETS_DIR)/xhtml/docbook.xsl networkmanager-manual.xml

fo:
	xsltproc -o networkmanager-manual.fo $(STYLESHEETS_DIR)/fo/docbook.xsl networkmanager-manual.xml

pdf: fo
	fop -pdf networkmanager-manual.pdf -fo networkmanager-manual.fo

clean:
	rm -rf networkmanager-manual.html networkmanager-manual.fo networkmanager-manual.pdf

To use the makefile, just change the input and output names (networkmanager-manual.*) to whatever you want them to be. Note: The w3-Organization has blocked the download of the necessary dtd files by unknown user agents. Due to this (at least in Karmic) fop throws a TransformerException with the notice that the w3 server returned a 503 HTTP response. The workaround seems to be to set up a local dtd repository, as noted here and here. The dblatex program can also do this.

Editing Programs

1. Bluefish

• This editor has syntax highlighting and code snippets for DocBook and many other languages.
• See http://bluefish.openoffice.nl/index.html

1. conglomerate (WYSIWYG)

• Somewhat beta. Doesn't hide the gory details. You still need to read the DocBook reference. Just makes it graphical.
• See http://www.conglomerate.org/

1. VIM file type plugin "xmledit"

• Good for vim-lovers. See http://www.vim.org/scripts/script.php?script_id=301
• A recent update based on the above script. http://www.vim.org/scripts/script.php?script_id=1397

1. EMACS XML support

• Some say DocBook is easy to write only under psgml. Some use Emacs only for psgml-mode.
• nxml-mode however is far superior to psgml-mode. It does real-time syntax and error highlighting.

1. See also DocBookEditors.