个人工具

UbuntuHelp:DocBook/zh

来自Ubuntu中文

跳转至: 导航, 搜索

目的

本页的目的是提供一个 DocBook 格式的概述。它介绍此格式的一些优点,提供关于此格式更多的阅读的链接,同时包含了一个简短的教程。

DocBook是什么?

DocBook是一个用于当今许多文档编制任务中的基于XML的标准。当你想要创建一个DocBook文档源码时,你需要编写XML文件来描述文档布局、段落界限和其它属性。如果你此前曾经见过HTML源码,你可能会觉得XML文件的结构很熟悉。XML更像是老式的HTML的改进,它可以用于生成完整的网页页面和其它的标记文档。

DocBook的优点是什么?

DocBook是一个OASIS标准,是大部分开源项目存储它们文档的格式。DocBook是开源应用程序。这个项目在Souce Forge主办,且在GPL下可用。DocBook可用于文档类型定义(DTD)和XML模式(XSD)。此项目有一个跨越开源和商业群体的大的开发者和支持社区。 项目使用DocBook的最重要的原因包括如下:

  1. DocBook 是一个标准
  2. DocBook 是开源的
  3. DocBook 被用于大部分大项目
  4. DocBook 有一个大的开发者和支持社区

DocBook同样是一个为文档编制团队解决了许多发布问题的XML应用程序和XML技术。解决的问题包括如下:

  • Single-sourcing
  • 协同创作
  • 跨平台编辑
  • 多通道发布
  • 提升信息质量和一致性
  • Enhancing functionality of electronic output
  • Negating vendor lock-in

关于以上几点更多的信息请查阅 http://www.sastc.org.za/index.php?option=com_content&task=view&id=18&Itemid=35 如果你已经理解了XML那么你将很轻易的开始学习DocBook。如果你还不知道XML,那么好消息是,学习DocBook将有助于你学习XML。以下是任何人开始学习DocBook必读的两本书。

进一步阅读

如果你已经安装了'docbook-defguide'包,你可以通过你的网页浏览器用如下地址获得指南:

 
http://localhost/doc/docbook-defguide/html/docbook.html (assuming that your Apache still has /doc aliased to /usr/share/doc) 

你也可以使用如下命令获得它:

 
lynx /usr/share/doc/docbook-defguide/html/docbook.html

同时阅读这些作品对实践也是有用的。想要实践的话,你需要一个XML发布工具和一个XML编辑器。DocBook网站和Wiki将为你提供关于工具和编辑器的更多信息的链接。你可以使用这些工具和编辑器来编写DocBook文档。 "[Ubuntu DocBook Interchange Protocol]"中说明了在Ubuntu文档编制项目中对DocBook的使用。

快速教程

DocBook看起来像什么?

就像HTML那样,DocBook定义了一定数量的“标签”。要设置作者名称你可以就像这样写...

<author>
Christoph Haas
</author>

如同你看到的,这和HTML非常相似。以下是一个完整的XML文档,是一个有用的例子。 用于书写这些标签的“flavor”就是XML。因此它被称为DocBook/XML。(另外的一个'flaovr'将是相差不是很大的SGML。XML比SGML要严格。HTML是SGML语言中的一种。大部分人反对SGML,所以Debian中的文档现在被转换成了XML格式的。)即使你还没有使用过XML你也应该不会有太大问题。

样式表

要创建针对你的XML输入的相应的输出文档,你同样需要一个样式表。样式表被称为“XSL转换”(XSLT),用“可扩展样式表语言”(XSL)写成。 本质上,XSLT描述了如何将一个文档转换成另外一个。 通常你不需知道样式表的样子。 你也需要一个“处理器”来使用XML和XSLT并创建相应的输出文件。我们将使用免费的“xsltproc”程序来达到这个目的。 你可将你的文档转换成如下一些可用的样式表:

  • Postscript
  • PDF
  • XHTML
  • man
  • texinfo

有些转换器可以将DocBook转换成Yelp。Yelp是Gnome帮助格式。

Hello World

首先你需要安装如下程序包:

- xsltproc (the XSL Transformations Processor)
- docbook-xsl (stylesheets for HTML, XHTML, HTML Help and others)
- docbook-defguide (The Definitive Guide to DocBook - recommended)

