<< 返回在线教程

DocBook学习笔记

发布时间:2004年7月7日

更新时间:2006年06月13日,更新How-To。

Abstract

介绍DocBook在linux系统和windows系统下的安装和使用。本文档还在不断整理完善中,如有错漏请网友多多指正,谢谢。


Table of Contents

1. DocBook简介
2. DocBook编译环境安装
2.1. windows下编译环境安装
2.1.1. 目录结构
2.1.2. 环境变量设置
2.1.3. 建立SGML解释环境
2.1.4. 建立XML的编译环境
2.2. linux下编译环境安装
3. xsltproc
4. 用DocBook写作
4.1. How-To
4.1.1. 以不同字符集输出HTML文档
4.1.2. 指定多页输出时html文档名
4.1.3. 指定输出路径
4.1.4. 实现HTML格式输出文件中章内小节自动编号
4.1.5. 用calloutlist标签实现自动编号的小图标标注
4.1.6. 特殊字符表示方法
4.1.7. 使以图标方式标注note元素
4.1.8. 用样式表格式化DocBook的HTML输出
4.1.9. 链接表示法
4.1.10. 几种列表表示法
4.1.11. 表格

List of Tables

4.1. 特殊字符

List of Examples

2.1. check.gsm
2.2. check.dsl
2.3. ISO 特殊字符catalog文档
2.4. catalog
2.5. mybook.sgm
2.6. xml测试文件check.xml
2.7. xsl格式转换文件check.xsl
2.8. mybook.xml

Chapter 1. DocBook简介

DocBook是一种文档工具,广义上来说和写字板,Word,vi之类的工具是一样的。但DocBook是一种所想即所得的文档编写工具,DocBook用标签来标识你所要的文档排版效果,用样式表来输出你所要的文档格式,可实现一次输入,多种输出。基于sgml和xml标签的灵活性,可多人协同工作。而Word之类的是所见即所得的工具,基于可视化的操作,你在电脑显示器上看到的排版效果就是你打印出来的效果。这类文档在编写时可能很方便,但修改和维护起来就很麻烦,而且不能实现多种输出。DocBook的应用范围很泛,特别在开源领域,开源技术很多文档都是用DocBook写的,如Linux HOW-TO,http://www.tldp.org等。

Chapter 2. DocBook编译环境安装

2.1. windows下编译环境安装

2.1.1. 目录结构

c:\unix

为DocBook在windows系统中起一个根目录,盘符可自定。但为了减少配置文件的修改,尽量保持这个配置。

c:\unix\etc\sgml

放置sgml全局配置文件的地方。

c:\unix\usr\bin

放置DocBook执行程序。

c:\unix\usr\lib

放置DocBook的相关库文件。

c:\unix\usr\include

放置一些程序的头文件。

c:\unix\usr\share\sgml

放置有关sgml的模块。

c:\unix\usr\share\sgml\docbook

放置有关docbook的格式文件。

c:\unix\usr\share\sgml\jade-dsssl

openjade提供的DSSSL样式表基本模块放置目录。

c:\unix\usr\share\sgml\isoent

支持sgml跨平台所需的iso字符模块目录。

2.1.2. 环境变量设置

为了正常运行DocBook的编译程序,需配置两个环境变量,一个是可执行程序和动态支持库的目录变量,另一个是SGML_CATALOG_FILES变量,这个变量用于指出模块的catalog文件目录,可设为.catalog和c:\unix\etc\sgml\catalog。

2.1.2.1. windows 95/98下的设置

在windows 98,95中可把以下设置加到autoexec.bat批处理文档中即可,如下示:

  • SET PATH=C:\unix\usr\bin;C:\unix\usr\lib;%PATH%

  • SET SGML_CATALOG_FILES=.\catalog;C:\unix\etc\sgml\catalog

2.1.2.2. windows xp/2000下的设置

