第 2 章 制作更完整的DocBook文档

目录

1. 文档声明
2. 将文档物理分割
3. 认识更多的docbook标签
3.1. 关于“文档种类”的标签
3.2. 认识更多的“文档元素”
3.2.1. list
3.2.2. inline
3.2.3. admonitions
3.2.4. Line-specific environments
3.2.5. callout
3.2.6. superscript和subscript

前面通过firstbook.xml的例子展示了一份docbook xml文档基本的样子。并将其转换为了html和pdf文件。接下来需要我们做更多细致的工作,使文档更加完善、完美。

1. 文档声明

一份XML文档的声明部分通常由可选的XML声明、可选的DTD声明(可能还会包括一些内部的实体元素定义)和文档根元素组成。

  1. xml文档声明

    XML文档通常以XML声明开始,通常包含版本、编码格式等,例如:

    <?xml version="1.0" encoding="utf-8"?>

    版本和编码格式会告诉处理程序采用什么的方式来处理我们的xml文本。一般情况下,xml的处理程序默认version是1.0,encoding是uft-8或utf-16,在这种情况下,我们可以不用写xml文档声明。如果使用xml1.1格式或其他的编码格式那就必须声明。

    无论什么版本和编码,建议保留完整的声明。这是一种良好的习惯。

  2. docbook DTD文档声明

    docbook DTD是docbook xml的文档声明,这也不是必须的。但,历史的原因,几乎所有的docbook xml文件都包含了这个部分。docbook DTD部分可以清晰地告诉我们使用了哪个版本的DTD及文档的根元素是什么,这个声明紧随xml声明之后,如下的样子:

    <?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,使用了5.0版本的dtd。在某些程序处理xml文档时,需要验证相关标签是否存在或者是否符合规范,那这个docbook.dtd就会被读取。如果我们已经下载这个docbook.dtd到我们的电脑里,也可以用将它指向本的的文件,如下:

    <?xml version='1.0' encoding="utf-8"?>
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
                       "/usr/local/docware/docbook-5.0/dtd/docbook.dtd">
    [提示]提示
    上面的例子根元素是book,另外常用的两个标签是article和set。article是一篇文章,篇幅上比book要小。set是book的合集,篇幅上更大。
  3. 根元素

    根元素紧跟在文档类型声明之后,和docbook DTD的声明类似,这个部分也是可选的。但有时候很多程序会调用这些信息,而且docbook从版本5以后直接使用了一些xlink里的一些特性,所以建议保留这些内容:

    <?xml version='1.0' encoding="utf-8"?>
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
                       "/usr/local/docware/docbook-5.0/dtd/docbook.dtd">
                       
    <book xmlns:xlink='http://www.w3.org/1999/xlink' 
          xmlns="http://docbook.org/ns/docbook" 
          xml:lang="zh_cn" 
          version="5.0">  

这些看似废话一样的声明其实是大有用处的,主要是一些程序会从这些声明里面读取很多信息,以用于文档的处理。所以,建议将这部分固定为自己的docbook xml文件的“头”部分。那么前面的firstbook.xml就写成如下非常正规的样子:

  1 <?xml version='1.0' encoding="utf-8"?>
  2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
  3       "/usr/local/docware/docbook-5.0/dtd/docbook.dtd">
  4       
  5 <book xmlns:xlink='http://www.w3.org/1999/xlink'
  6       xmlns="http://docbook.org/ns/docbook"
  7       xml:lang="zh_cn"
  8       version="5.0">
  9       
 10   <title>docbook简要参考⼿册</title>
 11   <subtitle>DocBook 5.0 and XSLT 1.0 Stylesheet</subtitle>
 12   
 13   <chapter><title>制作第⼀份docbook⽂档</title>
 14     <para>前面已经提到过,docbook主要分为SGML和XML两个版本,不论哪个版本,都称为DocbookDTD... ...</para>
 15     <para>docbook的入门是有一定门槛的,需要很多方面的配合,才能产出一份不错的文档。... ...</para>
 16     <sect1><title>基础环境搭建</title>
 17       <para>... ...</para>
 18     </sect1>
 19     
 20     <sect1><title>书写DocBook格式的xml⽂件</title>
 21       <para>... ...</para>
 22     </sect1>
 23  
 24     <sect1><title>生成我们需要的文件</title>
 25       <para>... ...</para>
 26     </sect1>
 27 
 28   </chapter>
 29   
 30   <chapter><title>制作更完整的DocBook文档</title>
 31     <para>... ...</para>
 32   </chapter>
 33 
 34 </book>