Table of Contents
本文译自Lars Vogel的DocBook with Eclipse教程Q?http://www.vogella.de/articles/DocBook/article.html
在翻译过E中Q本Z留原文的一切链接?
原文一切权利归原作者所有，译文一切权利归本h所有。如Ʋ{载原文，请征得作者授权。如Ʋ{载译文，h明本文原始链接?
本文的翻译已获得原作者授权?
DocBook是一U文档标准，用以创徏l构化的U文本文档。用DocBook创徏的文档能够方便的在不同的操作pȝ之间以及不同的文本处?工具之间q行ULQƈ可以通过XSLT 转ؓ其他的输出格式?span class="emphasis">XSLT是EXtensible Stylesheet Language Transformation的羃写?׃DocBook是用纯文本~辑的，因此你可以用Q何一个文?~辑器来~写DocBookQƈU_版本控制pȝ的管理?
目前Q有多种不同的样式表Q能够把DocBook文g转换Z同的输出格式Q例如{换ؓHTMLQpdfQjava help以及Unix man pages.
DocBook有两U主要的文档Q一U是bookQ另一U是article。其?
-
Article: 用来写一些技术文章，下文都以articleZ。article通常是由一pd的sectionl成?/p>
-
Book: 用来写一些更长的描述。book比article多了一U结构：chapter?/p>
下面是一个DocBook文档的例子?
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../docbook-xml-4.5/docbookx.dtd"> <article> <articleinfo> <title>DocBook Intro</title> <author> <firstname>Lars</firstname> <surname>Vogel</surname> </author> </articleinfo> <sect1 label="1.0"> <title>An introduction to DocBook</title> <para> This is text. </para> </sect1> </article>
Note
h意，在上面的例子中，DTD文g的位|：当前目录的上一U目录，其中的docbook-xml-4.5文g夹内?/p>
惌创徏DocBook文gq{换成其他格式Q你需要以下工P
-
DocBook的DTD文g。这个文件定义了DocBook文档的格式?/p>
-
XSLT样式表，用来把DocBook文档转换成其他格式?/p>
-
XSLT解析?/p>
我们使用Eclipse 作ؓXML~辑器，Xalan作ؓXSLT解析器，q?Apache Ant 来进行XSLT的{换?
你需要安装EclipseQ可以参看这文?Eclipse IDE 来学习Eclipse的安装和使用。我们需要用到的Ant已经被集成到Eclipse里面了，因此关于Ant我们不需要安装Q何额外的东西?
你还需要下载Docbook的DTDQ以及用来{换的Docbook文档的样式表。Docbook的DTD可以?http://www.oasis-open.org/docbook/xml/4.5下蝲Q?而XSLT样式表可以在 http://docbook.sourceforge.net/ 下蝲。在写这文档时Q最新的版本?#8220;1.75.2”Q译者注Q在译q篇文档Ӟ最新的版本?.76.1Q。你需要下载的docbook-xsl的发布文Ӟ 例如“docbook-xsl-1.75.2.zip”?
要命的是JVM自带的XSL处理器在处理XSLT样式表的时候有问题……所以我们需要从 http://xml.apache.org/xalan-j/ 下蝲XalanQ用来作为我们的XSL处理器?
可以在Eclipse中，创徏一?de.vogella.docbook.first"的新工程Q方法是File -> New -> ProjectQƈ从弹出的 H口中选择General -> Projects.
在工E中创徏如下的目录结构：
-
output : Docbook转换成其他格式时的输出目?/p>
-
docbook-xml-4.5: 用来放Docbook的DTD定义文g
-
docbook-xsl: 用来放进行Docbook转换的样式表文g
-
lib: 用来包含你需要的库文Ӟ用来创徏pdfQ?/p>
-
documents: 用来放你的DocBook文g
把DocBook的DTD和XSLT的样式表攑օ相应的文件夹中?
在lib文g夹下创徏xalan文g夹，q把xalan相关的jar包拷入这个文件夹中?l果应该看v来是q样的：
?#8220;documents”文g多w面，创徏一?#8220;book.xml”文gQƈ输入下面的xml文g
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../docbook-xml-4.5/docbookx.dtd"> <article> <articleinfo> <title>DocBook Intro</title> <author> <firstname>Lars</firstname> <surname>Vogel</surname> </author> </articleinfo> <sect1 label="1.0"> <title>An introduction to DocBook</title> <para> This is text. </para> </sect1> </article>
在xml文g中，“../docbook-xml-4.5/docbook.dtd”对应于我们刚刚创建的文g夹以及放入的DTD文g?
接下来我们配|ANT。在工程目录中，创徏build.xml文g如下Q?
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="build-html">
<description>
This Ant buildhtml.xml file is used to transform DocBook XML to html output
</description>
<!--
- Configure basic properties that will be used in the file.
-->
<property name="docbook.xsl.dir" value="docbook-xsl" />
<property name="doc.dir" value="output" />
<property name="documents" value="documents" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<!-- Making xalan available -->
<path id="xalan.class.path">
<pathelement location="lib/xalan/serializer.jar" />
<pathelement location="lib/xalan/xalan.jar" />
<pathelement location="lib/xalan/xercesImpl.jar" />
<pathelement location="lib/xalan/xml-apis.jar" />
</path>
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${doc.dir}" />
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${documents}" destdir="${doc.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="style.css" />
<classpath refid="xalan.class.path" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${doc.dir}">
<fileset dir="lib">
<include name="style.css" />
</fileset>
</copy>
</target>
</project>
q行build.xml文gQ右?-> Run As -> Ant BuildQ。运行之后，在你的output文g多w面， 应该已经有一?#8220;book.html”了?
恭喜你完成了W一个Docbook文档Qƈ利的{成了HTML格式Q?
下面是一些用Docbook标签的概览?/p>
Table 1. Docbook一些重要的标签
| Tag | 说明 |
|---|---|
| <![CDATA[ 此处可输入特D字W?e.g. & ]]> | 在标{中可以输入某些Ҏ字符Q例如某些xml以及Docbook的特D字W?/td> |
| <programlisting> </programlisting> | 表示该文本是E序代码 |
| <emphasis> </emphasis> | 表示用强调（HighlightQ该文本 |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="example1.txt" /> | 包含example1.xml的内宏V该文g可以是一个独立的xml文g |
| <ulink url="http://www.heise.de/newsticker">German IT News</ulink> [a] | 在文档中创徏一个超链接 |
| & | 在文档中插入“&”W号 |
|
[a] 译者注QDocbook5改变了超链接的格式。关于Docbook5以及更详l的Eclipse配置Docbook教程Q会很快攑և?不过Q即使是在Docbook5的环境下Q用ulink一样可以顺利的用XSLT转换Q只不过Eclipse的xml~辑器会提示有错误? |
|
下面是一个创格的例子
<table frame='all'> <title>Sample Table</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <colspec colname='c1' /> <colspec colname='c2' /> <thead> <row> <entry>a4</entry> <entry>a5</entry> </row> </thead> <tfoot> <row> <entry>f4</entry> <entry>f5</entry> </row> </tfoot> <tbody> <row> <entry>b1</entry> <entry>b2</entry> </row> <row> <entry>d1</entry> <entry>d5</entry> </row> </tbody> </tgroup> </table>
生成的表格看h是这L
没有序号的列表可以这样创建：
<itemizedlist> <listitem> <para>Item1</para> </listitem> <listitem> <para>Item2</para> </listitem> <listitem> <para>Item3</para> </listitem> <listitem> <para>Item4</para> </listitem> </itemizedlist>
输出l果如下Q?/p>
-
Item1
-
Item2
-
Item3
-
Item4
而带~号的列表可以这样写Q?/p>
<orderedlist> <listitem> <para>This is a list entry</para> </listitem> <listitem> <para>This is another list entry</para> </listitem> </orderedlist>
输出l果如下Q?/p>
-
This is a list entry
-
This is another list entry
链接可以用下面的Ҏ来创建：[a]
<para> We use the Ant integrated into Eclipse. See <ulink url="http://www.vogella.de/articles/ApacheAnt/article.html"> Apache Ant Tutorial</ulink> for an introduction into Apache Ant. </para>
Docbook转成pdf的过E是Q先由docbook转成XSL-FO格式Q再利用Apache FOP把FO转成 pdf。因此，我们首先需要Apache FOP相关的库?
XML FOQ是XML Formating Object的意思，FO格式是一U处理打印、印刷介质的XML标准?
可以?a class="link" target="_top">http://xmlgraphics.apache.org/fop/下蝲FOP的最新版本?
从下载的FOP发行版中Q把所有的jar文g都拷贝到你的lib文g夹中Qƈ把这些库都加入到ant 的build path中。可以参?Apach Ant Tutorial来修改ant的build path?
要在ant中用fopQ我们首先应当定义一个fop相关的ant taskQ然后在后面的脚本中使用q个d?下面的这个例子演CZ怎样定义一个ant taskq怎样调用。第二个例子是一个完整的build.xml文g的例子?
<!--
- Defines the ant task for fop
-->
<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" />
<!-- Transformation into pdf
- Two steps
- 1.) First create the FO files
- 2.) Then transform the FO files into pdf files
-->
<!--
- target: build-pdf
- description: Iterates through a directory and transforms
- .xml files into .fo files using the DocBook XSL.
-->
<target name="build-pdf" depends="depends, xinclude"
description="Generates HTML files from DocBook XML">
<!-- Convert DocBook Files into FO -->
<xslt style="${fo.stylesheet}" extension=".fo" basedir="${src.tmp}"
destdir="${src.tmp}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="section.autolabel" expression="1" />
</xslt>
<!-- Convert FO Files into pdf -->
<fop format="application/pdf" outdir="${doc.dir}">
<fileset dir="${src.tmp}">
<include name="**/*.fo" />
</fileset>
</fop>
</target>
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="all">
<description>
This Ant build.xml file is used to transform DocBook XML to
various output formats
</description>
<!--
- Defines the ant task for xinclude
-->
<taskdef name="xinclude" classname="de.vogella.xinclude.XIncludeTask" />
<!--
- Defines the ant task for xinclude
-->
<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" />
<!--
- Configure basic properties that will be used in the file.
-->
<property name="javahelp.dir" value="${basedir}/../Documentation/output/vogella/javahelp" />
<property name="src" value="${basedir}/documentation" />
<property name="output.dir" value="${basedir}/../Documentation/output/vogella/articles" />
<property name="output.tmp" value="${basedir}/output.tmp" />
<property name="lib" value="${basedir}/lib/" />
<property name="docbook.xsl.dir" value="${basedir}/docbook-xsl-1.72.0" />
<property name="xinclude.lib.dir" value="${basedir}/lib/" />
<!--
- Usage of the differect style sheets which will be used for the transformation
-->
<property name="eclipse.stylesheet" value="${docbook.xsl.dir}/eclipse/eclipse.xsl" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<property name="fo.stylesheet" value="${docbook.xsl.dir}/fo/docbook.xsl" />
<property name="javahelp.stylesheet" value="${docbook.xsl.dir}/javahelp/javahelp.xsl" />
<property name="chunk-html.stylesheet" value="${docbook.xsl.dir}/html/chunk.xsl" />
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${output.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${output.dir}" />
</target>
<!--
- target: copy
- Copies the images from the subdirectories to the target folder
-->
<target name="copy">
<echo message="Copy the images" />
<copy todir="${output.dir}">
<fileset dir="${src}">
<include name="**/images/*.*" />
</fileset>
</copy>
</target>
<!--
- target: xinclude
- description: Creates one combined temporary files for the different inputs files.
- The combined file will then be processed via different ant tasks
-->
<target name="xinclude">
<xinclude in="${src}/DocBook/article.xml" out="${output.tmp}/DocBook/article.xml" />
<xinclude in="${src}/JavaConventions/article.xml" out="${output.tmp}/JavaConventions/article.xml" />
<xinclude in="${src}/JUnit/article.xml" out="${output.tmp}/JUnit/article.xml" />
<xinclude in="${src}/EclipseReview/article.xml" out="${output.tmp}/EclipseReview/article.xml" />
<xinclude in="${src}/HTML/article.xml" out="${output.tmp}/HTML/article.xml" />
<xinclude in="${src}/Eclipse/article.xml" out="${output.tmp}/Eclipse/article.xml" />
<xinclude in="${src}/Logging/article.xml" out="${output.tmp}/Logging/article.xml" />
<!--
<xinclude in="${src}/ant/article.xml" out="${src.tmp}/ant/article.xml" />
-->
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
<param name="section.autolabel" expression="1" />
<param name="html.cleanup" expression="1" />
<outputproperty name="indent" value="yes" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${output.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
<!--
- target: build-javahelp
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-javahelp" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${javahelp.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${javahelp.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<outputproperty name="indent" value="yes" />
</xslt>
</target>
<!--
- target: chunks-html
- description: Iterates through a directory and transforms
- .xml files into seperate .html files using the DocBook XSL.
-->
<target name="build-chunks" depends="depends, xinclude" description="Generates chunk HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
<param name="section.autolabel" expression="1" />
<param name="html.cleanup" expression="1" />
<param name="chunk.first.selection" expression="1" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${output.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
<!-- Transformation into pdf
- Two steps
- 1.) First create the FO files
- 2.) Then transform the FO files into pdf files
-->
<!--
- target: build-pdf
- description: Iterates through a directory and transforms
- .xml files into .fo files using the DocBook XSL.
- Relativebase is set to true to enable FOP to find the graphics which are included
- in the images directory
-->
<target name="build-pdf" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<!-- Convert DocBook Files into FO -->
<xslt style="${fo.stylesheet}" extension=".fo" basedir="${output.tmp}" destdir="${output.tmp}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="section.autolabel" expression="1" />
</xslt>
<!-- Convert FO Files into pdf -->
<fop format="application/pdf" outdir="${output.dir}" relativebase="true">
<fileset dir="${output.tmp}">
<include name="**/*.fo" />
</fileset>
</fop>
</target>
<!--
- target: chunks-html
- description: Iterates through a directory and transforms
- .xml files into seperate .html files using the DocBook XSL.
-->
<target name="build-eclipse" depends="depends, xinclude" description="Generates Eclipse help files from DocBook XML">
<xslt style="${eclipse.stylesheet}" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
</xslt>
</target>
<target name="all" depends="copy, build-html, build-pdf, build-chunks, build-eclipse">
</target>
</project>
我们可以通过修改XSLT样式表的参数来媄响输出的l果。下面其中一些参数的介绍?/p>
Docbook允许在{换成html的时候，导入q包含一个外部的html文g。你可以使用q种技术，在生?html的时候向其中插入javascript代码?
下面是一个包含html文g的例子?
<?dbhtml-include href="../../myadditonalcontent.html"?>
Inserting external HTML code 有更多的描述?
XInclude技术能帮你重新l织你的docbook文g。你可以在书写每一个章节的时候，都?一个单独的xml文gQ然后用一个ȝxml文g把这些章节都l合h。简单的_XInclude 能把不同的xml文gl合成ؓ一个大的xml文g?
例如Q假设你要引入一?#8220;foo.xml”文gQ则可以写成Q?
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="foo.xml" />
下面q个例子是要把导入的文g当做文本Q?[1]
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="bar.xml" />Eclipse XSL project提供一个XInclude的ant task。在此，我很自豪的告诉各位：q个ant task是我提供lXSL project ?)
Eclipse XSL工具提供了对XSLT的支持，包括XSL的编辑以及debug的支持。虽然我们这里仅仅用其中的ant taskQ?但还是得完整的安装整个包?
安装XSL工具可以通过Eclipse的update manager完成?[2] 你可以通过 Using the Eclipse update manager 来获得更多信息?
在你的Eclipse安装路径中找?#8220;org.eclipse.wst.xsl.core.jar”q把q个jar包加入到ANT的classpath中?q样Q你应该可以创建和q行xinclude tast了。下面是一个build.xml文g的例子：
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="usage">
<description>
This Ant build.xml file is used to transform DocBook XML to various
output formats
</description>
<!--
- Configure basic properties that will be used in the file.
-->
<property name="doc.dir" value="${basedir}/output" />
<property name="src" value="${basedir}/src" />
<property name="src.tmp" value="${basedir}/src.tmp" />
<property name="lib" value="${basedir}/lib/" />
<property name="docbook.xsl.dir" value="${basedir}/docbook-xsl-1.72.0" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<property name="xinclude.lib.dir" value="${basedir}/lib/" />
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${doc.dir}" />
</target>
<!--
- target: xinclude
- description: Creates one combined temporary files for the different inputs files.
- The combined file will then be processed via different ant tasks
-->
<target name="xinclude">
<xsl.xinclude in="${src}/DocBook/article.xml" out="${src.tmp}/DocBook/article.xml" />
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${src.tmp}" destdir="${doc.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${doc.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
</project>
http://www.sagehill.net/docbookxsl/index.html Docbook XSL Online Book
http://sourceforge.net/projects/docbook/ Docbook XSLT样式表项?
http://docbook.sourceforge.net/release/xsl/current/doc/ XSLT样式表的参数手册
http://sourceforge.net/apps/mediawiki/xslthl/index.php?title=Main_Page 如何使用XSLT实现语法高亮
http://www.docbook.org/tdg/en/html/docbook.html Docbook参数手册
http://xmlgraphics.apache.org/fop/ Apache FOP目
[1] 译者注Q这块儿没看明白Q哪位高人指点一下？
[2] 译者注QXSL工具被包含在WTPQWeb Develop PlatformQ中?如果你装的Eclipse是J2EE版本Q很可能q个工具在你的Eclipse上已l有了?/p>
Antony Lee 2011-08-07 02:00 发表评论
]]>Antony Lee 2011-06-13 15:40 发表评论
]]>Antony Lee 2011-06-10 15:23 发表评论
]]>Antony Lee 2011-06-09 12:17 发表评论
]]>Antony Lee 2011-01-09 16:12 发表评论
]]>原理很简单，是用程序去获得腾讯星|站的源码，然后单解析一下就可以了。原来试囄dom解析Q结果发现腾讯和新浪的网站都会解析出错，一狠心q脆直接用字W串的替换?/p>
Java那个E序的功能多一些，写了d“明天”、“本周”、“下周”、“本月”、“下月”的功能Q主函数中提供了d“明天”的功能Q默认会在当前工作目录下生成“yuncheng_XXX.txt”文件。实在懒得写客户端了Q甚至于命o行客L都不惛_了，因ؓ昨天写这个破东西写到?1点半Q原以ؓ很简单的呢，l果郁闷坏了。真是水q_q度下滑啊?/p>
今天晚上用python写了一个程序，q是我用Python写的W一个程序哟~~Q如果不helloworld的话。。。）q个E序功能比较单，只能获得明日q程?/p>
刚刚写出来而已Q注释很乱，代码很ؕ。写q篇博客只是因ؓ母鸡心态：好歹有了个新东西了，怎么也得让我叫唤两声吧?/p>
下蝲地址Q?/p>http://www.rayfile.com/files/bc9485dc-88e8-11de-b777-0014221f469f/
Antony Lee 2009-08-15 00:32 发表评论
]]>