A gentle guide to DocBook 
簡單介紹 DocBook

How to use the portable document creator
如何使用這個可移植的文檔創(chuàng)建程序

作者：Joe "Zonker" Brockmeier (jbrockmeier@earthlink.net) 自由作家
發(fā)布日期：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 創(chuàng)建文檔
包含圖像
包含代碼
包含列表
一個簡單的模板
轉換為其他的文件格式
導出到 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 創(chuàng)建一個簡單的文檔。Joe Brockmeier 帶你創(chuàng)建一個文檔并且使用 SGML-tools Lite 來解析文檔創(chuàng)建文檔的 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.
如果你曾經(jīng)聽聞如何給開源項目撰寫文檔，或者你已經(jīng)瀏覽了 Linux 文檔項目或者任何服務于 Linux 或者其他開遠項目的文檔的頁面，你可能已經(jīng)聽說了 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 創(chuàng)建一個簡單的文章（文檔）以及如何使用 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 已經(jīng)以種種形式存在很久了，從 1991 年開始。起初 DocBook 被創(chuàng)建來幫助交換 UNIX 文檔。自那以后，DocBook 又經(jīng)歷了四個主要的版本，現(xiàn)在是在格式化信息標準進步組織，更常見的是 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 存為純文本；否則他們不能被正確的解析。如果你不想把你的文檔以多于一種格式來使用，像打印版本和網(wǎng)絡版本，你可能會發(fā)現(xiàn) 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 的另外一個優(yōu)勢是它把作者從對文檔的排版和格式的擔心中解脫出來。DocBook 僅僅關心文檔的結構。例如，一個作者簡單地使用 DocBook 地 <emphasis> 標簽來表明文本需要被強調。根據(jù)需要轉換為什么樣的格式，強調的地方可能會變成斜體，下劃線，或者被設置為粗體。這不再是作者在編寫文檔時擔心的問題。

Creating a document with DocBook
用 DocBook 創(chuàng)建文檔

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 創(chuàng)建文檔不難。我們將集中精力看看如何使用 SGML DTD 創(chuàng)建文檔。除了文檔聲明這一個例外，本文中的所有內容都能同時用于 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.
首先，打開你最喜歡的文本編輯器，創(chuàng)建一個新的文檔。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 的版本以及你創(chuàng)建的文檔的類型。

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.
現(xiàn)在我們開始給文檔添加一些內容。從標題，作者信息以及一個小段落開始。這個簡短的例子展示了一些在用的基本的 DocBook 的標簽，或者元素。DocBook 的元素可能看上去和 HTML 標簽類似，但是記住 DocBook 的解析器比你的 Web 瀏覽器得要求要嚴格得多。你可以不聲明 HTML 文檔，甚至省略一些 "必須" 的標簽，但是 DocBook 不會這么寬大。注意包括所有必須的元素并且用合適的順序使用他們。

<!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.
這兒使用的大部分元素是其意自明的。一些元素，比如 <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（段落）。你可能發(fā)現(xiàn) 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> 元素。

<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.
當你使用 SGML-tools Lite或者其他 DocBook 轉換工具渲染它時，這些代碼在你的文檔中包含了 fuzzy.eps 圖像。注意 eps 時用于但因文檔或者轉換為PDF 的良好格式，但是你可能使用 JPEG，GIF，或者 PNG 文件于網(wǎng)絡發(fā)布。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>       
  <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.
注意上面的代碼使用了 < 和 > 字符，這將在 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>
<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.
在我開始學習 DocBook 時我發(fā)現(xiàn)創(chuàng)建一個簡單的模板是相當容易而嘗試在我腦子中記住所有必要的元素則不是那么容易。這是一個基本的文章模板，它將幫助你開始寫你的第一個 DocBook 文檔。你應當能夠簡單地從你地瀏覽器剪切和粘貼到你最常用的文本編輯器中并且開工。你應當檢查你要用 DocBook 的版本號是不是和在模板中聲明的版本一樣。如果不是，確保把它改變?yōu)楹线m的版本。

<!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.
寫作的人經(jīng)常使用 DocBook 但是從不用自己把文檔渲染為其他格式。然而，如果你需要，只要你有了一個完成的 DocBook 文件，你就能用 SGML-tools Lite 把那個文件轉換為好幾種文件格式。如果你正在使用 Linux，你可能已經(jīng)安裝了 SGML-tools Lite 或者 SGML-tools。你可能想要檢查看你是否它們是否已經(jīng)安裝了能用，或者它們在你的安裝 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 文件時得到錯誤，檢查你文檔的語法。經(jīng)常問題僅僅是簡單如像忘記 "/" 的錯誤或者誤拼寫的元素。

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 將產(chǎn)生一個內有結果 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 參數(shù)告訴 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 適合商業(yè)打印。轉換為 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 進行更多的學習。在看了這篇文章之后，你應當能夠創(chuàng)建基本的 DocBook 文檔并且使用 SGML-tools Lite 來從 DocBook 文件創(chuàng)建有用的輸出。要獲得關于 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.
要獲得更多細節(jié)，參見 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.