What is AsciiDoc? Why do we need it?

写作是困难的。

曾经的经验使我们对此深信不疑。

但是,我们却不能逃避,尤其是在技术行业。 我们 必须 书写。 如果没有好的文档,即使再华丽的软件都一无是处。 如果连用户都失败了,那么项目也好不到哪里去。

除非你的 UI 的可发现性 特别好,否则说 “这个特性不需要文档” 就等同于说 “产品做不到。”
— Nick Coghlan

换句话说

成也文档,败也文档。
— Matthew Ginnard

为什么,为什么我们要把文档隐藏在复杂的 XML 模式例如 DocBook,为什么要让复杂的文字处理器使我们分析?为什么我们要浪费时间与繁琐的所见即所得编辑器作战?

想象一下,如果写文档能像写电子邮件一样简单该多好?

真能 办到

思想就在轻量级编辑语言背后,例如 AsciiDoc。 它们提供纯文本语法、精美的修饰、以及直觉性的标记,这些就是为方便人类以原始格式来阅读、书写和编辑文档而设计的。 自然直觉的语法让你可以专注在内容上。 最好的还在于纯文本可以非常快速容易地转化出其他格式,例如 HTML 5,来展示。

在这个 AsciiDoc 介绍里,我们将说明它是什么,它为什么有价值以及什么使它有别于其他的替代品,例如 Markdown。 你将会发现减少编写文档痛苦的关键在于减少尖括号,而你需要的知识就隐藏其中。

学习如何减少书写和发布文档的工作—​无论它是笔记、文档、文章、书籍、网页或者散文—​参得书写之禅,释放禁锢在心灵中的灵感,前进。

什么是 AsciiDoc?

AsciiDoc 指两种事物:

  1. 一种成熟的[1],纯文本书写格式,可用于书写笔记、文章、文档、书籍、电子书、网页、幻灯片、博客帖子、man 帮助等等。

  2. 文本处理器及将 AsciiDoc 文档转化为数十种格式(被称为 后端)的工具链,包括 HTML、DocBook、PDF和ePub等。[2].

AsciiDoc 属于 轻量级标记语言 家族,它们中最知名的就是 Markdown。 AsciiDoc 从中脱颖而出的重要原因是它支持所有起草文章,技术手册,书籍,演讲和散文的必要结构元素。 事实上,它能够满足大多数的排版需求,即使是最先进的出版需求以及技术术语。

一个有力事实证据就是, 很多 O’Reilly 作者包括 Matthew McCulloughTim BerglundSimon St.LaurentMatt NeuburgIan Darwin 已经开始使用 AsciiDoc 来编写它们的书籍来描述具有标志性意义的技术库。

从一开始,AsciiDoc 就被设计成用于替换 DocBook,这是一种 AsciiDoc 可以生成的格式。 AsciiDoc 也可以生成精美的 HTML 5、PDF、eBooks、man 帮助,甚至幻灯片。 它可以覆盖从初稿到出版之间的所有需求。

现在,我们已经知道 AsciiDoc 具体是什么,来让我们看看为什么需要它。

为什么使用 AsciiDoc?

作为人类,交流和思考都没有任何障碍。 事实上,我们很精通这些。 它只是一个心理活动,当一个想法飞入我们脑中。

另一方面,写作却很少来得这么容易。

当把我们的想法写下来时,我们 很难 找到相应的恰当词汇,至少我们不知该如何安排、组织它们。 That damn inner critic disrupts the stream of consciousness we coast on while talking or thinking.

我们就可以合理下结论:写作是困难的。

或者呢?

关于写作: 电子邮件 vs 文档

书写电子邮件很简单。 我们经常写。 每天,我们都要回复数十封电子邮件和社交媒体信息。 这设计到通过写作来沟通。 对,就是 写作

当我们龙飞凤舞地敲击键盘回复邮件时,我们很难意识到我们是在书写…​ 无比流畅!

这就表明…​

大多数人写邮件没有问题。 他们几乎不会意识到他们是在写作。 没有任何写作的限制。 当有人问你一个问题时,你点击回复,然后尽情打字。

所以,为什么我们却需要努力地写 文档 呢?

我们之所以需要努力地写文档的主要原因是我们并不像想写邮件一样写文档。 相反,我们允许复杂的文字处理器来不断地扰乱我们,把实际内容隐藏在复杂的 XML 模式中,比如 DocBook,或者就是和繁琐的所见即所得编辑器抗争。

我们是如何让自己进入这个烂摊子呢?

文字处理器,作家真正的阻碍

When you’re in the writing (i.e., typing) phase, you want the words to flow onto the screen with minimal distractions and interruptions. Flow, not just time, is essential.

Most word processors excel at distracting you from writing. The result: you write less (ironic, huh?).

In a word processor, before you can type the first word on a blank white screen, you’re forced to think about what font family you want, what font size you want, what lines spacing you want and so on. Once you do get going, auto-correct, spelling and grammar suggestions entice you to backtrack and lose your next thought. “Smart” quotes and auto-linking messes with the text as fast as you can enter it. If you paste text, it likely gets added to the document with a different font family, size and even color.

