利用DITA Map组织信息

DITA Map是将不同Topic和其他内容资源按照一定的结构组织起来的文档，描述了各个Topic之间的层级和关系，支持通过引用和构建层级关系将不同的Topic或submap组合在一起。根据类型定义（Document Type Definition）的不同，DITA Map的可细分为<map>和<bookmap>，均以.ditamap为后缀。

DITA Map的应用场景

• 组织和管理内容：Map可以将不同的DITA文件组织在一起，形成一个有层次结构的文档集合。通过Map，可以在更高级别（如Rootmap）更好地管理内容，方便查找、维护和扩展。
• 控制文档输出：Map可以指定需要输出的文档、输出的格式以及输出的目标。因此，可以根据需要生成不同的交付物，比如HTML、PDF、EPUB等。
• 定义文档结构：Map可以定义文档的结构和内容，包括文档的标题、摘要、作者、版权信息等。这些信息可以在生成文档时自动插入到文档中。
• 定义Keyword：Map提供了一种间接的寻址机制，增强内容的可移植性，如<keydef>。<keydef>是<topicref>的特殊化。
• 构建Topic关系：使用Map中的主题层次结构、关系表格（<reltable>）等，定义Topic之间或与其他非DITA内容的关系。
• 支持重用和共享：Map可以引用Submap或DITA文件，实现内容的批量重用和共享。不同的文档可以共享相同的内容，减少重复工作，提高效率。

<map>和<bookmap>

<bookmap>是一种特殊的<map>，包括<frontmatter>、<backmatter>、<appendix>、<bookmeta>、<author>等特殊的标记对，多用于组织和管理书籍或其他长篇文档的结构和内容。一般而言，如果需要同源开发生成多个输出格式，如HTML、PDF、CHM，或者想要减少维护工作量，优先考虑使用<map>。

Map的嵌套

通常，一个DITA Map对应一个用户主题。例如，所有安装主题应该放在一个安装DITA地图中。然而，将整本书或帮助系统的所有主题都包含在一个地图中可能会创建一个笨重的DITA地图。

为了管理您的内容，而不是为您的产品、服务或技术创建一个庞大的DITA地图，可以在其他DITA地图中嵌套较小的DITA地图来创建子地图。将您的内容分成子地图有助于您管理内容。使用子地图来：

注：由于目前资料开发使用的样式表仅支持<bookmap>，因此后文仅讨论<bookmap>嵌套submap的情况，即Rootmap均为<bookmap>。

Submap的应用场景

有了嵌套，Rootmap主要负责提供文档集合的结构信息，而Submap则指定具体的Topic集合。Submap的主要应用场景包括：

• 按章节组织内容：例如，将”安装“部分变成Submap。这样不仅支持后期在其他产品中复用，同时能更好得管理不同Topic集合，尤其是当Topic数量过多时。
• 协同写作：例如将手册正文划分为不同的submap之后，不同的技术作者只需专注于某一个或某几个章节的内容，无需再最后合并汇总时反复修改Rootmap。
• 隔离更新频繁的内容：为了减少维护工作量和提高复用效率，可以用单独的DITA Map组织经常更新的内容。

Map嵌套存在的问题

除了前面介绍的应用场景外，还有一种典型的需求：将产品B（通常为可独立阅读和维护的子产品，例如App）的手册内容添加到主产品的Map中，以增加产品手册的完整性，同时便于产品A、产品B的维护和更新。具体而言：

• 要求1：在产品A的用户手册中，产品B的主体内容作为其中一章单独出现。
• 要求2：原产品B手册中的标题层级，在产品A的手册中，均往下降一级（如章标题变成节标题）。

产品A

<bookmap xml:lang="en-US">
 <booktitle>
		<mainbooktitle>Product A User Manual</mainbooktitle>
 </booktitle>
 <chapter href="topics/Overview.dita">
		<!-- ... -->
 </chapter>
 <chapter href="topics/Mounting.dita">
		<!-- ... -->
 </chapter>
 <chapter href="topics/Wiring.dita"/>
</bookmap>

产品B

<bookmap xml:lang="en-US">
 <booktitle>
		<mainbooktitle>Product B User Manual</mainbooktitle>
 </booktitle>
 <chapter href="topics/Overview.dita">
		<!-- ... -->
 </chapter>
 <chapter href="topics/Operation.dita">
		<!-- ... -->
 </chapter>
 <chapter href="topics/Configuration.dita"/>
</bookmap>

第一种情况：在<chapter>中引用<bookmap>

在Rootmap中，先引用不同的Topic作为<chapter>，再在单个<chapter>中引用具体的Submap。这也是通用的做法。

<bookmap xml:lang="en-US">
 <booktitle>
		<!-- ... -->
 </booktitle>
 <chapter href="Overview.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Mounting.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Wiring.dita"/>
 <chapter href="Using_productB.dita">
  <topicref href="productB.ditamap" format="ditamap"/>
 </chapter>
</bookmap>

但是实际操作中，会发现生成输出后，标题层级不符合要求。原来的章标题（L1 Heading），并没有降级为节标题（L2 Heading）。

第二种情况：直接引用<bookmap>

在Rootmap中，直接设置<chapter>的@href为Submap。

同样，会发现生成输出后，产品B的内容并没有作为单独一章出现。

<bookmap xml:lang="en-US">
<booktitle>
<mainbooktitle>Product A User Manual</mainbooktitle>
</booktitle>
 <chapter href="Overview.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Mounting.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Wiring.dita"/>
 <chapter href="productB.ditamap" format="ditamap"/>
</bookmap>

第三种情况：<bookmap>引用<map>

根据前两种情况判断，必须以在单个<chapter>中引用具体的Submap为前提，才能满足要求1。此时如果尝试替换产品B的<bookmap>为<map>，会发现条件2也满足了。

<bookmap xml:lang="en-US">
<booktitle>
<mainbooktitle>Product A User Manual</mainbooktitle>
</booktitle>
 <chapter href="Overview.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Mounting.dita">
		<!-- ... -->
 </chapter>
 <chapter href="Using_productB.dita">
  <topicref href="productB.ditamap" format="ditamap"/>
 </chapter>
</bookmap>

<map>
    <title>Product B User Manual</title>
    <topicref href="Overview.dita"/>
    <topicref href="Operation.dita"/>
    <topicref href="Configuration.dita"/>
</map>

<bookmap>还是<map>？

通过上述分析，可以总结得出：

• 在当前的编辑条件下，使用<bookmap>作为Rootmap。
• 如需在Rootmap中引用多个”章节“，使用<bookmap>。
• 如需把包含多层Topic嵌套关系的Map（子产品的“Map”）作为一章插入到Rootmap中，使用<map>。

featured image from Unsplush