從 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