使用Asciidoc代替Markdown和Word撰写开发文档

原创
2015/10/30 17:32
阅读数 2.6W

开发文档一般都由Word或Markdown(格式)撰写,前则多见于企业项目,后则在开源界很流行。但在实际使用中总觉得不尽人意。

他们的不是

Word的问题

  1. 表现上:格式过于复杂,导致写出来的文档排版、格式很不统一,千人千面,不利于标准化
  2. 工具上:要么收费(MS)要么广告多(WPS)要么不稳定(一些开源的Office),另外这些都是很重工具
  3. 不被开源界待见,你说你写了个开源工具,文档是word的,很不和谐呀……:confused:

Markdown的问题

  1. 表现上:绝对是矫枉过正了,它的语法太简单了,用MD写一篇文章(如本文)还凑合,但要写一个文档的话束缚太多了,谁用谁知道
  2. 工具上:Gitbook不错,将MD文档用GIT托管是个很不错的Idea,不过它的新版本把导出功能给阉割了(需要用命令行处理),不厚道,有点被gitbook平台绑架的感觉

说了这两个东西不是,那么自然会引荐更合适的喽,这就是我们主角 Asciidoc :heart:

你的好

Asciidoc有什么魅力呢?

  1. 简洁而不简陋的语法,它专门为编写书籍而生,在语法的支持上很到位,但不像Word那样可以随性,可以让你的文档更统一美观
  2. AsciidocFX工具开源跨平台,使用体验很不错,更可以导出HTML、PDF、EBook等格式
  3. Gitbook也支持这个语法(如果你希望用它的话)

一图胜千言

AsciidocFX效果

如何学习Asciidoc?

  1. 了解语法 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
  2. 有个中语版的语法介绍 http://houqp.github.io/wbwa/wbwa.html
  3. 有更好的示例吗?当然有喽,用AsciidocFX可以方便地建书籍示例: 新建示例书籍

它生成的HTML如下:

代码和表格示例

不要怀疑,这些图及公式是Asciidoc语法生成的图片!

绘图及公式

Enjoy!

展开阅读全文
打赏
2
23 收藏
分享
加载中
有用
2019/09/06 13:47
回复
举报
更多评论
打赏
1 评论
23 收藏
2
分享
返回顶部
顶部