Docbook开发手记

版本:v2.4.5

Crifan Li

摘要

本文先简介了什么是Docbook,然后详细介绍了如何搭建中文的Docbook开发环境,再详细记录了Docbook开发过程中所遇到的各种注意事项和遇到的问题及解决办法,同时给出很多常见的Docbook中各种元素的示例代码,另外也记录了一些值得参考的Docbook相关的资料。

[提示] 本文提供多种格式供:
在线阅读 HTML HTMLs PDF CHM TXT RTF WEBHELP
下载(7zip压缩包) HTML HTMLs PDF CHM TXT RTF WEBHELP

HTML版本的在线地址为:

http://www.crifan.com/files/doc/docbook/docbook_dev_note/release/html/docbook_dev_note.html

有任何意见,建议,提交bug等,都欢迎去讨论组发帖讨论:

http://www.crifan.com/bbs/categories/docbook_dev_note/

2015-05-12

修订历史
修订 2.4.5 2015-05-12 crl
  1. 添加一个问题解答:listitem in namespace encountered in listitem
  2. 添加一个qanda的示例代码
  3. 添加示例:合并单元格的表格
  4. 添加示例:chapter的xml域
修订 2.4 2013-10-09 crl
  1. 完善了代码示例部分
  2. 更新整理了appendix附录部分,把最新的所有的book都整理进来了
  3. 添加了filename,screenco等示例代码
  4. 更新了所有的xml:id
  5. 添加示例代码:figure内包含2张mediaobject图片
  6. 添加示例代码:内嵌元素中的keycap
  7. 修正了个别的笔误,修改了部分细节内容,添加了引用reference
  8. 添加整理了:Docbook相关的资源和工具下载
  9. 添加了:Docbook相关的知识和概念
  10. 添加示例:programlisting和screen
  11. 添加示例:filename是后缀名
修订 1.1 2012-06-14 crl
  1. 完成此文的框架
  2. 各个章节都已添加了一些基本的内容,关于参考资料的部分,已添加大部分内容
  3. 收集了一些常见问题及解决办法
  4. 分割成多个文件
  5. 添加了关于实体定义部分的介绍
  6. 添加了调试fo部分的内容
  7. 添加了如何搭建docbook环境
  8. 添加了什么是Docbook
  9. 添加了代码示例部分

目录

