简单介绍 DocBook

简单介绍 DocBook A gentle guide to DocBook

简单介绍 DocBook

How to use the portable document creator

如何使用这个可移植的文档创建程序

作者：Joe "Zonker" Brockmeier (jbrockmeier@earthlink.net) 自由作家

发布日期：1 September 2000

译者：taowen (taowen.bitapf.org)

翻译日期：2004 年 2 月 4 日

出处：IBM DeveloperWorks

Contents:

What is DocBook?

Why use DocBook?

Creating a document with DocBook

Including images

Including code

Including lists

A basic template

Converting to other file formats

Exporting to HTML

Exporting to plain text

Exporting to PostScript

Where to go next

Resources

About the author

什么是 DocBook？

为什么使用 DocBook？

用 DocBook 创建文档

包含图像

包含代码

包含列表

一个简单的模板

转换为其他的文件格式

导出到 HTML

导出到纯文本

导出到 PostScript

下一步干什么

资源

关于作者

This article explains what DocBook is and how to create a simple document using DocBook. Joe Brockmeier walks you through creating a document and using SGML-tools Lite to parse the document and make HTML, PostScript, plain-text, and PDF versions of the document. He also includes further references on DocBook and tips on where to find SGML-tools lite and other DocBook tools.

本文解释什么是 DocBook 并且使用 DocBook 创建一个简单的文档。Joe Brockmeier 带你创建一个文档并且使用 SGML-tools Lite 来解析文档创建文档的 HTML，PostScript，纯文本，以及 PDF 版本。他还包括了 DocBook 的更多参考资料以及去哪儿找 SGML-tools lite 以及其他 DocBook 的工具的提示。

If you've ever thought about writing documentation for an open source project, or if you've browsed the Linux Documentation Project or any page dedicated to documentation for Linux or other open source projects, you've probably heard of DocBook. But you may not be quite sure what it is.

如果你曾经听闻如何给开源项目撰写文档，或者你已经浏览了 Linux 文档项目或者任何服务于 Linux 或者其他开远项目的文档的页面，你可能已经听说了 DocBook。但是你可能还不怎么确信它是什么。

What is DocBook?

什么是 DocBook？

DocBook is a markup language defined by an SGML or XML document type definition (DTD). Basically, DocBook is a set of tags that describe a document's structure. DocBook tags are similar to HTML tags, so if you've done any HTML, then DocBook won't be entirely foreign to you. DocBook is a bit more involved than HTML, but it is also much more useful than plain HTML because it facilitates the rendering of multiple formats from a single document. This article will describe how to create a simple article (document) in DocBook and how to use SGML-tools Lite to render several types of file-formats from that document.

DocBook 是一个由 SGML 或者 XML 文档类型定义（DTD）定义的标记语言。简单地说，DocBook 是一套描述文档结构地标签。DocBook 的标签类似于 HTML 的标签，因此如果你写过 HTML，那么 DocBook 对你来说不会太陌生。DocBook 比 HTML 要更复杂一些，但是它也比普通的 HTML 要有用得多因为它提供了把一个单一文档渲染为多种格式的功能。本文将描述如何用 DocBook 创建一个简单的文章（文档）以及如何使用 SGML-tools Lite 来从这个文档渲染出好几种文件格式。

DocBook has been around, in one form or another, since 1991. Originally DocBook was created to help exchange UNIX documentation. Since then DocBook gone through four major versions and now is under the guidance of the Organization for the Advancement of Structured Information Standards, better known as OASIS (see Resources).

DocBook 已经以种种形式存在很久了，从 1991 年开始。起初 DocBook 被创建来帮助交换 UNIX 文档。自那以后，DocBook 又经历了四个主要的版本，现在是在格式化信息标准进步组织，更常见的是 OASIS （参见资源），的领导下。

Occasionally, the term DocBook is also used as a catchall term to describe the markup language and the tools used to convert DocBook documents into other formats. Technically, DocBook is only the DTD, but without SGML-tools Lite and other conversion tools DocBook isn't quite as useful.

偶然地，DocBook 这个词也被当作一个万金油的词来描述标记语言以及用来把 DocBook 文档转换为其他格式的工具。技术上，DocBook 仅仅是 DTD，但是没有 SGML-tools Lite 以及其他转换工具，DocBook 不会太有用。

Why use DocBook?

为什么使用 DocBook？

