簡單介紹 DocBook

A gentle guide to DocBook 

簡單介紹 DocBook

How to use the portable document creator

如何使用這個可移植的文檔建立程式

作者：Joe "Zonker" Brockmeier ([email protected]) 自由作家

釋出日期：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">

<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（段落）。你可能發現 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 檔案于網絡釋出。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 時我發現建立一個簡單的模闆是相當容易而嘗試在我腦子中記住所有必要的元素則不是那麼容易。這是一個基本的文章模闆，它将幫助你開始寫你的第一個 DocBook 文檔。你應當能夠簡單地從你地浏覽器剪切和粘貼到你最常用的文本編輯器中并且開工。你應當檢查你要用 DocBook 的版本号是不是和在模闆中聲明的版本一樣。如果不是，確定把它改變為合适的版本。

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

寫作的人經常使用 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 [email protected]. 

其它連結

DocBook

http://www.oasis-open.org/docbook/

DocBook XSLT stylesheets and DSSSL stylesheets

http://sourceforge.net/projects/docbook/

Saxon XSLT and XQuery processor

http://sourceforge.net/projects/saxon/

DocBook學習:

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