Docbook介绍
1. 什么是Docbook
1.1. Docbook出现的背景
1.2. Docbook是什么
1.2.1. 截图说明Docbook的:一种(xml)格式输入,多种(html,htmls,chm,pdf,txt,rtf等等)格式输出
1.2.1.1. Docbook的一种输入:xml源码(文件)
1.2.1.2. Docbook的多种输出:HTML,HTMLs,PDF,CHM,RTF,TXT,WEBHELP等格式
2. 我为何选择Docbook
1. Windows下的Docbook的环境搭建
1.1. 搭建Docbook之前需要知道的最基本的事情
1.1.1. 我们的目标
1.1.2. 关于格式转换方面的知识
1.2. 纯Windows环境下的Docbook开发环境的搭建
1.2.1. 建立好文件夹
1.2.2. 下载windos版本的xsltproc
1.2.3. 下载docbook-xsl-ns-1.77.1
1.2.4. 下载fop-1.0并添加fop配置文件
1.2.4.1. 下载fop-1.0
1.2.4.2. 配置FOP的环境变量FOP_HOME
1.2.4.3. 添加fop配置文件fop.xconf
1.2.5. 准备docbook的源码:xml文件
1.2.6. 从xml生成html
1.2.6.1. 为生成html准备配置文件
1.2.6.2. 将xml转换为html
1.2.7. 从xml生成pdf
1.2.7.1. 为生成pdf准备配置文件
1.2.7.2. 将xml转换为fo
1.2.7.3. 将fo转换为pdf
1.3. Windows环境下的,基于Cygwin的Docbook开发环境的搭建
1.3.1. 安装Cygwin
1.3.2. 下载cygwin下使用fop-1.0
2. Docbook开发过程中的注意事项和心得
2.1. Docbook 4和Docbook 5的区别
2.2. 关于实体定义
2.3. qanda系列的用法
2.4. FOP相关注意事项
2.4.1. FOP的字体设置
2.5. Docbook开发过程中的一些有用的提示
2.5.1. Docbook最佳实践
2.5.1.1. Docbook中id的命名规则
2.6. Docbook开发过程中如何调试错误
2.6.1. 举例说明如何实现方便地调试Docbook生成pdf过程中所出现的错误
2.7. Docbook开发过程中的一些感悟
2.7.1. Docbook更关注内容
2.7.2. Docbook与盖楼
2.8. Docbook环境进化过程简单记录
3. Docbook开发过程中的常见问题及解答
常见问题
3.1. ValidationException: Property ID xxx previously used
3.2. ValidationException: xxx is not a valid child of xxx
3.3. ValidationException: xxx is missing child elements
3.4. docbook5中指定表格table中列column的宽度
3.5. 除了章(Chapter)有编号之外,其他不同层级的小节(section)都是没有编号的,想要给各小节添加索引编号
3.6. 已经include了xsl配置文件了,但是自己添加的参数配置,不起效果
3.7. xsltproc出错:Element xxx in namespace xxx encountered in book, but no template matches
3.8. pdf中没有出现/显示revhistory所对应的历史版本
3.9. 生成pdf的时候出错:严重: Image not found. URI: xxx.png. (See position xxx)
3.10. 想要给book中的标题下面添加一个版本号
3.11. 输出的pdf中的revhistory历史版本的内容中的表格无边框,想要添加边框
3.12. 如何去掉docbook中输出的pdf中,除了带链接的文字之外的那个链接地址
3.13. 给docbook生成的pdf中的带链接的文字,添加下划线和设置字体颜色为蓝色
3.14. 如何给docbook的pdf添加bookmark书签的功能
3.15. Docbook的pdf,去除正文对于标题的缩进indent
3.16. 生成的pdf中emphasis无效果,想要实现给pdf中emphasis的文字加粗或斜体
3.17. 如何给(docbook中的)xsl中定义实体Entity
3.18. 给docbook的pdf中的等式(equation)设置背景色
3.19. 如何将默认的输出单个的HTML页面,改为输入多个HTML页面?
3.20. 如何给docbook中的表格(table)的第一行(firstrow或thead)添加背景色?
3.21. 如何用docbook生成chm(微软帮助文件)?
3.22. docbook生成的chm的左边目录等内容都是乱码
3.23. 如何将qanda的标题添加到TOC目录中去?
3.24. 如何将docbook转换为(和word兼容的)RTF文档?
3.25. 如何用Docbook生成Webhelp?
3.26. 用fop生成pdf过程中出现警告:warning: Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400"
3.27. Docbook中使用fop过程中出错:严重: Couldn’t find hyphenation pattern zh_cn
3.28. cygwin/linux下的fop运行出错:Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/xmlgraphics/image/loader/ImageContext
3.29. Docbook中用xsltproc生成HTML过程中出错:runtime error xxx/chunker.xsl line 226 element document, invalid value for indent,xsltRunStylesheet : run failed
3.30. docbook的xsltproc生成的HTML中Charset的值是空的,不是所设置的UTF-8
3.31. 如何给Docbook中添加abbrev缩略词一项,且放置在目录之后,正文之前?
3.32. 给Docbook的HTML的等式(equation),程序源码(programlisting)等添加背景色
3.33. PDF中和HTML中的图片显示,始终不能统一,要么HTML中是放大的,要么PDF中不能完全显示,所以希望PDF和HTML中的图片显示可以用同一套代码来统一
3.34. 想要设置HTML和PDF中的图片的标题都是居中对齐
3.35. 生成PDF中,程序代码programlisting中单行代码太长,超出页面宽度,无法显示
3.36. Docbook生成的pdf中,当表格在quote中时,表格头部却在底端显示,而且如果内容是多行的,还会显示出多行
3.37. Docbook中的callout图片在programlisting中不显示
3.38. An fo:block is wider than the available room in inline-progression-dimension
3.39. TransformerException: The column-number or number of cells in the row overflows the number of fo:table-columns specified for the table
3.40. 如何通过xref(在别处)引用某个段落(para)?
3.41. WARNING: Content overflows the viewport of the fo:region-body on page 9 in block-progression direction by 99828 millipoints. (See position 2:5700)
3.42. PDF中callout不能点击跳转(而HTML中却可以)
3.43. callout图片在programlisting的源码中不显示
3.44. 如何在(只使用co而没有使用areaspec的)源码中多个位置,指向同一个co(callout)?
3.45. 新的docbook-xsl-ns-1.77.0生成的html中的revhistory中单元格无边框
3.46. WARNING: Glyph "?" (0x21b5, carriagereturn) not available in font "MicrosoftYaHei".
3.47. 如何实现给table中(多个)特定位置添加相应的注释?
4. Docbook参考资料
4.1. Docbook相关的资源和工具下载
4.2. 关于对于Docbook的介绍和解释方面的资料
4.3. 关于对于Docbook的开发过程中可以参考和查阅的资料
5. 未解决的问题
5.1. 支持各种语言的代码的语法高亮
5.2. 中文hypernate断字
5.3. 给callout的co重新编号
6. Docbook各种元素用法举例
6.1. chapter, section, sect1-sect5
6.2. 段落
6.3. 图片figure
6.4. 表格,表格嵌套,表格单元格合并
6.5. 注释callout
6.6. 链接,引用
6.7. 等式
6.8. list列表系列
6.9. 简单列表simplelist,literallayout
6.10. xinclude文件,xinclude文件中的其中一部分的内容
6.11. filename:文件,文件夹,后缀名,
6.12. admonitions:note,caution,warning,tip和important
6.12.1. note
6.12.2. caution
6.12.3. warning
6.12.4. tip
6.12.5. important
6.13. 一些inline元素:keycap,guibutton,keycombo
6.13.1. keycap
6.14. programlisting代码和screen屏幕输出
6.14.1. programlisting代码
6.14.1.1. 带CDATA的programinglist示例
6.14.1.2. 不带CDATA的programinglist示例
6.14.2. screen屏幕输出
6.14.2.1. 带CDATA的屏幕输出screen
6.14.2.2. 不带CDATA的屏幕输出screen
6.15. 问题和回答
7. Docbook相关的知识和概念
7.1. 输出类型:html和打印输出print out
7.2. docbook中的条件编译:profiling
7.3. 关于docbook中的图片方面的内容
7.4. docbook的一些变体
7.4.1. 简化版的docbook
7.4.2. docbook(制作)幻灯片
7.4.3. docbook(制作)网站
A. 已通过Docbook发布的资料
A.1. 基础知识相关
A.2. 嵌入式相关
A.3. 上层软件相关
A.4. 其他
参考书目

插图清单

1. 截图举例:Docbook的XML源码
2. 截图举例:Docbook的可以生成多种格式
3. 截图举例:Docbook的XML源码生成的HTML
4. 截图举例:Docbook的XML源码生成的HTMLs
5. 截图举例:Docbook的XML源码生成的PDF
6. 截图举例:Docbook的XML源码生成的CHM
7. 截图举例:Docbook的XML源码生成的TXT
8. 截图举例:Docbook的XML源码生成的RTF
9. 截图举例:Docbook的XML源码生成的WEBHELP
3.1. coref在HTML中的效果

表格清单

2.1. Docbook中id命名规则

范例清单

3.1. co用法示例
3.2. coref用法示例
6.1. chapter,section,sect1-sect5
6.2. 普通的段落:para
6.3. 带标题的正式的段落:formalpara
6.4. 带标题的图片:figure
6.5. figure内包含2张mediaobject图片
6.6. 不带标题的非正式的图片:informalfigure
6.7. 行内图片:inlinemediaobject
6.8. 表格:table
6.9. 带嵌套(embedded)表格:informaltable
6.10. 待单元格合并的表格:namest,nameend,morerows
6.11. programlisting的callout:programlistingco
6.12. screen的callout:screenco
6.13. 没有callout的co实现在任意位置使用co然后在别处使用coref去引用
6.14. 带xlink域名的link
6.15. xref引用
6.16. 等式equation
6.17. itemizedlist
6.18. 带emphasis的itemizedlist
6.19. 带指定编号类型的orderedlist
6.20. 简单列表simplelist
6.21. 简单列举literallayout
6.22. xinclude主文件中使用xinclude
6.23. 被xinclude包含的子文件:preface.xml
6.24. 被xinclude包含的子文件:ch01_build_env.xml
6.25. filename是文件,文件夹的例子
6.26. 示例:filename是后缀名
6.27. note举例
6.28. caution举例
6.29. tip举例
6.30. keycap举例
6.31. 举例:带CDATA的programinglist
6.32. 举例:不带CDATA的programinglist
6.33. 举例:带CDATA的screen
6.34. 举例:不带CDATA的screen
6.35. 举例:问题和解答qanda相关的示例代码
7.1. 添加role参数实现条件编译