docbook——不错的文档编辑格式

Edit by King      

docbook是什么？它既不是一个文档标准，也不是一个文档编辑器，它仅仅是一份XML文档。docbook通过DTD（scheme）来规范一个XML文档，并且根据这些标签，通过xslt将XML转换成可视化程度更高、使用范围更加广泛的文档（如html, chm, pdf等）。

      以前编辑文档的时候，总是会遇到页面样式的问题。在写文档本身的时候，还要顾及到文档的最后展示的样子，在不断编写文本的时候，需要同时调整格式。使用docbook最大的好处，就在于内容和页面样式完全分离，在编辑的使用，只需要使用标准的标签，不用过多的考虑使用的样式。而这些标签在转换后，都会变成对应的class，直接通过css来改变整体的样式。

      还有一个问题，就是文档保存的格式，有的人习惯查看chm的文档，有的人则喜欢chm格式，或者是html格式（如果在服务器上分发）。docbook作为XML格式的文本，就很好的充当了这些格式的中间状态，通过xslt，可以很方便的转换成其他格式（不过pdf在中文显示上有点问题）。而且，docbook的标签本身就具备可读性。

      说了这么多关于docbook的东西，简单来介绍下写法。（推荐看下《DocBook : The Definitive Guide》这本书。）docbook中最基本的几个标签，就是<book></book>标签，表示一本书，<chapter></chapter>标签用来表示章节。这里再说一个它的有点，就是所有的有序序列（如章节序列、有序列表、小节序列）都不用关注序列编码，在进行xslt转换的时候会自动进行编码。

      文档中，很多地方都可能会引用源代码，docbook有<programlisting>标签，可以指定一个language属性。这个属性在进行标准的xslt的时候，不能被正常的转换，需要使用扩展的xslt进行转换。我平时使用xslthl来进行转换，可以支持ini, c, c++, java, xml等语言的高亮。同时可以修改xsl文件，来指定对应属性的高亮（如关键字、属性、注释）颜色。

     docbook能够使用的标签有很多，可以去网上慢慢找下（不过不幸的是，官方网站http://www.docbook.org/ 貌似被墙，需要使用代理了）。平时真正使用到的，除了前面说到的，可能也只有para, example, sect1等。最后贴下目前使用的xsl文件（首先需要下载docbook提供的xsl文件，这里展示的基本都是对原文件的配置）：

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xslthl="http://xslthl.sf.net"
exclude-result-prefixes="xslthl"
version="1.0">

<!--调用样式表-->
<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh5/current/html/docbook.xsl"/>

<xsl:param name="chunker.output.encoding" select="'utf-8'"/> 
<!--标准信息所使用的语言-->
<xsl:param name="l10n.gentext.language" select="'zh_cn'"/>
<!--指定样式表-->
<xsl:param name="html.stylesheet" select="'docbook.css'"/>
<!--对于警告类信息是否使用图形 0 1-->
<xsl:param name="admon.graphics" select="1"/>

<xsl:param name="highlight.source" select="1"/>

<xsl:param name="base.dir" select="'target/single/'"/>

<!--生成的 HTML 文件内容是否进行缩排 yes no-->
<xsl:param name="chunker.output.indent" select="'yes'"/>
<!--给节编号 0 1-->
<xsl:param name="section.autolabel" select="1"/>
<!--节的编号是否包含章的编号 0 1-->
<xsl:param name="section.label.includes.component.label" select="1"/>
<!--表格边框的属性是否使用预设 CSS 来指定-->
<xsl:param name="table.borders.with.css" select="0"/>
<!--参考书目是否进行编号-->
<xsl:param name="bibliography.numbered" select="1"></xsl:param>


<!--目录深度-->
<xsl:param name="toc.max.depth" select="2"/>
<!--sect#页面上显示目录-->
<xsl:param name="generate.section.toc.level" select="0"/>
<!--sect#可以生成目录条目-->
<xsl:param name="toc.section.depth" select="2"/>
<!--目录中收录哪些内容-->
<!--包括 toc,title,figure,table,example,equation -->
<!-- nop 为空 -->
<xsl:param name="generate.toc">
appendix  toc
article/appendix  nop
article   toc,title
book      toc,title,example
chapter   toc,title
part      toc,title
preface   toc,title
qandadiv  toc
qandaset  toc
reference toc,title
sect1     toc
sect2     toc
sect3     toc
sect4     toc
sect5     toc
section   toc
set       toc,title
</xsl:param>

<!--在源码中插入 <?linebreak?> 标记，生成 Html 时替换为<br> -->
<xsl:template match="processing-instruction('linebreak')">
<br/>
</xsl:template>

<xsl:template match="xslthl:string" mode="xslthl">
<b class="hl-string"><xsl:apply-templates mode="xslthl"/></b>
</xsl:template>

<xsl:template match="xslthl:comment" mode="xslthl">
<i class="hl-comment" ><xsl:apply-templates mode="xslthl"/></i>
</xsl:template>

<xsl:template match="xslthl:directive" mode="xslthl">
<span class="hl-directive" style="color: maroon"><xsl:apply-templates mode="xslthl"/></span>
</xsl:template>

<xsl:template match="xslthl:tag" mode="xslthl">
<b class="hl-tag" style="color: #000096"><xsl:apply-templates mode="xslthl"/></b>
</xsl:template>

<xsl:template match="xslthl:attribute" mode="xslthl">
<span class="hl-attribute" style="color: #F5844C"><xsl:apply-templates mode="xslthl"/></span>
</xsl:template>

<xsl:template match="xslthl:value" mode="xslthl">
<span class="hl-value" style="color: #993300"><xsl:apply-templates mode="xslthl"/></span>
</xsl:template>

<xsl:template match="xslthl:html" mode="xslthl">
<b><i style="color: red"><xsl:apply-templates mode="xslthl"/></i></b>
</xsl:template>

<xsl:template match="xslthl:xslt" mode="xslthl">
<b style="color: #0066FF"><xsl:apply-templates mode="xslthl"/></b>
</xsl:template>

<!-- Not emitted since XSLTHL 2.0 -->
<xsl:template match="xslthl:number" mode="xslthl">
<span class="hl-number"><xsl:apply-templates mode="xslthl"/></span>
</xsl:template>

<xsl:template match="xslthl:annotation" mode="xslthl">
<i><span class="hl-annotation"><xsl:apply-templates mode="xslthl"/></span></i>
</xsl:template>

<!-- Not sure which element will be in final XSLTHL 2.0 -->
<xsl:template match="xslthl:doccomment|xslthl:doctype" mode="xslthl">
<b class="hl-tag" style="color: blue"><xsl:apply-templates mode="xslthl"/></b>
</xsl:template>

</xsl:stylesheet>