The main selling point for DocBook is its portability. A document written in DocBook markup can be converted into HTML, PostScript, PDF, RTF, DVI, and plain ASCII text easily and quickly without any expensive tools. In fact, DocBook and all of the tools used to work with DocBook are freely available under open source licenses. DocBook documents are plain text, and can be edited with any text editor or word processor that can save documents as plain ASCII text. Note that if you use a word processor, take extra care to save DocBook documents as plain text; otherwise they will not parse correctly. If you'll want to use your documentation in more than one format, like print and online, you'll find DocBook is a great solution.

DocBook 的主要卖点是可移植性。一个用 DocBook 标记语言写的文档能够快速简单地转换为 HTML，PostScript，PDF，RTF，DVI，以及 ASCII 纯文本，并且不需要任何昂贵的工具。事实上，DocBook 以及所有配套 DocBook 使用的工具都是在开源授权下自由供使用的。DocBook 文档是纯文本，并且能够用任何文本编辑器或者能够把文档存储为 ASCII 文本的字处理器编辑。注意，如果你使用的是字处理器，格外要注意把 DocBook 存为纯文本；否则他们不能被正确的解析。如果你不想把你的文档以多于一种格式来使用，像打印版本和网络版本，你可能会发现 DocBook 是一个极好的选择。

Another advantage of DocBook is that it frees the author from worrying about the formatting and layout of a document. DocBook is only concerned with the structure of a document. For instance, an author simply uses the DocBook markup to indicate text that should be emphasized with the <emphasis> tag. Depending on what format the document is converted to, the emphasized portion may be italicized, underlined, or set in boldface type. This is one less thing for the author to worry about while writing a document.

DocBook 的另外一个优势是它把作者从对文档的排版和格式的担心中解脱出来。DocBook 仅仅关心文档的结构。例如，一个作者简单地使用 DocBook 地 <emphasis> 标签来表明文本需要被强调。根据需要转换为什么样的格式，强调的地方可能会变成斜体，下划线，或者被设置为粗体。这不再是作者在编写文档时担心的问题。

Creating a document with DocBook

用 DocBook 创建文档

Creating a document with DocBook is easy. We'll focus on creating a document using the SGML DTD. With the exception of the document declaration, everything in this article should apply to XML as well as the SGML DTD.

用 DocBook 创建文档不难。我们将集中精力看看如何使用 SGML DTD 创建文档。除了文档声明这一个例外，本文中的所有内容都能同时用于 XML 和 SGML DTD。

To begin, fire up your favorite text editor and create a new document. The first line of a DocBook document is the document declaration.

首先，打开你最喜欢的文本编辑器，创建一个新的文档。DocBook 文档的第一行是文档声明

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

Every DocBook document requires a document declaration to be considered valid. This lets SGML-tools Lite, or whatever tool you're using, know what version of the DTD you are using and the type of document that you are creating.

所有 DocBook 要成为 valid 的都需要一个文档声明。这使得 SGML-tools Lite 或者任何其他你正在使用的工具，知道 DTD 的版本以及你创建的文档的类型。

Now we'll start adding a little meat to the document. We'll start with a title, author information, and a short paragraph. This brief example shows a few of the basic DocBook tags, or elements, in use. While DocBook elements may look similar to HTML tags, remember that DocBook parsers are much more demanding than your average Web browser. While you can get away with not declaring an HTML document, or even skipping some "required" tags, DocBook is not quite so forgiving. Be careful to include all required elements and use them in their proper order.

现在我们开始给文档添加一些内容。从标题，作者信息以及一个小段落开始。这个简短的例子展示了一些在用的基本的 DocBook 的标签，或者元素。DocBook 的元素可能看上去和 HTML 标签类似，但是记住 DocBook 的解析器比你的 Web 浏览器得要求要严格得多。你可以不声明 HTML 文档，甚至省略一些 "必须" 的标签，但是 DocBook 不会这么宽大。注意包括所有必须的元素并且用合适的顺序使用他们。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<title>A gentle guide to DocBook</title>

<surname>Brockmeier</surname>

</author>

</articleinfo>

<title>A brief introduction to DocBook</title>

<para>

If you've ever thought about writing documentation for an open source project...

</para>

</sect1>

</article>

Most of the elements used here are self-explanatory. Some of the elements, such as the <firstname> and <surname> elements, are only valid when nested inside their parent elements. The <firstname> and <surname> elements, for example, are valid nested within their parent element <author> but would not be valid if used within the <para> element.

