关键概念

这个页面将向您介绍一些在学习AsciiDoc时会遇到的概念和术语。文档后面会更深入地覆盖每个概念。使用这个页面作为开始熟悉这些行话的方式。

文档

在AsciiDoc中，文档代表最顶层的块元素。它由一个可选的文档头部和要么a）一个或多个由可选序文开头的部分，要么b）仅由一系列顶层块组成。

文档可以通过文档头部进行配置。头部本身不是一个块，但它为文档贡献了元数据，比如文档标题和文档属性。

一个元素是文档中可识别、可寻址、可组合的内容块。一个AsciiDoc文档仅仅是它包含的所有元素的组合。

元素是一个类型的层级结构，其中某个元素可能是一系列元素的专门化。例如，侧边栏块是一种区块元素，因此它具有所有区块元素的特征，并且还添加了一些自己的特点。

元素包括文档本身、章节、块、块宏、分隔符以及内联短语和宏。

区块元素（.term）通常垂直堆叠（按行）在其他区块元素的上方或下方。区块元素通常简称为（.term）区块。区块构成了文档的主要树状结构。

一个*内联元素*是块元素内或其属性之一（例如，块标题）中的内容跨度。内联元素包括格式化文本（斜体、粗体等）、内联宏命令和元素引用。填补这些元素之间空白的是未替换的文本。内联元素比块元素结构要松散，因为它们更侧重于替换而不是树状结构。

属性是用于在AsciiDoc语言中存储和披露元数据的名称/值对。属性可以用来影响语法、控制行为、自定义样式、激活或配置集成，或存储内联替换内容。属性确实使AsciiDoc区别于其他轻量级标记语言。

属性实际上是一个抽象术语。属性有两种具体的分类：文档属性和元素属性。

文档属性，顾名思义，是直接与文档相关联的。它们用于在运行时导出有关文档的信息，控制处理器的行为，并且存储可重用的值或短语。因此，它们是一种与处理器进行双向通讯的渠道。

文档属性可以在内容中通过属性引用来引用（只要启用了属性替换）。一个文档属性可以在文档中使用属性条目来定义（通常在文档头部），也可以通过API或CLI来定义。并非所有文档属性都可以被修改。

元素属性是特定元素上的元数据，例如块元素或行内元素。它们在属性列表中定义，并且只适用于那个元素。属性列表的位置取决于元素。属性名可以是字符串（即，命名属性）也可以是隐式的数值索引（即，未命名的，位置属性）。

与文档属性不同，元素属性不能直接从内容中引用，也不能在文档模型上直接引用。换句话说，它们不能通过属性引用来解析。元素属性丰富或配置元素的行为，例如应用角色或设置图像的宽度。元素属性是使用元素上的属性列表或者像块标题行这样的可用简写来定义的。

在您阅读此文档时，您将经常看到对术语宏的引用。宏是一种语法，用于表示非文本元素或者可以使用提供的元数据扩展成文本的语法。请访问https://en.wikipedia.org/wiki/Macro_(computer_science)[宏^]，以了解更多关于这个术语的含义。

这是一个块宏的例子：

图片::sunset.jpg[日落]

这是一个内联宏的例子：

点击带有 image:star.png[Star] 图片的按钮来收藏该项目。

你可以将宏视为一种函数。宏的语法遵循一个形式，由名称、有时是可选的目标以及一个由零个或多个元素属性组成的属性列表构成，这些属性被包含在方括号中。

宏有两种变体：块状和内联。在块状宏中，名称和目标之间用两个冒号(::)分隔，并且必须独占一行。在内联宏中，名称和目标之间用一个冒号(:)分隔，可以与文本和其他内联元素并列。块状宏总是会被解析，而内联宏只有在启用宏替换的地方才会被解析。

AsciiDoc中有另一种语法，看起来非常像块宏，但它们不是。这些是预处理器指令。

预处理指令是一种控制输入到解析器中的行的函数。条件预处理指令可以根据属性的存在（ifdef、ifndef）或其他任意条件（ifeval）配置要包含或排除的行。包含指令可以从其他文档添加额外的行到该文档中。

预处理器指令与块宏有共同特征。就像块宏一样，预处理器指令必须单独占据一行。虽然预处理器指令可以访问文档属性，但它并不知道其周围的上下文。它只是一个行处理器。像块宏一样，include指令可以有元素属性，不过它们只适用于预处理操作本身。