DocBook

  • 介绍

如果你还在使用Word这个笨重的工具来维护一些大型的文档,那么正处在水深火热中的你特别适合来看这边文章。

有了DocBook这个工具,你不再需要关注文档的格式、样式等问题了,生成文档。PDF、HTML、EPUB这些格式都是被支持的,你只需要将文档内容使用XML的方式按照章节划分即可。

  • Eclipse插件

使用Eclips插件的话,可以免去很多DocBook环境搭建的麻烦。下面就是在线安装的地址:

http://sourceforge.net/projects/dep4e/files/repository/

如果不知道这么安装Eclipse插件的话,请查看《Eclipse插件使用篇》。下图是在安装完插件后可以看到的新建DocBook工程向导。

新建DocBook工程向导
新建DocBook工程向导

DocBook在Eclipse中的环境目录如下:

configuration\org.eclipse.osgi\1383\0\.cp\resources

  • 物理分割
  • 逻辑分割
  1. Sets包含两个或者更多的book,你可以使用set标签。
  2. Books可能是在文档中最常见的顶层元素了。DocBook对于book的定义非常松散。一个book元素可以包含如下元素:
    1. Dedication几乎总是出现在一本书的最前面;
    2. 导航组件
    3. Divisions是仅次于元素book的元素。Divisions包含parts和references。一个parts包含很多组件。一个references包含很多reference。
    4. 组件,类似于一本书(book)中的章节(chapter)。
  3. 组件(Components)
  • 插入图片

对于尺寸比较大的图片,在PDF和HTML中可能会发生风格不一致的情况,这时候你可以针对具体的格式来添加不同的图片或者配置。详情请看下图:

PDF格式的输出文档,可调整的格式比较少,而对于HTML格式的我们就可以通过添加自定CSS来实现各种效果。

  • 插入源码

注意,上面的programlisting最好只放在一行,不然你引入的代码可能不对齐。

  • 插入超链接

<ulink url="http://www.sonatype.org/nexus/">http://www.sonatype.org/nexus/</ulink>

  • 插入摘要

<abstract><para>A trivial example of recursive sections.</para></abstract>

  • HTML配置

本文隐藏内容 登陆 后才可以浏览

  • PDF配置

本文隐藏内容 登陆 后才可以浏览

  • 使用Ant生成字体文件

本文隐藏内容 登陆 后才可以浏览

这里有已经生成好的字体文件(https://yunpan.cn/cYphbnA9Uvi2W  访问密码 56a8)。

  • Visual Editor for XML

看到这里,你应该已经能够编写一个本DocBook了。但如果对这种直接操作XML的方式感觉很麻烦的话,这里再次推荐一个Eclipse插件——Vex(Visual Editor for XML)。

安装地址为http://download.eclipse.org/vex/milestones/1.1/

备注:如果这里的地址失效,或者你在安装的时候有任何问题,还希望有分享精神的您一定要在下面留言告知!谢谢!请查看《Eclipse插件使用篇》。

插件安装完成之后,在xml文件上右键选择打开方式即可:

Eclipse文件打开方式选择
Eclipse文件打开方式选择

有了这个插件之后,你就可以像编辑Word那样有了所见即所得的效果。

  • 文档迁移

如果你很喜欢本文介绍的内容,希望在自己的项目上实施,却苦于已经有了很多Word版本的文档,担心迁移会需要浪费很多时间。没关系,我这里推荐一个方法。

先把word保存为html格式,然后把所有的图片都拷贝出来,再把所有的文章拷贝到文本文件中,最后你可以使用Vim文本替换来把普通的文本转化为合格的XML格式。

这里提醒的是,通过上面的方式拷贝出来的图片有可能特别多,但仔细观察就能发现图片都是连续的。

安装我做的例子,把一个418页的word文档转化为pdf、html格式,大概需要花一个工作日就能搞定。

  • 编译错误

configure: error: C++ preprocessor “/lib/cpp” sanity check

添加c++

configure: error: cannot guess build type; you must specify one

Invalid configuration BUILD': machine BUILD’ not recognized

configure: error: “OpenSP include files do not exist”

D:\Work\docbook>tools\xslt\bin\xsltproc.exe -o books\docbok5_demo\output\html\docbook5_demo.html config\docbook-xsl-ns-1.77.18\docbook_html.xsl books\docbok5_demo\docbook5_demo.xml

D:\Work\docbook>tools\xslt\bin\xsltproc.exe -o books\docbok5_demo\output\html\docbook5_demo.fo config\docbook-xsl-ns-1.77.18\docbook_fo.xsl books\docbok5_demo\docbook5_demo.xml

D:\Work\docbook>tools\fop-2.1\fop.cmd -c config\fop\fop.xconf -fo books\docbok5_
demo\output\fo\docbook5_demo.fo -pdf books\docbok5_demo\output\pdf\docbook5_demo
.pdf

  • 参考

http://www.ibm.com/developerworks/cn/java/j-ap06108/

http://www.worldhello.net/doc/docbook_howto/ar01s03s01.html

http://blog.csdn.net/sarkuya/article/details/6854323

http://www.docbook.org/tdg5/en/html/ch02.html

http://www.vogella.com/tutorials/DocBook/article.html

发表评论

电子邮件地址不会被公开。 必填项已用*标注