从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档

写文档一直是程序员很是讨厌的工做, 甚至和改需求同样使人厌烦. 在程序员眼里比写程序还难, 即使强制执行下来文档质量也很难让人满意.

相信大多数公司写文档都是用 Word, 笔者也是用了 Word 写了好几个项目的文档. 架构, 设计, 运维等好几份, 呵呵, 即使是写的再好, 交给客户也基本是不看的. 一个文档是项目组内好几个成员编写的, 你们各写各的模块, 各自的实现, 而后一块儿合并, 合并时修改字体, 字号, 目录等, 第一次合并还好, 再升级几个版本后, 你们改了哪里, 没改哪里, 根本看不出来.

因而我就开始找一些文档工具. 我的一直看 Spring 的项目文档, Pdf 格式和在线 Html 格式都写的很是漂亮. 相信你们都很熟悉. 以下:

因而锁定了 Docbook 这个文档工具. Docbook 是支持 Maven 的, 在 pom 的 plugins 中加上支持 Docbook 的 plugin.

'''

<plugin>
            <groupId>org.jboss.maven.plugins</groupId>
            <artifactId>maven-jdocbook-plugin</artifactId>
            <version>2.3.8</version>
            <extensions>true</extensions>
            <dependencies>
                <dependency>
                    <groupId>org.jboss</groupId>
                    <artifactId>jbossorg-docbook-xslt</artifactId>
                    <version>1.1.1</version>
                </dependency>
                <dependency>
                    <groupId>org.jboss</groupId>
                    <artifactId>jbossorg-jdocbook-style</artifactId>
                    <version>1.1.1</version>
                    <type>jdocbook-style</type>
                </dependency>
                <dependency>
                    <groupId>org.jboss.jdocbook</groupId>
                    <artifactId>jdocbook-core</artifactId>
                    <version>1.0.7</version>
                    <exclusions>
                        <exclusion>
                            <groupId>net.sf.docbook</groupId>
                            <artifactId>docbook-xml</artifactId>
                        </exclusion>
                        <exclusion>
                            <groupId>net.sf.docbook</groupId>
                            <artifactId>docbook-xsl</artifactId>
                        </exclusion>
                    </exclusions>
                </dependency>
                <dependency>
                    <groupId>net.sf.docbook</groupId>
                    <artifactId>docbook-xml</artifactId>
                    <type>pom</type>
                    <version>5.0</version>
                </dependency>
                <dependency>
                    <groupId>net.sf.docbook</groupId>
                    <artifactId>docbook-xsl</artifactId>
                    <type>pom</type>
                    <version>1.76.1</version>
                </dependency>
            </dependencies>
            <executions>
                <execution>
                    <id>tutorial_zh_CN</id>
                    <phase>package</phase>
                    <goals>
                        <goal>resources</goal>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <sourceDocumentName>index.xml</sourceDocumentName>
                        <masterTranslation>zh-CN</masterTranslation>
                        <sourceDirectory>${basedir}/src/main/docbook</sourceDirectory>
                        <fontsDirectory>${basedir}/src/main/fonts</fontsDirectory>
                        <imageResource>
                            <directory>${basedir}/src/main/docbook</directory>
                        </imageResource>
                        <cssResource>
                            <directory>${basedir}/src/main/docbook</directory>
                        </cssResource>
                        <formats>
                            <format>
                                <formatName>html</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/xhtml.xsl
                                </stylesheetResource>
                                <finalName>index.html</finalName>
                            </format>
                            <format>
                                <formatName>html_single</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/xhtml-single.xsl
                                </stylesheetResource>
                                <finalName>index.html</finalName>
                            </format>
                            <format>
                                <formatName>pdf</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/pdf.xsl</stylesheetResource>
                                <finalName>${project.name}-zh_CN-${project.version}.pdf</finalName>
                            </format>
                        </formats>
                        <options>
                            <xincludeSupported>true</xincludeSupported>
                            <autoDetectFonts>true</autoDetectFonts>
                        </options>
                    </configuration>
                </execution>
            </executions>
        </plugin>

''' 而后组织好文档目录结构, 就能够生成各类格式的文档的了. 编写的文档是 xml 格式, 能使用文本对比工具作对比. 文档也被拆分红不少章节, 成员各编辑各的章节, 管理也方便许多, 直接在项目目录下建个 Maven 项目, 项目内存放这些文档.

