利用配置内容元素助手来简化 DITA 编写

在许多情况下，元素具有宽松的内容模型并且可以接受大量子元素。例如，DITA 列表项元素 ( <li>) 接受 60 多个子元素。Oxygen XML Editor /Author 包括允许内容架构师对可能的元素或属性施加一些约束，或在内容编辑方式中强加一些最佳实践的支持。

对于特定用例的示例，假设您希望将 DITA 列表项元素 ( <li>) 限制为仅接受段落元素 ( <p>)。在这种情况下，当将列表项 ( ) 插入文档时，完成内容元素助手 Content Completion Assistant 不应提供段落 ( ) 以外的任何元素。

更改内容模型的一种方法是更改​关联模式（XML 模式、DTD、RelaxNG）中的元素定义，但在某些情况下这可能很复杂。幸运的是 Oxygen XML Editor提供了一种简单的替代方法，即使用配置文件为每个元素自定义内容完成建议。

设置完成内容元素的配置文件

要自定义 完成内容元素助手的配置文件，请执行以下步骤：

1. 在框架目录中为特定文档类型（例如，OXYGEN_INSTALL_DIR/frameworks/dita/resources ）创建一个新的资源文件夹（如果它尚不存在）。
2. 打开首选项对话框（选项>首选项）并转到文档类型关联。选择特定的文档类型，单击“编辑”按钮，然后在“类路径”选项卡中添加指向该资源文件夹的链接（如果它尚不存在）。
3. 创建新配置文件或编辑现有配置文件。

• 要轻松创建新的配置文件，您可以使用Oxygen XML 编辑器中包含的Content Completion Configuration文档模板（File > New > Framework templates > Oxygen Extensions > Content Completion Configuration）。文档模板包含有关如何在配置文件中使用每个元素和属性的详细信息。
• 如果特定文档类型的配置文件 ( cc_config.xml ) 已经存在（在资源文件夹中），您可以修改这个现有文件。
• 如果您扩展一个框架，您需要从基本框架复制cc_config.xml文件的内容并修改它（例如，在您的框架扩展文件夹中创建一个资源文件夹并将文件放在那里）。您还需要确保在您的扩展中包含cc_config.xml文件的文件夹（例如resources）在类路径选项卡中列在基本框架的文件夹之前。如果您只想在您的自定义内容完成配置文件中进行小的更改或添加额外的规则，您需要将其命名为cc_config_ext.xml并且其中的所有规则都与基本cc_config.xml文件合并。合并是通过在处理基本cc_config.xml文件中的规则集后考虑cc_config_ext.xml文件中指定的所有规则来完成的。

4.对您的自定义配置文件进行适当的更改。

5.使用固定名称将文件保存在特定文档类型的资源文件夹中： cc_config.xml（例如，OXYGEN_INSTALL_DIR/frameworks/dita/resources/cc_config.xml）。

6.重新启动应用程序并打开一个 XML 文档。在Content Completion Assistant中，您应该会看到您的自定义设置。

提示：在某些情况下，您可以简单地使用 刷新 ( F5 ) 操作来测试您的自定义，而无需重新启动应用程序。

注意：在Classpath选项卡中，如果您引用了多个资源文件夹，每个资源文件夹都有自己的cc_config.xml文件，则Classpath选项卡中列出的第一个引用优先，多个配置文件不会合并。

配置为每个元素建议的元素或属性

为了自定义为每个单独元素建议的元素或属性，配置文件 ( cc_config.xml ) 使用 <elementProposals>元素。此元素允许您自定义或过滤元素的子元素和属性。

警告：请注意，您只能选择特定上下文中模式已允许的元素或属性。例如，您不能将架构不允许的元素指定为特定节点的子节点。

元素：

要控制为元素建议的元素，您可以为元素使用以下属性<elementProposals>：

• path - 文档中与将更改其内容完成建议的元素匹配的路径。例如，"title"匹配文档中的所有<title>元素，而"chapter/title"仅匹配作为该<title>元素的直接子元素的<chapter>元素。您可以在此属性中使用简化形式的 XPath。
• XPath 表达式可以接受多个属性条件，并且在每个条件内您可以使用AND/OR布尔运算符和括号来覆盖优先级。
• 您可以使用以下一个或多个属性条件（不考虑默认属性值）：
• element<@attr> - 匹配包含指定属性的指定元素的所有实例。
• element - 匹配不包含指定属性的指定元素的所有实例。
• element<@attr = "value"> - 匹配包含具有给定值的指定属性的指定元素的所有实例。
• element<@attr != "value"> - 匹配包含指定属性且其值与给定值不同的指定元素的所有实例。

示例：以下是如何在属性条件内使用多个布尔运算符和圆括号的示例：

*<@a and @b or @c and @d>*<@a and (@b or @c) and @d>