按照“我的电脑”--“属性”--“高级”--“环境变量”进入环境变量设置框,在下面的“系统变量”的path中加入执行程序与运行库路径,并新建一个变量,变量名为SGML_CATALOG_FILES,值为.\catalog;C:\unix\etc\sgml\catalog,按确认完成。设置完成后可在命令行窗口用path和set命令确认设置是否生效。

2.1.3. 建立SGML解释环境

要正确解释DocBook文档,需安装配置以下内容:

  • 安装openjade for windows,以执行自动转换。

  • DocBook的DTD模块。

  • DocBook的Dsssl样式表。

  • ISO发布的特殊字符模块。

  • 本机SGML的catalog配置文档。

2.1.3.1. 安装openjade for windows

openjade是SGML解释器,在unix like系统中,它是分OpenSP和Openjade两部份的。OpenSP负责检查我们写的SGML是否合法,并把一些宏展开,其实就是C语言的预编译器。openjade负责把通过OpenSP整理的sgml文件按样式表转换成不同的格式文件。windows版的openjade中已包含了OpenSP和Openjade两部份内容。到http://prdownloads.sourceforge.net/openjade/openjade-1.3-1.exe download下载openjade软件,for windows的最新版就只有这个了。下载完后就可安装,安装路径可随便选,安装完成后,把bin目录下的所有可执行文件拷到c:\unix\usr\bin目录下;把bin目录下所有.dll动态链接文件拷到c:\unix\usr\lib目录下;把dsssl目录下所有文件拷到c:\unix\usr\share\sgml\jade-dsssl目录下。好了,到现在为止,已安装好openjade软件了。我们可以地在命令窗口测试一下。

2.1.3.1.1. 文件格式解释测试

为了测试openjade命令,我们要制作一个SGML文件。内容如下:

Example 2.1. check.gsm


