开启 AsciiDoc 规范之旅

作者 Sarah WhiteDan Allen -

在过去一年中,社区对 AsciiDoc 规范的呼声此起彼伏,很明显,大家已经准备好让 AsciiDoc 迈出这一步。我们也这么认为。我们还联系了 AsciiDoc 的创始人 Stuart,他也表示支持。所以,现在是时候着手此事了。

在 Eclipse Foundation 拥有新家

我们希望 AsciiDoc 能有一个光明的未来,并拥有发展壮大所需的资源。为了实现这一目标,我们决定向 Eclipse Foundation 提交一份 AsciiDoc 语言规范提案。Eclipse Foundation 为规范的制定提供了一个平台,并致力于透明和开源,这些价值观与 AsciiDoc 及其社区高度契合。Eclipse Foundation 规范流程 (EFSP) 提供了一个清晰但可自定义的结构,降低了流程停滞的风险,并确保了结果在实际世界中的可用性。该流程是公开的、供应商中立的,所有源材料和最终产物都是开源的。

AsciiDoc 成为规范意味着什么?

AsciiDoc 语言规范将包括一个开源的规范文档,其中定义了必需和可选的 API 定义、语义行为、数据格式和协议,以及一个开源的技术兼容性套件 (TCK),开发人员可以使用它来开发和测试兼容的实现。(熟悉 Asciidoctor 的 Dan 和我的人都知道,一个开源的 TCK 是我们的硬性要求)。根据 EFSP 的定义,兼容的实现必须完全实现规范版本的所有非可选元素,必须满足相应 TCK 的所有要求,并且不得更改指定的 API。

对于用户和开发者来说,AsciiDoc 规范都将意味着一个清晰、可用的 AsciiDoc 定义及其解释方式。开发者将能够围绕 AsciiDoc 构建实现、工具和服务,而不会有稀释其含义或分裂它的风险。反过来,用户将拥有更多的选择、更高的文档可移植性,并确保兼容的实现和工具能够按照版本化的规范处理他们的 AsciiDoc 文档。

Asciidoctor 将何去何从?

我们计划让 Asciidoctor (RubyGem) 成为 AsciiDoc (规范) 的独立、兼容的实现。(这并不意味着 Asciidoctor 的整体将迁移到 Eclipse Foundation)。为了通过 TCK 测试,这可能意味着 Asciidoctor 中需要添加、删除或更改功能,以满足规范的必需和可选元素。Asciidoctor.js 和 AsciidoctorJ 项目,如果他们选择这样做,也可以决定成为独立的、兼容的实现,并且拥有比以前更大的自由度。这将为新兴的实现将 AsciiDoc 带到更多平台腾出空间。

一旦规范流程开始进行,我们将了解更多信息,并及时向您通报预期情况。

准备好了吗?开始吧!

创建 AsciiDoc 规范的下一步是将其作为一个规范项目提交给 Eclipse Foundation。我和 Dan(作为 OpenDevise,代表 Asciidoctor)计划提交的提案将由 Eclipse 管理组织审查,然后发布供社区审查和评论。想了解更多关于规范流程的信息,我鼓励您查看 Wayne Beaton 的博文 第二部分:EFSP第三部分:创建。规范流程是 Eclipse 开发流程 (EDP) 的一个分支,您可以在 第一部分:EDP 中阅读。您也可以阅读 EFSP 文档

通过一个可以适应 AsciiDoc 社区需求的规范流程,我和 Dan 相信该语言将以可持续且实质性的方式发展,从而跟上社区当前和未来的需求。我们非常期待开始,希望您能加入我们,共同努力,让 AsciiDoc 成为一项规范!


太棒了!AsciiDoc 真是不可思议!我印象深刻!(2012)

作者 Dan Allen -

大家可能听说了,Google+ 正在沉没。可悲的是,我当初发现 AsciiDoc 时发布的那篇帖子也将随之消失……一切都始于那里。我对 AsciiDoc 的兴趣,甚至 Asciidoctor 的起源,都可以追溯到这篇帖子。为了不让这段历史消失,我决定将其保存在 Asciidoctor 博客上。请注意,这篇帖子中的一些引用已经过时。

Google+ 帖子

在花了两天时间将几篇完整的技术教程转换为 AsciiDoc 并深入研究其功能后,我现在可以称得上精通 AsciiDoc 了。

AsciiDoc 是一种轻量级但功能强大的标记语言,它应有尽有

  • 它易于阅读

  • 它内容全面

  • 它可扩展

  • 它能生成精美的输出(HTML、DocBook、PDF、ePub 等)

这才是一门值得用来写书的轻量级标记语言!

如果您有兴趣用它来写书,请参阅 git-scribe:https://github.com/schacon/git-scribe