输入如下行到一个文件中,并命名此文件为test.xml:

 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://docbook.org/xml/4.2/docbookx.dtd">
<article>
  <title>My first DocBook document</title>
  <sect1>
     <title>The greeting</title>
     <para>
       Hello world
     </para>
  </sect1>
</article>

请注意,你应该使用UTF-8来进行字符编码。 你也可以将你的终端或者编辑器转换成UTF-8模式。 运行这个命令:

xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml

你应该可以在当前路径发现一个叫“test.html”的文件。使用你最喜欢的网页浏览器来查看它。 现在你发现那一行命令干了些什么了吗? “xsltpro”是转换程序。“-o test.html'”设置输出文件。下一个参数“.../docbook.xsl”是你用于转换的样式表 —— 它将XML转换成XHTML。然后最后“test.xml”告诉xsltproc你的输入文件的位置。

定制样式表

看到DocBook输出文件,你大概会失望了。能够自动转换文档很好,可是它可能根本不符合你的网页设计或“企业形象”。然而还是有补救方法的。 样式表一般提供了一定数量的参数以供你调整。通常你可以导入“标准”样式表来写你自己的样式表。比如:

 
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
   <xsl:param name="toc.max.depth">1</xsl:param>
   <xsl:param name="html.stylesheet" select="'/ubuntu.css'"/>
   <xsl:template name="user.header.content">
     <a href="/">Back to main page</a>
   </xsl:template>
</xsl:stylesheet>

这个样式表首先导入前面提到的docbook.xsl。 它也设置了几个参数:

  • 设置TOC(table of contents)的最大深度为“1”。这样只有<sect1>节可以被包含在TCO中。
  • 最终的XHTML文档将会使用“ubuntu.css”样式表(CSS)。
  • 在页面的顶端包含一个到主页的链接。

这些设置只在XHTML样式表中起作用。对于其它的输出格式你需要其它的设置。上面的设置记录在/usr/share/doc/docbook-xsl/doc/html/index.html 中 你也可以参考http://www.sagehill.net/docbookxsl/

Makefile

如果你多个XML文件或样式表,你也许要在一个Makefile中完成所有的处理。例如:

 
# Add your language file here:
TARGETS = faq.html

XSLTPROC = /usr/bin/xsltproc
XSL = ubuntu.xsl

%.html: %.xml $(XSL)
   @$(XSLTPROC) -o $@ $(XSL) $<

all: $(TARGETS)

clean:
   @rm -f *.html

DocBook 到 PDF

将一个DocBook转换成PDF的最简单的方法是安装xsl-fo样式表(转换成FO格式)和fop(转换FO为PDF格式)。因为一些原因,xsl-fo样式表在docbook-xsl-doc-pdf软件包中。

sudo aptitude install fop docbook-xsl-doc-pdf

现在转换你的DocBook文件为PDF,运行:

xsltproc -o intermediate-fo-file.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl input-docbook-file.xml
fop -pdf final-pdf-file.pdf -fo intermediate-fo-file.fo

这里是一个针对名为“networkmanager-manual.xml”的DocBook的Makefile例子:

STYLESHEETS_DIR = /usr/share/xml/docbook/stylesheet/nwalsh

all: html pdf

html:
	xsltproc -o networkmanager-manual.html $(STYLESHEETS_DIR)/xhtml/docbook.xsl networkmanager-manual.xml

fo:
	xsltproc -o networkmanager-manual.fo $(STYLESHEETS_DIR)/fo/docbook.xsl networkmanager-manual.xml

pdf: fo
	fop -pdf networkmanager-manual.pdf -fo networkmanager-manual.fo

clean:
	rm -rf networkmanager-manual.html networkmanager-manual.fo networkmanager-manual.pdf

要想使用这个makefile,只需要将输入输出名字改为任何你想要的名字。 “注意:”W3组织已经锁定了未知用户代理对关键DTD文件的下载。因此(至少在Karmic中)fop将抛出一个TransformerException异常,警告W3服务器返回了一个503 HTTP响应。工作区好像要建立一个本地的DTD仓库,在herehere中有提到。dblatex程序也可以这么做。 Toucdhown! That's a really cool way of putting it!