Undo. Undo. Undo!

Let’s not even talk about inserting source code. The designers of word processors clearly did not.

Format. Format. Format!

After burning time fighting with its interface, you rightfully conclude that the word processor is trying to sabotage your writing process.

We need an easier way to write!

But how?

使用你所知道的

What if you could write documentation like you write e-mail?

Imagine being able to forget about layout, typesetting, styling (and even some semantics) and just write. That’s the idea behind lightweight markup languages such as Markdown and AsciiDoc.

Here’s how John Gruber introduced Markdown (in March 2004):

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

The single biggest source of inspiration for Markdown’s syntax is the format of plain text e-mail.

— John Gruber, Creator of Markdown

Similarly, here’s how Stuart Rackham introduced AsciiDoc (2 years earlier):

You write an AsciiDoc document the same way you would write a normal text document. There are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats.
— Stuart Rackham, Creator of AsciiDoc

These languages are designed to enable humans to write documents, and for other humans to be able to read them, as is, in raw form.

下面是一个基本的 AsciiDoc 文档示例:

= Introduction to AsciiDoc
Doc Writer <doc@example.com>

A preface about http://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,ruby]
puts "Hello, World!"

这是纯文本语法,我们 了解 这些!

相比这些,使用 DocBook 来书写同样的文档:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article lang="en">
  <articleinfo>
    <title>Introduction to AsciiDoc</title>
    <date>2013-01-01</date>
    <author>
      <firstname>Doc</firstname>
      <surname>Writer</surname>
      <email>doc@example.com</email>
    </author>
    <authorinitials>DW</authorinitials>
  </articleinfo>
  <simpara>
    A preface about
    <ulink url="http://asciidoc.org">AsciiDoc</ulink>.
  </simpara>
  <section id="_first_section">
    <title>First Section</title>
    <itemizedlist>
      <listitem>
        <simpara>item 1</simpara>
      </listitem>
      <listitem>
        <simpara>item 2</simpara>
      </listitem>
    </itemizedlist>
    <programlisting language="ruby"
        linenumbering="unnumbered">
      <![CDATA[puts "Hello, World!"]]>
    </programlisting>
  </section>
</article>

呀!

即使 DocBook (和 HTML)不复杂,但是他们却输在了可读性上。

DocBook is nice, but (like XML) it is not meant for editing nor for merging changes (by humans). Using AsciiDoc (which translates to DocBook perfectly) is a much easier way of developing.
— Dag Wieers

AsciiDoc gets us back to what’s important: writing. You can drop those angle brackets, but you don’t have to drop the semantics. And it’s a syntax a human can actually edit, efficiently.

Use AsciiDoc for document markup. Really. It’s actually readable by humans, easier to parse and way more flexible than XML.
— Linus Torvalds

Here’s the really great thing about AsciiDoc. Worse case scenario, you convert it to DocBook as a common exchange format. DocBook is the “no lock-in” exit path for AsciiDoc. You decide AsciiDoc doesn’t work out, you can bail on it without losing a word. No need to invent another format. That’s why so many people are going all in on it.

谁在使用 AsciiDoc?

AsciiDoc 并不如 Markdown 一样被广泛接受。但是,它却可以用在一些很严肃的地方。下面是一些值得关注的例子:

例子要比推荐的这些多得多。 他们也许给你一些灵感,让你如何在项目中成功使用 AsciiDoc。

AsciiDoc 书写之禅

AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets. In other words, it’s about discovering writing zen.

AsciiDoc works because:

  • It’s readable

  • It’s concise

  • It’s comprehensive

  • It’s extensible

  • It produces beautiful output (HTML, DocBook, PDF, ePub and more)

AsciiDoc is easy to write and its easy to read (in raw form). It’s also easy to proof and edit. After all, it’s plain text, just like that familiar e-mail.

The AsciiDoc syntax is intuitive because it recognizes time-tested, plain text conventions for marking up or structuring the text. The punctuation was carefully chosen to look like what it means. A user unfamiliar with AsciiDoc can figure out the structure and semantics (i.e., what you mean) just by looking at it. Best of all, it only requires a text editor to read or write.

AsciiDoc allows you to focus on the actual writing and only worry about tweaking the output when you are ready to render the document. The plain-text of an AsciiDoc document is easily converted into a variety of output formats, beautifully formatted, without having to rewrite the content.

Copy text from an e-mail into a document and see how quickly you can turn it into documentation. Almost immediately, you’ll find your writing zen and enjoy the rewarding experience of sharing knowledge.

Live or die by documentation?
“Live!”

下一步

With an understanding of what AsciiDoc is and why it’s so desperately needed, you’re encouraged to delve into the AsciiDoc syntax covered in the AsciiDoc Writer’s Guide. If you’re just looking for a cheat sheet, check out the AsciiDoc Quick Reference. Hopefully you’ll agree the syntax just makes sense.


1. AsciiDoc 已经出来十多年,最早于2002年发布。
2. 有两个 AsciiDoc 处理器实现。原始处理器,被命名为 AsciiDoc,由 Python 实现。更现代的实现是 Asciidoctor,由 Ruby 实现。