带标记的描述列表

Warning

尚未成为AsciiDoc语言的官方部分，因此应被视为实验性的。

Asciidoctor 引入了一种列表类型，它是描述列表与无序或有序列表之间的混合体。这种混合列表，通常被称为无序或有序描述列表，其外观类似于无序或有序列表，不同之处在于每个列表项的主题以加粗文本强调，并且要么通过停止字符后跟一个空格与描述文本分隔，要么堆叠于描述文本之上。

Note	当前，只有Asciidoctor PDF支持此页面上定义的语法，尽管HTML转换器中的支持正在开发中。Asciidoctor EPUB 3支持略有不同的变体，它对无序列表使用了不同的块样式（itemized`而不是`unordered）。尽管这种差异将在未来的版本中得到统一。

引言

在无序和有序的描述列表中，每个项目的第一个术语前都会有一个标记。额外的术语会被忽略。无序列表的标记是一个项目符号，有序列表的标记是一个数字。这个术语有效地成为了主题，以粗体文字显示。

这是带有记号的描述列表的一个例子。

这种列表类型还提供了对插入术语后的停止字符的控制，以便它能更自然地流入条目描述。它还可以配置成使主题堆叠在描述之上。本页描述了这种列表类型的语法以及如何自定义其外观。

在AsciiDoc中，带有标记的描述列表的定义就像普通描述列表一样。区别在于它必须用`unordered`或`ordered`块样式进行注释。`unordered`块样式创建无序列表，而`ordered`块样式创建有序列表。

这是一个无序描述列表的例子。

[无序]
boolean:: 使用 true 和 false，不使用 1 和 0 或 T 和 F
number:: 使用阿拉伯数字而不使用标点（除了用小数点表示浮点数）
enumerated value:: 只使用允许的值中的一个，并且注意大小写

这种语法在支持的地方会显示为：

要创建一个有序列表，请将区块风格改为`ordered`。

[有序]
&:: 和号
>:: 大于号

这种语法在支持的地方会显示为：

默认情况下，主题（即术语）后紧跟着一个冒号（仍然为粗体），并且与描述之间有一个空格间隔。你可以使用名为 subject-stop 的块属性来替换冒号为其他字符（或字符序列）。

[unordered,subject-stop=)]
alpha:: 部分功能已完成，不稳定，可能会有改动
beta:: 功能已完善且正在进行测试

这种语法在支持的地方会显示为：

如果术语以句号或subject-stop属性的值结尾，则不添加主题停止符。

Tip	要在主题和可见的停止字符之间插入空格，请在subject-stop属性值的开头添加一个空格字符。您还需要用双引号将值括起来，以保留空格字符。

默认情况下，带有标记的描述列表使用紧凑型布局。换句话说，主题和描述出现在同一行，由主题停止符和一个空格分隔。要让主题像普通描述列表那样出现在描述之上，请为列表添加`stack`角色。在这种情况下，仅当明确指定时才添加停止符号。

[unordered.stack]
boolean:: 使用 true 和 false，而不使用 1 和 0 或 T 和 F
number:: 使用不含标点的阿拉伯数字（除了小数点表示浮点数）
enumerated value:: 只使用允许的值中的一个，并且注意大小写

这种语法在支持的地方会显示为：

Warning

我们可能会决定用“堆叠”选项（即“%stacked”）来替换“栈”角色。或者，我们可能会决定反转默认行为，让带有标记的描述列表默认为堆叠样式，而将“内嵌”作为一种选择（即“%run-in”）。当这个特性被标准化时，我们将进行这些调整。

作为使用带标记的描述列表的替代方法，你可以使用普通的无序或有序列表，并手动格式化主题和停止字符。

* *布尔值：* 使用 true 和 false，不要使用 1 和 0 或 T 和 F
* *数字：* 使用阿拉伯数字，不要使用标点符号（浮点数中的小数点除外）
* *枚举值：* 只使用允许的值中的一个，并且注意大小写

这种语法在短期内为你提供了最大的可移植性。

虽然缺乏适当的语义，但另一种实现相同结果的方法是将单项描述列表嵌套在一个空列表项内。

* {空}
布尔值:: 使用 true 和 false，不使用 1 和 0 或者 T 和 F
* {空}
数字:: 使用没有标点符号的阿拉伯数字（浮点数中的小数点除外）
* {空}
枚举值:: 只使用允许的值之一，注意大小写