标签：
写文档一直是程序员非常讨厌的工作, 甚至和改需求一样令人厌烦. 在程序员眼里比写程序还难, 即便强制执行下来文档质量也很难让人满意.
相信大多数公司写文档都是用 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
输出也可以用一个 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
从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档
标签：
原文地址：http://my.oschina.net/zhzhenqin/blog/415942
