文档章节

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

孤岛旭日
 孤岛旭日
发布于 2015/10/30 17:32
字数 580
阅读 6392
收藏 19

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

© 著作权归作者所有

孤岛旭日
粉丝 46
博文 58
码字总数 30599
作品 3
杭州
架构师
私信 提问
Asciidoctor Maven 插件

参考资料 1,使用Swagger2Markup、asciidoctor-maven-plugin和asciidoctorj-pdf插件生成PDF格式的API文档中文问题解决 2、asciidoc最佳实践-maven插件 3、Asciidoctor Maven插件使用 4、Asc...

近在咫尺远在天涯
05/07
53
0
Pandoc 1.15.2 发布,文档格式转换工具

Pandoc 1.15.2 发布,该版本包含众多改进和 bug 修复,详细列表请看这里。 Pandoc 可将多种文档格式,包括:markdown, reStructuredText, textile, HTML, DocBook, or LaTeX 转成: HTML for...

oschina
2015/11/26
788
1
SpringBoot2基于Swagger2生成离线Api文档

通过swagger2与swagger-ui可以很方便的生成系统的在线api文档,这方面的博客网上有很多。 但是利用swagger生成离线api文档的博客就不多了。有的无法兼容springboot2,有的配置起来太麻烦,复...

谢随安
01/30
0
0
RTextDoc 1.6 发布,LaTeX/TeX 编辑器

RTextDoc 1.6 发布了,改进内容: Support for AsciiDoc markup language is added. ASciiDoc is powered by the AsciiDoctor engine. The following features for AsciiDoc are added: a d......

oschina
2013/11/23
325
2
Calcurse 2.9.0 发布,基于控制台的日程管理

Calcurse 是一个基于文本的个人日程安排软件,可对事件、委任和每日事务进行跟踪,可配置的提醒系统。 新版本支持短日期格式,新增 "backword-kill-word" 行编辑功能,自动删除空的条目;使用...

红薯
2011/05/29
511
0

没有更多内容

加载失败,请刷新页面

加载更多

Giraph源码分析(八)—— 统计每个SuperStep中参与计算的顶点数目

作者|白松 目的:科研中,需要分析在每次迭代过程中参与计算的顶点数目,来进一步优化系统。比如,在SSSP的compute()方法最后一行,都会把当前顶点voteToHalt,即变为InActive状态。所以每次...

数澜科技
今天
4
0
Xss过滤器(Java)

问题 最近旧的系统,遇到Xss安全问题。这个系统采用用的是spring mvc的maven工程。 解决 maven依赖配置 <properties><easapi.version>2.2.0.0</easapi.version></properties><dependenci......

亚林瓜子
今天
10
0
Navicat 快捷键

操作 结果 ctrl+q 打开查询窗口 ctrl+/ 注释sql语句 ctrl+shift +/ 解除注释 ctrl+r 运行查询窗口的sql语句 ctrl+shift+r 只运行选中的sql语句 F6 打开一个mysql命令行窗口 ctrl+l 删除一行 ...

低至一折起
今天
9
0
Set 和 Map

Set 1:基本概念 类数组对象, 内部元素唯一 let set = new Set([1, 2, 3, 2, 1]); console.log(set); // Set(3){ 1, 2, 3 } [...set]; // [1, 2, 3] 接收数组或迭代器对象 ...

凌兮洛
今天
4
0
PyTorch入门笔记一

张量 引入pytorch,生成一个随机的5x3张量 >>> from __future__ import print_function>>> import torch>>> x = torch.rand(5, 3)>>> print(x)tensor([[0.5555, 0.7301, 0.5655],......

仪山湖
今天
6
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部