DITA Tips：重用技巧

什么是DITA重用

重用指在多个文档中使用相同内容，优势在于一次创建，多次使用。当源内容有变更时，只需要改动一次，引用该源的内容将同步更新。

重用的优势

重用是基于DITA进行结构化写作的优势之一。对于写作人员，重用更是利用DITA的主要动机。主要优势包括：

保证内容和写作风格的一致性
提升写作效率和内容管理效率
节省开发成本

重用的类型

类型	说明
改变目的的重用	针对不同的目的的交付件，重用内容相同的Topic。
简单的元素级重用	使用内容参引或关键词引用。
条件文本	使用条件处理区分在不同的场景下需要出现不同描述的情况。

重用的级别

DITA支持Topic级别的复用、元素级别的复用，结合设计好的条件语句，可以基于同样的内容模块输出面向不同用户、不同渠道的文档。

级别	说明
完全重用	完全重用表现为内容模块完全一致。常见于同系列产品或同类型文档之间，如产品介绍、常见问题、法律声明等等。
部分重用	部分重用表现为话题一致，但具体内容略有差别。如市场资料的产品介绍部分可稍加修改，直接用在技术资料中。
结构重用	结构重用表现为不同的文档使用相同的内容结构和基本元素。一般而言，同类型的文档存在标准化的内容结构。
最小模块重用	最小模块重用主要体现在短语级别，如术语、产品名称等。

DITA重用的应用场景

结构化开发的过程中，技术作者应主动思考内容重用的潜力。以下仅列举典型的应用场景：

通用内容：例如公司的联系方式、免责声明等可以在不同的手册中重复使用。
告警说明：产品的操作、维护等部分需要告警说明，而这些说明可以在不同产品线的手册中重复使用。
系列差异：一些产品可能有多个型号，这些型号之间可能有一些细微的差异。但无需为这些差异部分开发独立的手册。
UI文本：UI文本主要出现在对话框、按钮等人机交互界面。在软件开发初期，UI文本往往无法固定。考虑其更新的频率，使用重用可以做到后期统一更新，减少维护成本。

实现DITA重用

前提条件

DITA几乎支持任何颗粒度的重用。内容模块的重用率越高，越值得花时间设计与维护。在规划重用内容模块之前，需考虑如下几点：

被重用内容的更新频率
被重用内容是否准确、完整
同属性的内容是否可以被重用
被重用内容的文件是否存储在单独的文件中，以便后期维护

基于`<conref>`重用

<conref>非常灵活，支持重用来自某个源文件的内容片段，如列表、步骤、表格、短语、句子以及段落。

以重用<uicontrol>为例：

创建指定用于存储重用元素的DITA文件（仓库），如reuse_uicontrol.dita，id为“resue”。

在reuse_uicontrol.dita中新增<uicontrol>，确保元素ID易于识别。

<concept id="Reuse" xml:lang="en-US">
 <title>forReuse</title>
 <conbody>
	<wintitle id="home">Home</wintitle>
	<uicontrol id="sign_up">Sign up</uicontrol>
	<uicontrol id="u_login">Login</uicontrol>
	<wintitle id="w_login">Login</wintitle>
		...
 </conbody>
</concept>

在目标Topic文件中，使用<conref>添加不同的<uicontrol>。

<step>
 <cmd>
	 Click <uicontrol conref="reuse_uicontrol.dita#Reuse/sign_up"/> on the 
	 <wintitle conref=".reuse_uicontrol.dita#Reuse/w_login"/> page.
 </cmd>
</step>

在根MAP中引用reuse_uicontrol.dita，标记@processing-role为“reference-only”。
```
<topicref href="reuse_uicontrol.dita" processing-role="resource-only"/>
```

基于`<keyref>`重用

<keyref>可以重用简单的变量，如产品名称、产品型号等。

以重用公司名称为例：

在DITA MAP中新增关键字定义“company_name”。

<keydef keys="company_name">
 <topicmeta>
  <keywords>
   <keyword>SUNGROW</keyword>
  </keywords>
 </topicmeta>
</keydef>

在目标位置，新增<keyword>，选择@keyref。

<p>
	It is prohibited to use data contained in firmware or 
	software developed by <keyword keyref="company_name"/>.
</p>

基于DITAVAL重用（条件发布）

条件处理支持为内容定义受众、版本等其他明显特征，并决定在输出时筛选哪些内容。

如XYZ产品分为型号A和型号B，仅在拓扑图方面存在差异：

在<fig>标记对上设置条件及属性。

<fig id="A_topology" product="A">
 <title>Model A</title>
 <image id="imageA" href="img/A_topology.png" width="70mm"/>
</fig>

<fig id="B_topology" product="B">
 <title>Model B</title>
 <image id="imageB" href="img/B_topology.png" width="70mm"/>
</fig>

新增两个DITAVAL文件，ForA.ditaval和ForB.ditaval，分别对应适用于型号1的发布，以及适用于型号2的发布。
ForA.ditaval
```
<val>
    <prop action="exclude" att="product" val="B"/>
</val>
```
ForB.ditaval
```
<val>
    <prop action="exclude" att="product" val="A"/>
</val>
```
在发布时，选择需要应用的DITAVAL文件。

基于DITAMAP重用

DITAMAP通过引用和层级关系已将多个Topic组合在一起。对于可重用的、且构成层级关系的组合内容，可以先整合为一个MAP，然后在根MAP中引用。在后续文章中，将具体介绍bookmap相互引用时的注意事项。