初识DocBook(编写技术文档的工具)
2014-05-29 14:22
295 查看
突然在Linux下看到一堆命令:
[root@localhost default]# do
do docbook2rtf docbook2txt dosfsck doveconf doxytag
docbook2html docbook2tex domainname dosfslabel dovecot
docbook2man docbook2texi done doveadm doxygen
[root@localhost default]# man docbook2txt
马上百度了docbook的相关资料。
DocBook是一种文档工具,特别适合技术人员用做文档编写。感觉早该知道有这玩意了,就像知道visio和project这样良好的工具一样,好的工具就像是武侠世界里的神器,只不过这个神器人人可得,却不是人人知道。
下面内容是转载自 http://blog.sina.com.cn/s/blog_517d1cb00100uqcv.html
责搭建一个叫做AutoDoc的环境用于帮助开发人员协作编写技术文档并生成各种不同类型的输出(比如:HTML, PDF, RTF等)。
AutoDoc 的基础是 DocBook 以及 FOP, Ant, Ant-Contrib, Maven, Hudson, SVN 等技术和开源项目。
AutoDoc的总体架构图:
关于Hudson,Maven和SVN的安装和配置,这里我就不详述了。请参考官方文档。
我们需要在Eclipse里为AutoDoc创建一个Project,然后导入其他依赖的组件。下面是AutoDoc用到的资源:
docbook-5.0
docbook-xsl-ns-1.76.1
fop-1.0
ant-contrib
ant
(推荐使用DownThemAll!下载)
注意:apache-ant-1.7.*需要使用Java 1.6运行。其他版本,请查看Release Notes。
下面对各个组件需要导入的文件做一个简单的介绍:
docbook-5.0: 只需要导入docbook.dtd文件。
docbook-xsl-ns-1.76.1: 导入所有文件。
fop-1.0: 导入build和lib文件夹中的所有jar文件。
ant-contrib: 导入根目录下的ant-contrib-1.0b3.jar和lib文件夹下的所有jar文件。
导入的过程:
选择Project, 右键->“Import...”
在Import对话窗口,填入“Archive”到“Select an import source”文本框中,然后选择“Archive File”节点,点击“Next”
点击“Browser...”选择对应的zip文件,比如“D:\Download\docbook-5.0.zip”。点击“File Types...”,在“Select Types”对话窗口选择目标文件的扩展名,比如“*.dtd”,点击“OK”。
点击“Finish”
源文件(基于DocBook DTD的XML文件以及其他相关文件)的组织结构图:
采用这个组织结构的原因是:
易于组织文档以及文档片断和插入文档中的图片等
易于维护和管理
构建过程比较复杂:
如果temp文件夹存在,删除
拷贝src文件夹下的文件到temp文件夹(导出文件除外,比如*.pdf,*.html等)
将隶属文件(partition source files)中的XML指令和DOCTYPE指令删除(用空格替换)
将主文件中的DTD路径替换为公共路径(配置在build.properties文件中)
扫描temp文件夹及其子文件夹下所有符合命名规则 - “*main.xml”的XML文件(即主文件)
处理主文件,导出*.fo文件
基于*.fo文件,导出*.pdf文件和*.rtf文件
导出*.html文件(修改图片文件的绝对路径为相对路径 - 这样无论在本地还是Web服务器都可正常显示图片)
构建完毕,剩下的工作就是学习DocBook
DTD 和 DocBook
XSL了。基于此,Developer可以编写,修改和管理技术文档,并实现“一次编写,随便阅读”。
[root@localhost default]# do
do docbook2rtf docbook2txt dosfsck doveconf doxytag
docbook2html docbook2tex domainname dosfslabel dovecot
docbook2man docbook2texi done doveadm doxygen
[root@localhost default]# man docbook2txt
马上百度了docbook的相关资料。
DocBook是一种文档工具,特别适合技术人员用做文档编写。感觉早该知道有这玩意了,就像知道visio和project这样良好的工具一样,好的工具就像是武侠世界里的神器,只不过这个神器人人可得,却不是人人知道。
下面内容是转载自 http://blog.sina.com.cn/s/blog_517d1cb00100uqcv.html
责搭建一个叫做AutoDoc的环境用于帮助开发人员协作编写技术文档并生成各种不同类型的输出(比如:HTML, PDF, RTF等)。
AutoDoc 的基础是 DocBook 以及 FOP, Ant, Ant-Contrib, Maven, Hudson, SVN 等技术和开源项目。
AutoDoc的总体架构图:
关于Hudson,Maven和SVN的安装和配置,这里我就不详述了。请参考官方文档。
我们需要在Eclipse里为AutoDoc创建一个Project,然后导入其他依赖的组件。下面是AutoDoc用到的资源:
docbook-5.0
docbook-xsl-ns-1.76.1
fop-1.0
ant-contrib
ant
(推荐使用DownThemAll!下载)
注意:apache-ant-1.7.*需要使用Java 1.6运行。其他版本,请查看Release Notes。
下面对各个组件需要导入的文件做一个简单的介绍:
docbook-5.0: 只需要导入docbook.dtd文件。
docbook-xsl-ns-1.76.1: 导入所有文件。
fop-1.0: 导入build和lib文件夹中的所有jar文件。
ant-contrib: 导入根目录下的ant-contrib-1.0b3.jar和lib文件夹下的所有jar文件。
导入的过程:
选择Project, 右键->“Import...”
在Import对话窗口,填入“Archive”到“Select an import source”文本框中,然后选择“Archive File”节点,点击“Next”
点击“Browser...”选择对应的zip文件,比如“D:\Download\docbook-5.0.zip”。点击“File Types...”,在“Select Types”对话窗口选择目标文件的扩展名,比如“*.dtd”,点击“OK”。
点击“Finish”
源文件(基于DocBook DTD的XML文件以及其他相关文件)的组织结构图:
采用这个组织结构的原因是:
易于组织文档以及文档片断和插入文档中的图片等
易于维护和管理
构建过程比较复杂:
如果temp文件夹存在,删除
拷贝src文件夹下的文件到temp文件夹(导出文件除外,比如*.pdf,*.html等)
将隶属文件(partition source files)中的XML指令和DOCTYPE指令删除(用空格替换)
将主文件中的DTD路径替换为公共路径(配置在build.properties文件中)
扫描temp文件夹及其子文件夹下所有符合命名规则 - “*main.xml”的XML文件(即主文件)
处理主文件,导出*.fo文件
基于*.fo文件,导出*.pdf文件和*.rtf文件
导出*.html文件(修改图片文件的绝对路径为相对路径 - 这样无论在本地还是Web服务器都可正常显示图片)
构建完毕,剩下的工作就是学习DocBook
DTD 和 DocBook
XSL了。基于此,Developer可以编写,修改和管理技术文档,并实现“一次编写,随便阅读”。
相关文章推荐
- 转载_让Developer用DocBook编写技术文档
- 基于AJAX技术编写的在线英汉互译小工具
- 优秀技术文档编写的技巧
- 让代码飞一会儿:快速编写 HTML 和 CSS 的工具和技术
- 我最喜爱的十大技术文档写作工具
- XDC工具相关在线技术文档
- 编写优秀技术文档的技巧
- 学习编写java类的技术文档
- Doxygen 编写软件参考文档的工具
- [转载][精华] 编写优秀技术文档的技巧
- 谈谈技术文档的编写
- OCS技术文档及资源工具下载
- 想编写出优秀技术文档,先学学这四招——写得还可以吧
- 编写优秀技术文档的技巧
- 让代码飞一会儿:快速编写 HTML 和 CSS 的工具和技术
- 编写优秀技术文档的技巧
- 编写优秀技术文档的技巧
- Txt2tags 使用指南 强大的文档编写工具
- 让代码飞一会儿:快速编写 HTML 和 CSS 的工具和技术
- 技术文档编写的参考