可是, docbook 语法着实让你们都头疼, 我学习了一遍没关系, 你们都学习一遍. 文档中夹杂大量的 xml 标记, 加个图片, 加个段落, 加个列表等很是麻烦. 困难的是有时候加个图片生成 pdf 已经超出 pdf 显示范围了.

在 github 上看到有人用 ascii-doc 写开源翻译文档, 语法是 markdown 格式, 并且能生成各类格式. 我边尝试了一把, 起初还觉得是 Maven 的 plugin, 找了好久没找到这样的 plugin. 无果. 无心中发现了 pandoc 这个工具, 编写文档可使用 markdown, 简单的 pandoc 命令就能生成 html, epub, word, pdf 等格式, 我深深的被吸引. 我用的 Mac, 安装这类软件很麻烦, 网上说需什么 brew, 或者源码编译安装. 几回尝试都不成功, 试了好久就想放弃. 可是最后在一个 blog 中发现一个链接, 终于下载到了 pandoc 的 OS X 的安装包. 花了很大力气, 不敢独享, 分享给你们: http://pan.baidu.com/s/1c0fJ01i | pandoc-1.9.4.2.dmg

Pandoc 确实是文档的终结者, 能把 txt, word, pdf, docbook, markdown 等格式相互转换. 其实他们相互转换仍是有些兼容性问题的. 可是只要能把 markdown 格式转成任意格式, 那就是最重要的功能. 如把 markdown 转成 html 命令: pandoc -f markdown -o readme.html readme.md

• -f 来源的格式
• -o 输出到文件

输出也能够用一个 css 把网页修饰的更漂亮一点. 能够加 -c style.css 等等.

如要转成word 格式, 可使用命令:

pandoc -f markdown -o readme.docx readme.md

如你所见, pandoc 能够用 -o 指定的文件的后缀来肯定你要输出的是什么格式. pandoc 转成 pdf 须要latex支持, 而且对中文支持须要在命令行指定中文编码字符集:

pandoc -f markdown -o readme.pdf --latex-engine=xelatex -V  mainfont="SimSun" readme.md

在生成 word, pdf, html 时, 也仍然可使用 -c 加上一个 css 参数来控制让文档更美观一些.

下面是 pandoc 命令行:

pandoc --help
pandoc [OPTIONS] [FILES]
Input formats:  native, json, markdown, markdown+lhs, rst, rst+lhs, docbook,
            textile, html, latex, latex+lhs
Output formats: native, json, html, html5, html+lhs, html5+lhs, s5, slidy,
            slideous, dzslides, docbook, opendocument, latex, latex+lhs,
            beamer, beamer+lhs, context, texinfo, man, markdown,
            markdown+lhs, plain, rst, rst+lhs, mediawiki, textile, rtf, org,
            asciidoc, odt, docx, epub
Options:
  -f FORMAT, -r FORMAT  --from=FORMAT, --read=FORMAT                    
  -t FORMAT, -w FORMAT  --to=FORMAT, --write=FORMAT                     
  -o FILENAME           --output=FILENAME                               
                    --data-dir=DIRECTORY                            
                    --strict                                        
  -R                    --parse-raw                                     
  -S                    --smart                                         
                    --old-dashes                                    
                    --base-header-level=NUMBER                      
                    --indented-code-classes=STRING                  
                    --normalize                                     
  -p                    --preserve-tabs                                 
                    --tab-stop=NUMBER                               
  -s                    --standalone