查看“DocBookGuide”的源代码

----
请大家一起来完善此文档。你可以直接修改，或添加评论。

维护者：MillenniumDark

作者：Weakish Jiang

主要贡献者: 

贡献者：


----
== DocBook指南 ==

version Alpha-20060810-0012


Copyright (c)  2006 Ubuntu中文
Copyright (c) 2006 Weakish Jiang
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".


=== 前言 ===
DocBook提供了一个写作结构化文档的很好的系统，特别适合计算机技术方面的文档，当然，也可应用于其他方面。DocBook已被众多组织应用。特别的，大量开源项目将其作为文档的标准格式，包括Linux 内核, GNOME, KDE, Samba, 以及 Linux Documentation Project。比如，你可以在[http://www.gnupress.org/potentialauthors.html gnupress.org]上找到这样一段话：“我们选定的文档格式的标准是简单而强大的语言，TeXinfo；也可以使用DocBook。“ 你可以在[http://wiki.docbook.org/topic/WhoUsesDocBook DocBookwiki]上找到更多使用Docbook的组织、公司和个人。

这是我自己做的Docbook的笔记，更精确的说是，Docbook XML的笔记。本笔记只是介绍性的。要使用DocBook，还需参考其他资料。对DocBook或HTML/XHTML有一些初步的了解将帮助你更好的理解本文，但不是必需的。

访问以下网址来获得本文档的最新版本：
http://wiki.ubuntu.org.cn/DocBookGuide

本文的资料来源主要是DocBook: The Definitive Guide和DocBook 5.0: The Definitive Guide，by Norman Walsh and Leonard Muellner， with contributions from Bob Stayton。



=== 目录 ===

=== 导论 ===
==== XML介绍 ====
本章简要介绍XML。

一些需要了解的基本概念：

*结构化的、语义的标记（structured, semantic markup）
*元素（elements）
*属性（attributes）
*项（entities）

===== 结构化的、语义的标记 =====
这种标记最基本的特征就是它标记的是文档的结构和语义内容，而不是描述文档的样式。

XML使用一对< >来标记元素。这种标记的优点是:

清晰:: 比如，标题以<title>开始， 以</title>结束。
层次性:: 元素可组成丰富、分明的层次。
纯文本:: XML 使用Unicode编码，这使得它具有很好的可移植性和通用性。


结构化、语义化的标记可以使你的文档更容易被程序－－尤其是发布程序－－解释。从宽泛的意义上说，使用这种标记，你的文档就成为了信息数据库。程序可以以多种多样的方式来编译、提取以及生成文档。

===== 元素和属性 =====
XML标记主要包括元素、属性和项。元素是我们用来描述文档的结构和语义的主要的术语。大多数元素由一组标签（tag）组成。比如，DocBook用一组<para></para>标示段落。还有少数标签是空标签,比如<code><nowiki><xref/></nowiki></code>。

元素可以带有一个或多个属性，也可以不带属性。属性用来提供进一步的信息。比如，上面提到的para元素就可以带一个id属性，以实现参见（cross-reference）的功能：
<pre><nowiki>
<para id="idvalue">
</nowiki></pre>

===== 项 =====
项是XML中的一个基础性的概念。它们可以实现一些相联系而有所不同的功能，这使得它们看起来有点复杂。

笼统的说，项使你可以指派一个名字给一些数据，然后用这个名字引用这些数据。

具体的说，项分为两大类，普通项（general entity）和参数项（parameter entity）。

普通项以&开头，以;结尾。普通项又可以分为两种，曰内部（internal）普通项，曰外部（external）普通项。

内部普通项，就是用代号代替一串文本。通过插入这些代号可以引用相应的文本。比如，如果你的文档里经常提到“全家福寿衣花圈专门店”，那你就可以把它设为项。首先，你需要这样来声明，“qjf”是一个项，它代表“全家福寿衣花圈专门店”：
<pre><nowiki>
<!ENTITY qjf "全家福寿衣花圈专门店">
</nowiki></pre>
以后，如果你需要输入“全家福寿衣花圈专门店”，那你只要输入<code><nowiki>&qjf;</nowiki></code>就行了。可以省掉不少打字。

所谓外部普通项，是用来引用外部文档的。这个可以用来将逻辑上单一的文档分成物理上的若干份文档分别储存。比如，你的文档有四章。你可以分别创建四个文件来放四章的内容。然后，在你的DocBook文档里作如下声明：
<pre><nowiki>
<!ENTITY ch1 SYSTEM "第一章.sgm">
<!ENTITY ch2 SYSTEM "第二章.sgm">
<!ENTITY ch3 SYSTEM "第三章.sgm">
<!ENTITY ch4 SYSTEM "第四章.sgm">
</nowiki></pre>
接着，这样来引用它们：
<pre><nowiki>
<book>
&ch1;
&ch2;
&ch3;
&ch4;
</book>
</nowiki></pre>

分析器（parser）将直接插入四个文件的内容到主文档。

外部普通项还可以用于其他类型的文件，比如图片。它们的用法有所不同。这里就不细讲了。

有一些特殊的字符也需要借助项（内部普通项）来表示。比如<和>在XML文档里用于将标签括起来，那如何去除它们的特殊含义呢？不像在UNIX的大多数shell里一样，可以通过<code><nowiki>\ "" ''</nowiki></code>之类的符号来去除特殊含义，在XML里，你必须用另外的符号来表示它们。比如，使用<code><nowiki>&lt;</nowiki></code>和<code><nowiki>&gt;</nowiki></code>来表示<和>。还有一种情况，有些字符并无特殊含义，但是输入起来可能比较困难，所以也为它们提供了相应的项。比如，用<code><nowiki>&Uuml</nowiki></code>表示Ü。这两种项都不需要声明，因为它们已经写进DTD里了。

注意，在XML里，字符可以通过<code><nowiki>&#999;</nowiki></code>这样的方式表达，999是这个字符的Unicode编码，这和项很像，但是从技术角度而言，不是一回事。

至于参数项，只出现在DTD等标记声明中。以%，而非&开始。主要用于定制DTD。

==== 创建DocBook文档 ====
这一章具体介绍如何创建DocBook文档。

由于我们的焦点在DocBook XML文档上，就先来讨论一下XML特定的引入（prologue）部分吧。

===== XML文档 =====
下面的章节将介绍XML文档引入部分的特色。

====== XML声明（XML Declaration） ======
通常，XML的开头 有一个XML声明。
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
</nowiki></pre>
version="1.0"表示XML的版本是1.0，而encoding="utf-8"则表示文档的编码是utf-8。

如果你的文档采用XML 1.0，编码使用utf-8或者utf-16, 那么XML声明可以省略，当然，不省略也没错。

====== 文档类型声明（Document Type Declaration） ======
DTD对XML而言，不是必需的。事实上，如果你使用RELAX NG，那你的文档一般就不包含DTD了。

我们来看一个例子：
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
</nowiki></pre>
这个例子声明文档的根元素是book，<code><nowiki>PUBLIC "-//OASIS//DTD DocBook V5.0//EN"  "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd"</nowiki></code>则是说明使用什么样的DTD的。

====== 内部子集（Internal Subset） ======
我们把上面的例子变一下，再加点声明：
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
<!ENTITY nwalsh "Norman Walsh">
<!ENTITY chap1 SYSTEM "chap1.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>
</nowiki></pre>
这些新增的声明被成为内部子集，相应的，<code><nowiki>PUBLIC "-//OASIS//DTD DocBook V5.0//EN"  "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd"</nowiki></code>则被称为外部子集（external subset）。

内部子集在分析XML的时候是优先的，而如果同一个项有两个或两个以上的声明，以首先分析的为准。也就是说，内部子集将覆盖外部子集的设定。

====== 根元素 ======
所有的XML文档有且仅有一个根元素。虽然文档类型声明和根元素之间可能有注释和处理指令（processing instruction），但一般文档类型声明之后就是根元素。
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
<book>...</book>
</nowiki></pre>
重要的是，根元素必须实际地（physically）紧跟在文档类型声明之后，不能放在外部项里。

====== XML文档的注意事项 ======
*XML的标记是大小写敏感的。在DocBook XML里，所有元素、属性、项都必须小写。
*所有的属性都必须加引号，可以用双引号（"），也可用单引号（'），但不可以用前后引号（“ 和 ”）。
*像这样标记空标签<code><nowiki> <xref/></nowiki></code>
*处理指令用<code><nowiki><? ?></nowiki></code>括起来。

===== 公共标识（Public Identifier），系统标识（System Identifier）和目录文件（Catalog File） =====
当需要引用DTD或外部项的时候，可以使用公共标识或系统标识。因此，它们统称为外部标示（external identifier）。在XML中，系统标识是必需的，而公共标识是可选的。

公共标识是一个全球唯一、摘要性的名字，在上文的例子中，<code><nowiki>-//OASIS//DTD DocBook V5.0//EN</nowiki></code>就是一个公共标识，而<code><nowiki>http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd</nowiki></code>则是一个系统标识。

历史上，使用公共标识的好处是，它可以使你的文档更容易移植（portable)。因为在任何安装了DocBook的系统上，公共标识都可以被解析为适当的本地版本（如果公共标识可以被解析的话）。现在，系统标识也可以以一种类似的方法被解析了。