这儿使用的大部分元素是其意自明的。一些元素，比如 <firstname> 和<surname> 元素，仅仅在它们的父元素中才是有效的。例如，<firstname> 和<surname> 元素嵌套在它们的父元素 <author> 中是有效的但是如果使用在 <para> 元素中就不是有效的。

There are five levels of the sect element: <sect1> through <sect5>. Unlike HTML where you can skip from a <h1> tag to a <h3> tag, you cannot skip from a <sect1> to a <sect3> element. DocBook is much more strict than HTML.

sect 元素有5个级别：<sect1> 到 <sect5>。不像 HTML，其中你可以忽略 <h1> 标签直接到 <h3> 标签，你不能越过 <sect1> 直接到<sect3> 元素。DocBook 比 HTML 严格多了。

The next element is the <para> element. The <para> element is easy to remember because it stands for paragraph. You will probably find that the majority of DocBook elements make sense, and you probably won't need to look up the common elements after writing one or two documents with DocBook.

下一个元素是 <para>。<para> 元素很容易记住，因为它意为 paragraph（段落）。你可能发现 DocBook 的大部分元素是有意义的，而且你可能用 DocBook 写了一两个文档之后个不需要查找常用的元素了。

Some elements in DocBook can also include attributes that further describe the element. The <sect1> element in the above example includes a label attribute. Generally elements have optional attributes. However, some elements like the <ulink> element require an attribute. If you're unsure, check the official DocBook documentation to see what attributes are applicable to the elements you are using (see Resources).

一些 DocBook 中的元素也能包括进一步描述元素的属性。前面例子的 <sect1> 元素包含一个 label 属性。通常元素都有可选的属性。然而，一些元素像 <ulink> 必须有属性。如果你不确信，检查官方的 DocBook 文档看看哪些属性可以作用于你正在使用的元素。（参见资源）

Including images

包含图像

To include an image in your document, you can use any of several elements. The <graphic> element is being phased out in favor of the <imageobject> element, so we will focus on the use of the <imageobject> element.

要把图像包含到你的文档中，你可以使用几种元素。<graphic> 元素不如 <imageobject> 元素，因此我们将关注 <imageobject> 元素的使用。

To include an image in your document, you will use three elements: the <mediaobject> element, the <imageobject> element, and the <imagedata> element.

要在你的文档中包含图像，你将使用三个元素：<mediaobject> 元素，<imageobject> 元素，以及 <imagedata> 元素。

</imageobject>

</mediaobject>

This code includes the fuzzy.eps image in your document when you render it using SGML-tools Lite or one of the other DocBook conversion tools. Note that eps is a good format for printing documents or converting to PDF, but you would want to use a JPEG, GIF, or PNG file for Web publication. The DocBook rendering tools do not convert image file formats, so you'll need to have them in a native format for whatever type of output you want to use.

当你使用 SGML-tools Lite或者其他 DocBook 转换工具渲染它时，这些代码在你的文档中包含了 fuzzy.eps 图像。注意 eps 时用于但因文档或者转换为PDF 的良好格式，但是你可能使用 JPEG，GIF，或者 PNG 文件于网络发布。DocBook 渲染工具不会转换文件格式，因而你对你想要的任何类型的输出需要保持它们是原生格式。

Including code

包含代码

Often when writing documentation it is useful to quote source code within the document. The <programlisting> element is used to display source code as is. This is similar to the <pre> tag in HTML, however the <programlisting> element can include other DocBook elements that will get interpreted.

时常在编写文档时，在文档中引用源代码是有用的。<programlisting> 元素用来照实显示源代码。这类似于 HTML 中的 <pre> 标签，然而 <programlisting> 元素能够包含其他会被解释的 DocBook 元素。

<para>

function F_pollList() {

global $db,$G_URL;

$sql = "SELECT *,DATE_FORMAT(Birthstamp,'%c/%e/%y @ %h:%i %p') ";

$sql .= "AS Date FROM T_PollQuestions";

$question = @mysql_query($sql,$db);

$nquestion = mysql_num_rows($question);

F_start("List of Polls");

if ($nquestion > 0) {

} else {

print "There are no polls available at this time.";

}

F_end();

}

</programlisting>

</para>

Note that the above code uses the < and > characters, which would cause problems in an HTML document. SGML-tools Lite converts < and > to their appropriate escape codes when converting to HTML.

注意上面的代码使用了 < 和 > 字符，这将在 HTML 文档中导致问题。SGML-tools Lite把 < 和 > 在转换为 HTML 时把 < 和 >转换为它们相应的转义字符。

