Docbook

From PostgreSQL 中文维基, PostgreSQL 中文站, PostgreSQL 中国社区, PostgreSQL Chinese community

docbook 已经成为了 Unices 系统上的准文档标准

libxml 的 xsltproc 普遍用来处理 docbook 的 xml

xsltproc 有默认的 catalog 加载：

luoyi@skyking:/export/m1/luoyi/asciidoc$ strings /usr/bin/xsltproc  |grep /etc/xml
                 file:///etc/xml/catalog are activated by default

因此，查看 /etc/xml/catalog 可以得知系统的 docbook 配置：

luoyi@skyking:/export/m1/luoyi/asciidoc$ head /etc/xml/catalog
<?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">
  <delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML" catalog="file:///etc/xml/docbook"/>
  <delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML" catalog="file:///etc/xml/docbook"/>
  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file:///etc/xml/docbook"/>
  <delegateURI uriStartString="http://www.oasis-open.org/docbook/" catalog="file:///etc/xml/docbook"/>
  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.1.2/" catalog="file:///etc/xml/docbook"/>
  <delegateURI uriStartString="http://www.oasis-open.org/docbook/xml/4.1.2/" catalog="file:///etc/xml/docbook"/>
  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/" catalog="file:///etc/xml/docbook"/>

可以看到，/etc/xml/catalog 文件把所有和 docbook 相关的 XML 元素（sorry，我搞不清楚 XML 里那些概念，暂时用“元素”这个词笼统概括一下）都重定向到 /etc/xml/docbook ：

luoyi@skyking:/export/m1/luoyi/asciidoc$ head /etc/xml/docbook
<?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">
  <public publicId="-//OASIS//DTD DocBook XML V4.5//EN" uri="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/>
  <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.5//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/calstblx.dtd"/>
  <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/soextblx.dtd"/>
  <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.5//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/dbpoolx.mod"/>
  <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.5//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/dbhierx.mod"/>
  <public publicId="-//OASIS//ELEMENTS DocBook XML HTML Tables V4.5//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/htmltblx.mod"/>
  <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.5//EN" uri="file:///usr/share/xml/docbook/xml-dtd-4.5/dbnotnx.mod"/>

/etc/xml/docbook 又把这些 XML 元素定向到 docbook 对应版本的发布目录，在这个机器上是 /usr/share/xml/docbook：

luoyi@skyking:/export/m1/luoyi/asciidoc$ ls /usr/share/xml/docbook/
xml-dtd-4.5/  xsl-stylesheets-1.72.0/

docbook 的发布包由 dtd 和 xsl-stylesheets 组成，可以到 sf.net 上下载最新的 Release

asciidoc 生成的 docbook 用的 docbook 版本：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ head ./lbook.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

因此我们到 /etc/xml 下面找 *DTD DocBook XML V4.2//EN* 被变成啥了：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ grep -A 2 'DTD DocBook XML V4.2' /etc/xml/*
/etc/xml/docbook:  <public publicId="-//OASIS//DTD DocBook XML V4.2//EN" uri="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"/>
/etc/xml/docbook-  <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2" rewritePrefix="file:///usr/share/xml/docbook/xml-dtd-4.5"/>
/etc/xml/docbook-  <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2" rewritePrefix="file:///usr/share/xml/docbook/xml-dtd-4.5"/>

可以看到它们都变成 /usr/share/xml/docbook/xml-dtd-4.5 目录下的东西了。

以上是 DTD 的定义。

asciidoc 对 docbook 的 xsl 做了一些修修补补，因此自带了一个目录 docbook-xsl，来看生成 fo 文件所用的 xsl 文件：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ grep -A 3 'xsl:stylesheet' ../asciidoc-8.2.6/docbook-xsl/fo.xsl
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
<xsl:import href="common.xsl"/>

