本教程讨论了使用AsciiDoc的优点，并向我们展示了如何在Linux中安装和使用AsciiDoc。

为什么选择AsciiDoc(或者其他任何文本文件格式)？

首先，内容和演示文稿之间有明显的分隔。由于某些文本格式(例如TeX或者HTML)需要严格遵守纪律，因此这种说法值得讨论。另一方面，通过以所见即所得的编辑器使用模板和样式表，可以以某种方式实现某种程度的分离。

什么是AsciiDoc？

严格来说，AsciiDoc是一种文件格式。它定义了语法构造，这些构造处理器理解文本各个部分的语义。通常是为了产生格式正确的输出。

即使该定义看起来很抽象，也很简单：文档中的某些关键字或者字符具有特殊的含义，这将更改文档的呈现方式。这与HTML中的标记完全相同。但是，与AsciiDoc的主要区别在于源文档的属性易于人类阅读。

检查我们的GitHub存储库以比较使用几种常见的文本文件格式如何产生相同的输出：(咖啡手册想法由http://www.linuxjournal.com/article/1158提供)

• coffee.man使用古老的troff处理器(基于1964 RUNOFF程序)。今天主要用于编写手册页。我们可以在下载coffee。*文件后通过在命令提示符下键入man。/ coffee.man来尝试一下。
• coffee.tex使用LaTeX语法(1985)获得与PDF输出几乎相同的结果。 LaTeX是一种排版程序，特别适合科学出版物，因为它能够很好地格式化数学公式和表格。我们可以使用pdflatex coffee.tex从LaTeX源生成PDF。
• coffee.html使用HTML格式(1991)来描述页面。我们可以使用喜欢的网络浏览器直接打开该文件以查看结果。
• 最后，" coffee.adoc"正在使用AsciiDoc语法(2002年)。我们可以从该文件生成HTML和PDF：

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

如何在Linux中安装AsciiDoc？

由于存在许多依赖性，因此AsciiDoc的安装相对复杂。我的意思是复杂，如果我们想从源代码安装它。对于我们大多数人来说，使用包管理器可能是最好的方法：

apt-get install asciidoc fop

或者以下命令：

yum install acsiidoc fop

AsciiDoc教程：如何用AsciiDoc编写？

AsciiDoc是一种人类可读的文本文件格式。因此，我们可以使用所选的文本编辑器编写文档。甚至还有专门的文本编辑器。它们的语法

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[theitroad Linux Blog]

// Inline Images
image:https://theitroad.local/wp-content/uploads/2017/06/theitroad-text-logo.png[theitroad Text Logo]

// Block Images
image::https://theitroad.local/wp-content/uploads/2017/06/theitroad-text-logo.png[theitroad Text Logo]

但是AsciiDoc语法要丰富得多。如果我们需要更多，我可以将我们指向该漂亮的AsciiDoc速查表：http://powerman.name/doc/asciidoc

如何渲染最终输出？

我将假设我们已经按照AsciiDoc格式编写了一些文本。如果不是这种情况，我们可以在此处下载直接从AsciiDoc文档中复制的一些示例文件：

# Download the AsciiDoc User Guide source document
BASE='https://raw.githubusercontent.com/theitroad/asciidoc-intro/master'
wget "${BASE}"/{asciidoc.txt,customers.csv}

由于AsciiDoc是人类可读的，因此我们可以通过电子邮件直接将AsciiDoc源文本发送给某人，接收者将能够读取该消息而无需再费力。但是，我们可能需要提供一些格式更精美的输出。例如，作为Web发布的HTML(就像Ive在本文中所做的一样)。或者作为PDF打印或者显示使用。

在所有情况下，我们都需要一个处理器。实际上，我们将需要使用多个处理器。因为在产生最终输出之前，AsciiDoc文档将被转换成各种中间格式。由于使用了几种工具，一个工具的输出是下一个工具的输入，因此我们有时会说一个工具链。

即使我在这里解释了一些内部工作细节，我们也必须了解大部分这些细节对我们而言是隐藏的。除非可能是在最初必须安装工具时，或者如果我们想微调过程的某些步骤，否则可能会导致这种情况。

实践

对于HTML输出，我们只需要asciidoc工具。对于更复杂的工具链，我建议我们使用a2x工具(AsciiDoc发行版的一部分)，该工具将按顺序触发必要的处理器：

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

即使可以直接产生HTML输出，" asciidoc"工具的核心功能仍然可以将AsciiDoc文档转换为中间的DocBook格式。 DocBook是一种基于XML的格式，通常用于(但不限于)技术文档发布。 DocBook是一种语义格式。这意味着它描述了文档内容。但不是它的介绍。因此，格式化将是转换的下一步。为此，不管输出格式是什么，都通过XSLT处理器处理DocBook中间文档，以直接产生输出(例如XHTML)或者另一种中间格式。

在生成PDF文档时，就是这种情况，其中DocBook文档将(随意)转换为LaTeX中间表示形式或者XSL-FO(用于页面描述的基于XML的语言)。最后，专用工具会将表示形式转换为PDF。

工具链必须处理PDF输出的分页这一事实特别证明了生成PDF的额外步骤。对于像HTML这样的流格式，这不是必需的。

dblatex还是fop？

由于有两个PDF后端，所以通常的问题是哪个最好？我无法为我们解答。

两种处理器都有优点和缺点。最终，选择将是需求和口味之间的折衷。因此，我建议我们在选择要使用的后端之前花一些时间尝试一下两者。如果遵循LaTeX路径，则dblatex将是用于生成PDF的后端。如果我们更喜欢使用XSL-FO中间格式，它将是Apache FOP。因此，不要忘记查看这些工具的文档，以了解根据需求自定义输出将非常容易。当然，除非我们对默认输出感到满意！

如何自定义AsciiDoc的输出？

将AsciiDoc转换为HTML

开箱即用的AsciiDoc可以生成非常漂亮的文档。但是迟早我们将自定义外观。

确切的更改将取决于我们使用的后端。对于HTML输出，大多数更改可以通过更改与文档关联的CSS样式表来完成。

例如，假设我要用红色显示所有节标题，我可以创建以下custom.css文件：

h2 {
    color: red;
}

并使用稍微修改的命令处理文档：

# Set the 'stylesheet' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

我们还可以通过将角色属性添加到元素来进行更精细的更改。这将转换为生成的HTML中的class属性。

例如，尝试修改我们的测试文档以将角色属性添加到文本的第一段：

[role="summary"]
AsciiDoc is a text document format ....

然后将以下规则添加到" custom.css"文件中：

.summary {
    font-style: italic;
}

重新生成文档：

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

• 等：第一段现在以斜体显示。通过一点点创意，一些耐心和一些CSS教程，我们应该能够随意定制文档。

将AsciiDoc转换为PDF

定制PDF输出稍微复杂一些。不是从作者的角度来看，因为源文本将保持不变。最终使用与上述相同的角色属性来识别需要特殊处理的零件。

但是我们不能再使用CSS定义PDF输出的格式。对于最常用的设置，可以从命令行设置一些参数。某些参数可以与dblatex和fop后端一起使用，其他参数特定于每个后端。

有关dblatex支持的参数列表，请参见http://dblatex.sourceforge.net/doc/manual/sec-params.html

有关DocBook XSL参数的列表，请参见http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

由于调整边距是非常普遍的要求，因此我们可能还需要看看以下内容：http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

如果两个后端之间的参数名称在某种程度上是一致的，则用于将这些值传递到后端的命令行参数在dblatex和fop之间会有所不同。因此，请先仔细检查语法，如果这显然行不通。但老实说，在撰写本文时，我无法使body.font.family参数与dblatex后端一起使用。由于我通常使用FOP，也许我错过了一些东西吗？如果我们对此有更多线索，我将非常乐意在本文结尾的评论部分阅读建议！

值得一提的是使用非标准字体，即使需要一些额外的工作。但是它在Apache网站上有很好的记录：https：//xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
    --fop \
    --xsltproc-opts='--stringparam page.margin.inner 10cm' \
    --xsltproc-opts='--stringparam body.font.family Helvetica' \
    --xsltproc-opts='--stringparam body.font.size 8pt' \
    asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn't ?!?)
a2x -v --format pdf \
    --dblatex-opts='--param page.margin.inner=10cm' \
    --dblatex-opts='--stringparam body.font.family Helvetica' \
    asciidoc.txt

用于生成PDF的细粒度设置

如果只需要调整一些预定义的设置，则全局参数非常有用。但是，如果我们想微调文档(或者完全更改布局)，则需要付出额外的努力。

DocBook处理的核心是XSLT。 XSLT是一种以XML表示法表达的计算机语言，它允许编写从XML文档到其他内容的任意转换。是否使用XML。

例如，我们将需要扩展或者修改DocBook XSL样式表，以为所需的新样式生成XSL-FO代码。并且，如果我们使用dblatex后端，则可能需要修改相应的DocBook-to-LaTeX XSLT样式表。在后一种情况下，我们可能还需要使用自定义LaTeX软件包。但是我不会专注于此，因为dblatex并不是我自己使用的后端。如果我们想了解更多信息，我只能指出官方文档。但是再次，如果我们对此有所了解，请在评论部分中分享提示和技巧！

即使只专注于fop，我实际上也没有足够的空间来详细说明整个过程。因此，我将仅向我们展示可用于获得与上面的HTML输出中的CSS行很少的类似结果的更改。即：红色部分标题和斜体摘要段落。

我在这里使用的技巧是创建一个新的XSLT样式表，导入原始的DocBook样式表，但是覆盖我们要更改的元素的属性集或者模板：

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!-
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!-
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>

</xsl:stylesheet>

然后，我们必须请求a2x使用该自定义XSL样式表来生成输出，而不是使用--xsl-file选项的默认输出：

a2x -v --format pdf \
    --fop \
    --xsl-file=./custom.xsl \
    asciidoc.txt

熟悉XSLT，此处给出的提示以及我们喜欢的搜索引擎上的一些查询后，我认为我们应该可以开始自定义XSL-FO输出了。