====== 公共标识 ======
公共标识的重要特性是它是独一无二的。也就是说，在任何系统上，它都将被解析为同一份文档，尽管存储的路径不同。因此，你不应重复使用公共标识，任何发布的修改版本应该使用新的公共标识。

公共标识可以包含大写字母、小写字母、数字，以及下面的符号：“'”, “(“, “)”, “+”, “,”, “-”, “.”, “/”, “:”, “=”, “?”, 空格，回行。

大多数公共标识都符合ISO 8879标准（虽然，ISO/IEC 9070:1991是比较新的标准）。该标准定义了形式化公共标识（formal public identifier，简称FPI）。FPI有严格的形式，以保证它的全球唯一性。
<pre><nowiki>
prefix（前缀）//owner-identifier（使用者标识）//text-class（文本类） text-description（文本描述）//language（语言）//display-version（显示版本）
</nowiki></pre>



前缀

前缀为“+”（注册公共标识）或“-”（未注册公共标识）。ISO有时使用ISO及标准号作为前缀，但这只适用于ISO。

注册可以保证使用者标识的唯一性。但由于有权分配注册公共标识的机构很少，所以未注册公共标识更常见。

使用者标识

标识拥有这个公共标识的个人或组织。注册可以确保使用者标识的唯一性。如果未注册，就要选用适当的名称来保证使用者标识的唯一性。比如，使用公司的名称，使用域名，都是一个好主意。使用个人的姓名也很常见，当然，很显然，这有可能引起冲突。

