- 装备 tags:
- foss
- linux published: true comments: true
写文档是头疼事，没人愿意写文档。在word里写文档，时间长了都怀疑自己是不是搞技术的。我阅历有限，在我的印象里就没有用word格式看过什么有价值的东西。只要一打开word想到的就是连篇累牍的废话、码字。word最重要的功能是什么？保存。其次呢？字数统计。我所写过的word文档绝大多数都是“只写”的，通常作为流程里的一个附件，没有人真正去看。
以上是人身攻击，接下来比较实际的问题，word文档不是符合unix哲学的东西。格式不开放，你就没有办法进行diff操作，把word文档放到svn里，只能使用最基本的版本控制，没法查看changeset，只知道改了，不知道改了什么。
为了改变这种情况，我试过用docbook格式。docbook用xml书写，定义了一套复杂的Schema，详细到作者的email都有定义。docbook还有丰富的工具集，可以通过xsl把docbook转换成所有你知道的文档格式。Maven: the Definitive Guide就是用docbook写成的。不过用docbook也存在一些问题，docbook太复杂了，用纯文本编辑器很难处理，作者的学习曲线也比较高，需要所见即所得的编辑器支持。与docbook相类似的DITA，也存在这样的问题，它们是重量级的格式。
轻量级的Wiki格式不错，但是Wiki格式很让人头疼就是没有统一的规范。举例，dokuwiki里顶级标题是6个=，而moinmoin里顶级标题恰恰相反是一个=，不portable，文档维护起来就非常麻烦。
铺垫了这么多，委屈以上格式了，该markdown出场了。markdown是简单的html原型，用来生成html，它的设计目标就是为了KISS，兼容html。看看一些必要的格式吧：（或者直接看Wikipedia）
标题
# 标题
## 二级标题
...
###### 六级标题
对于一级标题还可以这么写
headline
========
二级标题可以
headline
--------
这个怎么输入呢，我想起来前几天看vim hacks里的一组快捷键
yypoVr=
yypoVr-
谁用谁知道
段落：
一段文本以两个换行结束。
换行：
一行文本行末两个空格。
图片
用markdown，图片的alt你不写都不行。
链接
[Linktext](link "linktitle")
列表
ul 无序列表
*
*
ol 有序列表
1.
2.
以上就是主要的格式支持。用标题来划分文档层次，没有多余的格式，没有机会让你五颜六色。
在linux上可以安装markdown的处理脚本：
apt-get install markdown
安装vim的语法文件：
http://www.vim.org/scripts/script.php?script_id=1242
这里是一个简单的例子：
http://github.com/sunng87/exaile-doubanfm-plugin/blob/master/README.mkd
The post is brought to you by lekhonee v0.7