3. 认识更多的docbook标签
上一页 第 2 章 制作更完整的DocBook文档 下一页

3. 认识更多的docbook标签

3.1. 关于“文档种类”的标签

从我们平时使用的角度来看，可以把docbook的文档种类分为三个部分，article、book和set。

  1. article

    article从篇幅上来说一般会比book要小，写一篇小的文章，这种类型比较合适。article标签可以说是和chapter标签是平级的。前面描述的xml头文件和物理分割特性同样适用于article。与book不同的是，article由section（sect1）组成。

  2. book

    book就是“书”，前面的firstbook.xml就是典型的book。它是由章节组成。

  3. set

    set是书的合集，可以把多本书放在一起，就像book把多个chapter放在一起一样。

除了set、book、article之外，还有很多这种逻辑上的文档组织类标签，包括：part、appendix、glossary、refentry等。

3.2. 认识更多的“文档元素”

3.2.1. list

list类的文档元素在docbook里一共有8种，这里我们只讲两种，其余的请参考tdg文档。

  1. itemizedlist，没有编号，每个条目用小圆点标注的列表，它的子节点是listitem，比如下面的例子

      1 <itemizedlist>
  2   <listitem>该用什么样的一些样式展示不同的一些文档元素？如一些代码、或者系统命令等。</listitem>
  3   <listitem>如何保证同样的文档元素总是保持一样的显示风格？</listitem>
  4   <listitem>如何进行版式的一些设计？用word来排版对我来说实在太痛苦。</listitem>
  5   <listitem>如何让文档能够同时生成在线阅读的版本和可以打印的版本？</listitem>
  6   <listitem>如何完成多人协作书写，又同时保证样式的完全一致？</listitem>
  7 </itemizedlist>

    上面这个例子就是这份文档序言里的内容。

  2. orderedlist，这是编号的list，它的子节点是listitem，比如下面的例子

      1 <orderedlist>
  2   <listitem>该用什么样的一些样式展示不同的一些文档元素？如一些代码、或者系统命令等。</listitem>
  3   <listitem>如何保证同样的文档元素总是保持一样的显示风格？</listitem>
  4   <listitem>如何进行版式的一些设计？用word来排版对我来说实在太痛苦。</listitem>
  5   <listitem>如何让文档能够同时生成在线阅读的版本和可以打印的版本？</listitem>
  6   <listitem>如何完成多人协作书写，又同时保证样式的完全一致？</listitem>
  7 </orderedlist>

    显示出的效果如下：

    1. 该用什么样的一些样式展示不同的一些文档元素？如一些代码、或者系统命令等。
    2. 如何保证同样的文档元素总是保持一样的显示风格？
    3. 如何进行版式的一些设计？用word来排版对我来说实在太痛苦。
    4. 如何让文档能够同时生成在线阅读的版本和可以打印的版本？
    5. 如何完成多人协作书写，又同时保证样式的完全一致？

  3. simplelist，没有任何“修饰”，它的子节点是member，比如下面的例子

      1 <simplelist type='vert' columns='3'>
  2     <member>bibliolist</member>
  3     <member>calloutlist</member>
  4     <member>glosslist</member>
  5     <member>itemizedlis</member>
  6     <member>orderedlist</member>
  7     <member>segmentedlist</member>
  8     <member>simplelist</member>
  9     <member>variablelist</member>
 10 </simplelist>

    显示样式如下：

    bibliolistitemizedlissimplelist
    calloutlistorderedlistvariablelist
    glosslistsegmentedlist 

  4. variablelist，一个列表，其中每个条目都由一组一个或多个术语和一个相关的描述组成。比如下面的例子

      1 <variablelist><title>Font Filename Extensions</title>
  2       <varlistentry>
  3        <term><filename>TTF</filename></term>
  4         <listitem>
  5          <para>TrueType fonts.</para>
  6         </listitem>
  7     </varlistentry>
  8       <varlistentry>
  9       <term><filename>PFA</filename></term>
 10         <term><filename>PFB</filename></term>
 11       <listitem>
 12           <para>
 13           PostScript fonts. <filename>PFA</filename> files are common
 14             on <acronym>UNIX</acronym> systems, <filename>PFB</filename>
 15           files are more common on Windows systems.
 16           </para>
 17       </listitem>
 18       </varlistentry>
 19    </variablelist>

    显示样式如下：

    Font Filename Extensions

    TTF

    TrueType fonts.

    PFA, PFB

    PostScript fonts. PFA files are common on UNIX systems, PFB files are more common on Windows systems.

3.2.2. inline

可以称之为内联元素。这一类的标签非常多，主要是有一些特殊的技术性内容会出现在正文的内容里，但它的字体可能要发生一些变化，以引起读者的注意。或者通过字体或大小上的一些固定样式，在读者看到时，一下就可以分辨出它是什么类的内容。比如一些系统的命令、文件名、命令选项及参数等。