文本类

文本类标明和公共标识相联系的文档的类型。常见的有：

DOCUMENT:: SGML或XML文档。
DTD:: DTD或者DTD的部分。
ELEMENTS:: 元素声明的集合。
ENTITIES:: 项声明的集合。
NONSGML:: 非SGML或XML的数据。

文本描述

有关文档的描述。不可以包含//字符串。

语言

文档使用的语言，尽可能使用ISO标准的双字母语言代码。

显示版本

用于区分内容相同，仅仅是显示设备或适用系统不同的文档。

比如，ISO Latin 1 character set（拉丁字符集一）的FPI是
<pre><nowiki>
-//ISO 8879-1986//ENTITIES Added Latin 1//EN
</nowiki></pre>
那么，该字符集的XML版就应该适用这样的FPI：
<pre><nowiki>
-//ISO 8879-1986//ENTITIES Added Latin 1//EN//XML
</nowiki></pre>

====== 系统标识 ======

系统标识通常是本地系统上的文件。系统标识必须以URI的形式给出。简单的文件名将被解析为相对URI（relative URI），包含系统标识的文档所在目录将被作为解析时的工作目录。

====== 目录文件 ======

为了最大限度地使用外部XML资源的信息，我们使用目录文件将XML外部标识映射为URI，当然，也可以将系统标识映射为不同的URI。

