“写作是困难的。”
这就是经验让我们相信的。
但是，我们无法回避它，尤其是在科技行业。我们必须写作。即使是最出色的软件，没有良好的文档也是无用的。如果用户失败了，项目也随之失败。
除非你的 UI 可发现性非常好，否则说“该功能未记录”就等于说“产品无法做到”。
换句话说，
成败皆因文档。
那么，为什么我们要通过将内容埋藏在 DocBook 等 XML 模式中，允许复杂的文字处理器分散我们的注意力，或者浪费时间与挑剔的所见即所得编辑器搏斗来使写作变得更加困难呢？
想象一下，如果写作文档就像写电子邮件一样简单。
可以做到.
这就是 AsciiDoc 等轻量级标记语言背后的理念。它们提供一种纯文本语法，并辅以细致但直观的标记，旨在供人类阅读、编写和编辑原始格式。语法的自然感觉使您专注于内容。最重要的是，纯文本可以快速轻松地转换为 HTML5 等输出格式进行呈现。
在本指南中，我们将介绍 AsciiDoc 是什么，它为何有价值，以及它与 Markdown 等替代品的区别。您会发现，逃离写作文档的痛苦的关键在于放弃那些埋没您知识的尖括号。
要学习如何减少写作和发布内容的（无论是笔记、文档、文章、书籍、网页还是传统的散文）工作量，并达到写作的禅意，或者仅仅是释放您脑中的想法，请继续阅读。
什么是 AsciiDoc？
AsciiDoc 是两样东西
AsciiDoc 属于轻量级标记语言家族，其中最著名的是Markdown。AsciiDoc 在此家族中脱颖而出，因为它支持起草文章、技术手册、书籍、演示文稿和散文所需的所有结构化元素。事实上，它甚至能够满足最先进的发布需求和技术语义。
作为事实的证明，包括Matthew McCullough、Tim Berglund、Simon St.Laurent、Matt Neuburg 和 Ian Darwin 在内的许多 O’Reilly 作者都使用 AsciiDoc 为那套标志性的技术丛书编写书籍。
从一开始，AsciiDoc 的设计初衷就是作为DocBook 的一种快捷方式替代品，而 DocBook 是 AsciiDoc 可以生成的格式之一。AsciiDoc 还可以生成精美的 HTML5、PDF、电子书、man 页甚至演示文稿。它涵盖了从初稿到发布的各个环节。
现在我们已经了解了 AsciiDoc 是什么，让我们来考虑一下为什么需要它。
为什么选择 AsciiDoc？
作为人类，我们毫不费力地交谈和思考。事实上，我们在这方面非常流利。这是一种想法出现时就会发生的活动。
另一方面，写作很少如此轻松。
当需要将想法写下来时，我们挣扎着寻找词汇——或者至少是如何组织和安排它们。那该死的内在批评家打断了我们在交谈或思考时所依靠的意识流。
可以合理地得出结论，写作就是很困难。
还是说，并非如此？
关于写作：电子邮件 vs 文档
写电子邮件很容易。我们一直都在这样做。每天，我们都会回复几十封电子邮件和社交媒体消息。这涉及到通过写作进行交流。没错，就是写作！
然而，在我们回复电子邮件时，在噼里啪啦的打字声中，我们几乎没有意识到自己在写作……并且是流利地写作！
结果证明……
大多数人都 OK 写电子邮件。他们不认为这是写作。没有写作障碍。有人问你一个问题，你[按下]回复，然后就开始打字。
那么，为什么我们难以撰写文档呢？
我们之所以难以写作的主要原因是，我们不像写电子邮件那样写文档。相反，我们允许自己被复杂的文字处理器分散注意力，将内容埋藏在 DocBook 等 XML 模式中，或者与挑剔的所见即所得编辑器搏斗。我们是如何陷入这种困境的？
文字处理器，真正的写作障碍
当您处于写作（即打字）阶段时，您希望文字以最少的干扰和中断流到屏幕上。流畅性，而不仅仅是时间，是至关重要的。
大多数文字处理器都擅长让你分心写作。结果：你写得更少（讽刺吧？）。
在文字处理器中，在您能够在空白的白屏幕上输入第一个字之前，您就被迫考虑您想要的字体系列、字体大小、行距等等。一旦您开始写作，自动更正、拼写和语法建议就会诱使您回溯并丢失下一个想法。“智能”引号和自动链接会快速地篡改您输入的文本。如果您粘贴文本，它很可能会以不同的字体系列、大小甚至颜色添加到文档中。
撤销。撤销。撤销！
我们甚至都不想谈论插入源代码。文字处理器的设计者显然没有这样做。
格式。格式。格式！
在花费时间与界面斗争之后，您会理所当然地得出结论，文字处理器正试图破坏您的写作过程。
我们需要一种更简单的写作方式！
但是如何实现呢？
使用你所知道的
如果你能像写电子邮件一样写文档，那该多好？
想象一下，您可以忘记布局、排版、样式（甚至一些语义）而只需写作。这就是轻量级标记语言（如 Markdown 和 AsciiDoc）背后的理念。
这是 John Gruber 对 Markdown 的介绍（2004 年 3 月）
Markdown 格式语法的首要设计目标是使其尽可能易于阅读。
Markdown 格式的文档应可作为纯文本直接发布，看起来不像是用标签或格式指令标记过的。
Markdown 语法的最大灵感来源是纯文本电子邮件的格式。
同样，Stuart Rackham 对 AsciiDoc 的介绍（早两年）
您编写 AsciiDoc 文档的方式与编写普通文本文档的方式相同。没有标记标签或奇怪的格式表示法。AsciiDoc 文件设计用于直接查看、编辑和打印，或转换为其他演示格式。
这些语言旨在让人们能够编写文档，让其他人能够直接阅读原始格式的文档。
这是一个基本的 AsciiDoc 文档示例
= Introduction to AsciiDoc
Doc Writer <doc@example.com>
A preface about https://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 很好，但（像 XML 一样）它不适合编辑或（由人类）合并更改。使用 AsciiDoc（可完美转换为 DocBook）是开发的一种更简单的方法。
AsciiDoc 使我们回到重点：写作。您可以放弃那些尖括号，但不必放弃语义。它是一种人类可以高效编辑的语法。
使用 AsciiDoc 进行文档标记。真的。它对人类来说是可读的，比 XML 更易于解析，并且灵活得多。
AsciiDoc 最棒的地方在于。最坏的情况是，您可以将其转换为 DocBook 作为通用的交换格式。DocBook 是 AsciiDoc 的“无锁定”退出路径。如果您觉得 AsciiDoc 不适合您，可以随时放弃它，而不会丢失一字一句。无需发明另一种格式。这就是为什么如此多的人全心投入于此。
谁在使用 AsciiDoc？
AsciiDoc 的普及程度不如 Markdown，但在一些非常重要的地方得到了使用。以下是一些值得注意的例子：
-
GitHub 在存储库、Wiki 和 Gist 中支持 AsciiDoc 语法（由Asciidoctor 提供支持）
-
NFJS, the Magazine 的文章是用 AsciiDoc 编写的
-
Java EE 平台（CDI）的上下文和依赖注入
-
规范（AsciiDoc 源代码）
-
网站（AsciiDoc 源代码）
-
-
Golo 编程语言指南（AsciiDoc 源代码）
-
Neo4j 图数据库项目（AsciiDoc 源代码）
-
Phusion Passenger 用户指南（AsciiDoc 源代码）
-
Git 用户手册（AsciiDoc 源代码）
-
企业 Web 开发：从桌面到移动（AsciiDoc 源代码）
这些示例不仅仅是证明。它们应该能为您自己的项目成功使用 AsciiDoc 提供思路。
AsciiDoc 写作的禅意
AsciiDoc 的核心在于能够专注于表达您的想法，轻松写作，并在不被复杂应用程序或尖括号干扰的情况下传递知识。换句话说，就是发现写作的禅意。
AsciiDoc 之所以有效，是因为
-
它易于阅读
-
它简洁
-
它内容全面
-
它可扩展
-
它能生成精美的输出（HTML、DocBook、PDF、ePub 等）
AsciiDoc 易于编写，易于阅读（原始格式）。它也易于校对和编辑。毕竟，它和熟悉的电子邮件一样，都是纯文本。
AsciiDoc 的语法是直观的，因为它识别了久经考验的纯文本约定来标记或组织文本。标点符号经过精心选择，看起来就像它所代表的含义。不熟悉 AsciiDoc 的用户可以仅通过查看来弄清结构和语义（即，您的意图）。最重要的是，它只需要一个文本编辑器即可阅读或编写。
AsciiDoc 使您能够专注于实际写作，而只在准备转换文档时才考虑调整输出。AsciiDoc 文档的纯文本可以轻松转换为各种输出格式，并且格式精美，无需重写内容。
将电子邮件中的文本复制到文档中，看看您能多快地将其变成文档。几乎立刻，您就会发现自己的写作禅意，并享受分享知识的令人满意的体验。
成败皆因文档？
“成功！”
后续步骤
在了解了 AsciiDoc 是什么以及它为何如此迫切需要之后，我们鼓励您深入研究《AsciiDoc 作者指南》中介绍的 AsciiDoc 语法。如果您只是在寻找备忘单，请查看AsciiDoc 快速参考。希望您也会认为它的语法很有道理。