• 以下只是简化的 XPath 表达式的示例：
• 元素名称
• //元素名称
• /元素名称1/元素名称2/元素名称3
• //xs:本地名称
• //xs:文档<@lang="en">

说明：使用名称空间前缀要求您在<elementProposals>元素或祖先元素上声明它。例如：<elementProposals xmlns:db5 = "http://docbook.org/ns/docbook" path = "db5:listitem" insertElements = "db5:para" />

其他重要说明：

• 如果@path缺少该属性，则自定义将应用于所有元素的提案。您可以有意省略此属性并使用possibleElements或rejectElements来指定或限制框架的特定元素。例如，假设在您的 DITA 文档中，您希望限制您的用户使用<image>和<fig>元素，因为您不希望图像包含在您的输出中。配置文件应如下所示：<elementProposals rejectElements="image fig" />
• 由于@path缺少该属性，指定的元素将从整个框架的提案中过滤掉。
• 如果特定文档类型具有名称空间，@path则应包含限定名称。例如，在 TEI 文档中，如果要为<span>元素设置可能的属性列表，则需要使用这样的限定名称（注意命名空间前缀“ t ”的声明及其用法）：<config xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation = "http://www.oxygenxml.com/ns/ccfilter/config http://www.oxygenxml.com/ns/ccfilter/config/ccConfigSchemaFilter.xsd" xmlns = "http://www.oxygenxml.com/ns/ccfilter/config" xmlns:t = "http://www. tei-c.org/ns/1.0" > <elementProposals path = "t:span" possibleAttributes = "type" />
• insertElements - 以空格分隔的子元素名称序列。每次将@path属性中指定的元素插入到文档中时，这些子元素也将按照它们列出的顺序插入。例如，insertElements="b i"将恰好插入一个<b>元素，后跟一个<i>元素。空值 ( "") 表示不应插入任何子元素。

说明：如果缺少此属性，则将插入默认的必需子元素，如文档的关联模式中所指定的那样。

• possibleElements@path - 以空格分隔的元素名称列表，当在属性中指定的元素内调用时，将显示在内容完成列表中。例如，"b i codeph ph"表示内容完成助手@path在对属性中指定的元素调用时将包含这四个元素。还支持以下其他可能的值：无- 内容完成列表中将没有提案。ALL - 关联模式中指定的所有可能元素都将显示在内容完成列表中。如果缺少此属性，这也是默认行为。INSERTED - 提案将与@insertElements属性中定义的元素列表相同。当使用此属性指定多个元素时，仅使用一个条目，元素名称以空格分隔：<elementProposals possibleElements = "bi codeph ph" />
• rejectElements - 一个以空格分隔的元素名称列表，将从内容完成列表中显示的提案列表中过滤掉。每次将@path属性中指定的元素插入到文档中时，内容完成助手中的建议列表将包括关联模式中定义的条目，减去该属性中指定的元素。

说明：

• 此设置使应用程序的行为就像该位置的架构不允许拒绝的元素一样。大多数工具栏操作在插入内容时都会考虑架构。如果该特定位置的架构不允许插入的内容，则应用程序会尝试在允许插入内容的附近找到另一个位置。
• 例如，假设您拒绝在段落中插入图像。如果用户将光标放在段落内并使用插入图像的工具栏操作，则图像将插入到当前段落之后而不是当前位置。
• 如果您想要避免让用户直接从内容完成机制插入元素并希望他们改用工具栏操作，最好使用“文档类型配置”对话框来删除元素。
• 当使用此属性指定多个元素时，仅使用一个条目，元素名称以空格分隔：<elementProposals rejectElements = "image fig imagemap foreign" />

属性：

要控制为元素建议的属性，您可以为元素使用以下属性<elementProposals>：

• path - 文档中与将更改其属性建议的元素匹配的路径。例如，"title"匹配文档中的所有<title>元素，而"chapter/title"仅匹配作为该<title>元素的直接子元素的<chapter>元素。您可以在此属性中使用简化形式的 XPath。有关此类形式的 XPath 表达式的示例，请参阅XML 首选项中的注释。笔记：
• 如果缺少此属性，则自定义将应用于所有元素的提案。您可以有意省略此属性并使用possibleAttributes或rejectAttributes来指定或限制整个框架的属性。
• 例如，假设您只想在自定义框架中允许一组有限的属性。配置文件应如下所示：
• <elementProposals possibleAttributes = " id 域 href 范围格式类型 conref 道具 keyref 类" />
• 由于@path缺少该属性，这适用于整个框架，并且只会提出指定的属性。
• insertAttributes - 将与元素一起插入的以空格分隔的属性名称序列。<elementProposals path = "ol/li" insertAttributes = "产品平台" />
• insertAttribute - 这与前面的属性类似，但这个属性还允许您为将要插入的属性指定一个值。这个属性应该像这样使用：<elementProposals path = "ol/li" > <insertAttribute name = "platform" value = "test" /> </elementProposals>
• possibleAttributes - 以空格分隔的属性名称列表，当在属性中指定的元素内调用时，将显示在内容完成列表中@path。
• 当使用此属性指定多个属性时，仅使用一个条目，属性名称以空格分隔：<elementProposals possibleAttributes = "范围格式类型" />
• rejectAttributes - 一个以空格分隔的属性名称列表，将从内容完成列表中显示的建议列表中过滤掉。每次将@path属性中指定的元素插入到文档中时，内容完成助手中的建议列表将包括关联架构中定义的条目，减去此属性中指定的属性。
• 当使用此属性指定多个属性时，仅使用一个条目，属性名称以空格分隔：<elementProposals rejectAttributes = "重要平台产品" />