Including lists

包含列表

One thing that you'll probably want to do as well is make lists -- either bulleted lists or numbered lists -- using the <itemizedlist> element:

你可能还像做的一件事是做列表——要点列表或者序号列表——使用 <itemizedlist> 元素：

<para>

This is how you create an non-numbered list.

</para>

<para>This is a list entry</para>

</listitem>

<para>This is another list entry</para>

</listitem>

</itemizedlist>

<para>

This is how you create a numbered list.

</para>

<para>This is a list entry</para>

</listitem>

<para>This is another list entry</para>

</listitem>

</orderedlist>

The <listitem> can be used with either the <orderedlist> or the <itemizedlist> elements. It cannot be used by itself, however.

<listitem> 能够使用在 <orderedlist> 或者 <itemizedlist> 元素中。然而它不能单独使用。

A basic template

一个简单的模板

When I started learning DocBook I found it was easier to create a basic template rather than trying to remember all of the necessary elements off the top of my head. This is a basic article template, which may help you get started on your first DocBook documents. You should be able to simply cut and paste this from your browser into your favorite text editor and get started. You should check to be sure that the version of DocBook you are using is the same as the version in the declaration in the template. If not, be sure to change it to the proper version.

在我开始学习 DocBook 时我发现创建一个简单的模板是相当容易而尝试在我脑子中记住所有必要的元素则不是那么容易。这是一个基本的文章模板，它将帮助你开始写你的第一个 DocBook 文档。你应当能够简单地从你地浏览器剪切和粘贴到你最常用的文本编辑器中并且开工。你应当检查你要用 DocBook 的版本号是不是和在模板中声明的版本一样。如果不是，确保把它改变为合适的版本。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<title>Sample DocBook Template</title>

<firstname>firstname here</firstname>

<surname>lastname here</surname>

</author>

</articleinfo>

<sect1>

<title>Section 1 Title</title>

<para>

This is a paragraph.

</para>

<sect2>

<title>Section 2 Title</title>

<para>

This is another paragraph...

</para>

</sect2>

<sect2>

<title>Section 2 pt. 2</title>

<para>

Yet another paragraph...

</para>

</sect2>

</sect1>

</article>

Converting to other file formats

转换为其他文件格式

Often authors will use DocBook and never actually need to render the documents into other formats themselves. However, if you need to once you have a finished DocBook file, you can then convert that file into several other types of files using SGML-tools Lite. If you're using a Linux distribution, you may already have SGML-tools Lite or SGML-tools already installed. You may want to check and see if they're already installed and working, or if they are on your installation CDs.

写作的人经常使用 DocBook 但是从不用自己把文档渲染为其他格式。然而，如果你需要，只要你有了一个完成的 DocBook 文件，你就能用 SGML-tools Lite 把那个文件转换为好几种文件格式。如果你正在使用 Linux，你可能已经安装了 SGML-tools Lite 或者 SGML-tools。你可能想要检查看你是否它们是否已经安装了能用，或者它们在你的安装 CD 上。

If you get errors when trying to parse your DocBook files, check the syntax of your document. Often something as simple as a forgotten "/" or misplaced element is the only problem.

如果你在尝试着解析你的 DocBoo 文件时得到错误，检查你文档的语法。经常问题仅仅是简单如像忘记 "/" 的错误或者误拼写的元素。

If you don't have them already installed, and you want to be able to render documents yourself, you can download them from the SGML-tools Lite home page. To get the latest version, go to the SGML-tools Lite home page hosted on SourceForge (see Resources) and download either the source or RPMs and follow the instructions on the SGML-tools Lite home page to install them.

如果你还没有安装它们，而你想要你自己能渲染文档，你能从 SGML-tools Lite 的主页上下载它们。要获得最新的版本，前往位于 SourceForge 的 SGML-tools Lite 的主页（参见资源）并且下载要么源代码要么 RPM，跟着 SGML-tools Lite 主页上的指令来安装它们。

Exporting to HTML

导出到 HTML

To export a DocBook document named filename.sgml to HTML, simply type the following:

要把名字为 filename.sgml 的 DocBook 文档导出到 HTML，简单地这么输入：

sgmltools -b html filename.sgml

If the document has no major errors, SGML-tools Lite will produce a "filename" directory with the resulting HTML files inside.

