DocBook

前言：我的 DocBook 之旅

我为什么选择了 DocBook

2001下半年，负责撰写防火墙API参考

一个需要持久维护的文档，Word文档很难

一个可以在 Web 上生成表现一致且美观的文档

榜样的力量

LDP

DocBook 推广受阻

学习曲线陡峭，公司内部难以推广

技术人员的“专利”

人员流动频繁，培训跟不上

不付费的培训难以维持 ;-)

协同著作能力较差

需要依靠版本控制系统建立协同著作功能

可能还需要建立邮件列表提供邮件通知功能

需要建立可行的内部网站管理规范，以便通过网站对文档的展示

文档的自动编译

新文档的加入

文档的分类

Wiki 在协同著作上面具有先天的优势

DocBook 生命力依旧

出版领域上的优势

包括个人发表作品

DocBook 满足多种格式需要。主要是可打印版本的需求

和 Wiki 比起来，DocBook 撰写的文档可以下载，本地浏览

DocBook 的文档可署名、和分发，更有成就感

我的文档写作模式

Wiki 是协同著作的首选，也可以作为日志系统

FreeMind 整理思路，针对大文档

DocBook，产品文档，个人著作出版

什么是 DocBook

What is Docbook

一种标识语言

技术文档撰写

独立机构维护

技术上说，DocBook是一个XML DTD或者 SGML DTD

以 SGML DTD 描述，历史最久，XML DTD 则后来居上

DocBook 文档描述语意，而非表现

表现交给样式表处理，因此文档具有相似的外观

文档撰写更加关注内容本身，而非表现

与传统字处理软件的不同

倒是有点像字处理软件之前

作者提供手稿，编辑识别文档结构，录入，修饰格式，出版

优点

Single Sourcing (单一源文件维护)

可版本控制

通用、开放的XML格式

缺点

协同协作方面，不如 Wiki

格式排版，不如 latex

样式表

要理解为工具而非类似 CSS 一样的语言

SGML/XML 标记语言基础

Why SGML?

SGML 用于 DocBook 有更长久的历史

SGML 的工具也比较完善，比如一直在用 DSSSL 进行 DocBook 到 rtf 的转换

XML 则比较新，但后来居上

SGML/XML 共性

共性？您是说 SGML/XML 语言的交集么？这么说可就有点问题，因为 XML 是 SGML 子集

structured, semantic markup

数据结构，与表现分开

而 HTML 则离开的太远

elements

attributes

实体（entities）

简单的说：类似于宏定义，用一个名称标识一块数据，引用该名称就引入该数据

复杂因为有多种分类方法

可以用在两种不同文件中

DTD 和文档中

一般实体和参数实体

一般实体又分为内部一般实体和外部一般实体

两种不同类型的实体

已析和未析

两种或三种不同的引用方法

一般实体和外部实体

一般实体

一般实体声明位于文档的序言中

一般实体的声明可以引用一般实体，除非出现循环调用

常用的一般实体的定义可以放在 DTD 中，实现声明一次，多处使用

外部实体

可以在一个文档中引用另外的文档

如: 将一篇文章分为几个部分，用外部实体方式定义、包含

如: 引用图片文件

可析实体

外部数据是需要直接包含进来的文本数据，称为 parsed entities

例如

声明：

<!ENTITY ch01 SYSTEM "ch01.sgm">

<!ENTITY ch02 SYSTEM "ch02.sgm">

<!ENTITY ch03 SYSTEM "ch03.sgm">

<!ENTITY ch04 SYSTEM "ch04.sgm">

引用

<book>

&ch01;

&ch02;

&ch03;

&ch04;

</book>

非析实体

外部数据是一个图片，则称为 unparsed entities

例如

声明：

<!ENTITY tree SYSTEM "tree.eps" NDATA EPS>

引用：

<graphic entityref="tree"></graphic>

字符实体

特殊字符

<, >, &

会被误认为元素或者实体

因此需要

其它字符，如非打印字符，Unicode 字符，中文等

SGML

特殊字符由第三方实体分类文件定义，也称数据实体

xml

XML 可以用形如 &#xhhhh; 的数字字符对照表示 Unicode 字符

而 SGML 则必须进行定义

参数实体

仅出现于 DTD 当中

SGML 还可以出现于文档当中的标记块中

<![keyword[ and end with ]]>

常见的标记块

INCLUDE

IGNORE

CDATA

以 % 开始而非 & 符号

示例

参数实体定义

<!ENTITY % draft "IGNORE">

引用参数实体，实现对文本块的控制

<![%draft;[

<para>

This paragraph only appears in the draft version.

</para>

]]>

参数实体定义

<!ENTITY % draft "INCLUDE">

引用参数实体，实现对文本块的控制

<![%draft;[

<para>

This paragraph only appears in the draft version.

</para>

]]>

注释

处理指令

好形与有效性

SGML 的特征

SGML 资料，参见： http://xml.coverpages.org/general.html#overview

文档结构

序言

SGML 文档必须有一个序言

SGML Declaration (可选)

一个可选的 SGML Declaration（SGML声明）

但一般和 DTD 一起存放在外部的文件中，命名为“docbook.dcl”；

在 catalog 文件中：

SGMLDECL "dtd/4.2/docbook.dcl"

SGML Declaration 参考： http://www.oasis-open.org/cover/wlw11.html

Document Type Declaration (必选)

例如:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!ENTITY nwalsh "Norman Walsh">

<!ENTITY chap1 SYSTEM "chap1.sgm">

<!ENTITY chap2 SYSTEM "chap2.sgm">

]>

声明根元素是什么

book

声明使用的 DTD

内部子集

<!ENTITY nwalsh "Norman Walsh">

<!ENTITY chap1 SYSTEM "chap1.sgm">

<!ENTITY chap2 SYSTEM "chap2.sgm">

外部子集

例如: PUBLIC "-//OASIS//DTD DocBook V3.1//EN"

如何引用外部子集？

public/system 标志符

catalog 文件

可以用 Public 或者 SYSTEM 标志符

SGML 多用 PUBLIC 标志符，因为有更好的移植性

XML 降低了 Public 标志符地位。

XML 必须有 System 标志符，而不必有 Public 标志符

实际上 Public 标志符依赖 Catalog 文件

使用外部的 Catalog 文件，建立 Public 标志符到本地的文件映射

SYSTEM 标志符格式不限

在 SGML 中通常是直接指向本地的文件名，因在移植上的问题，一般多用 Public 标志符

如： /usr/local/sgml/docbook/3.1/docbook.dtd

内部子集的声明优先于外部子集

根元素

根元素紧接着序言部分（当然注释、处理指令（processing instructions）除外）

与 XML 兼容性问题

大小写问题

SGML中元素、属性大小写不敏感

但是，实体名称大小写敏感

为向 XML 移植方便，请都用小写字母

属性是否用引号的问题

除非属性值包含空格，否则可以不用引号将属性值括起来；

XML必须用引号将属性值扩起来

如何将文章分解成几块

（利用外部实体）

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!ENTITY chap1 SYSTEM "chap1.sgm">

<!ENTITY chap2 SYSTEM "chap2.sgm">

<!ENTITY chap3 SYSTEM "chap3.sgm">

<!ENTITY appa SYSTEM "appa.sgm">

<!ENTITY appb SYSTEM "appb.sgm">

]>

<book><title>My First Book</title>

&chap1;

&chap2;

&chap3;

&appa;

&appb;

</book>

<chapter id="ch1"><title>My First Chapter</title>

<para>My first paragraph.</para>

...

注意不要在该文档文件头加入 DTD!

XML 的特征

XML 资料参见：http://xml.coverpages.org/xmlIntro.html

文档结构

序言

XML Declaration (可选)

<?xml version="1.0" standalone="no"?>

如果没有 XML Declaration，则版本为1.0，编码为 utf-8

Document Type Declaration (可选)

严格的说，XML 并不需要一个 DTD

例如:

<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"

"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd">

声明根元素是什么

如: book

声明使用的 DTD

内部子集

<!ENTITY nwalsh "Norman Walsh">

<!ENTITY chap1 SYSTEM "chap1.sgm">

<!ENTITY chap2 SYSTEM "chap2.sgm">

如何引用外部子集？

public/system 标志符

catalog 文件

例如: PUBLIC "-//OASIS//DTD DocBook V3.1//EN"

如何引用外部子集？

SYSTEM 标志符（必选）

降低了 Public 标志符的作用

SYSTEM 标志符在 XML 中必须是 URI 格式

可以是 URL

也可以是本地文件： file:///usr/local/sgml/docbook/3.1/docbook.dtd

PUBLIC 标志符（可选）

内部子集的声明优先于外部子集

根元素

根元素紧接着序言部分

当然注释、处理指令（processing instructions）除外

其它

XML所有的标记大小写敏感

DocBook 的元素、属性、实体最好都用小写

所有属性的值无论有空格与否，都要用引号括起来

空元素要如下写法：<br/>

处理指令格式： <?pitarget data?>

而 SGML 的处理指令没有最后一个问号，形如：<?pitarget data>

Catalog 文件

The catalog file format was defined in 1994 by SGML Open (now OASIS). The formal specification is contained in OASIS Technical Resolution 9401:1997.

优点

增加了可移植性，因为不同机器的 DTD, Entities, DSSSL/XSL 可以存放于不同位置；

避免了对带宽占用。XML 格式的 DocBook，SYSTEMID 格式为 URI，可以直接到网络上抓取，通过 catalog 建立本地映射，提高加载速度，以及减小对带宽占用

可以通过 SYSTEM sysid1 sysid2 建立本地文件映射，可以写出可移植的 Makefile

方便 DTD、样式表升级

SGML 格式的 Catalog 文件

语法

由一系列 Ket/Value 对组成

如： PUBLIC, SYSTEM, SGMLDECL, DTDDECL, CATALOG, OVERRIDE, DELEGATE, and DOCTYPE.

SGMLDECL 定义 SGML 声明

SGMLDECL sysid

定义 SGML Declaration。很多工具具有默认的 SGML Declare

SGMLDECL "docbook/3.1/docbook.dcl"

对不同文档设置不同 SGMLDecl

DTDDECL pubid sysid

如果一个文档的 DocType 符合 pubid, 则使用 sysid 作为 SGMLDecl

如: 在一个 catalog 文件中既定义 DTD 的

声明文件，又定义XML的声明文件

SGMLDECL "dtd/docbook-4.5/docbook.dcl"

DTDDECL "-//OASIS//DTD DocBook XML V4.5CR1//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

DTDDECL "-//OASIS//DTD DocBook XML V4.2//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

DTDDECL "-//OASIS//DTD DocBook XML V3.1//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

PUBLIC/SYSTEM 定位 DTD 位置

PUBLIC pubid sysid

<html>PUBLIC 关键字用于 public identifiers 到 system identifiers 的映射：

<div><blockquote><i>

PUBLIC "-//OASIS//DTD DocBook V3.1//EN" "docbook/3.1/docbook.dtd"

</i></blockquote></div>

SYSTEM sysid1 sysid2

<html>SYSTEM 关键字用于 system identifiers 到 system identifiers 的映射:

<div><blockquote><i>

SYSTEM "http://nwalsh.com/docbook/xml/1.3/db3xml.dtd"<br>

<blockquote><i>

"docbook/xml/1.3/db3xml.dtd"

</blockquote></i>

</i></blockquote></div>

OVERRIDE bool

默认 System 标志符优先于 Public 标志符

OVERRIDE YES，则Public 标志符优先

DOCTYPE name sysid

如: DOCTYPE BOOK n:/share/sgml/docbook/3.1/docbook.dtd

定义缺省的 Doctype, 当文档没有指定 public/system 标识，或者没有定义DocType 时

CATALOG 实现 catalog 文件的级联

其它

DELEGATE 实现条件 catalog 级联

如: DELEGATE "-//OASIS" "/usr/sgml/oasis/catalog"

引用到 "-//OASIS" 后，采取读取相应的 catalog 文件

ENTITY name sysid

实体

ENTITY %name sysid

参数实体

示例

-- Comments are delimited by pairs of double-hyphens,

as in SGML and XML comments. --

OVERRIDE YES

SGMLDECL "n:/share/sgml/docbook/3.1/docbook.dcl"

DOCTYPE BOOK n:/share/sgml/docbook/3.1/docbook.dtd

PUBLIC "-//OASIS//DTD DocBook V3.1//EN"

n:/share/sgml/docbook/3.1/docbook.dtd

SYSTEM "http://nwalsh.com/docbook/xml/1.3/db3xml.dtd"

n:/share/sgml/Norman_Walsh/db3xml/db3xml.dtd

工具

openjade, opensp 可以利用该格式的 catalog 文件

可以在 openjade, opensp 等工具中用命令行 -c catalogfile 指定位置

也可以通过环境变量 SGML_CATALOG_FILES 指定Catalog 文件，多个catalog文件可以用冒号分隔

XML格式的 Catalog 文件

语法

public/system 定位 DTD 位置

uri 定位 XSL 样式表位置

（本地到本地）

uri 将 web 地址对应本地文件

（URL 到本地）

rewriteSystem 建立重写规则，

简化、合并 URI 项

nextCatalog 实现 catalog 文件级联

For DocBook 4.4:

<nextCatalog catalog="/usr/share/xml/docbook44/catalog.xml" />

For DocBook 4.1.2:

<nextCatalog catalog="/usr/share/xml/docbook412/docbook.cat" />

示例

工具

xsltproc, Saxon, Xalan 可以利用该格式的 catalog 文件

除了 xsltproc 是使用环境变量 XML_CATALOG_FILES 外， Java 工具有自己的方式，参见后面的介绍

SGML 时代的 DocBook

DTD

定义 DocBook SGML 文档结构的 Schema Languages

SGML 和 XML 格式的 DTD 区别：

ISO 字符实体集（ISO character entity sets）格式不同，需要对应不同的 Entities 文件

内部定义的 ISO charset entities 格式

sgml

<!ENTITY euro SDATA "[euro ]">

xml

<!ENTITY euro "€">

定义 DTD 时，ho,hh 参数实体不同

sgml

<!ENTITY % ho "- O">

<!ENTITY % hh "- -">

xml

<!ENTITY % ho "">

<!ENTITY % hh "">

对参数实体的引用

引用 %ho; 的有 401 处

<!ELEMENT title %ho; (%title.char.mix;)*>

引用 %hh; 的有 0 处

DTD 中可能没有包含所需的 Entities，参见：

如今，DTD 已经不是唯一选择，还有 XML Schema, RELAX NG

Entities

参见: http://www.oasis-open.org/cover/topics.html#entities

DSSSL

what is it

a kind of Scheme (which is a kind of Lisp)

OpenJade

可以将 SGML/XML 转换为

html

rtf

text

Tex - DVI - PS - PDF

关于处理 XML 文件

If you handle XML with OpenJade, OpenJade will by default complain bitterly about any character outside the basic 32 to 128 ASCII range. That can be avoided by setting the following three environment variables:

SP_CHARSET_FIXED=YES

SP_ENCODING=XML

SGML_CATALOG_FILES=/usr/share/sgml/jade_dsl/xml.soc

有效性验证

onsgmls

onsgmls.exe -sv -c /share/catalog.sgml index.xml

onsgmls.exe -sv -c /share/catalog.sgml index.sgml

OpenSP

编译 OpenSP 之前

补丁: gcc3.4 下编译补丁

参见 Cygwin OpenSP 源代码包中的补丁

Cygwin OpenSP 补丁不再需要设置 LIBS 环境变量

export LIBS=-lintl

OpenSP 补丁

isSgmlChar

文件: include/Syntax.h

diff -r -u OpenSP-1.5.1/include/Syntax.h OpenSP-1.5.1-new/include/Syntax.h

--- OpenSP-1.5.1/include/Syntax.h 2005-12-18 10:38:50.890625000 +0800

+++ OpenSP-1.5.1-new/include/Syntax.h 2005-12-18 10:44:20.703125000 +0800

@@ -389,7 +389,7 @@

inline Boolean Syntax::isSgmlChar(Xchar c) const

{

- return c >= 0 && set_[sgmlChar].contains(Char(c));

+ return c >= 256 || c >= 0 && set_[sgmlChar].contains(Char(c));

}

inline const StringC &Syntax::reservedName(ReservedName i) const

允许中文注释

文件: lib/parseCommon.cxx

diff -r -u OpenSP-1.5.1/lib/parseCommon.cxx OpenSP-1.5.1-new/lib/parseCommon.cxx

--- OpenSP-1.5.1/lib/parseCommon.cxx 1999-11-04 16:36:13.000000000 +0800

+++ OpenSP-1.5.1-new/lib/parseCommon.cxx 2005-12-18 10:46:41.781250000 +0800

@@ -541,14 +541,12 @@

Token token;

while ((token = getToken(mode)) != tokenCom)