关于配置文件的其他重要说明

重要：

• 默认情况下，没有命名空间前缀的元素名称被认为来自no-namespace。考虑在配置文件的根上声明命名空间映射，并在@elementPath和@model属性中为元素名称添加前缀。
• 此配置文件仅影响内容完成帮助。它对从界面中其他区域（例如工具栏或菜单）调用的验证或操作没有影响。
• 要测试更改的效果，您应该重新启动应用程序。
• 当文档中的 XML 元素与 configured 列表匹配时elementProposals，顺序中的第一个优先。因此，请确保首先将更具体的elementProposals（路径较长的）放在配置文件中。
• 可以在以下属性中使用简单的通配符模式：@possibleElements、@rejectElements、@possibleAttributes和@rejectAttributes。例如，code*, *block, con*ref, _*。
• 编辑器变量可以用在元素的@value属性中。<insertAttribute>例如：<elementProposals path = "prolog/critdates/created" > <insertAttribute name = "date" value = "${date(yyyy-MM-dd)}" /> </elementProposals>
• 编辑器仅检测并避免简单的递归情况，并将其记录到控制台。因此，如果定义了复杂elementProposals的模式，则应避免无限递归。

示例：配置元素建议

• 示例 1：自动插入元素
• 假设您希望在插入<p>DITA 有序列表项元素 ( ) 时自动插入一个段落元素 ( ) <ol/li>，并且不允许有序列表项中除段落之外的任何其他元素。
• 为此，配置文件应包括以下内容：<elementProposals path = "ol/li" insertElements = "p" possibleElements = "_INSERTED_" />提示：此特定示例修改了在 DITA 文档中插入列表的操作。有几种方法可以在界面中调用此操作。例如，DITA菜单中有一个工具栏按钮和一个插入列表的操作。但是，由于配置文件只影响Content Completion Assistant，因此此修改不会影响工具栏或菜单操作的行为。如果您希望结果与内容完成建议相同，则需要单独配置这些操作。有关详细信息，请参阅自定义框架的作者模式编辑体验。
• 示例 2：插入复杂元素结构
• 对于更复杂的示例，假设您希望在插入 DITA<prolog>元素时插入一个复杂的结构。
• 例如，如果你想在<prolog>元素中插入以下结构： <prolog> <author> </author> <metadata> <keywords> <keyword> </keyword> <keyword> </keyword> </keywords> </metadata> </prolog>
• 配置文件应包括以下内容： <elementProposals path = "prolog" insertElements = "author metadata" /> <elementProposals path = "prolog/metadata" insertElements = "keywords" /> <elementProposals path = "prolog/metadata/keywords" insertElements = "keyword, 关键字" / >
• 示例 3：限制可能的元素
• 假设您还想将<keywords>元素的建议限制为仅允许用户插入<audience>或<keyword>元素。配置文件应包括以下内容：<elementProposals path = "prolog/metadata" insertElements = "keywords" possibleElements = "audience keywords" />
• 假设您只想限制您的用户<image>在 DITA 列表项元素 ( <li>) 中插入元素，但仍建议在关联模式中定义的所有其他元素。配置文件应如下所示：<elementProposals path = "li" rejectElements = "image" />

示例：配置属性建议

• 示例 1：自动插入属性
• 假设您希望在插入@idDITA 列表项元素 ( ) 时插入一个属性（具有空值）<li>。配置文件应包括以下内容：<elementProposals path = "li" insertAttributes = "id" />
• 示例 2：限制可能的属性
• 假设您还想限制在<li>插入 DITA 列表项元素 ( ) 时呈现给用户的属性选择的数量。配置文件应如下所示：<elementProposals path = "li" insertAttributes = "id" possibleAttributes = "id product platform audience" />
• 假设您只想限制您的用户@conref在 DITA 主题（<topic>元素）中插入属性，但仍建议在关联模式中定义的所有其他属性。配置文件应如下所示：<elementProposals path = "topic" rejectAttributes = "conref" />