## CSDN博客

### 简单介绍 DocBook

A gentle guide to DocBook

How to use the portable document creator

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

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.

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.

What is 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.

Why use 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

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.

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

<!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.

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.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
<title>A gentle guide to DocBook</title>
<author>
<firstname>Joe</firstname>
<surname>Brockmeier</surname>
</author>
</articleinfo>
<sect1 label="1.0">
<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.

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.

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).

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.

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 fileref="images.d/fuzzy.eps" format="eps">
</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.

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.

<para>
<programlisting>
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.

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:

<para>
This is how you create an non-numbered list.
</para>
<itemizedlist>
<listitem>
<para>This is a list entry</para>
</listitem>
<listitem>
<para>This is another list entry</para>
</listitem>
</itemizedlist>
<para>
This is how you create a numbered list.
</para>
<orderedlist>
<listitem>
<para>This is a list entry</para>
</listitem>
<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.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
<title>Sample DocBook Template</title>
<author>
<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.

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.

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.

Exporting to HTML

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

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.

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.

Exporting to 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.

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).

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.

Resources

Visit DocBook.org, the main DocBook site.

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.

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

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

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

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

0 0