如果文档没有什么重大错误，SGML-tools Lite 将产生一个内有结果 HTML 文件的 "filename" 目录。

Exporting to plain text

导出到纯文本

DocBook also supports plain-text documents. To render a plain ASCII-text document, use the following command:

DocBook 还支持纯文本文档。要渲染一个纯 ASCII 文本文档，使用一下命令：

sgmltools -b txt filename.sgml

This is the same as the command used to convert to HTML, except we've replaced "html" with "txt". The -b argument tells SGML-tools to use "txt" as the "backend". Currently there are several backends that are available: html, txt, rtf, ps, and dvi.

这和用来转换为 HTML 的命令是一样的，除了我们把 "html" 替换为 "txt"。-b 参数告诉 SGML-tools 使用 "txt" 作为 "backend"。当前有好几个 backend 可用：html，txt，rtf，ps，和 dvi。

Exporting to PostScript

导出到 PostScript

DocBook is capable of producing output suitable for commercial printing through PostScript. When converting to PostScript the command syntax is the same as for text or HTML:

DocBook 能够通过 PostScript 适合商业打印。转换为 PostScript 的命令的语法和对文本和 HTML 的一样：

sgmltools -b ps filename.sgml

However, it is worth noting that if you are including images in the document, you will need to have them saved in EPS format to have them included in the PostScript document. SGML-tools Lite will not covert GIF or JPEG to PostScript for inclusion in the final document.

然而，如果你在文档中包含了图像中这不值什么，你将需要把它们存为 EPS 格式以使它们包含在 PostScript 文档中。SGML-tools Lite 不会把 GIF 或者 JPEG 转换为 PostScript 用于包含在最终的文档中。

Where to go next

下一步干什么

This has just been a brief overview of using DocBook. It is by no means an exhaustive look at all of the elements or potential that DocBook has. Hopefully, however, this article will suffice to get you started learning more about DocBook. After following along with this article you should be able to create basic DocBook documents and use SGML-tools Lite to produce usable output from DocBook files. For more information on DocBook, you can consult the online documentation at DocBook.org (see Resources).

这就是对使用 DocBook 的简短的概览。它没有对元素和 DocBook 的潜力进行铺开的观察。然而希望这篇文章足够你开始对 DocBook 进行更多的学习。在看了这篇文章之后，你应当能够创建基本的 DocBook 文档并且使用 SGML-tools Lite 来从 DocBook 文件创建有用的输出。要获得关于 DocBook 的更多信息，你能够查询位于 DocBook.org 的在线文档。（参见资源）

If you would like to tinker a bit more with DocBook, a good place to start might be the Linux Documentation Project. Most of the documents in the LDP have a DocBook version available online that you could examine for more detailed usage of DocBook.

如果你想要对 DocBook 有更多的观察，一个好地方是 Linux 文档项目。LDP 中的大部分文档都有 DocBook 版本，你可以了解 DocBook 的更详细的用法。

Resources

资源

Visit DocBook.org, the main DocBook site.

访问 DocBook.org，DocBook 的主站点。

The Linux Documentation Project contains many documents written in DocBook. The LDP Author Guide has some tips on getting started with DocBook.

Linux 文档项目包含许多用 DocBook 编写的文档。LDP 作者指导有一些关于如何如 DocBook 门的提示。

Download either the source or RPMs at SGML-tools Lite and follow the instructions to install them. This site has the tools you need to convert DocBook documents to HTML, PDF, PostScript, RTF, or plain text.

下载 SGML-tools Lite 的源代码或者 RPM。这个站点有你需要的工具来把 DocBook 文档转换为 HTML，PDF，PostScript，RTF，或者纯文本。

At the OASIS DocBook Pages, you'll find the DocBook Technical Committee home page.

在 OASIS DocBook 也，你将找到 DocBook 技术委员会的主页。

For help getting started with any SGML DTD, see the W3C Overview of SGML Resources.

要帮助 SGML DTD 入门，参见 W3C 对 SGML 资源的概览

For more details, see the General SGML/XML Applications, OASIS' guide to SGML/XML apps.

要获得更多细节，参见 General SGML/XML Applications，OASIS 的 SGML/XML 程序指导。

About the author

关于作者

Joe "Zonker" Brockmeier is a contributing editor for Linux Magazine and has written Install, Configure and Customize Slackware Linux for Prima Publishing. Joe welcomes your questions, comments, or ideas for future articles on DocBook and can be reached at jbrockmeier@earthlink.net.