“UbuntuHelp:DocBook/zh”的版本间的差异

2010年6月17日 (四) 18:51的版本

本条目正在从其他语言的文档内容翻译成中文。 欢迎您积极参与翻译与修订。

文章出处:

https://help.ubuntu.com/community/DocBook

翻译人员:

麻辣丝瓜

点击翻译:

English  • 中文

目的

本页的目的是提供一个 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必读的两本书。

进一步阅读

• Doc'Book - The Definitive Guide http://www.docbook.org/tdg/en/html/docbook.html
• Doc'Book XSL – The Complete Guide http://www.sagehill.net/docbookxsl/index.html
• Doc'Book crash course: http://opensource.bureau-cornavin.com/crash-course/index.html.
• 啊 - Gnome帮助浏览器 - 使用DocBook/XML文件路径。在http://developer.gnome.org/projects/gdp/templates.html中可以找到模板
• 如果你想知道哪些tag用于哪里(而且太懒或查阅官方参考时感觉困惑)请阅读DocBookReference。

如果你已经安装了'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的使用。

Quick Tutorial

What does DocBook look like?

DocBook defines a number of 'tags' just like HTML does. To set the authors name you would write something like...

<author>
Christoph Haas
</author>

As you can see this is very similar to HTML. Below is a working example of a complete XML document. The 'flavor' used to write these tags is XML. Therefore it is called DocBook/XML. (The other 'flavor' would be SGML which is not greatly different. XML is stricter than SGML. HTML is a kind of SGML language. Most people believe that SGML is deprecated. Thus documentation in Debian is currently converted to XML.) Even if you have not yet used XML you should not have much trouble.

Style sheets

To create the output document from your XML input you also need a style sheet. Stylesheets are called 'XSL Transformations' (XSLT) and are written in a language called 'Extensible Stylesheet Language' (XSL). Basically XSLT describes how to convert one document into another. Usually you will not need to know how style sheets look. You also need a 'processor' that takes the XML and the XSLT and creates the output file from it. We will use the free 'xsltproc' program for that purpose. There is a number of stylesheets available to convert your document into: - Postscript - PDF - XHTML - man - texinfo Other converters exist to convert DocBook into formats like Yelp. Yelp is the the Gnome Help format.

Hello World

First you need to install the following packages:

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

Enter these lines into a file and call it 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>

Please note that you should use UTF-8 as a character encoding. You may need to switch your terminal and your editor to UTF-8 mode too. Run this command::

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

You should find a file 'test.html' in the current directory. View it with your favorite web browser. Now what did that line actually do? 'xsltproc' is the converter program. '-o test.html' sets the output file. The next parameter '.../docbook.xsl' is the stylesheet you are using for the conversion - this one converts XML to XHTML. And finally the 'test.xml' tells xsltproc where your input file is located.

Customising style sheets

You will probably be disappointed with the look of the DocBook output. It is great to have it convert the document automatically but it probably does not fit into your web design or 'corporate identity' at all. There is a remedy however. Style sheets usually provide a number of parameters that you can adjust. Usually you write your own stylesheet that imports the 'standard' style sheet. For example::

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

This stylesheet first imports the docbook.xsl mentioned earlier. It also sets a few parameters: - Set the maximum depth of the TOC (table of contents) to '1'. So only the <sect1> sections will be included in the TOC. - The final XHTML document will use the 'ubuntu.css' style sheet (CSS). - Include a link to the main page on top of the page. These settings only work with the XHTML style sheet. For other output format you need other settings. The settings above are documented at /usr/share/doc/docbook-xsl/doc/html/index.html You will also want to use http://www.sagehill.net/docbookxsl/ as a reference.

Makefile

If you have multiple XML files or style sheets you may want to have all the processing done in a Makefile. For example::

 
# 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 to PDF

The simplest way to convert a DocBook to PDF is to install the xsl-fo stylesheet (to convert to FO format), and fop (to convert FO to PDF). For some reason, the xsl-fo stylesheet is in the docbook-xsl-doc-pdf package.

sudo aptitude install fop docbook-xsl-doc-pdf

Now to convert your docbook file to pdf run:

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

Here's an example Makefile for a docbook named networkmanager-manual.xml:

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

To use the makefile, just change the input and output names (networkmanager-manual.*) to whatever you want them to be. Note: The w3-Organization has blocked the download of the necessary dtd files by unknown user agents. Due to this (at least in Karmic) fop throws a TransformerException with the notice that the w3 server returned a 503 HTTP response. The workaround seems to be to set up a local dtd repository, as noted here and here. The dblatex program can also do this.

Editing Programs

1. Bluefish

• This editor has syntax highlighting and code snippets for DocBook and many other languages.
• See http://bluefish.openoffice.nl/index.html

1. conglomerate (WYSIWYG)

• Somewhat beta. Doesn't hide the gory details. You still need to read the DocBook reference. Just makes it graphical.
• See http://www.conglomerate.org/

1. VIM file type plugin "xmledit"

• Good for vim-lovers. See http://www.vim.org/scripts/script.php?script_id=301
• A recent update based on the above script. http://www.vim.org/scripts/script.php?script_id=1397

1. EMACS XML support

• Some say DocBook is easy to write only under psgml. Some use Emacs only for psgml-mode.
• nxml-mode however is far superior to psgml-mode. It does real-time syntax and error highlighting.

1. See also DocBookEditors.