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

*爱你&永不变心* 提交于 2020-02-29 06:32:23

开发文档一般都由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!

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!