请看[http://www.oasis-open.org/committees/entity/spec.html XML Catalogs]（英文）获取更多信息。

===== 物理分割：将文档分为几份文件 =====

在上文讲外部普通项的时候已经讲了分割的方法，我把上文举的例子再拿出来，希望能唤起你的回忆：
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
<!ENTITY ch1 SYSTEM "第一章.sgm">
<!ENTITY ch2 SYSTEM "第二章.sgm">
<!ENTITY ch3 SYSTEM "第三章.sgm">
<!ENTITY ch4 SYSTEM "第四章.sgm">
]>
<book>
&ch1;
&ch2;
&ch3;
&ch4;
</book>
</nowiki></pre>
要注意，用外部普通项引用的文档是不允许含有文档类型声明的。比如，“第一章.sgm”的开头可以是这样：
<pre><nowiki>
<chapter id="ch1"><title>第一章</title>
<para>第一段</para>
…
</nowiki></pre>
但不可以这样
<pre><nowiki>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
<chapter id="ch1"><title>第一章</title>
<para>第一段</para>
…
</nowiki></pre>

还有另外一种方法，使用XInclude。上面的例子如果使用XInclude会如何呢？
<pre><nowiki>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>我的第一本书</title>
<xi:include href="ch1.xml"/>
<xi:include href="ch2.xml"/>
<xi:include href="ch3.xml"/>
<xi:include href="ch4.xml"/>
</book>
</nowiki></pre>

注意，这里完全省略了文档类型声明，但必须标明XInclude的名域（namespace）。

注意两种方法的区别，使用XInclude，引用的是独立、完整的XML文档。这就意味着，这些“子”文档，可以有自己独立的文档类型声明，id等的使用也是完全独立、互不相关的。所以，如果你打算将几篇独立的文章合成一本书，使用XInclude就比较好了（避免id的冲突）。反之，不建议使用XInclude，因为全局性(global)的id和idref将不可用。此外，XInclude可以用于无文档类型声明的文档，对于一些禁止文档类型声明的web应用程序（比如基于SOAP的）来说，这是一大优点。


===== 元素概览 =====
只是概览而已，来看看DocBook提供了哪些元素。

元素可以被分为以下几个层次：

*Set
*Book
*Division
*Component
*Section
*Meta-information element
*Block element
*Inline element

Sets是最高层，Books其次，一直到Inline elements。

下面我们来具体看一下这些类各包含哪些元素。

====== Set ======
set（集）是DocBook最顶层，它包含两个或更多的book。它用来将同一主题的book组织为一体。