switch (token) {

- case tokenUnrecognized:

- if (!reportNonSgmlCharacter())

- message(ParserMessages::sdCommentSignificant,

- StringMessageArg(currentToken()));

- break;

case tokenEe:

message(ParserMessages::commentEntityEnd, startLoc);

return 0;

+ case tokenUnrecognized:

+ if (reportNonSgmlCharacter())

+ break;

default:

if (markup)

markup->addCommentChar(currentChar());

清除 INCLUDE, LIBS 等环境变量

编译 OpenSP

./configure --prefix=/usr/local/opensp

make && make install

echo /usr/local/lib/opensp/lib >> /etc/ld.so.conf

catalog

SGMLDECL "/home/JiangXin/work/docbook/dtd/4.5/docbook.dcl"

CATALOG "/home/JiangXin/work/docbook/dtd/4.5/docbook.cat"

DOCTYPE book /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE article /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE chapter /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

应用

准备

创建一个 catalog 文件

catalog 文件

OVERRIDE YES

SGMLDECL "/home/JiangXin/work/docbook/dtd/4.5/docbook.dcl"

CATALOG "/home/JiangXin/work/docbook/dtd/4.5/docbook.cat"

DOCTYPE book /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE article /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE chapter /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

示例

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

-- "export SGML_CATALOG_FILES=/PATH/catalog" --

OVERRIDE YES

SGMLDECL "/home/JiangXin/work/docbook/dtd/4.5/docbook.dcl"

CATALOG "/home/JiangXin/work/docbook/dtd/4.5/docbook.cat"

CATALOG "/home/JiangXin/work/docbook/style/dsssl-1.79/catalog"

-- CATALOG "dtd/openjade/catalog" --

-- CATALOG "/home/JiangXin/work/docbook/dtd/entities/catalog.sgml" --

DOCTYPE book /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE article /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

DOCTYPE chapter /home/JiangXin/work/docbook/dtd/4.5/docbook.dtd

docbook.dcl 补丁

- LCNMCHAR ".-_"

- UCNMCHAR ".-_"

+ LCNMCHAR ".-_:"

+ UCNMCHAR ".-_:"

否则：

onsgmls:/home/JiangXin/work/docbook/dtd/4.5/htmltblx.mod:102:9:E: character ":"

invalid: only "CDATA", "ENTITIES", "ENTITY", "ID", "IDREF", "IDREFS", "NAME", "N

AMES", "NMTOKEN", "NMTOKENS", "NOTATION", "NUMBER", "NUMBERS", "NUTOKEN", "NUTOK

ENS" and parameter separators allowed

onsgmls:/home/JiangXin/work/docbook/dtd/4.5/htmltblx.mod:110:9:E: character ":"

invalid: only "CDATA", "ENTITIES", "ENTITY", "ID", "IDREF", "IDREFS", "NAME", "N

AMES", "NMTOKEN", "NMTOKENS", "NOTATION", "NUMBER", "NUMBERS", "NUTOKEN", "NUTOK

ENS" and parameter separators allowed

主要是如下参数实体中出现了 :

<!ENTITY % xml-space.attrib

"xml:space (preserve) #IMPLIED">

<!ENTITY % xml-base.attrib

"xml:case CDATA #IMPLIED">

<!ENTITY % i18n

"xml:lang NMTOKEN #IMPLIED">

示例文档

gb2312.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

<article>

<articleinfo>

<title>Hello World!</title>

<author><firstname>名</><surname>姓</></author>

</articleinfo>



<sect1><title>Hello World!</title>

<para>

Hello world! 这是我的第一个 DocBook 文档。

</para>

</sect1>

</article>

utf8.sgml

编码问题

多个环境变量用于处理多字节以及宽字符编码的 SGML/XML，如下：

SP_CHARSET_FIXED

只有当 SP_CHARSET_FIXED 设置为 1 或者 YES 时，OpenSP进入固定字符集模式

SP_ENCODING

当处于固定字符集模式时，的缺省字符集

可以是: utf-8, utf-16, gb2312, big5, cn-gb, euc-cn, cn-big5, is8859-n, ...

xml 含义为作为输入时，由XML 定义确定其编码，作为输出时，为 UTF-

SP_BCTF

当不处于固定字符集模式时，的缺省字符集

可用的有: utf-8, euc, big5, identity, fixed-2, fixed-4, sjis

onsgmls

功能

验证有效性

SP 环境变量

export SP_CHARSET_FIXED=1

export SP_ENCODING=utf-8

onsgmls.exe -s -c catalog.sgml utf8.sgml

命令行参数

-s 关闭输出

export SGML_CATALOG_FILES=/share/catalog.sgml

onsgmls.exe -s index.sgml

-c catalog 文件

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 onsgmls.exe -s -c catalog.sgml gb2312.sgml

-i NAME

如同在文档的 DTD 最开始，声明了 <!ENTITY % name "INCLUDE">

ospam

整理 SGML 标记(markup)

命令行

ospam.exe -p -m shorttag -c catalog.sgml index.sgml

osgmlnorm

格式化 sgml 文档

--comments 输出注释

-d 输出 prolog

示例

SP_ENCODING=utf-8 SP_CHARSET_FIXED=yes osgmlnorm -c catalog.sgml utf8.sgml 2>/dev/null | iconv -f utf-8 -t gb2312

SP_ENCODING= SP_CHARSET_FIXED= osgmlnorm --comments -c catalog.sgml gb2312.sgml

Bug

--comments 对于 UTF-8 编码的文件，当 SP_ENCODING＝utf-8 时无效

需要安装“中文注释”补丁

osx

SGML->XML转换工具

示例

SP_ENCODING=gb2312 SP_CHARSET_FIXED=YES osx -x preserve-case -x comment \

-c catalog.sgml gb2312.sgml | iconv -f utf-8 -t gb2312

SP_ENCODING=utf-8 SP_CHARSET_FIXED=YES osx -x preserve-case -x comment \

-c catalog.sgml utf8.sgml | iconv -f utf-8 -t gb2312

ospent

ospcat

XML 文件的验证

SP_ENCODING=gb2312 SP_CHARSET_FIXED=yes onsgmls.exe -s -c catalog.sgml gb2312.xml

OpenJade

编译 OpenJade 之前

参见 Cygwin OpenJade 源代码包中的补丁

OpenSP 的补丁参见：

清除 INCLUDE, LIBS 等环境变量

编译 OpenJade

./configure --prefix=/usr/local/openjade \

--enable-spincludedir=/usr/local/opensp/include/OpenSP \

--enable-splibdir=/usr/local/opensp/lib

make && make install

# 将 dsssl 目录(dsssl的 DTD 声明）拷贝到适当的目录下

# 并将 dsssl 目录下的 catalog 文件加入到 SGML_CATALOG_FILES

# 环境变量，或者加入到 CATALOG 文件中；

cp -R dsssl /docbook-dtd-dsssl-directory/openjade

echo /usr/local/lib/openjade/lib >> /etc/ld.so.conf

测试（参见 dsssl-doc 的例子）

测试文件

jtest.sgm (in dsssl-1.79-doc/doc)

jtest.dsl (in dsssl-1.79-doc/doc)

测试 openjade：

openjade -t rtf -d jtest.dsl jtest.sgm

可能出现的错误

openjade:jtest.dsl:1:72:W: cannot generate system identifier for public text "-//James Clark//DTD DSSSL Style Sheet//EN"

openjade:jtest.dsl:1:72:E: reference to entity "STYLE-SHEET" for which no system identifier could be generated

openjade:jtest.dsl:1:0: entity was defined here

openjade:E: specification document does not have the DSSSL architecture as a base architecture

原因是没有找到 Public 标志符 "-//James Clark//DTD DSSSL Style Sheet//EN" 的位置，

需要通过 catalog 文件建立 Public 标志符到 system 标志符的映射，

该 catalog 文件名，可以通过环境变量 SGML_CATALOG_FILES 指出，

或者通过 openjade 命令行的 -c 参数指明。

设置环境变量 SGML_CATALOG_FILES

export SGML_CATALOG_FILES=openjade/dsssl/catalog

openjade -t rtf -d jtest.dsl jtest.sgm

或者通过 -c 参数

openjade -c openjade/dsssl/catalog -t rtf -d jtest.dsl jtest.sgm

测试 DocBook DTD&DSSSL

设置环境变量 SGML_CATALOG_FILES

export SGML_CATALOG_FILES=dtd/catalog:dsssl/catalog:openjade/catalog

openjade -t rtf -d d:\where-you-unpacked-the-stylesheets\docbook\print\docbook.dsl test.sgm

openjade -t sgml -d d:\where-you-unpacked-the-stylesheets\docbook\html\docbook.dsl test.sgm

中文文档测试

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -t sgml -d d:\where-you-unpacked-the-stylesheets\docbook\html\docbook.dsl \

-V nochunks gb2312.sgml

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -t rtf -d d:\where-you-unpacked-the-stylesheets\docbook\print\docbook.dsl \

gb2312.sgml

catalog

语法参见前面的介绍

DSSSL

CATALOG "/home/JiangXin/work/docbook/style/dsssl-1.79/catalog"

DTD for DSSSL

CATALOG "~/work/docbook/bin/openjade-1.3.3-pre1/dsssl/catalog"

如何指定 DSSSL 样式表

通过 prolog 或者 DTD 中的 PI 声明位置。（两种格式）

格式1: <?stylesheet href="sysid" type="text/dsssl">

格式2: <?dsssl sysid>

openjade -d systemid

DSSSL systemid，声明 DSSSL 位置

和输入文件同名的，扩展名为 .dsl

一个DSSSL样式表文件可能包含

多个样式，如何指定？

两种方式定义的多样式DSSSL文件

仅通过参数进行实体控制，

只包含一个 style-specification

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [

<!ENTITY % html "IGNORE">

<![%html;[

<!ENTITY % print "IGNORE">

<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>

]]>

<!ENTITY % print "INCLUDE">

<![%print;[

<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>

]]>

]>

<style-sheet>

<style-specification use="docbook">

<style-specification-body>

;; common customization can go here

<![%print;[

;; customize the print stylesheet here

]]>

<![%html;[

;; customize the html stylesheet here

]]>

</style-specification-body>

</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>

不同的 style-specification 具有不同的 ID，

另外还有参数实体控制

<!DOCTYPE style-sheet PUBLIC

"-//James Clark//DTD DSSSL Style Sheet//EN" [

<!ENTITY % html "IGNORE">

<![%html;[

<!ENTITY % print "IGNORE">

<!ENTITY docbook.dsl PUBLIC

"-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"

CDATA dsssl>

]]>

<!ENTITY % print "INCLUDE">

<![%print;[

<!ENTITY docbook.dsl PUBLIC

"-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"

CDATA dsssl>

]]>

]>

<style-sheet>

<style-specification id="print" use="docbook">

<style-specification-body>

;; customize the print stylesheet

...

</style-specification-body>

</style-specification>



<style-specification id="html" use="docbook">

<style-specification-body>

... ...

</style-specification-body>

</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>

-d 参数或者 PI 中设置的 systemid，在文件名的结尾用 #id

可以指定 DSSSL 文件中特定的 style-specification.

openjade -d systemid#print

-i 参数，设定特定的实体参数为 INCLUDE

openjade -i html -d systemid#html

DSSSL 定制

DSSSL 是一个遵从 DSSSL 规范的 SGML 文档

default schema

/usr/local/openjade/share/openjade/builtins.dsl

一个包含了打印和HTML两种格式的样式表

www.tldp.org 对 dsssl 的定制

ldp.dsl，参见: http://www.tldp.org/authors/

定制

修改作者名称显示方式，姓在前

为 HTML 输出增加编码设置，两个参数实体： charset.gb2312, charset.utf-8

其它参见 ldp.dsl 的 differ

命令行参数

-d dsssl_spec

-c catalog_file

-t output_type

支持的输出格式有:

fot

flow object tree

rtf, rtf-95

rtf-95 produces output optimized for Word 95 rather than Word 97

tex

sgml, sgml-raw

sgml-raw 不在 tag 中插入换行符

xml, xml-raw

xml-raw 不在 tag 中插入换行符

html

mif

-o output_file

-i Entity_Name

相当于在 DSSSL 样式表中定义实体 Entity_Name 为 INCLUDE

<!ENTITY % Entity_Name "INCLUDE">

-V variable

相当于在 DSSSL 样式表中定义 (define variable #t)

-V variable=value

相当于在 DSSSL 样式表中定义 (define variable "value")

-V (define variable value)

相当于在 DSSSL 样式表中定义 (define variable value)

-wtype

定义错误类型

环境变量

SP_CHARSET_FIXED 和 SP_SYSTEM_CHARSET 被忽略

如同 SP_CHARSET_FIXED 设置为 1 以及 SP_SYSTEM_CHARSET 未设置

SP_ENCODING

控制输入文件的字符集

SGML_CATALOG_FILES

在该环境变量设置的列表中寻找 catalog 文件；

格式转换

（命令行示例）

sgml -> single html

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl \

-V nochunks -t sgml gb2312.sgml

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#html \

-i html -i charset.gb2312 -V nochunks -t sgml gb2312.sgml >gb2312.html

sgml -> multiple htmls

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl \

-t sgml gb2312.sgml

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#html \

-i html -i charset.gb2312 -t sgml gb2312.sgml >gb2312-ldp.html

sgml -> rtf

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#print \

-i print -i charset.gb2312 -t rtf gb2312.sgml

sgml -> pdf

JadeTeX, sourceforge, 2003/05/17, v3.13

sgml -> tex

tex -> DVI/PS/PDF

JadeTeX

sgml -> fot

XML

需要在命令行中定义 XML 的 declare 文件，

也可以在 catalog 中用 DTDDECL 指定

DTDDECL "-//OASIS//DTD DocBook XML V4.5CR1//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

DTDDECL "-//OASIS//DTD DocBook XML V4.2//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

DTDDECL "-//OASIS//DTD DocBook XML V3.1//EN" "dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl"

xml -> single html

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl \

-V nochunks -t sgml \

${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#html \

-i html -i charset.gb2312 -V nochunks -t sgml \

${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml >gb2312-xml.html

xml -> multiple htmls

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl \

-t sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#html \

-i html -i charset.gb2312 -t sgml \

${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

xml -> rtf

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 \

openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl#print \

-i print -i charset.gb2312 -t rtf \

${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

测试用例

test.sh

#!/bin/sh

SRCROOT=../../src

# onsgml test...

echo -ne "validate gb2312.sgml, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml gb2312.sgml

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "validate utf8.sgml, ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml utf8.sgml

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "validate gb2312.xml, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "validate utf8.xml, ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl utf8.xml

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "gb2312.sgml is NOT valid IF VALIDATED AS XML, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.sgml 2>/dev/null

[ $? -ne 0 ] && echo "pass" || echo "failed"

# osx test...

echo -ne "osx convert test, gb2312.sgml->gb2312.xml, ... "

tmpfile=`mktemp tmp-gb-xml.XXXXX`

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 osx -x preserve-case -x comment -c ${SRCROOT}/catalog.sgml gb2312.sgml | iconv -f utf-8 -t gb2312 > $tmpfile

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 onsgmls -s -c ${SRCROOT}/catalog.sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl $tmpfile

[ -f $tmpfile ] && rm $tmpfile

echo "pass"

# openjade test...

echo -ne "convert gb2312.sgml to multiple htmls, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl -t sgml gb2312.sgml

#rm t1.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert gb2312.sgml to one big html, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl -V nochunks -t sgml gb2312.sgml > gb2312-sgml.htm

#rm index.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert gb2312.sgml to rtf, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/print/docbook.dsl -t rtf gb2312.sgml

#rm gb2312.rtf

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.sgml to multiple htmls (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#html -i html -i charset.utf8 -t sgml utf8.sgml

#rm t1.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.sgml to one big html (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#html -i html -i charset.utf8 -V nochunks -t sgml utf8.sgml > utf8-sgml.htm

#rm index.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.sgml to rtf (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#print -i print -t rtf utf8.sgml

#rm gb2312.rtf

[ $? -eq 0 ] && echo "pass" || echo "failed"

# openjade XML test...

echo -ne "convert gb2312.xml to multiple htmls, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl -t sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

#rm t1.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert gb2312.xml to one big html, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/html/docbook.dsl -V nochunks -t sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml > gb2312-sgml.htm

#rm index.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert gb2312.xml to rtf, ... "

SP_ENCODING=gb2312 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/docbook-dsssl-1.79/print/docbook.dsl -t rtf ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl gb2312.xml

#rm gb2312.rtf

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.xml to multiple htmls (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#html -i html -i charset.utf8 -t sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl utf8.xml

#rm t1.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.xml to one big html (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#html -i html -i charset.utf8 -V nochunks -t sgml ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl utf8.xml > utf8-sgml.htm

#rm index.htm

[ $? -eq 0 ] && echo "pass" || echo "failed"

echo -ne "convert utf8.xml to rtf (ldap.dsl), ... "

SP_ENCODING=utf-8 SP_CHARSET_FIXED=1 openjade -c ${SRCROOT}/catalog.sgml -d ${SRCROOT}/dsssl/ldp.dsl\#print -i print -t rtf ${SRCROOT}/dsssl/docbook-dsssl-1.79/dtds/decls/xml.dcl utf8.xml

#rm gb2312.rtf

[ $? -eq 0 ] && echo "pass" || echo "failed"

xslproc

XML 时代的 DocBook

为什么使用 XML 格式的 DocBook？

xml LIB 和工具发展迅速

很多著名的编辑软件支持 XML 格式的输出，即使不是 DocBook 格式输出，也很容易和 XML 格式的 DocBook 进行转换

很多人都在用

OpenJade 也可用于 XML 格式的文件

XML 是 SGML 的子集

但使用的样式表不是XSL，而是 DSSSL

具体参见上节 OpenSP & OpenJade 的描述

XSL

与 DSSSL 相比的优势

通过参数进行定制

HTML 参数参考，参见 xsl 文档：doc/html

FO 参数参考，参见 xsl 文档：doc/fo

如何在命令行提供参数

xsltproc

xsltproc --output myfile.html \

--stringparam html.stylesheet "corpstyle.css" \

--stringparam admon.graphics 1 \

docbook.xsl myfile.xml

saxon

java com.icl.saxon.StyleSheet -o myfile.html myfile.xml docbook.xsl \

html.stylesheet="corpstyle.css" \

admon.graphics=1

Xalan

java org.apache.xalan.xslt.Process -out myfile.html -in myfile.xml \

-xsl docbook.xsl \

-param html.stylesheet "corpstyle.css" \

-param admon.graphics 1

只对源文件的一部分进行处理

前提

要处理的部分是一个整个的元素

该元素具有一个 id 属性值

例如

命令行

xsltproc \

--stringparam rootid "using" \

--output chap2.html \

html/docbook.xsl myfile.xml

HTML 输出的参数控制

分页

无分页 HTML

使用 docbook.xsl 样式表

xsltproc --output myfile.html docbook.xsl myfile.xml

xsltproc docbook.xsl myfile.xsl > myfile.html

分页 HTML

使用 html/chunk.xsl 样式表

xsltproc /usr/share/docbook-xsl/html/chunk.xsl myfile.xml

首页为 index.html

每一个部分的文件名根据 id 属性值设定，

或者由一个算法自动命名

use.id.as.filename

分页名称根据 id 属性确定

html.ext

设置扩展名

root.filename

设置首页的文件名

<xsl:param name="root.filename"></xsl:param>

首页文件名也根据 ID 属性确认

<xsl:param name="root.filename">root</xsl:param>

首页文件名为 root.html

不设置

则首页文件名为 index.html

base.dir 参数，如:

xsltproc -stringparam base.dir /usr/apache/htdocs/ chunk.xsl myfile.xml

<?dbhtml filename="intro.html" ?>

设置文件名，等同于在 element 设置 id 属性

<?dbhtml dir="UserGuide" ?>

紧接着根元素，定义了根元素以及子元素输出为 HTML 的目录；

例如:

<book><?dbhtml dir="UserGuide" ?>

<title>User Guide</title>

...

<chapter id="intro"><?dbhtml dir="FrontMatter" ?>

...

<chapter id="installing">

...

<appendix id="reference"><?dbhtml dir="BackMatter" ?>

生成的分页 HTML 如下:

UserGuide/index.html

UserGuide/FrontMatter/intro.html

UserGuide/installing.html

UserGuide/BackMatter/reference.html

加快文件输出速度

设置 chunk.fast 参数为非零值。xsltproc, saxon, xalan 都支持 EXSLT，MSXML 则不支持

目录的分页格式

参数 chunk.tocs.and.lots = 1

为文章目录创建单独一页

chunk.separate.lots = 1

分页级别

chunk.section.depth ，默认是1，如果设置为2，则 sect2 也分页

chunk.first.sections ，默认第一节和之前的内容在一页；

手动设置分页

使用chunktoc.xsl 样式表

输出文件缩进

chunker.output.indent=no/yes

<xsl:param name="chunker.output.indent">yes</xsl:param>

参数 chunk.quietly 设置为 1，则产生 html 文件过程不频繁显示消息

单一分页HTML

onechunk.xsl 样式表

和无分页的 docbook.xsl 相比，由于使用了为分页功能提供的 XSLT 扩展功能，可以提供如下参数。

参数

id 属性指定输出文件名。因此可以不必指定输出文件名，只需在 root 元素增加 id 属性

base.dir 参数可以设定输出文件的目录，因为 id 属性值不能包含 / 字符；

设置输出文件的编码，可以通过参数 chunker.output.encoding 实现

chunker.output.doctype-public 和 chunker.output.doctype-system 参数，则可以设定输出文件的 DOCTYPE

字符集编码

html/docbook.xsl 默认输出是 ISO8859-1，文件中的中文等非 ISO8859-1 字符，编码为 $#xxxx

对于分页的 HTML ，可以使用

chunker.output.encoding 参数

onechunk.xsl 样式表和 chunk.xsl 样式表，可以使用该参数定制输出文件编码

docbook.xsl 则不能采用这种方式

如：

xsltproc --stringparam chunker.output.encoding utf-8 \

/docbook/src/xsl/docbook-xsl-1.69.1/html/onechunk.xsl gb2312.xml

该功能可以用于 xsltproc, Saxon等支持 EXSLT 引擎，不能用于 Xalan?

docbook.xsl 需要定制样式表

来实现对输出编码的控制

由于没有设置参数来修改输出编码，只能通过建立一个文件层来定义

示例

<?xml version='1.0'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

version="1.0">

<xsl:import href="/path/to/html/docbook.xsl"/>

<xsl:output method="html"

encoding="UTF-8"

indent="no"/>

</xsl:stylesheet>

HTML 文件头： <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">

中文字符编码：

saxon.character.representation

CSS 嵌入 HTML

参数 html.stylesheet

示例

xsltproc --stringparam html.stylesheet corpstyle.css chunk.xsl myfile.xml

生成的 HTML Header 包含

定制 CSS

h2 即是 chapter，也是 sect1 的标题样式，因为h1保留给 book 的标题

div.chapter div.titlepage h2 {

font-size: 180%;

font-family: Helvetica;

font-weight: Bold;

color: #444444

}

为 programlisting 加背景色

pre.programlisting {

background-color: #FFFF99 ;

border: 1px solid #006600 ;

}

用户自定义样式

为 para 增加样式

定义 para.propagates.style 参数为非零值

在 DocBook XML 中为 para 增加 role 属性

DocBook XML:

<para role="primary">This feature of the product ...</para>

转换出来的 HTML 为段落增加样式

HTML output:

<p class="primary">This feature of the product ...</p>

emphasis

emphasis.propagates.style

例如：

DocBook XML:

Using an SQL <emphasis role="sqlsyntax">select</emphasis> statement

HTML output:

Using an SQL <span class="sqlsyntax">select</span> statement

CSS stylesheet entry:

.sqlsyntax {font-variant: small-caps;}

entry

entry.propagates.style

phrase

phrase.propagates.style parameters

章节编号

chapter.autolabel = 1|0

appendix.autolabel =1|0

section.autolabel =0|1

section.label.includes.component.label = 0|1

section.autolabel.max.depth = 8

图标控制

何处出现图标？

admonitions (note, tip, warning, caution, and important).

Next, Previous, Up, and Home for navigating among chunked output

Numbered icons for callouts.

admon 图标参数控制

admon.graphics = 0|1

是否显示图标

admon.graphics.path = images/

admon.graphics.extension = .png

Navigational icons

navig.graphics = 0|1

如: xsltproc -stringparam navig.graphics 1 chunk.xsl myfile.xml

Callout icons

callout.graphics.number.limit = 15

超过则显示文字，如 (16)

callout.graphics.path = images/callouts

callout.graphics.extension = png

时间和日期

可以插入 PI，输出文档的相应部位显示为编译时的时间

<?dbtimestamp format="Y-m-d H:M:S"?>

可打印版本输出的参数控制

与上节 HTML 参数控制基本相同的

图标

章节编号

输出特定章节

rootid 指定要打印的特定章节名称

generate.toc 为打印的部分章节添加编号

命令

xsltproc --output myfile.fo \

--stringparam rootid mychapterid \

--stringparam generate.toc "chapter title,toc" \

fo/docbook.xsl myfile.xml

页面控制

paper.type 纸张大小

paper.type

xsltproc --output myfile.fo \

--stringparam paper.type A4 \

fo/docbook.xsl myfile.xml

自定义纸张大小

page.width 与 page.height 参数

xsltproc --output myfile.fo \

--stringparam page.height 9in \

--stringparam page.width 7in \

fo/docbook.xsl myfile.xml

margin

page.margin.inner

page.margin.outer

排版控制

例如

xsltproc --output myfile.fo \

--stringparam body.font.family Helvetica \

--stringparam body.font.master 11 \

--stringparam title.font.family "Times Roman" \

--stringparam footnote.font.size 9 \

fo/docbook.xsl myfile.xml

分页符

防止不当的分页

XSL 的 keep-together 属性

例如 table 元素存在该属性，避免表格当中分页

XSL 的 keep-with-next 属性

例如章节标题通过该属性避免被孤立限制在一页的末尾

插入 PI 控制该属性

允许 table 中分页

<table>

<title>My long table</title>

<?dbfo keep-together="auto" ?>

...

样式表支持软分页符

软分页符又称为条件分页符，如果不符合特定条件，不插入分页符。

（例如：我需要在当前页为下述内容留出至少 2 英寸宽，否则插入分页符）

dbfo-need 示例

<para>Some text in a paragraph</para>

<?dbfo-need height="2in" ?>

<para>The following code snippet illustrates

the technique.</para>

<programlisting># Some sample code

</programlisting>

不支持插入硬分页符，

但用户可以定制 XSL

因为硬分页符难以管理，因而默认样式表不支持

但可以定制样式表，如下

样式表定制

<xsl:template match="processing-instruction('hard-pagebreak')">

<fo:block break-before='page'/>

</xsl:template>

在分页处增加 PI：<?hard-pagebreak?>

<para>Some text in a paragraph</para>

<?hard-pagebreak?>

<para>The following code snippet illustrates

the technique.</para>

<programlisting># Some sample code

</programlisting>

PDF 书签

PDF 支持在页面的一侧显示目录结构，此即书签

通过设置 fop.extensions 参数实现

xsltproc --output myfile.fo \

--stringparam fop.extensions 1 \

fo/docbook.xsl myfile.xml

添加空行

使用 literallayout 元素

在 literallayout 元素中的回车将予以保留

样式表定制层

Customization layers

何为定制层

建立一个新的 XSL 样式表，使得在不修改 DocBook 样式表前提下，对齐进行定制

便于升级

便于分发

定制层可以实现

设置参数

可以将常用的参数放在定制层里面，避免了在命令行中定义参数的烦琐

布尔值

示例: <xsl:param name="admon.graphics" select="1"/>

1 是布尔值，因此双引号即可

字符串

<xsl:param name="parametername" select="'parametervalue'"/>

双引号中的单引号，声明内容是字符串

如果忽略内部的字符串，会造成参数不起作用

或者：<xsl:param name="parametername">parametervalue</xsl:param>

属性集合定制

何为属性集合

XSL 样式表通过 xsl:attribute-set 将若干个 xsl:attribute 组织在一起为一个集合

如

<xsl:attribute-set name="section.title.properties">

<xsl:attribute name="font-family">

<xsl:value-of select="$title.font.family"/>

</xsl:attribute>

<xsl:attribute name="font-weight">bold</xsl:attribute>



<xsl:attribute name="keep-with-next.within-column">always</xsl:attribute>

<xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>

<xsl:attribute name="space-before.optimum">1.0em</xsl:attribute>

<xsl:attribute name="space-before.maximum">1.2em</xsl:attribute>

</xsl:attribute-set>

XSL 中如何引用属性集合

fo:block 的开始 tag，将属性值引入其中

如

<xsl:template name="section.heading">

<xsl:param name="level" select="1"/>

<xsl:param name="title"/>

<fo:block xsl:use-attribute-sets="section.title.properties">

...

</fo:block>

</xsl:template>

定制层中对属性集合的定制

定制层中定义的属性集合和原样式表中的定义向合并

例如定制层中定义

<xsl:attribute-set name="section.title.properties">

<xsl:attribute name="font-weight">normal</xsl:attribute>

<xsl:attribute name="text-align">left</xsl:attribute>

</xsl:attribute-set>

充实占位模板

占位模板是在 XSL 样式表定义中，预留的空的占位模板，

因为本身为空，因而对输出没有任何作用，仅为定制提供一个空间

定制层可以对占位模板重新定义，充实其内容

分页样式模板中存在一个占位模板 user.header.content ，

如果为该模板定义了内容，则每个分页内容的头部都会增加

内容。

其它占位模板，如:

user.preroot

user.head.content

添加 CSS 等

<xsl:param name="target.window" select="'_self'"/>

<xsl:template name="user.head.content">

<xsl:comment> (c) 2002 Copyright Megacorp, Inc. </xsl:comment>

<base target="{$target.window}"/>

<style type="text/css">

<xsl:comment>

@import "stylesheets/override.css"

body {background: url(graphics/bluesea.png);}

</xsl:comment>

</style>

</xsl:template>

添加时间信息的 meta

<xsl:template name="user.head.content">

<meta name="date">

<xsl:attribute name="content">

<xsl:call-template name="datetime.format">

<xsl:with-param name="date" select="date:date-time()"/>

<xsl:with-param name="format" select="'m/d/Y'"/>

</xsl:call-template>

</xsl:attribute>

</meta>

</xsl:template>

user.header.navigation

<xsl:template name="user.header.content">

<p><b>Hi Mom!</b></p>

</xsl:template>

user.header.content

SSI

（注意 xsl:comment 的运用）

<xsl:template name="user.header.content">

<div>



<xsl:comment>#include virtual="/cgi-bin/counter.pl"</xsl:comment>

</div>

</xsl:template>

JSP inclusion

（注意: xsl:text 的 disable-xxx 属性）

<xsl:template name="user.header.content">

<div>



<xsl:text disable-output-escaping="yes">

<%@ include file="/header.html" %>

</xsl:text>

</div>

</xsl:template>

user.footer.content

<xsl:template name="user.footer.content">

<HR/><P class="copyright">© 2002 Megacorp, Inc.</P>

</xsl:template>

user.footer.navigation

<xsl:include href="user.footer.navigation.xsl"/>

参见 OSX XSL 定制

创建新模板

定制文字

本地化设置

元素的 lang 属性

本地化设置

l10n.gentext.default.language

例如 <xsl:param name="l10n.gentext.default.language">zh_cn</xsl:param>

l10n.gentext.language

<xsl:param name="l10n.gentext.language">zh_cn</xsl:param>

设置语种，覆盖元素的 lang 设置

生成的文字（Generated text）是 XSL 样式表输出时添加的文字，这些文字存在本地化的问题

参见 common/en.xml

一种是 l:gentext 将打印字符(text) 对应于相应的元素(key)

如: common/en.xml 中

<l:gentext key="Abstract" text="Abstract"/>

common/zh_cn.xml 中

<l:gentext key="Abstract" text="摘要"/>

另外一种是上下文相关的文字定制，由 l:context 元素定义

如:

<l:context name="styles">

<l:template name="person-name" text="first-last"/>

</l:context>

<l:context name="title">

<l:template name="abstract" text="%t"/>

<l:template name="answer" text="%t"/>

<l:template name="appendix" text="Appendix %n. %t"/>

在定制层中定制

<xsl:param name="local.l10n.xml" select="document('')"/>

<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">

<l:l10n language="en">

<l:context name="xref-number-and-title">

<l:template name="chapter" text="Chapter %n: “%t”"/>

</l:context>

</l:l10n>

</l:i18n>

替换样式模板

最后一招，替换模板。自定义模板的优先级比缺省模板的优先级高

例如: 替换 body.attributes 模板，

为 body 增加属性定义

<xsl:template name="body.attributes">

<xsl:attribute name="onLoad">alert('Thanks for visiting')</xsl:attribute>

<xsl:attribute name="bgcolor">white</xsl:attribute>

<xsl:attribute name="text">black</xsl:attribute>

<xsl:attribute name="link">#0000FF</xsl:attribute>

<xsl:attribute name="vlink">#840084</xsl:attribute>

<xsl:attribute name="alink">#0000FF</xsl:attribute>

</xsl:template>

例如：

将模板

<xsl:template match="command">

<xsl:call-template name="inline.boldseq"/>

</xsl:template>

替换为

<xsl:template match="command">

<xsl:call-template name="inline.monoseq"/>

</xsl:template>

本地化设置

定制中文姓名显示方式

设置中文 person-name 显示方式为 family-given

<xsl:param name="local.l10n.xml" select="document('')"/>

<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">

<l:l10n language="zh_cn">

<l:context name="styles">

<l:template name="person-name" text="family-given"/>

</l:context>

</l:l10n>

</l:i18n>

定制 family-given 模板

<xsl:template name="person.name.family-given">

<xsl:param name="node" select="."/>

<xsl:if test="$node//surname">

<xsl:apply-templates select="$node//surname[1]"/>

</xsl:if>

<xsl:if test="$node//othername and $author.othername.in.middle != 0">

<xsl:if test="$node//surname">

<xsl:text> </xsl:text>

</xsl:if>

<xsl:apply-templates select="$node//othername[1]"/>

</xsl:if>

<xsl:if test="$node//firstname">

<xsl:if test="$node//surname

or ($node//othername and $author.othername.in.middle != 0)">

<xsl:text> </xsl:text>

</xsl:if>

<xsl:apply-templates select="$node//firstname[1]"/>

</xsl:if>

<xsl:if test="$node//lineage">

<xsl:text>, </xsl:text>

<xsl:apply-templates select="$node//lineage[1]"/>

</xsl:if>

<xsl:if test="$node//honorific">

<xsl:text> </xsl:text>

<xsl:apply-templates select="$node//honorific[1]"/>

<xsl:value-of select="$punct.honorific"/>

</xsl:if>

</xsl:template>

自定义 PI

示例

定制 html/docbook.xsl

<?xml version='1.0'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:import href="html/docbook.xsl"/>

<xsl:param name="html.stylesheet" select="'corpstyle.css'"/>

<xsl:param name="admon.graphics" select="1"/>

</xsl:stylesheet>

定制 html/chunk.xsl

替换 <xsl:import href="html/docbook.xsl"/> 为 <xsl:import href="html/chunk.xsl"/>

定制 fo

因为用到 fo:inline 元素，因此需要定义 fo 名字空间

示例

<?xml version='1.0'?>

<xsl:stylesheet

xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:fo="http://www.w3.org/1999/XSL/Format"

version="1.0">

<xsl:import href="fo/docbook.xsl"/>

<xsl:template match="lineannotation">

<fo:inline font-style="italic">

<xsl:call-template name="inline.charseq"/>

</fo:inline>

</xsl:template>

</xsl:stylesheet>

为何不能将多个定制层合并为一个文件？

因为 xsl:import 不能包含在条件语句（xsl:if 或 xsl:choose）之中

但是可以将共性的内容放在同一个文件，用 xsl:import 语句包含到不同的定制层

使用定制层

<html>xsltproc --output myfile.html <b>mystyles.xsl</b> myfile.xml

htmlhelp 输出定制

命令行

xsltproc \

../docbook-xsl/htmlhelp/htmlhelp.xsl \

myhelpdoc.xml

Window 参数

htmlhelp.title

窗口标题

htmlhelp.window.geometry

窗口大小和位置

例如 [160,64,992,704] 含义为左上角坐标和右下角坐标

htmlhelp.remember.window.position

记住上次位置

htmlhelp.show.menu

是否显示菜单

htmlhelp.show.favorites

htmlhelp.show.advanced.search

按钮选项

按钮显示选项

htmlhelp.show.toolbar.text 是否显示按钮文字

htmlhelp.button.hideshow

htmlhelp.button.back

htmlhelp.button.forward

htmlhelp.button.stop

htmlhelp.button.refresh

htmlhelp.button.home

htmlhelp.button.options

htmlhelp.button.print

htmlhelp.button.locate

htmlhelp.button.next

htmlhelp.button.previous

htmlhelp.button.zoom

自定义按钮

htmlhelp.button.jump1

是否显示自定义按钮1

htmlhelp.button.jump1.title

自定义按钮1的标题

htmlhelp.button.jump1.url

按钮1的 URL

目录选项

htmlhelp.hhc.show.root

htmlhelp.hhc.width

htmlhelp.autolabel

htmlhelp.hhc.section.depth=5

htmlhelp.default.topic

设置起始页，默认是 index.htm

文件名选项

htmlhelp.hhp

工程文件文件名

htmlhelp.hhc

htmlhelp.hhk

htmlhelp.chm

base.dir

HTML 存储目录，也可以不是目录而作为文件名前缀

manifest.in.base.dir

工程文件是否和 HTML 文件一起保存在 base.dir 中？

字符编码选项

HTML Help language

<l:context name="htmlhelp">

<l:template name="langcode" text="0x0409 English (UNITED STATES)"/>

</l:context>

htmlhelp.encoding

html 字符集编码

其它参数

htmlhelp.enumerate.images

将图像枚举在 hhp 工程文件中

htmlhelp.use.hhk

是否支持 index，DocBook 中 indexterm 创建 index

htmlhelp.hhc.folders.instead.books

htmlhelp.hhc.binary

PATCH

osx.html.prefix=hh-

为分页HTML 添加前缀，目的是使 htmlhelp 临时文件名不会搞乱正常的 HTML 输出

htmlhelp.extra.files

定义其它需要添加到 htmlhelp 工程文件中的文件列表

调试 XSL

用 <xsl:message> 打印调试信息

回车符: 


如

<xsl:message>In lists.xsl (match="itemizedlist"), the value of the

css.decoration parameter is <xsl:value-of select="$css.decoration"/>

</xsl:message>

常用的诊断变量

当前元素名称: <xsl:value-of select="local-name(.)"/>

当前元素内容: <xsl:value-of select="."/>

当前元素的某个属性: <xsl:value-of select="@some-atrribute"/>

信息输出格式化

回车: 


格式化文本: <xsl:text>...</xsl:text>

其它输出格式

rtf

FOP 暂时不能从 fo 输出到 rtf

但是可以用 xslt 直接输出 rtf

xslutil -out rtf output.rtf input.xml /usr/share/xml/docbook/fo/docbook.xsl

pdf

Catalog

语法参见前面的介绍

Catalog 文件在哪？

xsltproc

环境变量 XML_CATALOG_FILES

多个 catalog 用空格分隔，绝对路径采用 URI 格式，如 file:///

例如： export XML_CATALOG_FILES="catalog.xml file:///usr/share/xml/catalog.xml"

环境变量 XML_DEBUG_CATALOG 可以用于调试 xsltproc

例如命令:

XML_CATALOG_FILES="catalog.xml file:///usr/share/xml/catalog.xml" \

XML_DEBUG_CATALOG=1 \

xsltproc docbook.xsl myfile.xml

Saxon

下载 resolver.jar

http://xml.apache.org/commons/dist/

将 resolver.jar 加入 CLASSPATH

创建文件 CatalogManager.properties

示例

catalogs=catalog.xml;../../dtd/docbook44/docbook.cat

relative-catalogs=false

static-catalog=yes

catalog-class-name=org.apache.xml.resolver.Resolver

verbosity=1

catalogs=xxx;xxx －以分号分隔的catalog文件

relative-catalogs=bool －定义 catalog 文件相对路径以何为准

false: 相对 CatalogManager.properties 所在目录；

true: 相对文档所在的路径；

verbosity 设置调试等级，越高（最高4) 调试信息越多；

将包含 CatalogManager.properties 的目录加入 CLASSPATH

命令行示例

java -cp "/usr/java/saxon.jar:/docbook-xsl/extensions/saxon653.jar:\

/usr/share/resolver.jar;/usr/share" \

com.icl.saxon.StyleSheet \

-x org.apache.xml.resolver.tools.ResolvingXMLReader \

-y org.apache.xml.resolver.tools.ResolvingXMLReader \

-r org.apache.xml.resolver.tools.CatalogResolver \

-u \

-o myfile.html \

myfile.xml docbook.xsl

说明

-cp 参数临时将jar 文件加入到 CLASSPATH 中

-u 参数，则命令行提供的文件名不作为物理路径，而是视为 URI，可以用 catalog 中设置对应为物理路径

-x, -y, and -r 参数配置 Saxon 使用 resolver 代码

Xalan

过程和 Saxon 类似

命令行为

java -cp "/usr/java/xerces.jar:/usr/java/xalan.jar:\

/docbook-xsl/extensions/xalan25.jar:\

/usr/share/resolver.jar:/usr/share" \

org.apache.xalan.xslt.Process \

-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver \

-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver \

-out myfile.html \

-in myfile.xml \

-xsl http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl

示例

<?xml version="1.0"?>

<!DOCTYPE catalog

PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"

"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">



<group xml:base="file:///usr/share/xml/" >



<rewriteSystem

systemIdStartString="http://www.oasis-open.org/docbook/xml/4.4/"

rewritePrefix="docbook44/" />



<rewriteURI

uriStartString="http://docbook.sourceforge.net/release/xsl/current/"

rewritePrefix="docbook-xsl-1.68.1/" />



<nextCatalog catalog="docbook44/catalog.xml" />







<system

systemId="docbook.dtd"

uri="docbook44/docbookx.dtd" />



<uri

name="docbook.xsl"

uri="docbook-xsl-1.68.1/html/docbook.xsl" />

<uri

name="chunk.xsl"

uri="docbook-xsl-1.68.1/html/chunk.xsl" />

<uri

name="fo-docbook.xsl"

uri="docbook-xsl-1.68.1/fo/docbook.xsl" />

</group>

</catalog>

验证文档有效性

XSL 处理器在格式转换中，并不验证文档有效性，这将会导致好形，但不有效的 XML 文档，将导致转换后的文档格式异常。

xsltproc 的 xmllint

XML_CATALOG_FILES=/share/catalog.xml xmllint --valid --nonet --noout gb2312.xml

Xalan

xalansamples.jar

java Validate document.xml

XInclude

SGML 可以使用外部实体，来包含文件

XML 则通过 XInclude，可以将一篇文章分为几个物理文件，并组合在一起

XInclude示例

文件 intro.xml

<?xml version="1.0"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"

"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<chapter id="intro">

<title>Getting Started</title>

<section id="Installing">

...

</chapter>

文件 index.xml

（包含 intro.xml）

<?xml version="1.0"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"

"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<book>

<title>User Guide</title>

<para>This guide shows you how to use the software.</para>

<xi:include

xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />

...

</book>

XInclude语法要点

允许嵌套

href

href 部分可以是相对路径、绝对路径、网址或者其它格式的URI

URI 格式的 href，可以用 catalog 文件进行映射

例如

<xi:include href="file:///basics/intro.xml"

xmlns:xi="http://www.w3.org/2001/XInclude" />

XInclude早期的规范，允许在文件后面加上锚点来包含文章部分内容（现不支持），

新版本的规范，是通过 xpointer 实现。

xpointer

可以通过 xpointer 属性，只包含文档的部分内容，而不是默认的整个 root 元素

例如

<xi:include

href="intro.xml

xpointer="Installing"

xmlns:xi="http://www.w3.org/2001/XInclude" />

如果没有 href，只有 xpointer，则是将本文档的一部分包含

parse="text"

对包含文件不进行解析，特殊字符进行转换

& becomes &

< becomes <

> becomes >

" becomes "

parse="text"

encoding=xxx

可以指定包含文件的编码，尤其是当 parse="text" 时

当 parse="xml"，则该参数不应该提供，因为 XML 文件的前言可以指定编码

XInclude fallback

即如果 XInclude 包含文件找不到，fallback 提供的内容被显示

例如：

<xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude">

<xi:fallback>

<para><emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis></para>

</xi:fallback>

</xi:include>

entities

XInclude是用于替代实体，但是实体可以和 XInclude 配合使用

这样的优点是，包含的文件都声明在文件头 DOCTYPE 中，一目了然

XInclude 的 href 元素的值为实体引用

示例

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"

"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!ENTITY intro "part1/intro.xml">

<!ENTITY basics "part1/getting_started.xml">

<!ENTITY config "admin/configuring_the_server.xml">

<!ENTITY advanced "admin/advanced_user_moves.xml">

]>

<book>

<title>User Guide</title>

<para>This guide shows you how to use the software.</para>

<xi:include href="&intro;" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<xi:include href="&basics;" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<xi:include href="&config;" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<xi:include href="&advanced;" xmlns:xi="http://www.w3.org/2001/XInclude"/>

...

</book>

xsltproc

http://xmlsoft.org/XSLT/xsltproc2.html

libxml2

xmlcatalog

xmllint

xmltproc

命令行参数

xsltproc [options] stylesheet file [file ...]

-o/--output file

输出到文件

--timing

显示运行时间

--novalid

略过 XML 验证，不加载 DTD

--noout

不输出

--maxdepth val

--docbook

输入文件是 SGML 格式的 DocBook

--param name value

传递一个 Name/Value 对

value 是一个 UTF8 XPath 表达式，如果传递字符串，需要用 "'string'" 括起来，或者使用 --stringparam 参数

--stringparam name value

传递一个 Name/Value 对

value 是一个 Utf8 字符串

--nonet

不要通过网络传输 DTD, 实体等

--catalogs

默认是通过环境变量 XML_CATALOG_FILES 读取 catalog 文件，

--catalogs 则通过环境变量 $SGML_CATALOG_FILES 读取 Catalog 文件，

如果都没有设置，则读取 /etc/xml/catalog 文件。

--xinclude

do XInclude processing on document intput

命令行示例

HTML example:

XML_CATALOG_FILES=/share/catalog.xml xsltproc \

--nonet --timing --output gb2312.html \

--stringparam use.extensions 0 \

/share/xsl/docbook-xsl-1.69.1/html/docbook.xsl \

gb2312.xml

FO example

XML_CATALOG_FILES=/share/catalog.xml xsltproc \

--nonet --timing --output gb2312.fo \

--stringparam use.extensions 0 \

/share/xsl/docbook-xsl-1.69.1/fo/docbook.xsl \

gb2312.xml

Saxon

http://saxon.sourceforge.net/

版本

Saxon 6.5.3

XSLT 1.0 标准的实现

Instant Saxon 6.5.3

仅用于 Windows, 依赖 Microsoft Java VM

Saxon-B 8

开源版本，支持 XSLT 2.0 标准

Saxon-SA 8

Saxon 8 的商业标准。SA 含义为“schema aware”，即实现了 W3C XML Schema 标准

偏离开源精神，是否值得关注？

Xerces XML parser

有人将 Saxon 的 XML Parser换为 Xerces XML parser

下载：

http://xml.apache.org/xerces2-j/

安装配置

CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\

/usr/docbook-xsl/extensions/saxon653.jar

export CLASSPATH

Saxon with Xerces

CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\

/usr/docbook-xsl/extensions/saxon653.jar:/usr/share/xercesImpl.jar

export CLASSPATH

注意: Windows 下的路径分隔符为分号“;”

测试

java com.icl.saxon.StyleSheet -t

DocBook Saxon extensions

extensions/saxon65.jar

启用扩展

全局参数

use.extensions = 1

参数: callouts.extension

参数: textinsert.extension

参数: tablecolumns.extension

参数: linenumbering.extension

参数: graphicsize.extension

命令行

General syntax:

java com.icl.saxon.StyleSheet \

options \

xml-document \

stylesheet-path \

param=value

HTML example:

java com.icl.saxon.StyleSheet \

-o myfile.html \

myfile.xml \

docbook-xsl/html/docbook.xsl \

use.extensions=1

FO example:

java com.icl.saxon.StyleSheet \

-o myfile.fo \

myfile.xml \

docbook-xsl/fo/docbook.xsl \

use.extensions=1

Saxon with Xerces parser:

java \

-Djavax.xml.parsers.DocumentBuilderFactory=\

org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \

-Djavax.xml.parsers.SAXParserFactory=\

org.apache.xerces.jaxp.SAXParserFactoryImpl \

com.icl.saxon.StyleSheet \

-o myfile.html \

myfile.xml \

docbook-xsl/html/docbook.xsl

Xalan

Two Version

xalan-j_2_7_0-bin.tar.gz

xalan-j_2_7_0-2jars.tar.gz

XSL processor 和其它分作两个 Jar 文件打包而已

包含的 Jar 文件

xalan.jar

The main Xalan XSLT processor.

xercesImpl.jar

The XML parser used to parse the XML file.

xml-apis.jar

Provides the SAX, DOM, and JAVAX interfaces used by Xalan.

xalansamples.jar

A set of sample Java applications using Xalan. This file is not needed for DocBook processing.

xalanservlet.jar

Sample application using Xalan in a Java servlet. This file is not needed for DocBook processing.

xsltc.jar

Bundled set of XSLTC functions for compiling XSL stylesheets into a set of Java classes. This file is not needed for DocBook processing. It may not be present, depending on which package of Xalan you downloaded.

安装

注意: Java 1.4 包含一个版本的 Xalan, 需要替换掉

将新版本覆盖到 /usr/jre2/lib/endorsed 目录下

或者在命令行中指定另外目录作为 endorsed 目录

CLASSPATH=$CLASSPATH:/usr/Xalan/xalan.jar:/usr/Xalan/xml-apis.jar:\

/usr/Xalan/xercesImpl.jar:/usr/docbook-xsl/extensions/xalan25.jar

export CLASSPATH

java -Djava.endorsed.dirs=/usr/Xalan \

org.apache.xalan.xslt.Process \

-out myfile.html \

-in myfile.xml \

-xsl /docbook-xsl/html/docbook.xsl

其它版本的 Java，可以将 Xalan 安装在任意位置

设置 CLASSPATH

CLASSPATH=$CLASSPATH:/usr/Xalan/xalan.jar:/usr/Xalan/xml-apis.jar:\

/usr/Xalan/xercesImpl.jar:/usr/docbook-xsl/extensions/xalan25.jar

export CLASSPATH

测试是否正常工作

java org.apache.xalan.xslt.EnvironmentCheck

DocBook Xalan extensions

extensions/xalan25.jar

启用扩展

全局参数

use.extensions = 1

参数: callouts.extension

参数: textinsert.extension

参数: tablecolumns.extension

参数: linenumbering.extension

参数: graphicsize.extension

命令行

参考：

http://xml.apache.org/xalan-j/commandline.html

General syntax:

java org.apache.xalan.xslt.Process \

-out outputfile \

-in xml-document \

-xsl stylesheet-path \

-param name value

HTML example:

java org.apache.xalan.xslt.Process \

-out myfile.html \

-in myfile.xml \

-xsl docbook-xsl/html/docbook.xsl \

-param use.extensions 1

FO example:

java org.apache.xalan.xslt.Process \

-out myfile.fo \

-in myfile.xml \

-xsl docbook-xsl/fo/docbook.xsl \

-param use.extensions 1

fop

参见

http://www-128.ibm.com/developerworks/cn/xml/x-xslfo/

参见: http://www.rocksun.net/wiki/Wiki.jsp?page=DocBook

http://www.xmlmind.com/foconverter/install.html

下载

jai

also needed to download JAI in order to get picture insertion working

http://java.sun.com/products/java-media/jai/

fop

http://xml.apache.org/fop/

版本

0.20.5

0.90alpha

安装配置 0.20.5

FOP 0.20.5 不支持 png 等图形格式，需要安装 JAI

JAI 安装后，只需要将 jai_core.jar 和 jai_codec.jar 两个文件拷贝到 FOP 0.20.5 子目录中

命令行（批处理）

参见:

http://xml.apache.org/fop/running.html

xsltproc 生成 *.fo 文件

设置 fop.extensions 参数为 1，生成 XSL-FO 格式的输出

命令

xsltproc \

--output myfile.fo

--stringparam fop.extensions 1 \

docbook-xsl/fo/docbook.xsl \

myfile.xml

Convert a .fo file on Unix or Linux:

fop.sh -fo myfile.fo -pdf myfile.pdf

Convert an XML source file Unix or Linux:

fop.sh -xsl /docbook-xsl/fo/docbook.xsl -xml myfile.xml -pdf myfile.pdf

Convert a .fo file on Windows:

fop.bat -fo myfile.fo -pdf myfile.pdf

Convert an XML source file on Windows:

fop.bat -xsl /docbook-xsl/fo/docbook.xsl -xml myfile.xml -pdf myfile.pdf

命令行

Setting CLASSPATH:

CLASSPATH="/usr/java/fop-0.20.5/build/fop.jar:\

/usr/java/fop-0.20.5/lib/batik.jar:\

/usr/java/fop-0.20.5/xalan-version.jar:\

/usr/java/fop-0.20.5/lib/xercesImpl-version.jar:\

/usr/java/fop-0.20.5/lib/JimiProClasses.jar\

/usr/java/avalon-framework-cvs-version.jar"

export CLASSPATH

General syntax:

java org.apache.fop.apps.Fop [options] \

[-fo|-xml] infile \

[-xsl stylesheet-path] \

-pdf outfile.pdf

Convert a .fo file to pdf:

java org.apache.fop.apps.Fop \

-fo myfile.fo \

-pdf myfile.pdf

Convert an XML source file directly to pdf:

java org.apache.fop.apps.Fop \

-xml myfile.xml \

-xsl docbook-xsl/fo/docbook.xsl \

-pdf myfile.pdf

FOP 内存溢出问题

这是由于为 JAVA 分配的内存不足引起的

为 java 命令加上参数 -Xmx128m ，可以分配 128M 内存

可以修改 fop 批处理文件

<html>java <b>-Xmx128m</b> -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 \

<br> %3 %4 %5 %6 %7 %8

中文支持问题

参见: http://www.rocksun.net/wiki/Wiki.jsp?page=DocBook

xsl 定制

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>

<xsl:import href="C:/docbook/docbook-xsl-1.68.1/fo/docbook.xsl"/>

<xsl:param name="fop.extensions" select="1" />

<xsl:param name="variablelist.as.blocks" select="1" />

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

<xsl:param name="use.extensions" select="1" />

<xsl:param name="l10n.gentext.language" select="'zh_cn'" />

<xsl:param name="admon.graphics" select="1" />



<xsl:param name="body.font.family">SimSun</xsl:param>

<xsl:param name="title.font.family">SimSun</xsl:param>

</xsl:stylesheet>

fop 配置，增加中文字体

我们需要userconfig.xml来改变编译FO到PDF的一些默认属性，因为我们需要中文字体，需要用ttfreader.cmd来生成字体文件，这里我已经生成了文件在fonts目录下。然后建立userconfig.xml文件

userconfig.xml

<configuration>

















<fonts>



<font metrics-file="fonts\simfang.xml" kerning="yes" embed-file="C:\WINDOWS\Fonts\simfang.ttf">

<font-triplet name="FangSong_GB2312" style="normal" weight="normal"/>

</font>



<font metrics-file="fonts\simsun.xml" embed-file="C:\windows\fonts\simsun.ttc" kerning="yes">

<font-triplet name="SimSun" style="normal" weight="normal"/>

<font-triplet name="SimSun" style="normal" weight="bold"/>

<font-triplet name="NSimSun" style="italic" weight="normal"/>

<font-triplet name="NSimSun" style="italic" weight="bold"/>

</font>



</fonts>

</configuration>

xmlroff

DocBook 元素参考

词汇修饰

文字修饰

emphasis

字体强调

例如

<para>

The <emphasis>most</emphasis> important example of this

phenomenon occurs in A. Nonymous's book

<citetitle>Power Snacking</citetitle>.

</para>

superscript

上标

例如

<para>

The equation e<superscript>πi</superscript> + 1 = 0 ties together

five of the most important mathematical constants.

</para>

subscript

下标

例如

<para>

Thirsty? Have some H<subscript>2</subscript>O.

</para>

quote

引用文字，即将文字两端添加引号（或其它）扩起来。

示例

<para>

This software is provided <quote>as is</quote>, without expressed

or implied warranty.

</para>

文字语意

abbrev

指出句点结尾的缩写词汇

例如

<para>The <abbrev>Assn.</abbrev> of Computing Machinery would probably never

abbreviate “Association” like this.

</para>

acronym

指出大写首字母的词汇

例如

<para>

In the United States, <acronym>NASA</acronym> stands for the

National Aeronautics and Space Administration.

</para>

foreignphrase

phrase

为文字增加属性

wordasword

所指仅为文字

视窗对象

accel

定义快捷键

例如

<para os="windows">You can exit most Windows applications by selecting

<guimenuitem><accel>Q</accel>uit</guimenuitem> or

<guimenuitem>E<accel>x</accel>it</guimenuitem> from

the <guimenu><accel>F</accel>ile</guimenu> menu.

</para>

其它类似元素：

guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu, keycap, keycode, keycombo, keysym, menuchoice, mousebutton, shortcut

guiicon

出现在 GUI 界面中的图形 icon

例如

<para>The exact text of the <guilabel>Legend</guilabel> and other labels on the

graph is dependent upon the language of the current locale. Likewise,

the text of the <guibutton>OK</guibutton> button and other buttons may vary.

The <guiicon><inlinemediaobject>

<imageobject>

<imagedata fileref="figures/legend.png"/>

</imageobject>

</inlinemediaobject></guiicon>

icon and the other icons on the left side of the display may be

configured by the local administrator, but they are not

generally expected to vary from locale to locale.

</para>

定义

database, filename, hardware, medialabel, productname.

建立链接

anchor

建立锚点

例如

<para>

The anchor element<anchor id="example.anchor.1"/> is empty and contributes

nothing to the flow of the content in which it occurs. It is only useful

as a target.

</para>

ulink

指向 URL 的链接

url 属性为链接地址

打开链接的方式

如果定义变量 $ulink.target，则链接的属性 target 指向 $ulink.target

type 属性的定制

链接文字

如果是空元素，则 url 属性值作为链接文字

否则，元素内容为链接文字

例如

<para>

For more information, see the O'Reilly catalog entry for

<ulink url="http://www.ora.com/catalog/tex/"><citetitle>Making TeX

Work</citetitle></ulink>.

</para>

link

如果 link 元素有内容，则不管其是否具有 endterm 属性，都是将元素内容作为热点文字，指向 linkend 指向的文档内部的某个链接；

如果 link 元素没有内容，并且具有 endterm 属性，将 endterm 指向的元素的值，拷贝到 link 处，并作为热点文字，指向 linkend 指向的文档内部的 endterm 指向的链接；

例如

<sect1><title>Examples of <sgmltag>Link</sgmltag></title>

<para>

In this sentence <link linkend='nextsect'>this</link> word is

hot and points to the following section.

</para>

<para>

There is also a link to the section called

<quote><link linkend='nextsect' endterm="nextsect.title"/></quote>

in this sentence.

</para>

<sect2 id='nextsect'><title id='nextsect.title'>A Subsection</title>

<para>

This section only exists to be the target of a couple of links.

</para>

</sect2>

</sect1>

olink

不直接指向目标

例如 website 中指向网页的链接

xref

图像

mediaobjectco

A media object that contains callouts

内容模型

mediaobjectco ::=

(objectinfo?,imageobjectco,

(imageobjectco|textobject)*)

inlinemediaobject

inline 方式显示。可以组合对同一信息的各种可替换版本，如高分辨率图片、低分辨率图片、文本。打印输出优先选择高分辨率，网页版本可能二选一，文本输出选择文字版本。

内容模型

inlinemediaobject ::=

(objectinfo?,

(videoobject|audioobject|imageobject|imageobjectco|textobject)+)

例如

mediaobject.

以 block 方式显示。可以组合对同一信息的各种可替换版本，如高分辨率图片、低分辨率图片、文本。打印输出优先选择高分辨率，网页版本可能二选一，文本输出选择文字版本。

内容模型

mediaobject ::=

(objectinfo?,

(videoobject|audioobject|imageobject|imageobjectco|textobject)+,

caption?)

图片

figure

自动编号、带标题的图片

例如

<figure><title>The Pythagorean Theorem Illustrated</title>

<mediaobject>

<imageobject>

<imagedata fileref="figures/pythag.png"/>

</imageobject>

<textobject><phrase>An illustration of the Pythagorean Theorem</phrase></textobject>

</mediaobject>

</figure>

informalfigure

不带标题的 figure

设置图像的 border 为 0

使用 CSS

span.inlinemediaobject img {border: 0 ; }

表格

table

内容模型

示例

<table frame='all'><title>Sample Table</title>

<tgroup cols='5' align='left' colsep='1' rowsep='1'>

<colspec colname='c1'/>

<colspec colname='c2'/>

<colspec colname='c3'/>

<colspec colnum='5' colname='c5'/>

<thead>

<row>

<entry namest="c1" nameend="c2" align="center">Horizontal Span</entry>

<entry>a3</entry>

<entry>a4</entry>

<entry>a5</entry>

</row>

</thead>

<tfoot>

<row>

<entry>f1</entry>

<entry>f2</entry>

<entry>f3</entry>

<entry>f4</entry>

<entry>f5</entry>

</row>

</tfoot>

<tbody>

<row>

<entry>b1</entry>

<entry>b2</entry>

<entry>b3</entry>

<entry>b4</entry>

<entry morerows='1' valign='middle'><para> 

Vertical Span</para></entry>

</row>

<row>

<entry>c1</entry>

<entry namest="c2" nameend="c3" align='center' morerows='1' valign='bottom'>Span Both</entry>

<entry>c4</entry>

</row>

<row>

<entry>d1</entry>

<entry>d4</entry>

<entry>d5</entry>

</row>

</tbody>

</tgroup>

</table>

informaltable

不带标题的表格

Example

example

带标题，以及自动编号

示例

<example><title>A DSSSL Function</title>

<programlisting>

(define (node-list-filter-by-gi nodelist gilist)

;; Returns the node-list that contains every element of the original

;; nodelist whose gi is in gilist

(let loop ((result (empty-node-list)) (nl nodelist))

(if (node-list-empty? nl)

result

(if (member (gi (node-list-first nl)) gilist)

(loop (node-list result (node-list-first nl))

(node-list-rest nl))

(loop result (node-list-rest nl))))))

</programlisting>

</example>

informalexample

不带标题的示例

示例

<informalexample>

<programlisting>

sub print_content_model {

my($self) = shift;

local($_) = shift;

local(*FILE) = shift;

my(@cm) = $self->format_content_model2($_);

foreach $_ (@cm) {

print FILE $self->make_links($_, 1, 1), "\n";

}

}

</programlisting>

</informalexample>

qandaset

示例

<qandaset defaultlabel='qanda'>

<qandaentry>

<question>

<para>

To be, or not to be?

</para>

</question>

<answer>

<para>

That is the question.

</para>

</answer>

</qandaentry>

</qandaset>

DocBook Website

概念

由 XML 文件转换为网页

Website XML 文件的根元素是 website, 是由部分 DocBook 元素和部分 website 元素构成

website 的 DTD

website.dtd

Simplified DocBook DTD 的子集，只有150 个元素

website-full.dtd

DocBook DTD 的子集，约有400 个元素

layout.dtd

用户创建 layout.xml 网站结构文件的 DTD

autolayout.dtd

自动生成的 autolayout.xml 的 DTD

与 DocBook 的区别

website 不能使用的元素： set, book, chapter, article, index

在 catalog.xml 添加条目

layout.xml 文件

说明

DTD

<!ELEMENT layout ((config|style|script|headlink|copyright)*, toc+, notoc*)>

见 layout.dtd

layout.xml 文件好似一个目录索引文件

每一个 XML 文件对应于 layout.xml 中的一条 tocentry 记录

layout.xml 文件的目录条目

可以组成一个层次结构

tocentry 元素可以嵌套，即可以包含子 tocentry 元素，从而构成一个层次结构

该层次结构对应于网页左侧的导航条

layout.xml 将在样式表 autolayout.xsl 处理下，生成 autolayout.xml

XML 前言

<?xml version="1.0"?>

<!DOCTYPE layout PUBLIC "-//Norman Walsh//DTD Website Layout V2.5.0//EN"

"http://docbook.sourceforge.net/release/website/2.5.0/layout.dtd">

<layout> 根元素

顶级元素

(忠实拷贝)

config

<!ELEMENT config EMPTY>

<!ATTLIST config

param CDATA #REQUIRED

value CDATA #REQUIRED

altval CDATA #IMPLIED

>

网页左侧导航条展开层次

style

<!ELEMENT style (#PCDATA)>

<!ATTLIST style

src CDATA #IMPLIED

type CDATA #IMPLIED

>

style 元素设定每个网页都要用的样式表。（可为多个）

script

<!ELEMENT script (#PCDATA)>

<!ATTLIST script

src CDATA #IMPLIED

language CDATA #IMPLIED

type CDATA #IMPLIED

>

headlink

<!ELEMENT headlink EMPTY>

<!ATTLIST headlink

href CDATA #IMPLIED

media CDATA #IMPLIED

name CDATA #IMPLIED

rel CDATA #IMPLIED

rev CDATA #IMPLIED

src CDATA #IMPLIED

title CDATA #IMPLIED

type CDATA #IMPLIED

>

<!ELEMENT copyright (year+, holder+)>

如

<copyright>

<year>1999-2001</year><year>2006</year>

<holder role="http://nwalsh.com/~ndw/">Norman Walsh</holder>

</copyright>

toc 元素

说明

DTD

<!ELEMENT toc (tocentry*)>

<!ATTLIST toc

page CDATA #REQUIRED

dir CDATA #IMPLIED

filename CDATA #IMPLIED

>

toc 元素用于设定首页

虽然可以存在多个 toc，但是生成的多个主页及其子页面互相之间没有菜单上的关联，因而没有什么实际意义？

多 toc 的问题

最好只有一个 toc，因为如果存在多个 toc，可能会出现如下问题：

如果存在多个 toc，则 notoc 生成的页面在选择主页面时，会出现问题；(autolayout.xsl)

如果存在多个 toc，则形如 <xsl:if test="$autolayout/autolayout/toc[1]/@id = $id"> 的语句存在问题；(tabular.xsl)

属性

page 属性（必须）

page 参数的值为首页对应的 xml 文件名；

filename 属性

filename 属性的值为转换之后的 html 文件名

dir 属性

网页生成的目录

子元素

tocentry

示例

tocentry 元素

说明

DTD

<!ELEMENT tocentry ((title|titleabbrev|summary)*, tocentry*)>

<!ATTLIST tocentry

id ID #IMPLIED

page CDATA #IMPLIED

href CDATA #IMPLIED

dir CDATA #IMPLIED

filename CDATA #IMPLIED

revisionflag (added|changed) #IMPLIED

tocskip (0|1) "0"

>

定义首页下面的网页，tocentry 可以包含下一级的 tocentry，构成网页的层次结构

page 型页面

属性

page 属性的值为 XML 文件名

filename 属性为转换之后的 HTML 文件名

不要在 filename 中使用目录名，dir 属性是用来定义目录名的

dir 属性是目录名

如果 tocentry 嵌套，则 dir 目录也嵌套，除非指定绝对路径

dir 使用绝对路径 "/"，是相对于 output-root 目录

tocskip

tocskip 一般用于包含子项的 tocentry 条目，若设置 tocskip，则该条目直接指向第一个子条目

revisionflag

"changed"

修改条目指示

"add"

新增条目指示

"deleted"

删除条目指示

例如

href 型页面

属性

id 属性

href 属性

tocskip

参见

revisionflag

参见

元素

title

titleabbrev

summary

例如

<tocentry id="worldhello.net" href="http://www.worldhello.net/" tocskip="0">

<title>WorldHello.net</title>

<titleabbrev>WorldHello</titleabbrev>

<summary>Johnson's Homepage</summary>

</tocentry>

更多示例

notoc 元素

说明

DTD

<!ELEMENT notoc EMPTY>

<!ATTLIST notoc

page CDATA #REQUIRED

dir CDATA #IMPLIED

filename CDATA #IMPLIED

>

作为顶级元素存在，可以进行编译，但是不在导航条中生成链接

问题

当有多个 toc 存在时，notoc 在选择主页时只会选择第一个 toc 作为其主页

示例

webpage 网页

说明

DTD 参见 website.dtd 和 website-full.dtd

<!ENTITY % webpage.mix "(config*, head, (%bookcomponent.content;),

appendix*, bibliography*)">

一个 xml 文件将编译出对应的一个 html 文件，当然用不同的样式表，可以生成不同风格的多个网页

XML 前言

<?xml version="1.0"?>

<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.5.0//EN"

"website.dtd" >

或者

<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website Full V2.5.0//EN"

"website-full.dtd">

<webpage> 根元素

可选的任意 config 元素

显示在首页下方中间的页面链接

或 <config param="footerlink" value="page_id" altval="文字说明"/>

还可以定义在 autolayout.xml 中。

页面反馈（feedback）

参数 <xsl:param name="feedback.with.ids" select="0"/>

是否将网页 ID 加在 feedback URL 后面

参数 <xsl:param name="feedback.link.text">Feedback</xsl:param>

feedback 链接的文字

head 部分

title 元素

既作为导航条页面名称，也作为网页页面名称

titleabbrev

summary

keywords

优先级高于 layout.xml 的 copyright 元素

如

<head>

<title>Welcome to Website</title>

<summary>Introduction</summary>

<keywords>Norman Walsh, DSSSL, SGML, XML, DocBook, Website</keywords>

</head>

DocBook 元素构成网页的主体

<para>This small, somewhat contrived website demonstrates the

Website document type. Website provides a system for building static

Websites from XML content.</para>

即需即编：两种编译方式

XSLT编译方式

使用 xsltproc，每次编译所有的网页都要重新生成，不能做到只生成改变的网页

Saxon, Xalan 支持的 XSLT 扩展函数，可以做到只生成改变的网页

xslt 扩展

website/extensions/saxon653.jar

website/extensions/xalan25.jar

可用样式表

chunk-tabular.xsl

chunk-website.xsl

Makefile 编译方式

和 XSLT 相比，更灵活

网页创建流程

1. 创建 Makefile

2. 生成空文件 depends.tabular

3. 执行 make depends

先生成 autolayout.xml 文件

autolayout.xml: layout.xml

xsltproc --output $@ $(STYLEDIR)/autolayout.xsl $<

make depends

再生成 depends.tabular 文件

depends: autolayout.xml

xsltproc \

--output depends.tabular \

--stringparam output-root htdocs \

$(STYLEDIR)/makefile-dep.xsl \

$<

makefile-dep.xsl 样式表作用于autolayout.xml 文件

包含所有 HTML 依赖性定义。其格式为：

html/productlist.html: products.xml

... ...

4. make

make website

website 作为 make 的 target，参见 depends.tabular 文件

以后每次修改 layout.xml 或者网页 XML，

只执行本命令即可。即需即编

%.html: autolayout.xml

xsltproc \

--output $@ \

--stringparam autolayout-file autolayout.xml \

--stringparam output-root htdocs \

$(STYLEDIR)/tabular.xsl \

$(filter-out autolayout.xml,$^)

可用样式表

tabular.xsl

website.xsl

示例参见：

网页之间的链接: olink

由于网页来自不同 XML，因此不能用 xref 和 link

应该使用 olink

olink 有两个参数，一个定位文档，另外一个参数定位文档中的位置

例如: <olink targetdoc="home" targetptr="whatsnew"/>

targetdoc 的值是目标文档的 website 根元素的 id 属性

targetptr 的值是文档内部的 id 值，如果定位到文档头部，该值也可以和 targetdoc 一样

website.database.document

如果 olink 元素有内容，则作为链接的文字

如果 olink 元素为空元素，则需要依靠生成的 database 文件

两种编译方式

XSLT 编译

<html>

如：<br>

xsltproc \<br>

<b>--stringparam collect.xref.targets yes </b>\<br>

--stringparam output-root htdocs \<br>

../website/xsl/chunk-tabular.xsl \<br>

autolayout.xml

会生成文件 : website.database.xml

Makefile 编译

增加了一个步骤

步骤3之后，增加了使用样式表 website-targets.xsl 创建 website.database.xml 文件

website.database.xml: autolayout.xml

$(PROC) \

--output $@ \

website-targets.xsl $<

xslt 编译过程增加一个参数

<html>

%.html: autolayout.xml<br>

$(PROC) \<br>

--output $@ \<br>

<b>--stringparam website.database.document website.database.xml </b>\<br>

--stringparam output-root htdocs \<br>

tabular.xsl \<br>

$(filter-out autolayout.xml,$^)

Makefile 示例

PROC = XML_CATALOG_FILES=/docbook/src/catalog.xml xsltproc --nonet

XSLPATH = /docbook/src/xsl/docbook-xsl-1.69.1/website

all:

make website

include depends.tabular

autolayout.xml: layout.xml

$(PROC) \

--output $@ \

$(XSLPATH)/autolayout.xsl $<

make depends

depends: autolayout.xml

$(PROC) \

--output depends.tabular \

--stringparam output-root htdocs \

$(XSLPATH)/makefile-dep.xsl $<

website.database.xml: autolayout.xml

$(PROC) \

--output $@ \

$(XSLPATH)/website-targets.xsl $<

%.html: autolayout.xml

$(PROC) \

--output $@ \

--stringparam website.database.document website.database.xml \

--stringparam output-root htdocs \

$(XSLPATH)/tabular.xsl \

$(filter-out autolayout.xml,$^)

链接到其它网站

tocentry 可以定义除了网页之外，还可以直接定义 URL

如指向外部 URL

<tocentry id="nwalsh.com" href="http://nwalsh com">

<title>Norm Walsh's Website</title>

</tocentry>

指向本地其它页面的 URL

ulink

olink

增加非 website 网页

website CSS

两种方式定义

html.stylesheet 定义，缺点是 css 路径是绝对路径

另外一个方法，是在 layout.xml 中定义。好处是生成的 HTML 网页使用相对路径引用 CSS

例如

website 定制

参见

参考网站

google search plugin

http://www.schuerig.de/michael/about.html

http://gpl-violations.org/about-website.html

http://www.netfilter.org/about-website.html

DocBook slide

DocBook XSL 解密

website

首先明确一点 website 并非独立存在的，他依赖 DocBook 的 XSL

除了解决对 DocBook 的元素进行格式化外

还利用 DocBook XSL 中 common/, html/ 中的文件，如 l10n.xsl，

autolayout.xsl

功能：作用于 layout.xml 文件，生成 autolayout.xml 文件

模板 <xsl:template match="style|script|headlink|copyright|config">

<xsl:template match="style|script|headlink|copyright|config">

<xsl:apply-templates select="." mode="copy"/>

</xsl:template>

模板 <xsl:template match="toc">

模板 tocentry

如果有属性 href，调用模板 tocentry.href

否则，调用模板 tocentry.page

模板 tocentry.page

读取 page 属性指向的 XML 文件，读入 $page 变量

属性

page 属性

id 属性

page 页的第一个元素 (website元素) 必须具备 id 属性

dir 属性

dir 属性为该页目录，目录可以是相对于上一级 tocentry 的目录！或者是绝对目录

filename 属性

filename 变量来自 filename 属性，或者 layout.xml 的名为 default-filename config 元素，或者为 index.html

元素

元素 title|titleabbrev|summary 来自于 $page 页(webpage页)

title

titleabbrev

summary

递归子 tocentry

模板 tocentry.href

必须同时具备属性 href, id，且具备元素 title

属性

href

tocskip

元素

元素 title|titleabbrev|summary 来自于 layout.xml 本身

title

titleabbrev

summary

makefile-dep.xsl

功能: 作用于 autolayout.xml 文件，生成 depends.tabular 和 depends.notabular 文件

全局属性

如下属性最好是在命令行中提供，而不是在 XSL 定制层

<xsl:param name="add-website-depends" select="''"/>

用于为 website 目标添加附加的依赖

<xsl:param name="depends-file" select="''"/>

depends 文件名

<xsl:param name="output-root" select="''"/>

输出路径

<xsl:param name="filename-prefix" select="''"/>

生成 html 文件的前缀

<xsl:param name="remove-output-root" select="0"/>

默认生成的 clean 目标，是删除每个生成的 HTML 文件

如果设置 remove-output-root 为1，则删除整个 output-root

模板 <xsl:template match="autolayout">

创建目标 website:

创建目标

创建目标 distclean:

除 autolayout.xml website.database.xml 外，还有

创建目标 clean:

如果 $remove-output-root = 1

否则

模板 <xsl:template match="toc" mode="all">

获得空格分隔的目标文件名列表

模板 <xsl:template match="tocentry|notoc" mode="all">

获得空格分隔的目标文件名列表

模板 <xsl:template match="toc">

生成诸如 index.html : index.xml 的依赖

模板 <xsl:template match="tocentry|notoc">

生成诸如 target.html : source.xml 的依赖

website-targets.xsl

功能: 作用于 autolayout.xml 文件，生成 website.database.xml 文件

模板 <xsl:template match="autolayout" mode="collect.targets">

tabular.xsl

说明: 创建带左侧导航条的网页

全局参数

以图标方式显示警告

<xsl:param name="admon.style" select="''"/>

<xsl:param name="admon.graphics" select="1"/>

<xsl:param name="admon.graphics.path">graphics/</xsl:param>

<xsl:param name="admon.graphics.extension">.gif</xsl:param>

左侧导航条背景色

/webpage/config[@param='navbgcolor']/@value

或 $autolayout/autolayout/config[@param='navbgcolor']/@value

<xsl:param name="autolayout" select="document($autolayout-file, /*)"/>

模板 <xsl:template match="webpage">

网页 <head> 部分

<xsl:apply-templates select="head" mode="head.mode"/>

<xsl:apply-templates select="config" mode="head.mode"/>

<xsl:call-template name="body.attributes"/>

html/docbook.xsl

定义样式

<xsl:template name="body.attributes">

<xsl:attribute name="bgcolor">white</xsl:attribute>

<xsl:attribute name="text">black</xsl:attribute>

<xsl:attribute name="link">#0000FF</xsl:attribute>

<xsl:attribute name="vlink">#840084</xsl:attribute>

<xsl:attribute name="alink">#0000FF</xsl:attribute>

</xsl:template>

广告栏

<xsl:call-template name="allpages.banner"/>

是首页么

首页

<xsl:call-template name="home.navhead.cell"/>

<xsl:call-template name="home.navhead.upperright.cell"/>

<xsl:call-template name="home.navhead.separator"/>

非首页

<xsl:apply-templates select="./head/title" mode="title.mode"/>

网页右侧主体页面

执行 DocBook 样式表

<xsl:apply-templates select="child::node()[not(self::webpage)]"/>

脚注

<xsl:call-template name="process.footnotes"/>

网页左侧导航条

<xsl:apply-templates select="$toc">

<xsl:with-param name="pageid" select="@id"/>

</xsl:apply-templates>

页脚

<xsl:call-template name="webpage.table.footer"/>

空模板，参见

定制，参见

<xsl:call-template name="webpage.footer"/>

模板 home.navhead.cell

模板 home.navhead

模板 home.navhead.upperright.cell

模板 home.navhead.upperright

toc-tabular.xsl

全局参数

revsionflag 的文字

<xsl:param name="nav.text.revisionflag.added">New</xsl:param>

<xsl:param name="nav.text.revisionflag.changed">Changed</xsl:param>

<xsl:param name="nav.text.revisionflag.deleted"></xsl:param>

<xsl:param name="nav.text.revisionflag.off"></xsl:param>

图标样式

<xsl:param name="nav.icon.style">triangle</xsl:param>

可以选择: folder, folder16, plusminus, triangle, arrow

图标文件路径

<xsl:param name="nav.icon.path">graphics/navicons/</xsl:param>

<xsl:param name="nav.icon.extension">.gif</xsl:param>

导航条展开层次

<xsl:param name="toc.expand.depth" select="1"/>

模板: <xsl:template match="toc">

显示网页左侧导航条

显示 logo

若首页

显示图片 homebanner-tabular 作为 logo

非首页

显示图片 banner-tabular 作为 logo

<xsl:apply-templates select="tocentry">

默认是 1

模板: <xsl:template match="tocentry">

显示网页左侧导航条的内容

模板 <xsl:template name="insert.spacers">

模板 <xsl:template name="toc-rel-path">

模板 <xsl:template name="toc-directory-depth">

head.xsl

功能: 输出 HTML 的 <head> 部分

模板 <xsl:template match="head" mode="head.mode">

生成网页的 head

添加 html.stylesheet 定义的样式表到 Head 中

用户自定义模板 user.head.content 内容加入到模板中

website-common.xsl

空模板 allpages.banner

占位模板 <xsl:template name="allpages.banner"/>

模板 webpage.table.footer

（website-common.xsl）

空模板

<xsl:template name="webpage.table.footer"/>

模板 webpage.footer

（website-common.xsl）

$footer.hr

是否要在 footer 之前添加 <hr/>

第一行脚注

左栏显示 rcsdate，调用模板 rcsdate.format

直接显示rcsdate的 value 属性。CSS 样式为 footdate

中间栏

如果不是首页：

显示到主页的链接

<xsl:call-template name="homeuri"/>

<xsl:call-template name="gentext.nav.home"/>

显示预设置链接

<xsl:variable name="footers" select="$page/config[@param='footer']

|$page/config[@param='footlink']

|$autolayout/autolayout/config[@param='footer']

|$autolayout/autolayout/config[@param='footlink']"/>

<xsl:apply-templates select="$footers" mode="footer.link.mode"/>

右栏显示feedback

定义了 feedback.href 属性？

链接 href

$feedback.with.id 为 1? 则将 page_id 加在 feedback.href 后面

否则只将 feedback.href 作为 feedback 的 URL

链接文字

<xsl:param name="feedback.link.text">Feedback</xsl:param>

第二行脚注

右对齐显示版权信息

<xsl:when test="head/copyright">

<xsl:apply-templates select="head/copyright" mode="footer.mode"/>

</xsl:when>

第三行脚注

如果定义 sequential.links = 1

模板 process.footnotes

html/footnote.xsl

<xsl:template match="footnote" name="process.footnote" mode="process.footnote.mode">

模板 <xsl:template match="config" mode="footer.link.mode">

param="footlink"

value 属性是 pageid，通过 tocentry 得到页面 URL，载用该 URL 和 altvar 属性创建链接

否则直接用 value 属性当做 URL，创建链接

模板 <xsl:template match="head/title" mode="title.mode">

显示 <h1> 标题 </h1>

模板 root-rel-path

本页地址到主页空间的相对路径。如 ../../

模板 <xsl:template match="toc|tocentry|notoc" mode="olink.mode">

模板 tocentry

生成

<document targetdoc="home" baseuri="index.html" dir="">

<xsl:call-template name="div"/>

</document>

呼叫模板 div，在文件 common/targets.xsl 中

olink.xsl

功能: 跨文档的交叉引用

<xsl:template match="olink">

1. 传统的 olink

属性 targetdoc，或属性 targetptr 不为空

<xsl:apply-imports/> 调用其它优先级低的模板，即 DocBook html/xref.xsl 的模板

2. Website 更改过的 olink 语法

没有上述两个属性，而是具有属性 targetdocent

Those other olink attributes are targetdocent, linkmode, and localinfo

<xsl:template name="olink-entity">

<xsl:template name="select.target.database">

<xsl:template name="make.olink.href">

param.xsl

功能：定义全局参数

是否显示 HR

<xsl:param name="header.hr" select="1"/>

<xsl:param name="footer.hr" select="1"/>

feedback

<xsl:param name="feedback.href"/>

<xsl:param name="feedback.with.ids" select="0"/>

<xsl:param name="feedback.link.text">Feedback</xsl:param>

导航条

<xsl:param name="banner.before.navigation" select="1"/>

<xsl:param name="nav.table.summary">Navigation</xsl:param>

<xsl:param name="navtocwidth">220</xsl:param>

<xsl:param name="navbodywidth"/>

<xsl:param name="navbgcolor">#4080FF</xsl:param>

<xsl:param name="textbgcolor">white</xsl:param>

<xsl:param name="toc.spacer.graphic" select="1"/>

<xsl:param name="toc.spacer.text"> </xsl:param>

<xsl:param name="toc.spacer.image">graphics/blank.gif</xsl:param>

<xsl:param name="toc.pointer.graphic" select="1"/>

<xsl:param name="toc.pointer.text"> > </xsl:param>

<xsl:param name="toc.pointer.image">graphics/arrow.gif</xsl:param>

<xsl:param name="toc.blank.graphic" select="1"/>

<xsl:param name="toc.blank.text"> </xsl:param>

<xsl:param name="toc.blank.image">graphics/blank.gif</xsl:param>

首页

<xsl:param name="suppress.homepage.title" select="'1'"/>

<xsl:param name="sequential.links" select="'0'"/>

其它

<xsl:param name="currentpage.marker" select="'@'"/>

<xsl:param name="dry-run" select="'0'"/>

<xsl:param name="rebuild-all" select="'0'"/>

rss.xsl

功能: 将 RSS 1.0 文件整合到 webpage 中

例如在 <webpage> 嵌入 <rss feed> 标签

website/example/rss.xsl

<webpage id="rss">

...

<rss feed="http://nwalsh.com/rss/whatsnew.xml"/>

...

</webpage>

xbel.xsl

功能: 将 xbel 书签整合到 webpage 中

例如:

toc.xsl

功能: 显示非 tabluar 形式网页的顶部导航条

全局参数

<xsl:param name="max.toc.width" select="7"/>

模板 <xsl:template match="toc">

显示首页图标

若首页

显示 homebanner 图标

非首页

显示 banner 图标

显示 “|” 作为链接分隔符

<xsl:call-template name="process-children">

模板 <xsl:template name="process-children">

若首页

<xsl:call-template name="process-toc-children">

非首页

<xsl:call-template name="process-tocentry-children">

模板 <xsl:template name="process-tocentry-children">

模板 <xsl:template name="process-toc-children">

模板 <xsl:template match="tocentry">

website.xsl

说明: 创建纯文本、无表格的网页

可定制参数

banner.before.navigation

是否在页面导航的上方添加 banner

模板 <xsl:template match="webpage">

网页 <head> 部分

<xsl:apply-templates select="head" mode="head.mode"/>

<xsl:apply-templates select="config" mode="head.mode"/>

<xsl:call-template name="body.attributes"/>

html/docbook.xsl

广告栏

若定义 banner.before.navigation = 1，则在导航条上方显示 banner

若定义 banner.before.navigation = 0，则在导航条下方显示 banner

即调用 <xsl:call-template name="allpages.banner"/> 显示 banner

网页顶部导航条

<xsl:apply-templates select="$toc">

<xsl:with-param name="pageid" select="@id"/>

</xsl:apply-templates>

页面标题

<xsl:apply-templates select="./head/title" mode="title.mode"/>

执行 DocBook 样式表

<xsl:apply-templates select="child::node()[not(self::webpage)]"/>

脚注

<xsl:call-template name="process.footnotes"/>

页脚

<xsl:call-template name="webpage.footer"/>

chunk-common.xsl

全局参数

<xsl:param name="output-root" select="'.'"/>

<xsl:param name="dry-run" select="'0'"/>

<xsl:param name="rebuild-all" select="'0'"/>

模板 <xsl:template match="autolayout">

模板 <xsl:template match="toc|tocentry|notoc" mode="make">

模板 <xsl:template name="make.tocentry">

模板 <xsl:template match="*" mode="calculate-dir">

模板 <xsl:template match="autolayout" mode="collect.targets">

chunk-tabular.xsl

chunk-website.xsl

DocBook XSL

html/docbook.xsl

html/chunker.xsl

OSX 定制

l10n/i18n

person_name

待定

nav_home 起始页改为首页

<l:gentext key="nav-home" text="首页"/>

模板 template/layout.xml

config

<copyright>

<year>2002-2005</year>

<holder role="http://www.worldhello.net/">WorldHello.net</holder>

</copyright>

<copyright>

<year>2005-2006</year>

<holder role="http://www.OpenSourceXpress.com/">群英汇</holder>

</copyright>

style

模板 template/webpage.xml

config

head

<head>

<title>title... ...</title>

<titleabbrev>titleabbrev...</titleabbrev>

<summary>summary...</summary>

<keywords>keyword1, keyword2, ...</keywords>

</head>

tabular.xsl

用 URI 格式导入 DocBook website XSL

<xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/tabular.xsl"/>

确认 $XML_CATALOG_FILES 能够正确解析该 URI

<xsl:include href="osx-common.xsl"/>

<xsl:template name="webpage.table.footer">

在左侧导航条下方增加 Google 搜索

参数 navhead.in.allpage =1 ？

所有页面均显示 home.navhead, home.navhead.upperright

<xsl:template name="home.navhead.upperright">

显示到文字版的链接（可定制）

<xsl:template name="home.navhead">

website.xsl

用 URI 格式导入 DocBook website XSL

<xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/website.xsl"/>

确认 $XML_CATALOG_FILES 能够正确解析该 URI

顺序浏览

<xsl:param name="sequential.links" select="1"/>

banner.before.navigation

banner.before.navigation = 1/0，则在导航条上方或下方显示 banner

<xsl:include href="osx-common.xsl"/>

osx-common.xsl

设置网页输出编码

<xsl:output method="html" encoding="gb2312" indent="yes"/>

l10n 本地化设置

<xsl:param name="l10n.gentext.default.language">zh_cn</xsl:param>

定制中文姓名显示方式

设置 CSS 样式表

<xsl:param name="html.stylesheet.type">text/css</xsl:param>

<xsl:param name="html.stylesheet">/inc/css/tabular.css</xsl:param>

<xsl:param name="generate.id.attributes" select="0"/>

是否用水平分隔线分隔正文于 header 和 footer

<xsl:param name="header.hr" select="1"/>

<xsl:param name="footer.hr" select="1"/>

导航条以及正文的背景颜色设置

<xsl:param name="textbgcolor">white</xsl:param>

<xsl:param name="navbgcolor">#4080FF</xsl:param>

以图标方式显示警告

<xsl:param name="admon.graphics" select="1"/>

<xsl:param name="admon.textlabel" select="0"/>

<xsl:param name="admon.graphics.path">/images/docbook/</xsl:param>

<xsl:param name="admon.graphics.extension">.png</xsl:param>

以图标方式显示导航

<xsl:param name="navig.graphics" select="1"/>

<xsl:param name="navig.graphics.path">/images/docbook/</xsl:param>

<xsl:param name="navig.graphics.extension">.png</xsl:param>

以图标方式显示 callout

<xsl:param name="callout.graphics" select="1"/>

<xsl:param name="callout.graphics.path">/images/callouts/</xsl:param>

<xsl:param name="callout.graphics.extension">.png</xsl:param>

<xsl:param name="callout.graphics.number.limit">15</xsl:param>

其它图片

<xsl:param name="toc.spacer.image">/images/docbook/blank.png</xsl:param>

<xsl:param name="toc.pointer.image">/images/docbook/arrow.png</xsl:param>

<xsl:param name="toc.blank.image">/images/docbook/blank.png</xsl:param>

<xsl:param name="table.spacer.image">/images/docbook/spacer.png</xsl:param>

<xsl:param name="nav.icon.path">/images/navicons/</xsl:param>

是否章节编号

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

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

<xsl:param name="section.autolabel.max.depth" select="8"/>

顺序浏览

是否在网页最下方显示上一页、下一页，以便可以顺序的浏览整个网站

<xsl:param name="sequential.links" select="1"/>

标题显示位置

<xsl:param name="formal.title.placement">

figure after

example before

equation after

table before

procedure before

task before

</xsl:param>

待定制

<xsl:template name="allpages.banner"/>

$footer.hr

是否要在 footer 之前添加 <hr/>

第一行脚注

左栏显示 rcsdate，调用模板 rcsdate.format

直接显示rcsdate的 value 属性。CSS 样式为 footdate

中间栏

如果不是首页：

显示到主页的链接

<xsl:call-template name="homeuri"/>

<xsl:call-template name="gentext.nav.home"/>

显示预设置链接

<xsl:apply-templates select="$footers" mode="footer.link.mode"/>

右栏显示feedback

定义了 feedback.href 属性？

链接 href

$feedback.with.id 为 1? 则将 page_id 加在 feedback.href 后面

否则只将 feedback.href 作为 feedback 的 URL

链接文字

<xsl:param name="feedback.link.text">Feedback</xsl:param>

第二行脚注

右对齐显示版权信息

<xsl:when test="head/copyright">

<xsl:apply-templates select="head/copyright" mode="footer.mode"/>

</xsl:when>

第三行脚注

如果定义 sequential.links = 1

../common/osx-person-name.xsl

<xsl:param name="local.l10n.xml" select="document('')"/>

模板 <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">

模板 <xsl:template name="person.name.family-given">

chunk-tabular.xsl

用 URI 格式导入 DocBook website XSL: <xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/chunk-tabular.xsl"/>

<xsl:include href="osx-common.xsl"/>

chunk-website.xsl

用 URI 格式导入 DocBook website XSL: <xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/chunk-website.xsl"/>

<xsl:include href="osx-common.xsl"/>

layout.xml 和网页 XML 中的 config

两个定义config 的位置

layout.xml 的 config 条目是缺省属性，作用于所有网页

网页 XML 中定义的 config 覆盖 layout.xml 中定义

为什么不用 xsl 参数定制？

DocBook 用参数配置可以实现文档风格的一致

网站用 config 元素定制，实现网站分隔的多样化

navbgcolor: 导航条背景色

可以在运行时由样式表参数指定

navtocwidth: 导航条宽度

220

可以在运行时由样式表参数指定

homebanner-tabular: tabular 下，导航条顶部，主页时的 LOGO 图像

banner-tabular: tabular 下，导航条顶部，主页之外的其它页面的 LOGO 图像

homebanner: 非 tabular 下，导航条左侧，主页时的 LOGO 图像

banner: 非 tabular 下，导航条左侧，主页之外的其它页面的 LOGO 图像

footer：脚注中部，主页旁，指向外部的 URL 链接

footlink：脚注中部，主页旁，指向本地网页的链接

feedback.href：脚注左侧反馈的 URL

可以在运行时由样式表参数指定

rcsdate：底部脚注左侧显示版本日期

text-prefix

desc

其它

参数定制

<xsl:import href="chunk-tabular.xsl"/>



<xsl:param name="footer.hr" select="0"/>

<xsl:param name="feedback.link.text">Send us feedback</xsl:param>

<xsl:param name="textbgcolor">#C8C8C8</xsl:param>



<xsl:param name="admon.graphics" select="1"/>

定制层初级

自定义名字空间

http://www.opensourcexpress.com/docbook/xsl/current

override file

（重载）

website/tabular.xsl

<xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/tabular.xsl"/>

<xsl:include href="osx-common.xsl"/>

website/website.xsl

<xsl:import href="http://docbook.sourceforge.net/release/website/2.6.0/xsl/website.xsl"/>

<xsl:include href="osx-common.xsl"/>

website/chunk-tabular.xsl

website/chunk-website.xsl

common file

（osx-common.xsl）

最重要的，设置网页编码

<xsl:output method="html" encoding="gb2312" indent="yes"/>

同时，让输出网页进行格式化

设置样式表名称

<xsl:param name="html.stylesheet">/inc/css/website.css</xsl:param>

章节编号

l10n 本地化设置

<xsl:param name="l10n.gentext.default.language">zh_cn</xsl:param>

图标位置

<xsl:param name="admon.graphics.path">/images/docbook/</xsl:param>

<xsl:param name="navig.graphics.path">/images/docbook/</xsl:param>

<xsl:param name="table.spacer.image">/images/docbook/spacer.png</xsl:param>

中文姓名显示方式

<xsl:template name="person.name.family-given">

标题显示位置

<xsl:param name="formal.title.placement">

Google Search Bar

在 tabluar.xsl 中的 webpage.table.footer 模板中添加 google 的 form

<xsl:template name="webpage.table.footer">

另外一个方法是重新定义DTD，增加 google 的元素，并增加相应模板

定制层进阶

website xsl 研究

import & include

GIMP 风格 website

链接

网址

http://developer.gimp.org/

http://netfilter.org/

下载

http://svn.netfilter.org/netfilter/trunk/homepage

gimp

网站结构

目录 gimp-web-devel

README

cvs 维护的网站 xml 源代码

如何创建网站

install.sh

编译网页

将网站同步到本地目录 gimp-web 目录中

rsync -rlt --delete --exclude-from=install.exclude ./ $1

Makefile

先编译子目录 screenshots

用 convert 生成缩略图

再编译网页

ChangeLog

网站更新记录

install.exclude

在网站源代码目录 gimp-web-devel 和目标目录 gimp-web 同步时，应该排除的文件列表

*.xml

网站源代码

目录 gimp-web-devel/xsl

DocBook website 样式表

目录 gimp-web-devel/dtd

DocBook DTD

目录 gimp-web-devel/style

default.css 样式表

website xsl

基本和 netfilter 相同，只是 netfilter 对 gimp 风格进行了微调

具体参见 netfilter 关于 xsl 的描述

netfilter

说明

继承了 gimp 的风格

网页格局进行了微调

将模板 webpage.linkbar 的显示放在网页开头 allpages.banner 下方

增加模板 webpage.sponsor，显示在 webpage.footer 上方，即原 webpage.linkbar 之处

去掉了 webpage.validator 的显示

网站结构

目录 homepage

Makefile

在目录 homepage/xml 下执行 make

网站同步: 将 homepage/output 目录同步到对外的网站目录中

目录 homepage/xml

Makefile

几个 XML 文件，由模板生成

mirrors.xml

documentation/index.xml

$(NETFILTER_POMXMLS)

$(NETFILTER_ADVISORIES)

编译 website 网站

目录 homepage/output

website 网页输出目录

目录 homepage/xsl

DocBook website 样式表

目录 homepage/style

netfilter.css 样式表

website xsl

mine.xsl

全局参数

<xsl:param name="ulink.target" select="''" />

用到的参数

sponsor

layout.xml: <headlink rel="sponsor" href="..." title="image_filename"/>

banner

layout.xml: $autolayout/autolayout/config[@param='banner-left'], @value=image_filename, @altval="image_alt_text"

layout.xml: $autolayout/autolayout/config[@param='banner-right'], @value=image_filename, @altval="image_alt_text"

linkbar

layout.xml: autolayout/headlink[@rel='bookmark'], @value="link_text", @href="..."

显示 @title 内容，链接为 @href

模板 <xsl:template match="webpage">

网页 <head> 部分

<xsl:apply-templates select="head" mode="head.mode"/>

<xsl:apply-templates select="config" mode="head.mode"/>

广告栏

<xsl:call-template name="allpages.banner"/>

linkbar

<xsl:call-template name="webpage.linkbar"/>

网页左侧导航条

<xsl:apply-templates select="$toc">

<xsl:with-param name="pageid" select="@id"/>

</xsl:apply-templates>

左右分隔

<xsl:call-template name="hspacer"/>

网页右侧主体页面

网页标题

<xsl:apply-templates select="./head/title" mode="title.mode"/>

执行 DocBook 样式表

<xsl:apply-templates select="child::*[name(.) != 'webpage']"/>

脚注

<xsl:call-template name="process.footnotes"/>

页脚

<xsl:call-template name="webpage.sponsor"/>

<xsl:call-template name="webpage.footer"/>

模板 <xsl:template name="allpages.banner">

显示 banner-left, banner-right 图像，链接指向主页

模板 <xsl:template match="title" mode="head.mode">

如果 autolayout/config[@param='title'] 不为空，则在标题前面增加 “@value -”

显示 head/title 内容

模板 <xsl:template name="hspacer">

空模板

模板 <xsl:template name="webpage.linkbar">

模板 <xsl:template match="headlink" mode="webpage.linkbar">

如果存在 autolayout/headlink[@rel='bookmark']

显示 @title 内容，链接为 @href

模板 <xsl:template name="webpage.footer">

显示版权信息

如下优先级调用 head/copyright， autolayout/copyright

显示作者信息

<xsl:apply-templates select="$autolayout/autolayout/headlink" mode="webpage.footer" />

模板 <xsl:template match="headlink" mode="webpage.footer">

如果存在 autolayout/headlink[@rel='author']

显示 @title 内容，链接为 @href

模板 <xsl:template name="webpage.sponsor">

模板 <xsl:template match="headlink" mode="webpage.sponsor">

问题

mine.xsl

mine.xsl:44: <xsl:variable name="tocentry" select="$autolayout/autolayout//*[$id=id]"/>

$id=id，应该是 $id=@id !

mine.xsl:84: <xsl:apply-templates select="child::*[name(.) != 'webpage']"/>

child:* 最好写为 chind:node()

mine.xsl:121: <xsl:value-of select="($autolayout/autolayout/toc[@id='home'])[1]/@filename"/>

toc 的 id 没有必要一定是 home!

mytoc.xsl

全局参数

revsionflag 的文字

<xsl:template match="toc">

<xsl:template match="tocentry">

<xsl:template name="insert.spacers">

myxref.xsl

是为了扩展 docbook 的 ulink 的样式表

目的是为 ulink 增加了 mimetype 参数

<xsl:if test="@mimetype">

<xsl:attribute name="type">

<xsl:value-of select="@mimetype"/>

</xsl:attribute>

</xsl:if>

OSX 定制

DocBook

l10n

html/docbook.xsl

<xsl:include href="../common/l10n.xsl"/>

common/l10n.xsl

<xsl:param name="l10n.xml" select="document('../common/l10n.xml')"/>

<xsl:param name="local.l10n.xml" select="document('')"/>

<xsl:template name="gentext.nav.home">

<xsl:call-template name="gentext">

<xsl:with-param name="key" select="'nav-home'"/>

</xsl:call-template>

</xsl:template>

<xsl:template name="gentext">

用全局参数加载文档 XML 文档

<xsl:param name="l10n.xml" select="document('../common/l10n.xml')"/>

<xsl:param name="local.l10n.xml" select="document('')"/>

使用全局参数的好处是，用户可以覆盖 local.l10n.xml，来定制

在 XML 文档中找到对应语种和 key 的节点

<xsl:variable name="local.l10n.gentext"

select="($local.l10n.xml//l:i18n/l:l10n[@language=$lang]/l:gentext[@key=$key])[1]"/>

<xsl:variable name="l10n.gentext"

select="($l10n.xml/l:i18n/l:l10n[@language=$lang]/l:gentext[@key=$key])[1]"/>

xsl:choose 依次选择合适的 gentext

用户自定义（用户本地语种）

<xsl:when test="$local.l10n.gentext">

<xsl:value-of select="$local.l10n.gentext/@text"/>

</xsl:when>

系统预设（用户本地语种）

<xsl:when test="$l10n.gentext">

<xsl:value-of select="$l10n.gentext/@text"/>

</xsl:when>

系统预设（英文）

最后尝试英文的 gentext <xsl:value-of select="($l10n.xml/l:i18n/l:l10n[@language='en']/l:gentext[@key=$key])[1]/@text"/>

<xsl:template name="l10n.language">

如果定义的语种存在返回相应语种

如代码

<xsl:when test="$l10n.xml/l:i18n/l:l10n[@language=substring-before($adjusted.language,'_')]">

<xsl:value-of select="substring-before($adjusted.language,'_')"/>

</xsl:when>

否则返回 $l10n.gentext.default.language

common/l10n.xml

<!ENTITY zh_cn SYSTEM "zh_cn.xml">

...

<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">

...

&zh_cn;

</l:i18n>

common/zh_cn.xsl

<l:l10n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" language="zh_cn" english-language-name="Chinese Simplified">

<l:gentext key="Abstract" text="摘要"/>

...

<l:context name="styles">

<l:template name="person-name" text="first-last"/>

</l:context>

</l:l10n>

定制

语种选择

<xsl:param name="l10n.gentext.default.language">zh_cn</xsl:param>

l10n 本地定制

注意：只能在一处进行定制，否则只有最高优先级的有效

调试 l10n

在文件 common/l10n.xsl 的 gentext 模板中，添加 <xsl:message> 诊断元素

<xsl:template name="gentext">

...

<xsl:if test="$key = 'nav-home'">

<xsl:message terminate="yes">

language: <xsl:value-of select="$lang"/>,

local.l10n.gentext: <xsl:value-of select="$local.l10n.gentext/@text"/>,

l10n.gentext: <xsl:value-of select="$l10n.gentext/@text"/>




</xsl:message>

</xsl:if>

olink

target.database.filename

示例

<targetset>

<document targetdoc="osx" baseuri="http://www.OpenSourceXpress.com">

<div href="/" targetptr="full">

<xreftext>北京群英汇信息技术有限公司</xreftext>

</div>

<div href="/" targetptr="short">

<xreftext>群英汇</xreftext>

</div>

<div href="/" targetptr="web">

<xreftext>http://www.OpenSourceXpress.com/</xreftext>

</div>

</document>

</targetset>

website/olink.xsl

<xsl:template match="olink">

如果有 targetdoc 或者 targetptr 属性，调用系统模板处理 olink

<xsl:apply-imports/>

<xsl:template name="make.olink.href">

参数

olink.key

用 / 分隔 targetdoc, targetptr

target.database

从 target.database 获取属性值至变量

命中 targetdoc/targetptr 的 div|obj 节点的 href 属性值，赋予变量 $target.href

命中 targetdoc 的 document 节点的 dir 属性值，赋予变量 $target.dir

命中 targetdoc/targetptr 的 div|obj 节点的 element 属性值，赋予变量 $target.element

target.database 是否具有 sitemap 元素

若是 $use.sitemap = 1

否则 $use.sitemap = 0

变量 baseuri 赋值

如果 $use.sitemap = 1

必须预先设置 $current.docid 参数，否则不能计算相对 sitemap 路径

以 $current.docid 匹配 document 节点的 targetdoc属性，命中的节点的 dir 属性值，赋予变量 $target.dir

检索路径

否则，即 $use.sitemap = 0 时

获取 $root-rel，并输出

输出 $target.dir，如果不为空

遍历每一个 $target.database，输出 $targetdoc 对应的 baseuri

输出 $baseuri ，如果不为空

输出 targetptr 对应的 href 部分

当 $target.element = 'webpage' 并且 $targetdoc = $targetptr，则不显示 $target.href

否则输出 $target.href

docbook/html/xref.xsl

<xsl:template match="olink" name="olink">

变量

如果带有 id 属性，则显示 anchor，name=@id

如果带有 localinfo 属性，设定变量 localinfo

targetdoc, targetptr 型

如果具有 targetdoc 或者 targetptr 属性

为变量 $target.database.filename 赋值

加载 target.database.filename 至 $target.database

<xsl:variable name="target.database" select="document($target.database.filename,/)"/>

为变量 $olink.key 赋值

<xsl:call-template name="select.olink.key">

为变量 $href 赋值

<xsl:call-template name="make.olink.href">

为变量 $hottext 赋值

<xsl:call-template name="olink.hottext">

为变量 $olink.docname.citation 赋值

<xsl:call-template name="olink.document.citation">

为变量 $olink.page.citation 赋值

<xsl:call-template name="olink.page.citation">

输出

如果 $href 不为空

<xsl:when test="$href != ''">

<a href="{$href}" class="olink">

<xsl:copy-of select="$hottext"/>

</a>

<xsl:copy-of select="$olink.page.citation"/>

<xsl:copy-of select="$olink.docname.citation"/>

</xsl:when>

否则，没有链接只显示文字

<xsl:otherwise>

<span class="olink"><xsl:copy-of select="$hottext"/></span>

<xsl:copy-of select="$olink.page.citation"/>

<xsl:copy-of select="$olink.docname.citation"/>

</xsl:otherwise>

传统型

若具有 linkmode 属性

linkmode 得到 base URI

localinfo 得到文内链接

若 type 属性为 "href"

targetdocent 得到 base URI

localinfo 得到文内链接

<xsl:template name="anchor">

如果具有 id, xml:id 属性，则显示名位 @id 的锚点

docbook/common/olink.xsl

debug!

设定 $olink.debug=1，可以看到调试信息

<xsl:template name="select.olink.key">

<xsl:template name="select.target.database">

检查变量 $target.database.document 指向文件是否存在，若存在，返回该文件名

<xsl:template name="make.olink.href">

ulink

docbook/html/xref.xsl

<xsl:template match="ulink" name="ulink">

$ulink.target

如果定义变量 $ulink.target，则链接的属性 target 指向 $ulink.target

默认 $ulink.target = "_top"

如果是空元素，则 url 属性值作为链接文字

<xsl:when test="count(child::node())=0">

<xsl:value-of select="@url"/>

</xsl:when>

DocBook Tag FAQ

where to Google docbook archive?

http://lists.oasis-open.org/archives/docbook/

<graphic ...></graphic>，报错：end tag for element "GRAPHIC" which is not open

Graphic is empty in DocBook 4.1; replace <graphic></graphic> with <graphic>.

DocBook 5.0

下一次变革？RELAX NG

DocBook Tool Chain

norm's DocBook Processing Diagram（大图！）

验证工具

SGML

SP (sgml parser)

参考资料

主要参考文献

DocBook: The Definitive Guide

DocBook XSL: The Complete Guide

邮件列表存档

archive at OASIS

'http://lists.oasis-open.org/archives/docbook-apps

archive at Red Hat

http://sources.redhat.com/ml/docbook-apps

Howto Search in Google?

<html>搜索: <br>

<blockquote><i>关键字 site:list.oasis-open.org</i></blockquote>

网站参考

Wiki

http://wiki.docbook.org/topic/FrontPage

http://wiki.docbook.org/topic/DocBook

OASIS, DocBook 技术委员会官方网站

DocBook@SourceForge

TDG

norm

'http://nwalsh.com/docbook/procdiagram/index.html

http://sources.redhat.com/docbook-tools

sgmltools.org

文档

教程

http://wiki.docbook.org/topic/DocBookTutorials

TDG

DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner

http://opensource.bureau-cornavin.com/crash-course/

sgml-common

jade

jadetex

docbook-dtdXX-sgml

docbook-style-dsssl

perl-SGMLSpm

docbook-utils

psgml

其它

http://www.markupware.com/

工具

编辑工具

http://wiki.docbook.org/topic/DocBookAuthoringTools

DTD

Style

DSSSL

1.79 at 2004/11/03

XSL

1.69.1at 2005/08/11

其它

website 2.6.0 at 2005/04/18

slides/slides demo 3.4.0 at 2005/04/28

发布工具

http://wiki.docbook.org/topic/DocBookPublishingTools

dblatex

http://dblatex.sourceforge.net/

转换工具

http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator_ng.html

db2omf

http://www.tldp.org/downloads/

texi2db

http://www.tldp.org/downloads/

wt2db

http://www.tldp.org/downloads/

人物

<html><img src="norm.png"><br>

<center>Norman Walsh</center>

http://nwalsh.com

DocBook Technical Committee 主席

Sun公司

TDG主要作者

撰写了大部分的 DocBook XSL 样式表

<html><img src="jclark.png"><br>

<center>James Clark</center>

http://www.jclark.com/

SP (an open-source SGML parser)

DSSSL

Jade (James' DSSSL Engine)

关于本文

版本

0.1, 2006/01/20

2006/05/03 提交到 Whodo

作者

Jiang Xin

格式定义：DTD

格式

XML DTDs

如： docbook-xml-4.5b1.zip

SGML DTDs

如： docbook-4.5b1.zip

rng (RELAX NG Grammars )

如： docbook-rng-4.5b1.zip

xsd (W3C XML Schema Grammars)

如： docbook-xsd-4.5b1.zip

版本

5.0

用 RELAX NG 语法重构

格式

rng (RELAX NG Grammars )

对语法进行了删减，因而很多语法不向下兼容

大多之前定义的文档不需要修改

存在兼容性问题的，移植也很简单

4.5

存在 xml 和 sgml 两种格式

4.5 和 5 的差异

http://www.docbook.org/tdg5/en/showdiff.html

下载

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

谁在维护

OASIS Technical Committee

主席: Norman Walsh

格式转换：Scheme

XSL

what is it

XSL 通过 XSLT 将一种 XML 转换为另一格式的 XML

FOP

直接转换生成 PDF

JFOR

直接转换生成 rtf

PassiveTex

DocBook - FO - TeX - DVI - Postscript - PDF

出版工具

出版工具即DocBook 转换为可打印或者 WEB 页面

参见: http://wiki.docbook.org/topic/DocBookPublishingTools

DocBook 专有工具

DBLaTeX

web: http://dblatex.sourceforge.net/

版本: 0.1.8

0.1.8 版本不支持 Unicode/中文！

GemDoc

Web: http://www.gemdoc.net/

http://g1c.com/gemdoc/

Windows 软件，版本: 1.3.2

未注册版本会在文章下面加上一个链接

XSLT Engines

SAXON

参见: http://saxon.sourceforge.net/

版本: 8.6.1

xsltproc

xmlto

FO engines

FOP

http://xmlgraphics.apache.org/fop/download.html

版本: FOP 0.90 alpha 1

DSSSL 出版工具

OpenJade

http://openjade.sourceforge.net/

JadeTex

http://jadetex.sourceforge.net/

编辑工具

http://wiki.docbook.org/topic/DocBookAuthoringTools

写字板 8)

emacs

OpenOffice

http://xml.openoffice.org/xmerge/docbook/UserGuide.html

Eclipse

FOP

需要的软件

FOP 版本

0.20.5

0.91beta

fop 中 cygpath，会遇到 filename too long 的问题!

解决办法: 重新用 shell 实现一个 mycygpath，用 awk 分解再组合

函数 mycygpath

JDK

图像处理

JAI

安装

安装 Java, JAI

解开 fop 压缩包即可

export FOP_OPTS="-Xms100m -Xmx200m"

运行

扩大内存以及堆栈

fop 可能会用到更多的内存和 heap

传递 "-Xms100m -Xmx200m" 参数给 JVM

可以设置 FOP_OPTS 变量

export FOP_OPTS="-Xms100m -Xmx200m"

-Xmx

Xmx是java的一个选项，用来设置你的应用程序能够使用的最大内存数（看好，致使你的应用程序，不是整个jvm）,如果你的程序要花很大内存的话，那就需要修改缺省的设置，比如配置tomcat的时候，如果流量啊程序啊都很大的话就需要加大这个值了，不过有一点是要记住的，不要大得超过你的机器的内存，那样你的机器会受不了的，到时候就死翘翘了。

-Xms

Xms是另一个设置内存的参数,用它来设置程序初始化的时候内存栈的大小，增加这个值的话你的程序的启动性能会得到提高。不过同样有前面的限制，以及受到xmx的限制。

另外，一个操作系统通常都只使用jvm，这就是你说的“运行在同一个JVM中的程序”，不同的虚拟机的实现虽然千差万别，但是他们的运行模式都是一样的，只是性能有所不同罢了。

FOP 中文化

http://xmlgraphics.apache.org/fop/0.20.5/fonts.html

http://www.javaranch.com/journal/200409/CreatingMultipleLanguagePDFusingApacheFOP.html

Use the special xsl to build fo.

(And the FOP has bug to handle FO file which language is zh_cn, So you may have to replace language="zh_cn" to language="zh")

Must have the Chinese font files and use org.apache.fop.fonts.apps.

TTFReader to build the font metrics-files. And build pdf with '-c userconfig.xml' option.

DocBook FOP XSL 中文化

字体设置需要修改

<xsl:param name=“body.font.family”>SimSun</xsl:param>

<xsl:param name=“body.font.size”>12</xsl:param>

<xsl:param name=“title.font.family”>SimSun</xsl:param>

字体大小

语言选项

由于fop 只识别 zh，不识别 zh_cn 或 zh_tw，因此需要修改

language="zh_cn" 为 language="zh"

增加中文字体

中文 TrueType 字体

直接引用 Windows 的即可

由 FOP TTFReader 生成的 matrics 文件

cd fop

java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimSun c:\windows\fonts\simsun.ttc simsun.xml

java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader -ttcname SimHei C:\WINDOWS\Fonts\simhei.ttf simhei.xml

配置文件 fop/conf/userconfig.xml

在 <fonts></fonts> 之间增加

修改 fop.sh

设置 JAVA_HOME 环境变量

增加 JVM 堆栈大小

FOP_OPTS="-Xms100m -Xmx200m"

$JAVACMD -classpath ... $FOP_OPTS org.apache.fop.apps.Fop ...

传递配置文件 userconfig.xml 给 FOP

... org.apache.fop.apps.Fop -c e:/Home/WORK/project/subversion/svnbook/src/tools/fop/conf/userconfig.xml

示例

FOP_OPTS="-Xms100m -Xmx200m"

$JAVACMD -classpath "$LOCALCLASSPATH" $FOP_OPTS org.apache.fop.apps.Fop -c e:/Home/WORK/project/subversion/svnbook/src/tools/fop/conf/userconfig.xml "$@"

FOP 已知问题

章节标题不能太长，即 <title>...</title> 中文字不能太多，否则中断执行

如果设置表格列宽，可能造成 fop 死循环

如