可以这样理解

如果 Markdown 是个一年级学生,那么 AsciiDoc 就是博士生。

对于基本格式化,Markdown 和 AsciiDoc 的外观非常相似,这使得 AsciiDoc 成为 Markdown 的一个即插即用、无需思考的替代品(在简洁性和平滑迁移方面都是如此)。然而,AsciiDoc 的语法似乎永无止境。事实上,它确实没有尽头,因为它(可以)相当容易地进行扩展(和调整)。

那 Docbook 呢?啊!AsciiDoc 的妙处在于,您仍然可以生成 Docbook,而无需付出任何痛苦,也无需牺牲任何功能。也许 AsciiDoc 应该采纳这个口号

用 Docbook 写东西简直是反人类的。

我可以列出 AsciiDoc 支持的所有功能,但一个展示比任何语言都更能说明问题:http://powerman.name/doc/asciidoc

回到我的实验……

我有机会认真评估和比较了几种重要的轻量级标记语言:reStructuredText(及其补充 Sphinx)、Textile 和 AsciiDoc。毫无疑问,AsciiDoc 是赢家。如果软件中有“万无一失”这样的说法,那 AsciiDoc 就是了。

我首先将一篇完整的技术教程转换为 reStructuredText。花费了大约 3 个小时才艰难地弄懂语法并完成转换,但仍然存在一些遗漏。语法实在古怪(为什么痴迷于反引号和冒号?),而且很难记住。总的来说,让人感觉不舒服。我相当沮丧,准备放弃了。

睡前,一丝好奇心驱使我去尝试 AsciiDoc。在 15 分钟内,我就完成了整个文档的转换。此外,我还获得了 HTML、PDF、纯文本、ePub 和 Docbook 的输出。我甚至开始尝试额外的格式化和组织功能。我感觉像是找到了文档的圣杯。

这是那个实验的结果

文档可以很简单也很有趣。谁能想到呢?

我对 AsciiDoc 的兴奋程度与我对 git 的兴奋程度相当(两者结合简直是天作之合)。还有很多东西有待探索。我强烈鼓励大家去试试。AsciiDoc 甚至在 github(和 gists)上被支持为一种标记格式,非常容易上手。

如果您使用 Fedora,请直接从网站下载最新版本的 AsciiDoc,而不是安装 RPM 包。RPM 包缺少一些分发文件。
更新(2014-08-15)
由于这篇帖子经常被引用以获取有关 AsciiDoc 的信息,我将更新它,指向一个更近期的 AsciiDoc 速查表。请参阅 https://asciidoctor.org.cn/docs/asciidoc-syntax-quick-reference/

帖子活动

评论

39

57

分享

24

参与者

Henry Lee +1,Milan Navrátil +1,Ravishankar Haranath +1,Markus C +1,Chris Drew +1,csgeek 分享,Andrey “Bass” Shcheglov +1,Gavin Engel +1,Марк Сафронов +1 并分享,Liam OBrien +1,Anatoly Yakubov +1,Mhd Shulhan +1,Kartik Singhal +1,Ahmad Khayyat +1,Benjamin Kampmann 分享,Kevin Retzke +1,张文涛 +1 并分享,Shane Weng 分享,Alex Sherlock 分享,Sascha Lüdecke +1,Jonathan Bullock +1,Sten Aksel Heien 分享,Paulo Jerônimo +1,Anthonny Querouil 分享,Dave Campbell 分享,Leif Gruenwoldt +1 并分享,Søren Jones +1,Edmund Haselwanter +1,John Zoidberg +1,Ophir Radnitz +1,Italo Penna +1 并分享,Peti Koch 分享,Daniel Faust +1,cesare cugnasco +1,Tong Sun 分享,Jason Lee +1,Ding-Yi Chen +1,Aditya Raj Bhatt +1,sebastien rey coyrehourcq 分享,Martin Pool +1,Thomas McDermott +1 并分享,Easytouch 分享,Stéphane Gourichon 分享,Günter Zöchbauer +1,Timo Ollech +1,Antoni Silvestre Padrós +1,Dmitry Afanasiev +1 并分享,William Chambers 分享,Mani B +1,Anton Leontiev 分享,Fabricio Godoy +1,Gianluca Scacco 分享,Jeffrey Cardona +1,Brian Leathem +1,Samuel Bancal 分享,Jose Torres +1,Sebastian Peters +1,Ștefan Suciu +1,Roman Frołow +1 并分享,John Jelinek +1,Holger Joest 分享,Agam Brahma +1,Too simple, Sometimes naive +1,Jared Morgan +1,DeWitt Clinton +1,Alexander Zobkov +1


  • 1 / 1