StructuredText 2.11.1

使用Structured Text

警告！‘StructuredText’软件包已被弃用，将在Zope 2.12中删除。请使用‘zope.structuredtext’代替。

StructuredText的目标是使使用相对简单的纯文本格式表达结构化文本成为可能。简单结构，如项目符号或标题，通过某些“自然”定义的自然惯例表示。通过缩进来表示层次结构。

使用StructuredText包括一到三个逻辑步骤。在第一步中，使用‘StructuredText.Basic’功能将文本字符串转换为对象网络，如下例所示

raw=open("mydocument.txt").read()
import StructuredText
st=StructuredText.Basic(raw)

‘StructuredText.Basic’的输出只是一个包含结构化文本段落对象的StructuredTextDocument对象，这些对象按层次结构排列。段落由以换行符开始和结束的包含两个或更多空白字符的字符串界定。层次结构由缩进来表示。段落的缩进是在将制表符转换为空格后（假设每个制表符占用八个字符），包含非空白字符的行的最小前导空格数。

StructuredTextNode对象支持文档对象模型（DOM）API的只读子集。应该可以使用XML工具（如XSLT）处理‘StructuredTextNode’层次结构。

使用结构化文本的第二个步骤是根据文本内容应用额外的结构化规则。可以使用各种不同的文本规则。通常，这些规则用于实现用于生成文档的结构化文本语言，但在第二步中可以实施任何结构化文本语言。例如，可以使用结构化文本来实现表示结构化数据的结构化文本格式。第二步可能包含多个处理步骤，它通过处理或“着色”通用结构化文本段落对象的层次结构成为一个更专业化的对象网络来执行。通常，生成的对象还应实现DOM API，以便可以使用XML工具进行处理。

提供了一个文档处理器，用于将仅包含结构化文本段落的结构化文本文档对象转换为包含更多对象（如项目符号、标题、强调等）的结构化文本文档对象，这些对象使用文本中的提示。提示基于通常在电子邮件或新闻组帖子中看到的约定选择。但是，应该注意的是，这些约定在文化上有些依赖性，幸运的是，文档处理器可以轻松定制以实现替代规则。以下是一个使用DOC处理器转换前一个示例输出的示例。

doc=StructuredText.Document(st)

最后一步是处理第二步产生的着色网络，以产生额外的输出。最后一步可以由Python程序或XML工具执行。提供了一个Python输出器，用于文档处理器的输出，该输出产生超文本标记语言（HTML）文本。

html=StructuredText.HTML(doc)

自定义文档处理器

文档处理器由两个表格驱动。第一个表格名为“paragraph_types”，是一个用于着色段落的可调用对象或方法名称的序列。如果表格条目是一个字符串，则它是文档处理器要使用的方法的名称。对于每个输入段落，调用表格中的对象，直到其中一个返回一个值（不是“None”）。返回的值替换输出中的原始输入段落。如果段落类型表中的对象都没有返回值，则使用原始段落的副本。通过调用段落类型返回的新对象应实现ReadOnlyDOM、StructuredTextColorizable和StructuredTextSubparagraphContainer接口。请参阅“Document.py”源文件中的示例。

段落类型可以返回一个列表或元组替换段落，这允许段落被拆分为多个段落。

第二个表格“text_types”是一个用于着色文本的可调用对象或方法名称的序列。此表中的可调用对象按顺序用于将输入文本转换为新的文本或对象。可调用对象传递一个字符串并返回（“None”）或一个包含三个元素的元组，包括：

• 一个替换对象，

• 一个起始位置，

• 一个结束位置

从起始位置开始到结束位置的文本被（逻辑上）替换为替换对象。替换对象通常是实现ReadOnlyDOM和StructuredTextColorizable接口的对象。替换对象也可以是字符串、字符串列表或对象列表。替换是从头到尾进行的，替换结束位置之后的文本将被传递到字符类型对象进行处理。

示例：添加维基链接

我们想要添加对维基链接的支持。维基链接是包含大小写字母的文本字符串，其中至少有两个字母是大写的，并且第一个字母是大写的。