From 5efc5168467b40cb1bd5760555610aa18a79c3bb Mon Sep 17 00:00:00 2001
From: "Robert D. Anderson"
Date: Tue, 6 Dec 2022 10:17:57 -0600
Subject: [PATCH] Address review comments on impose-role
---
.../archSpec/base/impose-topicref-role.dita | 26 ++++++++++---------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/specification/archSpec/base/impose-topicref-role.dita b/specification/archSpec/base/impose-topicref-role.dita
index 270f5613..b6887f2b 100644
--- a/specification/archSpec/base/impose-topicref-role.dita
+++ b/specification/archSpec/base/impose-topicref-role.dita
@@ -31,12 +31,12 @@
map, which in turn references content. When resolving those references, processors need to
know which roles created by the topicref elements need to be
preserved for the content.
- For example, assume that a specialized setupProject element
- indicates that the referenced content plays the "setup a project" role in a publication. This
- might result in special formatting or generated headings when the content is rendered. If that
- element refers to a map instead of a topic, that specialized role still needs to be passed on
- to topics in the referenced map - regardless of what topicref
- elements might be used in that referenced map.
+ For example, assume a setupProject element that is specialized from
+ topicref indicates that the referenced content plays the "setup a
+ project" role in a publication. This might result in special formatting or generated headings
+ when the content is rendered. If that element refers to a map instead of a topic, that
+ specialized role still needs to be passed on to topics in the referenced map - regardless of
+ what topicref elements might be used in that referenced map.
The impose-role attribute provides a way for specialized elements to declare
whether processors should use this behavior. This attribute is only evaluated when a
topicref element refers to a map or branch of a map. In that case,
@@ -59,7 +59,9 @@
element. If a topicref refers to a branch of a map, the role is
imposed only on the root element of that branch. If a topicref refers
to an entire map, the role is imposed only on the highest-level topic references within that
- map. The role does not cascade to other nested referencs within the map.
+ map. The role does not cascade to other nested referencs within the map. For example, if a
+ chapter element applied that role to every reference in another
+ map, that map would be made up only of chapters nested within chapters.
For elements that do not create a role for the referenced content, the
impose-role attribute is defined with a default value indicating that the
target of the reference keeps its original role: impose-role="keeptarget".
@@ -140,16 +142,16 @@
Imposing a role on a referenced map
- In this scenario, a specialized chapter element refers an entire
- submap. The chapter element does not need to set the impose-role attribute
- directly, because it is defined with a default value in the XML grammar files. The element
- itself sets the format attribute to indicate this is a map
+
In this scenario, a specialized chapter element refers to an
+ entire submap. The chapter element does not need to set the impose-role
+ attribute directly, because it is defined with a default value in the XML grammar files. The
+ element itself sets the format attribute to indicate this is a map
reference:<bookmap>
<!-- ... title, front matter, and other chapters -->
<chapter href="nestedmap.ditamap" format="ditamap"/>
<!-- additional content -->
</bookmap>
- The referenced map contains three branches as children of of the root
+
The referenced map contains three branches as children of the root
map element:<map>
<title>Reusable map branches</title>
<topicref href="branch1.dita"> <!-- ... --> </topicref>