特殊:Badtitle/NS100:DocBook/zh:修订间差异
第58行: | 第58行: | ||
你也需要一个“处理器”来使用XML和XSLT并创建相应的输出文件。我们将使用免费的“xsltproc”程序来达到这个目的。 | 你也需要一个“处理器”来使用XML和XSLT并创建相应的输出文件。我们将使用免费的“xsltproc”程序来达到这个目的。 | ||
你可将你的文档转换成如下一些可用的样式表: | 你可将你的文档转换成如下一些可用的样式表: | ||
* Postscript | |||
* PDF | |||
* XHTML | |||
* man | |||
* texinfo | |||
有些转换器可以将DocBook转换成Yelp。Yelp是Gnome帮助格式。 | |||
==== Hello World ==== | ==== Hello World ==== |
2010年6月17日 (四) 19:54的版本
文章出处: |
{{#if: | {{{2}}} | https://help.ubuntu.com/community/DocBook }} |
点击翻译: |
English {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/af | • {{#if: UbuntuHelp:DocBook|Afrikaans| [[::DocBook/zh/af|Afrikaans]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ar | • {{#if: UbuntuHelp:DocBook|العربية| [[::DocBook/zh/ar|العربية]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/az | • {{#if: UbuntuHelp:DocBook|azərbaycanca| [[::DocBook/zh/az|azərbaycanca]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/bcc | • {{#if: UbuntuHelp:DocBook|جهلسری بلوچی| [[::DocBook/zh/bcc|جهلسری بلوچی]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/bg | • {{#if: UbuntuHelp:DocBook|български| [[::DocBook/zh/bg|български]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/br | • {{#if: UbuntuHelp:DocBook|brezhoneg| [[::DocBook/zh/br|brezhoneg]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ca | • {{#if: UbuntuHelp:DocBook|català| [[::DocBook/zh/ca|català]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/cs | • {{#if: UbuntuHelp:DocBook|čeština| [[::DocBook/zh/cs|čeština]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/de | • {{#if: UbuntuHelp:DocBook|Deutsch| [[::DocBook/zh/de|Deutsch]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/el | • {{#if: UbuntuHelp:DocBook|Ελληνικά| [[::DocBook/zh/el|Ελληνικά]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/es | • {{#if: UbuntuHelp:DocBook|español| [[::DocBook/zh/es|español]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/fa | • {{#if: UbuntuHelp:DocBook|فارسی| [[::DocBook/zh/fa|فارسی]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/fi | • {{#if: UbuntuHelp:DocBook|suomi| [[::DocBook/zh/fi|suomi]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/fr | • {{#if: UbuntuHelp:DocBook|français| [[::DocBook/zh/fr|français]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/gu | • {{#if: UbuntuHelp:DocBook|ગુજરાતી| [[::DocBook/zh/gu|ગુજરાતી]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/he | • {{#if: UbuntuHelp:DocBook|עברית| [[::DocBook/zh/he|עברית]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/hu | • {{#if: UbuntuHelp:DocBook|magyar| [[::DocBook/zh/hu|magyar]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/id | • {{#if: UbuntuHelp:DocBook|Bahasa Indonesia| [[::DocBook/zh/id|Bahasa Indonesia]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/it | • {{#if: UbuntuHelp:DocBook|italiano| [[::DocBook/zh/it|italiano]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ja | • {{#if: UbuntuHelp:DocBook|日本語| [[::DocBook/zh/ja|日本語]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ko | • {{#if: UbuntuHelp:DocBook|한국어| [[::DocBook/zh/ko|한국어]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ksh | • {{#if: UbuntuHelp:DocBook|Ripoarisch| [[::DocBook/zh/ksh|Ripoarisch]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/mr | • {{#if: UbuntuHelp:DocBook|मराठी| [[::DocBook/zh/mr|मराठी]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ms | • {{#if: UbuntuHelp:DocBook|Bahasa Melayu| [[::DocBook/zh/ms|Bahasa Melayu]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/nl | • {{#if: UbuntuHelp:DocBook|Nederlands| [[::DocBook/zh/nl|Nederlands]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/no | • {{#if: UbuntuHelp:DocBook|norsk| [[::DocBook/zh/no|norsk]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/oc | • {{#if: UbuntuHelp:DocBook|occitan| [[::DocBook/zh/oc|occitan]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/pl | • {{#if: UbuntuHelp:DocBook|polski| [[::DocBook/zh/pl|polski]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/pt | • {{#if: UbuntuHelp:DocBook|português| [[::DocBook/zh/pt|português]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ro | • {{#if: UbuntuHelp:DocBook|română| [[::DocBook/zh/ro|română]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/ru | • {{#if: UbuntuHelp:DocBook|русский| [[::DocBook/zh/ru|русский]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/si | • {{#if: UbuntuHelp:DocBook|සිංහල| [[::DocBook/zh/si|සිංහල]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/sq | • {{#if: UbuntuHelp:DocBook|shqip| [[::DocBook/zh/sq|shqip]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/sr | • {{#if: UbuntuHelp:DocBook|српски / srpski| [[::DocBook/zh/sr|српски / srpski]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/sv | • {{#if: UbuntuHelp:DocBook|svenska| [[::DocBook/zh/sv|svenska]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/th | • {{#if: UbuntuHelp:DocBook|ไทย| [[::DocBook/zh/th|ไทย]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/tr | • {{#if: UbuntuHelp:DocBook|Türkçe| [[::DocBook/zh/tr|Türkçe]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/vi | • {{#if: UbuntuHelp:DocBook|Tiếng Việt| [[::DocBook/zh/vi|Tiếng Việt]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/yue | • {{#if: UbuntuHelp:DocBook|粵語| [[::DocBook/zh/yue|粵語]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/zh | • {{#if: UbuntuHelp:DocBook|中文| [[::DocBook/zh/zh|中文]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/zh-hans | • {{#if: UbuntuHelp:DocBook|中文(简体)| [[::DocBook/zh/zh-hans|中文(简体)]]}}|}} {{#ifexist: {{#if: UbuntuHelp:DocBook | UbuntuHelp:DocBook | {{#if: | :}}DocBook/zh}}/zh-hant | • {{#if: UbuntuHelp:DocBook|中文(繁體)| [[::DocBook/zh/zh-hant|中文(繁體)]]}}|}} |
{{#ifeq:UbuntuHelp:DocBook|:DocBook/zh|请不要直接编辑翻译本页,本页将定期与来源同步。}} |
{{#ifexist: :DocBook/zh/zh | | {{#ifexist: DocBook/zh/zh | | {{#ifeq: {{#titleparts:DocBook/zh|1|-1|}} | zh | | }} }} }} {{#ifeq: {{#titleparts:DocBook/zh|1|-1|}} | zh | | }}
目的
本页的目的是提供一个 DocBook 格式的概述。它介绍此格式的一些优点,提供关于此格式更多的阅读的链接,同时包含了一个简短的教程。
DocBook是什么?
DocBook是一个用于当今许多文档编制任务中的基于XML的标准。当你想要创建一个DocBook文档源码时,你需要编写XML文件来描述文档布局、段落界限和其它属性。如果你此前曾经见过HTML源码,你可能会觉得XML文件的结构很熟悉。XML更像是老式的HTML的改进,它可以用于生成完整的网页页面和其它的标记文档。
DocBook的优点是什么?
DocBook是一个OASIS标准,是大部分开源项目存储它们文档的格式。DocBook是开源应用程序。这个项目在Souce Forge主办,且在GPL下可用。DocBook可用于文档类型定义(DTD)和XML模式(XSD)。此项目有一个跨越开源和商业群体的大的开发者和支持社区。 项目使用DocBook的最重要的原因包括如下:
- DocBook 是一个标准
- DocBook 是开源的
- DocBook 被用于大部分大项目
- 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.
- Yelp - 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的使用。
快速教程
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
- 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。 它也设置了几个参数: This stylesheet first imports the docbook.xsl mentioned earlier. It also sets a few parameters: - 设置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 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
- Bluefish
- This editor has syntax highlighting and code snippets for DocBook and many other languages.
- See http://bluefish.openoffice.nl/index.html
- 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/
- 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
- 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.
- See also DocBookEditors.