====== Book ======
book(书）通常作为DocBook的最顶层，因为set不常用。

====== Division和Component ======
division是book的下一层。包含part和reference（参考）。而part则包含component（component和part,division都有部分的意思。）
book下面也可以直接component，跳过division。

====== Sections ======
section（章节）元素有好几种
sect1, sect2, sect3, sect4, sect5:: 总共五层，可以一层层嵌套，但是必须由高到低。
section:: 可以无限地嵌套。
simplesect:: 不能嵌套。
bridgehead:: 只有标题而无内容的section。
refsect1…refsect3:: 和sect1, sect2, sect3, sect4, sect5类似，用于refentry（参考条目）中。
glossdiv, bibliodiv 和 indexdiv，分别用于词汇定义、参考书目和索引，不可嵌套。

====== Meta-Information ======
所有位于section层及以上的元素，以及另外一些元素，可以包含Meta-Information（元信息）。在DocBook5.0中，位于Meta-Information层的只有info（信息）元素。

info标识元信息区域，具体标识元信息内容的元素有title（标题），titleabbrev（标题缩略），subtitle（副标题），abstract（摘要）address（地址），annotation（注），artpagenums（出版时使用的页码），author（作者），authorgroup（作者群），authorinitials（作者姓名缩写或其他较短的标识），bibliocoverage（涉及的时空范畴），biblioid（文档标识），bibliomisc（其他信息），bibliomset（组织好了的相关书目信息），bibliorelation（与其他文档的关系），biblioset（原始形态的的相关书目信息），bibliosource（文档来源），collab（协作者），confgroup（关于会议的元信息），contractnum（文档的条款数），contractsponsor（条款的发起人），copyright（版权信息），date（日期），edition（版本），editor（编辑），extendedlink（XLink extended link），issuenum（期数，用于杂志），itermset（术语索引），keywordset（关键词），legalnotice（法律声明），mediaobject（媒体对象，例如录象、音频、图像），orgname（组织名称），othercredit（贡献者），pagenums（页码，用于参考条目），printhistory（印刷纪录），productname（产品名），productnumber（产品号），pubdate（出版日期），publisher（出版者），publishername（出版者名称），releaseinfo（发布信息），revhistory（修订纪录），seriesvolnums（卷数，用于丛书），subjectset（描述文档主题的术语），volumenum（卷数，用于文集）。

====== Block Element ======
看看有哪些元素属于block element（块元素）。

列表:: 包括calloutlist（callout列表），bibliolist（书目列表），glosslist（词汇列表），itemizedlist（无序列表），orderedlist（有序列表），segmentedlist（成分列表），simplelist（简单列表），variablelist（定义列表）。
告示:: 包括caution（注意）, important（重要提示）, note（注释）, tip（窍门）, 和 warning（警告）。
文本:: 包括address（地址），literallayout（纯文本），programlisting（代码），screen（文本抓屏），synopsis（命令、函数纲要）
注意screen用于屏幕上输出的文本，而screenshot才用于抓屏图片。
例子，图片和表格:: 包括example, informalexample, figure, informalfigure, table, 和 informaltable。
formal和informal的差别在于是否包含标题。
DocBook支持CALS表格和HTML表格。
段落:: 包括para（段落）, simpara（简单段落，不可包含其他块元素）和formalpara（带标题的段落）。
等式:: 包括equation（等式，可带标题） 和informalequation（无标题等式）。
媒体文件:: audioobject(音频对象），imageobject（图片对象），imageobjectco（带callout的图片对象），videoobject（视频对象），textobject（文本对象）。
问题和答案:: 用于FAQ（常见问题解答）的元素是qandaset，它由qandaentry（包含一个问题及其解答）组成。问题和解答的集合可用qandadiv来分成章节。
任务和过程:: task（任务）用于描述 procedure（过程）。每个task包含asksummary（任务总结）, taskprerequisites（需求条件）, examples（例子，可选）, 以及一个描述任务相关信息的section。而procedure则由step（步骤）组成。step可能包含substep（子步骤）或 stepalternative（该步骤的替代步骤）。
synopsis:: 包括cmdsynopsis（用于命令），funcsynopsis（用于函数），classsynopsis（用于类）。
HTML 表单:: 包括以下HTML 4.01表单元素（请参看HTML资料了解它们的含义）：html:button，html:fieldset，html:form，html:input，html:label，html:legend，html:option，html:select，html:textarea。
其他:: blockquote(引用），epigraph（题记），msgset（有关的错误信息），sidebar（侧边栏）。

====== Inline元素 ======
DocBook提供了数量庞大的Inline元素，请根据你的需要（文档的主题，可用的时间）选用它们。你不需要在可以标记的地方都加上标记，只需在有必要加标记的地方加标记（也就是说，不是为标记而标记，标记是为了方便利用文档中的信息。）

大部分Inline元素都和技术相关。

以下分类只是方便参考，有些元素同时出现在多个分类中。

一般使用:: abbrev（缩略语），acronym（缩写），emphasis（强调），footnote（脚注），phrase（词组），quote（引用），trademark（商标）
参见:: anchor（锚，书签），citation（引用文章），citerefentry（引用参考），citetitle（引用标题），firstterm（术语，第一次出现），glossterm（列入词汇表的术语），link（超文本链接），olink（间接链接），xref（参见）。
标记:: foreignphrase（外语词），wordasword（字面意），computeroutput（计算机输出），literal（逐字复制自计算机系统的内容），markup（标记），prompt（提示符），replaceable（由读者替换的内容），optional（可选），tag（XML或SGML标签），userinput（用户输入）。
数学:: 支持MathML是DocBook的远期规划，目前只提供一些简单的支持:inlineequation（等式），mathphrase（数学语句），subscript（下标），superscript（上标）。
用户界面:: （请参阅相关资料了解元素含义）accel，guibutton，guiicon，guilabel，guimenu，guimenuitem，guisubmenu，keycap，keycode，keycombo，keysym，menuchoice，mousebutton，shortcut。
编程:: classname（类名），constant（常量），errorcode（出错码），errorname（错误名），errortype（错误信息类别），function（函数），msgtext（信息），parameter（参量），property（属性），replaceable（由读者替换的内容），returnvalue（函数返回的值），symbol（符号），token（代符），type（类型），varname（变量名）。
操作系统:: application（应用程序），command（命令），envar（环境变量），filename（文件名），option（参数），prompt（提示符），systemitem（系统项）。
其他（计算机相关）:: database（数据库），email，hardware（硬件）。


===== 创建book =====
看一个例子就够了。
<pre><nowiki>
<book>
<info>
<title>我的第一本书</title>
<author><firstname>Jane</firstname><surname>Doe</surname></author>
<copyright><year>1998</year><holder>Jane Doe</holder></copyright>
</info>
<preface><title>Foreword</title> ... </preface>
<chapter> ... </chapter>
<chapter> ... </chapter>
<chapter> ... </chapter>
<appendix> ... </appendix>
<appendix> ... </appendix>
<index> ... </index>
</book>
</nowiki></pre>

===== 创建Chapter =====
同样，用例子说话：
<pre><nowiki>
<chapter><title>我的第一章</title>
<para> ... </para>
<sect1><title>第一部分</title>
<para> ... </para>
<example> ... </example>
</sect1>
</chapter>
</nowiki></pre>

===== 创建Article =====
Article（文章）的结构和chapter比较类似：
<pre><nowiki>
<article>
<artheader>
<title>我的文章</title>
<author><honorific>Dr</honorific><firstname>Emilio</firstname>
<surname>Lizardo</surname></author>
</artheader>
<para> ... </para>
<sect1><title>iPod shuffle维修经过</title>
<para> ... </para>
</sect1>
<bibliography> ... </bibliography>
</article>
</nowiki></pre>

===== 创建Reference Page =====
DocBook中的Reference Page（参考页面），是要重现或再造UNIX里的“manpage”（man页面）。

看一个例子吧：
<pre><nowiki>
<refentry id="printf">

<refmeta>
<refentrytitle>printf</refentrytitle>
<manvolnum>3S</manvolnum>
</refmeta>

<refnamediv>
<refname>printf</refname>
<refname>fprintf</refname>
<refname>sprintf</refname>
<refpurpose>print formatted output</refpurpose>
</refnamediv>

<refsynopsisdiv>

<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdio.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>printf</function></funcdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>

<funcprototype>
<funcdef>int <function>fprintf</function></funcdef>
<paramdef>FILE *<parameter>strm</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>

<funcprototype>
<funcdef>int <function>sprintf</function></funcdef>
<paramdef>char *<parameter>s</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
<indexterm><primary>functions</primary>
<secondary>printf</secondary></indexterm>
<indexterm><primary>printing function</primary></indexterm>

<function>printf</function> places output on the standard
output stream stdout.
&hellip;
</para>
</refsect1>
</refentry>
</nowiki></pre>

===== 创建附文 =====

主要包括索引、词汇表、参考书目（引用书目）和目录。大部分都是由程序自动生成的。像目录，几乎总是由程序生成的，而参考书目则一般需要手工来写（除非你从数据库中提取信息）。至于索引和词汇表，它们的生成，需要你在文档中添加额外的标记。

====== 创建索引 ======
在一些高度结构化的文档中，比如某些Reference Page，可以实现全自动生成。你也可以编写程序，定义一些规则来自动创建索引。但这样的情况很少见。

大部分情况下，你都需要在文档中标明要收入索引的部分。

先看一个例子：
<pre><nowiki>
<para>
老虎<indexterm>
<primary>大猫</primary>
<secondary>虎</secondary></indexterm>
真的是一只很大的猫。
</para>
</nowiki></pre>

可以看到，我们使用indexterm标签标明索引条目，primary表示主要，secondary的意义较primary为小，还有第三级，是tertiary。

注意这种标记的妙处，索引条目无需在正文中出现。

这样子生成的索引是条目对应着页码，我们把上面的例子改一下，以便指定条目对应的文本范围：
<pre><nowiki>
<para>
老虎<indexterm id="tiger-desc" class="startofrange">
<primary>大猫</primary>
<secondary>虎</secondary></indexterm>
真的是一只很大的猫。…
</para>
⋮
<para>
老虎谈的够多了。<indexterm startref="tiger-desc" class="endofrange"/>. 让我们谈谈美洲豹吧。 
</para>
</nowiki></pre>
我们在indexterm元素上加上属性class="startofrange"，表明此indesterm指明了条目对应文本的开端，再加一个id属性，以便引用。

而条目对应文本的收尾则使用一个带class="endofrange"的元素来表示，这个元素的startref属性引用开端的那个indesterm元素的id。注意这个收尾的indexterm元素必须为空。用这样的方法，好处是可以不受其他元素的限制。如果只使用一对indexterm标签，会造成混乱的嵌套。

如果条目对应文本恰好是一个完整的文本对象（比如整个章节），那也可以使用下面的方法：
<pre><nowiki>
<indexterm zone="tiger-desc">
<primary>大猫</primary>
<secondary>虎</secondary></indexterm>
</nowiki></pre>
在这里索引的文本的范围是id为tiger-desc的一整块文本。

最后，DocBook包含了用于带有参见的索引条目的标记，比如“见猫，大”或者“参见狮子”。请参考see和seealso元素的介绍。

====== 创建词汇表 ======
你可以手工写词汇表，经常人们也是这么干的。但是下面我将谈谈自动生成的事情。比如说，你在文档中做如下的标记：
<pre><nowiki>
<glossterm linkend="xml">Extensible Markup Language</glossterm> is a new standard…
</nowiki></pre>
那么生成的词汇表应该是这个样子：
<pre><nowiki>
<glossary><title>词汇表的例子</title>
⋮
<glossdiv><title>E</title>

<glossentry id="xml"><glossterm>Extensible Markup Language</glossterm>
<acronym>XML</acronym>
<glossdef>
<para>关于XML的定义...</para>
<glossseealso otherterm="sgml">
</glossdef>
</glossentry>

</glossdiv>
</nowiki></pre>
当然，像缩略语为XML,XML的定义，参见sgml等信息，需要数据库提供了。

===== 创建参考书目 =====
你可以使用biblioentry元素，也可以使用bibliomixed元素。先看一个使用biblioentry的例子：
<pre><nowiki>
<biblioentry xreflabel="Kites75">
<authorgroup>
<author><firstname>Andrea</firstname><surname>Bahadur</surname></author>
<author><firstname>Mark</firstname><surname>Shwarek</surname></author>
</authorgroup>
<copyright><year>1974</year><year>1975</year>
<holder>Product Development International Holding N. V.</holder>
</copyright>
<isbn>0-88459-021-6</isbn>    
<publisher>
<publishername>Plenary Publications International, Inc.</publishername>
</publisher>
<title>Kites</title>
<subtitle>Ancient Craft to Modern Sport</subtitle>
<pagenums>988-999</pagenums>
<seriesinfo>
<title>The Family Creative Workshop</title>
<seriesvolnums>1-22</seriesvolnums>
<editor>
<firstname>Allen</firstname>
<othername role=middle>Davenport</othername>
<surname>Bragdon</surname>
<contrib>Editor in Chief</contrib>
</editor>
</seriesinfo>
</biblioentry>
</nowiki></pre>
可以看到，使用biblioentry元素，就像在写一个数据库的项一样。这些原始的信息以什么顺序显示，全部显示或部分显示，都要交给程序来处理。

而bibliomixed则提供了加工过的信息，作者在更大程度上控制这些信息如何展示，至少控制了展示的顺序。
<pre><nowiki>
<bibliomixed>
<bibliomset relation=article>
<surname>Walsh</surname>, <firstname>Norman</firstname>.
<title role=article>Introduction to Cascading Style Sheets</title>.
</bibliomset>
<bibliomset relation=journal>
<title>The World Wide Web Journal</title> 
<volumenum>2</volumenum><issuenum>1</issuenum>.
<publishername>O'Reilly & Associates, Inc.</publishername> and
<corpname>The World Wide Web Consortium</corpname>.
<pubdate>Winter, 1996</pubdate></bibliomset>.
</bibliomixed>
</nowiki></pre>

两者各有不同的用处。bibliomixed给作者更多对书目显示方式的掌控，而biblioentry则提供了输出格式的灵活性。比如，不同的组织对参考书目的格式可能有不同的要求（名字先还是标题先，是否显示isbn号，等等）。使用biblioentry，作者就无需改变DocBook源文档，而只需选用特定的程序。

==== DocBook编辑软件 ====
我使用emacs的nxml-mode编辑DocBook文档。

我使用emacs的nxml-mode编辑DocBook文档。

nxml-mode的好处就是自带DocBook的RELAX NG，装上了以后,可以实现边输入边检查的功能。 
比如，如果你的docbook里有这样一段 
<pre><nowiki>
<releaseinfo> 
<para>修订版本 1.6.7</para> 
</releaseinfo> 
</nowiki></pre>
xml-mode下没有反应，nxml-mode下，para会有一条红色下划线，把鼠标移到上面就会浮现错误提示"elements not allowed in this context" 

如果你使用v5.0,去docbook.sf.net下载最新的DocBook v5.0 的.rnc加入到nxml-mode中。
==== 发布 ====
要发布DocBook XML文档，需要使用Stylesheet语言。

===== Stylesheet简介 =====
我们将通过例子来介绍FOSIs、DSSSL、CSS、XSL四种语言，我们将下面一段作为例子，分别应用这四种语言：
<pre><nowiki>
<para>
这是一个例子。 <emphasis>强调</emphasis>的词语应显示为斜体.单层的 
<emphasis>嵌套<emphasis>强调</emphasis>应该可以工作。</emphasis>
</para>
</nowiki></pre>
====== FOSI stylesheet ======
<pre><nowiki>
<e-i-c gi="para">
<charlist>
<textbrk startln="1" endln="1">
</charlist>
</e-i-c>

<e-i-c gi="emphasis">
<charlist inherit="1">
<font posture="italic">
</charlist>
</e-i-c>

<e-i-c gi="emphasis" context="emphasis">
<charlist inherit="1">
<font posture="upright">
</charlist>
</e-i-c>
</nowiki></pre>
FOSIs是SGML文档，ADEPT Publisher和DL Composer等一些产品支持这一语言。

======  DSSSL stylesheet ======
<pre><nowiki>
(element para
(make paragraph
(process-children)))

(element emphasis
(make sequence
font-posture: 'italic
(process-children)))

(element (emphasis emphasis)
(make sequence
font-posture: 'upright
(process-children)))
</nowiki></pre>
很像Scheme，被Jade以及其他一些工具支持。

====== CSS ======
<pre><nowiki>
para              { display: block }
emphasis          { display: inline;
font-style: italic; }
emphasis emphasis { display: inline;
font-style: upright; }
</nowiki></pre>
原来用于html, 最近也开始用于xml了。

====== XSL ======
<pre><nowiki>
FIXME: THIS IS WRONG!

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
xmlns:fo="http://www.w3.org/XSL/Format/1.0"
version="1.0">

<xsl:template match="para">   
<fo:block>
<xsl:apply-templates/>  
</fo:block>
</xsl:template>  

<xsl:template match="emphasis">
<fo:sequence font-style="italic">
<xsl:apply-templates/>  
</fo:sequence>
</xsl:template>  

<xsl:template match="emphasis/emphasis">
<fo:sequence font-style="upright">
<xsl:apply-templates/>  
</fo:sequence>
</xsl:template>  

</xsl:stylesheet>
</nowiki></pre>
本身就是XML文档，是最流行的用于XML文档的stylesheet。

===== 使用XSL发布DocBook =====

请看Bob Stayton的DocBook XSL: [http://www.sagehill.net/docbookxsl/ The Complete Guide]一书。

==== 定制 ====
通过定制DocBook，你可以：
*新增元素
*去除元素
*改变元素的结构
*增加属性
*移除属性
*扩大、缩小属性的值的范围

定制，特别是扩展，将对你使用的工具和stylesheet语言产生很大的影响。

DocBook5.0使用独有的名域http://docbook.org/ns/docbook。你可以自由更改DocBook的schema，只是改了以后就不能称其为DocBook了。

通常你可以使用如下的格式来标识你的定制：
<pre><nowiki>
base_version-[subset|extension|variant] (name[-version])+
</nowiki></pre>
当你不想说明是subset还是extension时，留空或使用variant。

=== 参考 ===

FIXME 元素、属性等的详尽介绍。












===  附录 ===

==== GNU Free Documentation License ====

[[Include(fdl)
== xc
== 大标题文字 ==
 ==
]]


----------

== 反馈 ==