/etc/xml/catalog 里面对 http://docbook.sourceforge.net/release/xsl/ 作了重定向：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ grep 'http://docbook.sourceforge.net/release/xsl' /etc/xml/*
/etc/xml/catalog:  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/1.72.0" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
/etc/xml/catalog:  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/1.72.0" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
/etc/xml/catalog:  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
/etc/xml/catalog:  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>

也就是说我们所需要的所有的 docbook 文件都会到 /usr/share/xml/docbook/xsl-stylesheets-1.72.0 去访问。

我们一般来说都只需要升级 xsl ，以利用 docbook 新增的页面展现能力，只需要改 /etc/xml/catalog 即可：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ tail -n 11 /etc/xml/catalog
<!--
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/1.72.0" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/1.72.0" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.72.0"/>
  -->
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/1.73.2" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.73.2"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/1.73.2" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.73.2"/>
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.73.2"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="/usr/share/xml/docbook/xsl-stylesheets-1.73.2"/>
</catalog>

从 sf.net 下载 xsl-stylesheets ，直接解压缩到 /usr/share/xml/docbook 下对应的位置，即完成升级：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ ls /usr/share/xml/docbook/
xml-dtd-4.5/  xsl-stylesheets-1.72.0/  xsl-stylesheets-1.73.2/

在生成的 chunked-html 文件中，可以看到：

这样的信息，说明已经采用了升级后的 docbook 来生成文档。

docbook doctype = book 时，生成的 pdf 没有 revhistory；而 doctype = article 时，有 revhistory。

也许 docbook 官方认为 doctype = book 的时候，revhistory 不太好看吧，不过总是有人想要这个东西。

首先来看看这个现象的原因：

revhistory 这样的信息的展现，定义在：titlepage.templates.xsl 中（也就是它所在的地方应该是 titlepage）。

两个名词：recto （书籍的正封面） verso （书籍的内封面）

这是 book 类型的 titlepage 节选，注意它里面没有 revhistory：

  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/corpauthor"/>
  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/corpauthor"/>
  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/authorgroup"/>
  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/authorgroup"/>
  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/author"/>

这是 article 类型的 titlepage 节选，我把有 revhistory 的贴出来了：

NOTE: article 只有 recto 没有 verso ！

  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/pubdate"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/pubdate"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/pubdate"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revision"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revision"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revision"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revhistory"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revhistory"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revhistory"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/abstract"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/abstract"/>
  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/abstract"/>

由此可知，要给 book 类型增加 revhistory，主要就是做出合适的 fo/titlepage.templates.xsl 文件。从[DocBook 权威指南] 得知，该 xsl 文件是从 fo/titlepage.templates.xml 生成而来。因此最根本的方法是修正 fo/titlepage.templates.xml 文件：

luoyi@skyking:/usr/share/xml/docbook/xsl-stylesheets-1.73.2$ diff -u fo/titlepage.templates.xml.ORIG fo/titlepage.templates.xml
--- fo/titlepage.templates.xml.ORIG     2008-05-13 11:15:56.000000000 +0800
+++ fo/titlepage.templates.xml  2008-05-14 13:15:45.000000000 +0800
@@ -157,6 +157,7 @@
       <corpauthor/>
       <authorgroup t:named-template="verso.authorgroup"/>
       <author/>
+      <revhistory/>
       <othercredit/>
       <releaseinfo space-before="0.5em"/>
       <pubdate space-before="1em"/>

生成 fo/titlepage.templates.xsl 文件的方法：

luoyi@skyking:/export/m1/luoyi/asciidoc/lbook$ cat docbook_revbook.sh
#!/bin/sh
DOCBOOK=/usr/share/xml/docbook/xsl-stylesheets-1.73.2
xsltproc -o $DOCBOOK/fo/titlepage.templates.xsl $DOCBOOK/template/titlepage.xsl $DOCBOOK/fo/titlepage.templates.xml

取自"http://www.pgsqldb.org/mwiki/index.php/Docbook"

Docbook

From PostgreSQL 中文维基, PostgreSQL 中文站, PostgreSQL 中国社区, PostgreSQL Chinese community

Views

Personal tools

导航

搜索

工具