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 位置

<?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 prefer="public" xml:base="file:///usr/share/xml/" >

<public

publicId="-//OASIS//DTD DocBook XML V4.4//EN"

uri="docbook44/docbookx.dtd"/>

<system

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

uri="docbook44/docbookx.dtd"/>

<system

systemId="docbook4.4.dtd"

uri="docbook44/docbookx.dtd"/>

</group>

</catalog>

uri 定位 XSL 样式表位置

（本地到本地）

uri 将 web 地址对应本地文件

（URL 到本地）

<?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">

<system

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

uri="file:///usr/share/xml/docbook44/" />

<uri

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

uri="file:///usr/share/xml/docbook-xsl-1.68.1/html/docbook.xsl" />

<uri

name="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"

uri="file:///usr/share/xml/docbook-xsl-1.68.1/html/chunk.xsl" />

</catalog>

rewriteSystem 建立重写规则，

简化、合并 URI 项

<?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">

<rewriteSystem

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

rewritePrefix="file:///usr/share/xml/docbook44/" />

<rewriteURI

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

rewritePrefix="file:///usr/share/xml/docbook-xsl-1.68.1/" />

</catalog>

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 定制