当前位置: 首页 > 工具软件 > DocBook XSL > 使用案例 >

DocBook在Linux上的使用

姬锐
2023-12-01

DocBook在Linux上的使用

lli_njupt


1. 什么是DocBook

微软的Word实现了所见即所得的编辑方式,通常情况下它可以满足需求,甚至一些庞大的项目,使用它依然可以完成。但是当你尝试编写 一些需要嵌入特殊符号的文档时,比如源码,它总很难让人满意。一种非所见即所得的编辑方式是另外一种选择,它的出现甚至要早于Word。

DocBook有超出 15 年的历史了。它在 1991 年开始作为 HaL 和 O'Reilly 的合作项目。随着它的流行和成长,最后产生了自己 的维护组织,Davenport 组织。在 1998 年中期,它成为结构化信息标准促进组织(OASIS)的一个技术委员会(TC)。从 DocBook V5.0 开始,DocBook使用用 RELAX NG 和图解定义的 XML 词汇表。但是DocBook 比这些技术都早。它最初是用标准 SGML 文档类型 定义来描述的 SGML 词汇表,或者 DTD。——DocBook 5.0权威指南

总而言之,DocBook使用RELAX NG 和 XML词汇表作为标记来对文档排版和定制,并提供各种输出格式:html,pdf等。 一个Linux上的简单示例只需要两个文件*.xml和*.xsl,和一个应用程序xsltproc。.xml文件使用DocBook定义的标记对内容进行封装, 它的语法与html没有任何本质区别。这些标记指明了哪里是文档名,哪里是作者,哪里是文档段等等。所以我们的word文档就变成了.xml文件。 它是我们编辑的结果。.xsl是.xml文件转换为其他格式时所需要的规则,比如一个article标记怎么就转换为了html文件中的html和head标记。 xsltproc则是转换的工具,它用C语言写成,它的作用就是使用.xsl作为规则,转换.xml文件到目标文件。

2. DocBook的安装和使用

2.1. 安装DocBook

这里是一篇在Windows环境使用DocBook的文档。这里介绍在Linux环境中的使用,测试环境为:Linux ubuntu 10.0。DocBook并不是一个应用程序,它可以被看作一个环境,对DocBook的安装就是对DocBook环境的配置,一个最简环境包括xsltproc和一个.xsl转换文件。默认情况下,系统上已经安装了xsltproc,如果没有,使用以下命令安装:

#apt-get install xsltproc

http://sourceforge.net/projects/docbook/files/下载docbook-xsl-ns,它里面包含了转换所用的.xsl文件。到这里,一个基本的DocBook测试 环境就完成了。

2.2. 使用DocBook

文档http://www.ha97.com/book/OpenSource_Guide/index.html的第27章对DocBook的标记做了非常详细的讲解和演示。这里假设编辑一个test.xml文件。注意文件中指定的encoding="utf-8"编码方式,编辑器必须使用相同的编码方式对.xml进行编辑。另外.xml文件标记是大小写不敏感的,但是,它的开始标记和对应的结束标记必须一致。

这里下载最新的docbook-xsl-ns-1.75.2.tar.bz2,解压开后,查看README:

fo/docbook.xsl              - for XSL-FO
  fo/profile-docbook.xsl      - for XSL-FO (single-pass profiled)

  html/docbook.xsl            - for HTML (as a single file)
  html/chunk.xsl              - for HTML (chunked into multiple files)
  html/onechunk.xsl           - for HTML (chunked output in single file)
  html/profile-*              - for HTML (single-pass profiled versions)

  xhtml/*.xsl                 - for XHTML versions of the above

  htmlhelp/htmlhelp.xsl       - for HTML Help
  javahelp/javahelp.xsl       - for JavaHelp
  eclipse/eclipse.xsl         - for Eclipse Help

  manpages/docbook.xsl        - for groff/nroff man pages[1]
  [1] more information at http://wiki.docbook.org/topic/ManPages

  roundtrip/*.xsl             - for DocBook to WordML, etc., to DocBook

docbook-xsl-ns提供了转换fo,html,xhtml,manpages等对应的xsl文件。我们这里关心html文件夹,对应的.xsl是html/docbook.xsl。注意到文件中的如下规则:

<xsl:output method="html"
            encoding="ISO-8859-1"
            indent="no"/>

这里的encoding="ISO-8859-1"指明了转化后的.html文件的编码方式。显然对应含有中文的文档这种编码并不合适。需要改成encoding="UTF-8"。以下是测试的最终命令,注意./docbook-xsl-ns-1.75.2/html/docbook.xsl的路径。

xsltproc -o test.html ./docbook-xsl-ns-1.75.2/html/docbook.xsl test.xml

2.3. Makefile

即便是最精简的参数,转换.xml文件的命令依然太过冗长,没有人愿意每次都使用命令行。一个简单的Makefile将节约大量的调试时间。

XSLPATH=./docbook-xsl-ns-1.75.2/html
XSLFILE=$(XSLPATH)/docbook.xsl

XML_FILE=$(wildcard *.xml)
HTML_FILE=$(XML_FILE:.xml=.html)

all: $(HTML_FILE)

%.html : %.xml
        xsltproc -o $(@F) $(XSLFILE) $<

clean:
        rm -f *.html

2.4. 如何使用css

使用css层叠样式单,将使转化后的文档更美观,控制也更灵活。参数--stringparam html.stylesheet styles.css 将满足这个要求,把它加入到Makefile中的xsltproc行中,注意styles.css是一个示例名,它应该根据实际进行替换。

XML_FLAGS=--stringparam html.stylesheet styles.css 
		xsltproc -o $(@F) $(XML_FLAGS) $(XSLFILE) $<

使用一个成熟的.css文件模板是必要的,毕竟不是所有人都是css专家,也没有人总是喜欢发明轮子。附件中提供了一个akabook使用的styles.css文件,它基本可以满足通常的需求。

2.5. 章节自动编号

对章节自动编号,是非常强大的和基本的功能,添加参数--stringparam section.autolabel 1 :

XML_FLAGS=--stringparam html.stylesheet styles.css section.autolabel 1 
		xsltproc -o $(@F) $(XML_FLAGS) $(XSLFILE) $<

所有通过命令行添加的--stringparam 都可以更改.xsl来实现,这里不做深入探讨,相关的文件中有详细的介绍。还是在实践中掌握DocBook的使用吧。

2.6. 在vim中编译

待续......


 类似资料: