Docbook开发手记

目录

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. 其他

参考书目