开发文档一般都由Word或Markdown(格式)撰写,前则多见于企业项目,后则在开源界很流行。但在实际使用中总觉得不尽人意。
他们的不是
Word的问题
- 表现上:格式过于复杂,导致写出来的文档排版、格式很不统一,千人千面,不利于标准化
- 工具上:要么收费(MS)要么广告多(WPS)要么不稳定(一些开源的Office),另外这些都是很重工具
- 不被开源界待见,你说你写了个开源工具,文档是word的,很不和谐呀……:confused:
Markdown的问题
- 表现上:绝对是矫枉过正了,它的语法太简单了,用MD写一篇文章(如本文)还凑合,但要写一个文档的话束缚太多了,谁用谁知道
- 工具上:Gitbook不错,将MD文档用GIT托管是个很不错的Idea,不过它的新版本把导出功能给阉割了(需要用命令行处理),不厚道,有点被gitbook平台绑架的感觉
说了这两个东西不是,那么自然会引荐更合适的喽,这就是我们主角 Asciidoc :heart:
你的好
Asciidoc有什么魅力呢?
- 简洁而不简陋的语法,它专门为编写书籍而生,在语法的支持上很到位,但不像Word那样可以随性,可以让你的文档更统一美观
- AsciidocFX工具开源跨平台,使用体验很不错,更可以导出HTML、PDF、EBook等格式
- Gitbook也支持这个语法(如果你希望用它的话)
一图胜千言
如何学习Asciidoc?
- 了解语法 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
- 有个中语版的语法介绍 http://houqp.github.io/wbwa/wbwa.html
- 有更好的示例吗?当然有喽,用AsciidocFX可以方便地建书籍示例:
它生成的HTML如下:
不要怀疑,这些图及公式是Asciidoc语法生成的图片!
Enjoy!
来源:oschina
链接:https://my.oschina.net/u/816048/blog/524132