我们以系统命令iptables-save来举例说明，我们需要用这个命令将地址转换表（nat）保存到一份文件中，在xml文件中输入如下的文字：

<command>iptables-save</command> <option>-t</option> <parameter>nat</parameter> 
                                 <option>-f</option> <filename>nat.rules</filename>

那么就会得到如下的显示样式：

iptables-save -t nat -f nat.rules

通常情况下，像这样的一行命令，我们基本上只用command标签。在这里只是想用一个例子来说明这些inline的元素。类似这样的标签，还有数据库database、函数function、选项option、参数parameter等等。

3.2.3. admonitions

admonitions是一种较为醒目的提醒类信息，一共有5个标签， caution, important, note, tip, 和warning。在前面，已经有过一个tip的例子。下面我再看一个warning的例子，我们如果有如下的一段代码：

<warning>请小心使用iptables-save命令。</warning>

那么就会得到如下的显示样式:

[警告]警告
请小心使用iptables-save命令。

3.2.4. Line-specific environments

这个具体怎么翻译我还真拿不准，就不翻译了。这类标签不算多，大概7到8个的样子。用一个例子来说明吧。比如，我们有一个屏幕上的输出内容，想直接呈现给读者，就像前面的tree fisrtbook输出，我们可以使用screen标签，如下：

  1 <screen>
  2 chunxin@CC$ tree firstbook/
  3 firstbook/
  4 ├── chapters
  5 │   ├── chapter01_beginning.xml
  6 │   ├── chapter02_xml.xml
  7 │   ├── chapter03_xsl.xml
  8 │   └── chapter04_fonts.xml
  9 ├── firstbook.xml
 10 ├── colophon.xml
 11 ├── info.xml
 12 └── preface.xml
 13 </screen>

那么显示出来，就是如下的样子：

chunxin@CC$ tree firstbook/
firstbook/
├── chapters
│   ├── chapter01_beginning.xml
│   ├── chapter02_xml.xml
│   ├── chapter03_xsl.xml
│   └── chapter04_fonts.xml
├── firstbook.xml
├── colophon.xml
├── info.xml
└── preface.xml

显示的结果就感觉像是直接搬用了屏幕上的输出一样，让人一看就能明白。类似的标签还有programlisting, synopsis等。

3.2.5. callout

可以理解为一种标记注释，经常与Line-specific environments类的元素配合使用，例如我们有一段关于rsyslog.conf的配置文件，内容如下：

  1 ...
  2 $WorkDirectory /var/spool/rsyslog
  3 
  4 $IncludeConfig /etc/rsyslog.d/*.conf
  5 
  6 auth,authpriv.*			/var/log/auth.log
  7 ...

为了能够清晰地向读者说明配置文件各行的作用，如果可以在需要解释的位置做一个标记，然后使用标记定位来解释相应的内容，会使读者更一目了然。就像如下的样子：

  1 ...
  2 $WorkDirectory /var/spool/rsyslog 1
  3 
  4 $IncludeConfig /etc/rsyslog.d/*.conf 2
  5 
  6 auth,authpriv.*			/var/log/auth.log 3
  7 ...

1

定义rsyslog的工作目录

2

指定rsyslog在运行时要包含哪些文件

3

认证类的日志存在auth.log中

要实现上面的样式，代码如下：

  1 <programlisting linenumbering="numbered" language="common">...
  2 $WorkDirectory /var/spool/rsyslog <co id="WorkDirectory-co" linkends="WorkDirectory"/>
  3 
  4 $IncludeConfig /etc/rsyslog.d/*.conf <co id="IncludeConfig-co" linkends="IncludeConfig"/>
  5 
  6 auth,authpriv.*	 /var/log/auth.log <co id="auth-co" linkends="auth"/>
  7 ...</programlisting>
  8 
  9 <calloutlist>
 10   <callout arearefs="WorkDirectory-co" id="WorkDirectory">
 11     <para>定义rsyslog的工作目录</para>
 12   </callout>
 13   <callout arearefs="IncludeConfig-co" id="IncludeConfig">
 14     <para>指定rsyslog在运行时要包含哪些文件</para>
 15   </callout>
 16   <callout arearefs="auth-co" id="auth">
 17     <para>认证类的日志存在auth.log中</para>
 18   </callout>
 19 </calloutlist>

3.2.6. superscript和subscript

superscript和subscript是“上标”和“下标”，在一些不复杂的公式中可能会用到。

  • superscript，如下代码：

    e<superscript>πi</superscript> + 1 = 0

    将显示为 : eπi + 1 = 0

  • subscript，如下代码：

    H<subscript>2</subscript>O.

    将显示为 ：H2O.

上一页 上一级 下一页
2. 将文档物理分割 起始页 第 3 章 样式定义