<!DOCTYPE HTMLLite [
<!ELEMENT HTMLLite O O (H1|P)* >
<!ELEMENT (H1|P) - - (#PCDATA|EM|STRONG)* >
<!ELEMENT (EM|STRONG) - - (#PCDATA) >
]>
<HTMLLite>
<H1>SGML 解释器测试文件</H1>
<P>这是一个简短的,合乎 SGML 语言规格定义的文件,用于测试你的解释环境是否配置正确。</P>
<P>本文件采用 GPL 版权发布,欢迎转载、改写、散播。</P>
</HTMLLite>

切换到命令行界面,输入以下命令:

onsgmls -s check.sgm

如果没有什么提示信息返回,就说明测试通过了。-s选项表示显示出错信息。

2.1.3.1.2. 文件转换功能测试

这是openjade命令的最终工作了。我们要把上面的sgml文件通过openjade这个程序转换成rtf文件。怎么做呢?我们需要一个格式转换的样式表,现在我们就来制作一个check.dsl的样式表,以转换check.gsm文件。内容如下:

Example 2.2. check.dsl


<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN">
<style-sheet>
<style-specification>
<style-specification-body>
(element HTMLlite (make simple-page-sequence))
(element H1
(make paragraph
font-family-name: "Times New Roman"
font-weight: 'bold
font-size: 20pt
line-spacing: 22pt
space-before: 15pt
space-after: 10pt
start-indent: 6pt
first-line-start-indent: -6pt
quadding: 'center
keep-with-next : #t))
(element P
(make paragraph
font-family-name: "Times New Roman"
font-size: 12pt
line-spacing: 13.2pt
space-before: 6pt
start-indent: 6pt
quadding: 'start))
(element EM
(make sequence
font-posture: 'italic))
(element STRONG
(make sequence
font-weight: 'bold))
</style-specification-body>
</style-specification>
</style-sheet>

打开dos窗口,在同一目录下输入以下命令行。

openjade -t rtf -d check.dsl -c C:\unix\usr\share\sgml\jade-dsssl\catalog -o output.rtf check.sgm

2.1.3.2. 安装DocBook的DTD模块

DTD模块是为DocBook建立文档组织框架而设计的。DocBook最新的DTD可以到http://www.oasis-open.org/docbook/sgml下载。现在最新版的是4.2版的。文件名应该是docbook-4.2.zip 。下载完成后,在c:\unix\usr\share\docbook目录下建一个sgml-dtd-42的文件夹,把解压内容拷贝进来。最后把C:\unix\usr\share\sgml\docbook\sgml-dtd-42\docbook.cat 文档打开,删除里面“DTDDECL”行的内容,新版的DTD好象已经不含该项了。并另存为catalog。这样DTD模块就安装好了。

2.1.3.3. 安装DocBook的DSSSL样式表

样式表是控制DocBook文件转换成什么格式输出的文件。在DocBook中作得比较多的是由Norman Walsh 写的DSSSL样式表。我们可以到http://sourceforge.net/project/showfiles.php group_id=21935下载docbook-dsssl-1.78.zip。解压到C:\unix\usr\share\sgml\docbook 目录下,产生docbook-dsssl-1.78 子目录。DSSSL的catalog文件已有不用另外建立。好了,现在DSSSL也安装好了。

2.1.3.4. 安装ISO特殊字符模块

由于计算平台和操作系统会使用一些非ASCII的字符,所以为了实现跨平台应用,DocBook也要安装这些特殊字符,所以要下载由ISO组织发布的ISO entities module。可到http://www.tldp.org/authors/tools/entities.tar.gz下载。文件名是entities.tar.gz ,下载完成后,解压到C:\unix\usr\share\sgml\isoent 下即可。为了使sgml解释程序可以找到它,我们还要在该目录下建一个catalog文件。内容如下:

Example 2.3. ISO 特殊字符catalog文档


-- ...................................................................... --
-- ISO entity sets ...................................................... --

PUBLIC "ISO 8879:1986//ENTITIES Diacritical Marks//EN" "ISOdia"
PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" "ISOnum"
PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN" "ISOpub"
PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "ISOtech"
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "ISOlat1"
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN" "ISOlat2"
PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN" "ISOgrk1"
PUBLIC "ISO 8879:1986//ENTITIES Monotoniko Greek//EN" "ISOgrk2"
PUBLIC "ISO 8879:1986//ENTITIES Greek Symbols//EN" "ISOgrk3"
PUBLIC "ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" "ISOgrk4"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" "ISOamsa"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" "ISOamsb"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" "ISOamsc"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" "ISOamsn"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" "ISOamso"
PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" "ISOamsr"
PUBLIC "ISO 8879:1986//ENTITIES Box and Line Drawing//EN" "ISObox"
PUBLIC "ISO 8879:1986//ENTITIES Russian Cyrillic//EN" "ISOcyr1"
PUBLIC "ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" "ISOcyr2"

-- ...................................................................... --

这样,iso特殊字符模块也安装好了。

2.1.3.5. 建立全局索引档

到现在为止,所有程序和文档已安装好了,现在需建立一个全局索引档,把所有的文档串起来。该文档就是c:\unix\etc\sgml\catalog。需自已建立,内容如下:

Example 2.4. catalog


OVERRIDE YES
-- filename: catalog --
-- file function : Under this system,all DTD version catalog file --

CATALOG "c:/unix/usr/share/sgml/isoent/catalog" -- ISO external ENTITY declare file --
CATALOG "c:/unix/usr/share/sgml/jade-dsssl/catalog" -- openjade dsssl module --
CATALOG "c:/unix/usr/share/sgml/docbook/docbook-dsssl-1.78/catalog" -- DocBook out put stylesheet --
CATALOG "c:/unix/usr/share/sgml/docbook/sgml-dtd-42/catalog" -- DocBook SGML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/sgml-dtd-41/catalog" -- DocBook SGML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/sgml-dtd-40/catalog" -- DocBook SGML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/sgml-dtd-31/catalog" -- DocBook SGML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/xml-dtd-41/catalog" -- DocBook XML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/xml-dtd-412/catalog" -- DocBook XML version DTD module --
CATALOG "c:/unix/usr/share/sgml/docbook/xml-dtd-42/catalog" -- DocBook XML version DTD module --

SGML的catalog文档可以以层次关系进行互相引用,从而使我们不用把所有catalog文档的路径包含在SGML_CATALOG_FILES 环境变量中,只把最顶层的catalog文档包含进来就可以了。

[Note]

上面的catalog文档中还包含有41,31等版本的配置,如按本文的配置是可以不要的,所以实际应用时可根据自已的需要进行调整。

2.1.3.6. 实战DocBook SGML

现在我们来编写一个简单的DocBook sgml文档,并用openjade进行编译。

Example 2.5. mybook.sgm


<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
<book>
<bookinfo>
<title>An Example Book</title>

<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
</author>

<copyright>
<year>2000</year>
<holder>Copyright string here</holder>
</copyright>

<abstract>
<para>If your book has an abstract then it should go here.</para>
</abstract>

接着用以下命令进行编译就可以生成html文件了,如果想生成rtf格式文件,只要把-t sgml换成-t rtf就可以了。

openjade -t sgml -d C:\unix\usr\share\sgml\docbook\docbook-dsssl-1.78\html\docbook.dsl mybook.sgm

[Note]

用本机的DT<!DOCTYPE book SYSTEM "C:\unix\usr\share\sgml\docbook\xml-dtd-42\docbookx.dtd">可以加快编译的速度和不用依赖网络。

2.1.4. 建立XML的编译环境

SGML虽然功能强大,但较复杂,包罗万象,所以W3C设计了XML,一个SGML的精简集,语法大为简化,适合于网络传输。自DocBook4.0开始,DocBook每次新版发布,都会用SGML和XML各定义一次。那是不是要学两种语法呢?不用啦,它们的标签都大同小异。以下介绍一下XML编译环境的配置。

2.1.4.1. 安装xml解释程序

在windows平台上的xml解释器有很多,以java开发的工具为最多。现在我们介绍是以C语言编写的程序叫xsltproc。我们可到以下网址http://www.zlatkovic.com/pub/libxml/下载相关软件。一共要下载4个文件,分别是:

  • libxml2-2.6.7.win32.zip-----用于进行xml语法合法性检验和资料整理。

  • libxslt-1.1.4.win32.zip-----负责格式转换。

  • iconv-1.9.1.win32.zip-----语言转换工具。

  • zlib-1.1.4.win32.zip-----资料压缩处理工具。

安装方法和安装openjade的差不多,先解压,再把util目录中的内容拷到c:\unix\usr\bin文件夹中;把lib目录中的内容拷到c:\unix\usr\lib中,把include目录中的内空拷到c:\unix\usr\include目录中。4个文件的目录结构一类似,所以用同样的方法操作即可。

2.1.4.1.1. 制作xml测试文件

和sgml的测试文件大同小异,内容如下:

Example 2.6. xml测试文件check.xml


< xml version="1.0" encoding="gb2312" >
<!DOCTYPE HTMLLite [
<!ELEMENT HTMLLite O O (H1|P)* >
<!ELEMENT (H1|P) - - (#PCDATA|EM|STRONG)* >
<!ELEMENT (EM|STRONG) - - (#PCDATA) >
]>
<HTMLLite>
<H1>SGML 解释器测试文件</H1>
<P>这是一个简短的,合乎 xml 语言规格定义的文件,用于测试你的解释环境是否配置正确。</P>
<P>本文件采用 GPL 版权发布,欢迎转载、改写、散播。</P>
</HTMLLite>

2.1.4.1.2. 制用xml样式表

SGML用DSSSL来制作样式表,XML就用xsl或xslt来制作样式表。下面的是一个针对上例的样式表。

Example 2.7. xsl格式转换文件check.xsl


< xml version="1.0" encoding="gb2312" >
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:output method="html"/>
<xsl:template match="/">
<html>
<head>
<title>HTMLlite document</title>
</head>
<body bgcolor="#FFFFFF">
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
<xsl:template match="H1">
<h1>
<xsl:apply-templates/>
</h1>
</xsl:template>
<xsl:template match="P">
<p>
<xsl:apply-templates/>
</p>
</xsl:template>
<xsl:template match="EM">
<i>
<xsl:apply-templates/>
</i>
</xsl:template>
<xsl:template match="STRONG">
<b>
<xsl:apply-templates/>
</b>
</xsl:template>
</xsl:stylesheet>

2.1.4.1.3. 执行转换

xsltproc check.xsl check.xml > check.htm

现在就生成一个check.htm文件,你可以用浏览器打开看一下。

2.1.4.2. 安装XML格式的DocBook DTD模块

其实xml的dtd可安装也可不安装,因为可直接连接到网络上去使用,但速度可能就慢一点,要安装也很简单,和安装SGML的DTD一样,到http://www.oasis-open.org/docbook/xml下载docbook-xml-4.2.zip 文件,并解压到C:\unix\usr\share\sgml\docbook\xml-dtd-42目录下即可。注意目录下的文件,catalog文件已存在。

2.1.4.3. 安装DocBook的XSL样式表

同理,可到http://sourceforge.net/project/showfiles.php group_id=21935下载最新版本的xsl样式表。下载完成后解压到C:\unix\usr\share\sgml\docbook目录下即可。

2.1.4.4. 安装ISO特殊字符模块

xml的iso特殊字符模块在XML的DTD里已经有了,不用另外安装。你可以看一下C:\unix\usr\share\sgml\docbook\xml-dtd-42目录是不是有一个ent的子目录。

2.1.4.5. 本机catalog文件配置

可以和sgml的共用,所以不用配置了,可参见上面的内容

2.1.4.6. 实战DocBook XML

2.1.4.6.1. 制作测试文件

和SGML格式的文件差不多,只是开头文件宣告有一些差别。

Example 2.8. mybook.xml


< xml version="1.0" encoding="gb2312" >
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
>
<book>
<bookinfo>
<title>An Example Book</title>
<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
</author>

<copyright>
<year>2000</year>
<holder>Copyright string here</holder>
</copyright>

<abstract>
<para>If your book has an abstract then it should go here.</para>
</abstract>
</bookinfo>

<preface>
<title>Preface</title>

<para>Your book may have a preface, in which case it should be placed
here.</para>
</preface>

<chapter>
<title>My first chapter</title>

<para>This is the first chapter in my book.</para>

<sect1 id="1.1">
<title>My first section</title>

<para>This is the first section in my book.</para>
</sect1>
<sect1 id="1.2">
<title>my second section</title>
<para> this is the second section in my book.</para>
</sect1>
</chapter>
</book>

2.1.4.6.2. 执行转换

xsltproc C:\unix\usr\share\sgml\docbook\docbook-xsl-1.65.1\html\docbook.xsl mybook.xml >mybook.htm

2.2. linux下编译环境安装

在各种Linux的发行版中,docbook的编译环境多数都预先设置好了。如需了解如何安装请参考<<DocBook XML/SGML Processing Using OpenJade>>这篇文章。

Chapter 3. xsltproc

xsltproc是libxslt库的命令行处理程序,用于处理xml文档。我们利用xsltproc来处理docbook文档,输出各种格式的文档。官方网站:http://xmlsoft.org/

  • 利用样式表生成单页的html文档,生成文档名为debian.html,生成的文档位于当前目录。

    $ xsltproc --stringparam html.stylesheet docbook.css /usr/share/sgml/docbook/docbook-xsl-1.65.1/html/docbook.xsl debian.xml>debian.html
    
  • 利用样式表生成多页的html文档,每章和每小节都会生成独立的一个html文档,生成文档位于当前目录。

    $ xsltproc --stringparam html.stylesheet docbook.css /usr/share/sgml/docbook/docbook-xsl-1.65.1/html/chunk.xsl debian.xml
    

    用-o选项可指定生成文档的路径

Chapter 4. 用DocBook写作

4.1. How-To

4.1.1. 以不同字符集输出HTML文档

使用docbook.xsl样式表时,可生成单一文件。修改docbook.xsl样式表实现输出不同字符集的html文档,方法是修改以下的encoding项就可以了。

<xsl:output method="html"
            encoding="utf-8"
            indent="no"/>

使用chunk.xsl样式表时,可生成多页文件。可修改chuner.xsl。

<xsl:param name="chunker.output.encoding" select="'utf-8'"/>

或者在命令行中用参数指定。

$ xsltproc --stringparam html.stylesheet docbook.css --stringparam chunker.output.encoding UTF-8 /usr/share/sgml/docbook/docbook-xsl-1.65.1/html/chunk.xsl debian.xml       

4.1.2. 指定多页输出时html文档名

我们把docbook文档转换成html文档时,可以转换成一个大的html文档,也可以转换成多页的html文档。当转换成多页是,默认的文件是以ch01.html、ch02.html方式命名的,较不直观。我们可在docbook文档中添加一个属性,使它输出时按我们指定的文件名输出。

方法一:
<chapter>< dbhtml filename="first.html"  >
<title>Introduction</title>
...

方法二:
<chapter id="first">
<title>Introduction</title>
...

4.1.3. 指定输出路径

默认转换后的文档是保存在当前目录的,我们可在xsltproc命令行用-o选项指定转换后文档的输出路径,另外一种是在docbook中指定。

<book>< dbhtml dir="jims"  >
<title>Docbook Guide</title>
...
<chapter id="first">< dbhtml dir="technic"  >
...
<chapter id="second">
...
<appendix id="three">< dbhtml dir="read"  >
...

输出后的路径:
jims/index.html
jims/technic/first.html
jims/second.html
jims/read/three.html

4.1.4. 实现HTML格式输出文件中章内小节自动编号

默认HTML格式输出文件中的章内小节是没有自动编号功能的,如果要实现小节自动编号需要设置HTML格式的两个转换参数。

  • section.autolabel参数为1代表章内小节可自动编号,为0表示不会自动编号;

  • section.label.includes.component.label参数为1表示章内小节编号包含章节编号,为0表示不包含章节编号。

设置这两个参数可通过命令行方式,也可通过修改XSL转换文件方法。下面分别介绍这两种方法:

  • 通过命令行方式:

    $ xsltproc --stringparam  section.autolabel 1 \
               --stringparam  section.label.includes.component.label 1 \
               docbook.xsl  myfile.xml>myfile.htm
    
  • 修改XSL转换文件方式:

    DocBook文档的HTML格式转换样式文件一般位于/usr/share/sgml/docbook/docbook-xsl-1.65.1/html/目录下。通过查看docbook.xsl文件可知,在docbook.xsl中引用param.xsl作为参数设置文件,所有的参数都在这里设置。我们打开param.xsl文件,找到以下两行,再把参数置成1就可以了。

    <xsl:param name="section.autolabel" select="1"/>
    <xsl:param name="section.label.includes.component.label" select="1"/>
    

4.1.5. 用calloutlist标签实现自动编号的小图标标注

效果如下:

<html>

1<img tal:replace="structure container/logo">		

<h1>
2Welcome to <i tal:content="template/title">title</i>,	
    this my zope tutorial,I like zope,I like python too.</h1>
    <h2>another test page in my zope site is zoo</h2>
  3<a href = index_html>zoo</a>				

</html>

1

显示logo图片

2

用"template/title"值(zope home page)替换title。

3

建立一个到zoo目录的链接。

源码如下:

<para>
<screen>
&lt;html&gt;

<co id = "co.1.1" />&lt;img tal:replace="structure container/logo">		

&lt;h1>
<co id = "co.1.2" />Welcome to &lt;i tal:content="template/title">title&lt;/i>,	
this my zope tutorial,I like zope,I like python too.&lt;/h1>
&lt;h2>another test page in my zope site is zoo&lt;/h2>
<co id = "co.1.3" />&lt;a href = index_html>zoo&lt;/a>				

&lt;/html>
</screen>
	  </para>
	  <calloutlist>
		  <callout arearefs = "co.1.1">
			  <para>显示logo图片</para>
		  </callout>
		  <callout arearefs = "co.1.2">
			  <para>用"template/title"值(zope home page)替换title。</para>
		  </callout>
		  <callout arearefs = "co.1.3">
			  <para>建立一个到zoo目录的链接。</para>
		  </callout>
	  </calloutlist>
	  

上图中的每个小图标是放在images/callouts目录下的1.png、2.png、3.png文件,所以图标也可以自已设计。

4.1.6. 特殊字符表示方法

Table 4.1. 特殊字符

特殊字符实体表示法
<&lt;
>&gt;
&&amp;
"&quot;
'&apos;

4.1.7. 使以图标方式标注note元素

一般来说,note标注只会以“Note”文字的形式来标注,如:

Note
    为方便起见,sys模块包含一个maxint成员,该成员保留了整形变量的最大正数值。

我们也可用图标来标注。如:

[Note]
为方便起见,sys模块包含一个maxint成员,该成员保留了整形变量的最大正数值。

这样是不是美观很多,具体实现方法如下(以XML格式的DocBook文档为例):

  • 首先,我们需修改docbook的编译参数,位于param.xsl文件内,把以下几项修改成:

    <xsl:param name="admon.graphics.extension" select="'.png'"/>  #设置图标格式
    <xsl:param name="admon.graphics" select="1"/>                 #开启图标显示
    <xsl:param name="admon.graphics.path">images/</xsl:param>     #图标的路径
    
  • 接着,选择一个合适的图标,以note.png为文件名,保存到images/目录下。

  • 最后,重新编译文档,完成。

4.1.8. 用样式表格式化DocBook的HTML输出

有时我们想改变生成的HTML文件的表现形式,最好的办法是使用CSS(级联式样式表)。我们打开由DocBook生成的HTML文件可以看到,每个DocBook元素都会以<div class="element">标记,如:

<div class="chapter" lang="en">
  <div class="titlepage">
    <div>
      <div>
        <h2 class="title">
           <a name="Catalogs"></a>Chapter 3. XML catalogs
        </h2>
      </div>
   ...

这样,我们就可编写一个样式表,与生成的HTML文件中的class关联起来,从而格式化HTML文件的输出样式。下面是一个样式表的例子(可直接拷贝使用)。

/* CSS2 Stylesheet for _DocBook: The Definitive Guide_
 * Copyright (C) 1999, 2000, 2001, 2002 O'Reilly & Associates, Inc.
 *
 * $Id: defguide.css,v 1.1 2002/06/17 12:20:45 nwalsh Exp $
 */

DIV.example-output {
  padding-left: 15px;
  border-style: solid;
  border-width: 0px;
  border-left-width: 2px;
  border-color: black;
}

pre.screen {
  background: #E8E8E8;
}

pre.programlisting {
  background: #E8E8E8;
}

div.example-source {
  background: #E8E8E8;
}

p.publisher {
  text-align: center;
}
 
body.book {
/*  background-image: url(figures/htmltitlepage.gif); */
/*  background-repeat: no-repeat; */
/*  background-position: top center; */
}

div.component-title {
  text-align: right;
}
h1.label {
  font-size: 150pt;
  font-weight: normal;
  margin-bottom: 0px;
  padding-bottom: 0px;
  margin-top: 0px;
  padding-top: 0px;
}

div.component-title h1.title {
  margin-top: 0px;
  padding-top: 0px;
  margin-right: 20px;
  font-size: 36pt;
}

p.alpha-version {
  margin-top: 0px;
  padding-top: 0px;
}

hr.component-separator {
  height: 1px;
}

div.refentry div.titlepage {
  margin-left: 20px;
}

div.refentry div.titlepage h1.title {
  margin-left: -20px;
  margin-bottom: 0px;
  font-size: 36pt;
}

body {
  margin-top: 0px;
  padding-top: 0px;
  margin-left: 0px;
  margin-right: 0px;
  padding-left: 0px;
  padding-right: 0px;
}

div.navheader {
}

div.navfooter {
}

div.copyrightfooter {
  background-color: #c6bec6;
  margin-top: 0px;
  padding-top: 0px;
  padding-left: 10px;
  padding-right: 10px;
  padding-bottom: 2px;
}

div.copyrightfooter p {
  margin-top: 0px;
  padding-top: 10px;
}

div.refentry,
div.preface,
div.chapter,
div.appendix,
div.reference,
div.part,
div.bibliography,
div.glossary,
div.index,
div.colophon,
div.legalnotice,
div.sect1 {
  margin-left: 10px;
  margin-right: 10px;
}

div.book {
  margin-left: 10px;
  margin-right: 10px;
  margin-top: 5px;
}

thead {
  background-color: black;
  color: white;
}

table,
tbody,thead,tfoot,
tr,td {
  border-color: #8F8F8F;
}

div.docbookng-synopsis { border-left: 0.5pt solid black;
                         margin-left: 0.25in;
                         padding-left: 0.25in;
                         border-top: 0.5pt solid black;
                         margin-top: 0.25in;
                         border-bottom: 0.5pt solid black;
                         margin-bottom: 0.25in;
                       }

div.docbookng-synopsis
div.define-next        { border-top: 0.5pt solid black;
                         margin-top: 0.25in;
                         padding-top: 0.25in;
                       }

为了在输出的HTML文件中使用我们自定义的样式表,可使用xsltproc命令的--stringparam参数,如:

xsltproc --stringparam html.stylesheet  mystylesheet.css  docbook.xsl  myfile.xml
注:mystylesheet.css为我们定义的样式表,docbook.xsl为转换样式表,myfile.xml为我们的DocBook源文档

这样,输出的HTML文件中就会有以下的定义:

<link rel="stylesheet" href="mystylesheet.css" 
      type="text/css"> 

通过这种方法,我们就可用一个CSS样式表控制整个输出文件的表现形式,而不用修改DocBook的XSL样式表。

4.1.9. 链接表示法

4.1.10. 几种列表表示法

在撰写技术文章时,列表表示法能使文章的结构化和条理化大大增加,使文章重点突出。在docbook中的列表表示法,有如下几种:

  • 没有序号的列表表示法:

    <itemizedlist>
          <listitem>
                <para>列表内容</para>
          </listitem>
    </itemizedlist>
    ...
    
  • 带序号的列表表示法:

    <orderedlist>
          <listitem>
                <para>列表内容</para>
          </listitem>
    </orderedlist>
    ...
    
  • 上下层次结构的列表表示法:

    <variablelist>
          <varlistentry>
              <term>列表段标题</term>
              <listitem>
                  <para>列表内容</para>
              <listitem>
          </varlistentry>
    ...
    </variablelist>
    

4.1.11. 表格

下面是一个有两列的表格,cols属性可控制表格的列数:

<table>
   <title>表格标题</title>
   <tgroup cols="2">
     <thead>
       <row>
          <entry>列标题1</entry>
          <entry>列标题2</entry>
       </row>
     </thead>
    <tbody>
       <row>
          <entry>列内容1</entry>
          <entry>列内容2</entry>
       </row>
       ...
    </tbody>
   </tgroup>
</table>