"Rules" are mentioned
several times, but all we say is that each of these attributes cascades
(i.e. its value overrides the corresponding attribute value in a referenced
map). I don't see where we say what happens in a further-referenced submap. We
don't state any "rules" other than that single simple fact of cascading until we
get to the issues with specializations. This
is confusing. As a reader, I look for a list of things that look like rules.
The organization into sections leads the reader to expect that
the rules are different. Since the rules are the same, it would be best to state
them once, then have sections for the three kinds of examples. The section
titles should more clearly indicate that all three sections are about cascading
of attributes.
The body content before the first section could list the attributes that
cascade. These could be in two groups corresponding to the first two
sections:
The following attributes cascade from a referencing map to a referenced
map
Four of the
attributes on topic references
toc
audience
scope
print
All attributes on
metadata
elements
The table of attributes that do not
cascade is too prominent visually for so
much extraneous detail when your focus of interest is on cascading behavior.
The descriptions of these attributes are
not useful in this context (and introduce problems noted below); they could be
omitted, making it a simple list of attributes that do not cascade. Or the table
could be moved to the end, with a reference to it
here.
Following this summary
of "rules", the examples are in the
sections that follow. The titles of the first
two sections correspond to the
two groups of attributes listed above. The
last section combines some problem descriptions with examples. Maybe something
along these lines.
Examples of attributes on topic
references
Examples of attributes on metadata
elements
Preventing undesirable results with
specialized elements
There follow below some
particular passages with my comments tagged
with : preceding.
@conref Is evaluated separately from the map reference
:
Separately? Could this be more specific? Are we saying that @conref in a
referenced topic is resolved before the reference is resolved?
:
BTW, the description of @conref on the page for <map> says "This attribute
is used to reference an ID on a map that can be reused. See The conref attribute
for examples and details about the syntax." No example is given there, however.
This would be a pertinent example here, since attributes on the referencing map
would cascaded to the map referenced by @conref. I suppose the referencing map
could also include additional <topicref>s but they could only follow after
those in the referenced <map>.
@class Additional behavior described below
:
But you don't mention @class again after this. A copy/paste error?
@navtitle Provides the author a hint to the title of purpose of the
referenced DITA map
:
Should this say "title or purpose"?
: As noted earlier, do we even
need the attribute descriptions in this table? Why not just list the attributes
that do not cascade? That would eliminate the above three comments (but you
might consider the @conref example).
Elements that are contained within <topicmeta> or <metadata>
follow the same rules for cascading as apply within a single DITA
map.
:
The word "single" here doesn't make sense. In all relevant cases, we're talking
about maps that reference other maps.
: NB if you reorganize as suggested
this sentence goes away anyway.
In
simple maps this is straight-forward
:
straightforward is one word.
I've authored a new topic about
"Map-to-map cascading," based on review comments from Jeff Ogden, Dave
Helfinstine, Paul Grosso, and Robert Anderson. I'll copy and paste an HTML
version below; you also can grab the file
(map-to-map-cascading-of-metadata.dita) from the archSpec subdirectory in
SVN.
Can whoever authored feature proposal #12055 review this, please?
Thanks.
--------------------
Map-to-map cascading behaviors
When a DITA map is referenced by another DITA map, by default, certain
rules apply. These rules pertain to the cascading behaviors of attributes and
metadata elements.
Cascading of attributes
When a <topicref> element references a DITA map, the
referencing map sets certain attributes. For example, consider the following
code snippet from
test.ditamap:
<map>
<topicref="a.ditamap" format="ditamap" toc="no"/>
<topicref="b.ditamap" format="ditamap" audience="developer"/>
<topicref="c.ditamap" format="ditamap" scope="peer"/>
<topicref="d.ditamap" format="ditamap" print="no"/>
</map>When
test.ditamap is
processed, the following behavior occurs:
- The DITA topics that are referenced by a.ditamap do not appear in the navigation generated by
test.ditamap.
- The DITA topics that are referenced by b.ditamap are treated as if they have an @audience
attribute that is set to "developer".
- The DITA topics referenced by c.ditamap are
treated as if they have a @scope attribute that is set to "peer."
- The DITA topics that are referenced by d.ditamap are not generated when the map is
transformed to printed output.
In each case, the value of the attribute that is set in test.ditamap (the referencing DITA map) cascades; it
overrides the attribute value that is set in a.ditamap, b.ditamap,
c.ditamap, and d.ditamap (the referenced DITA maps).
Other attributes set in the referencing map do not override those
specified in the referenced DITA map. These attributes include all attributes
that (by definition) do not cascade.
| DITA attribute |
Comment |
| @conref |
Is evaluated separately from the map
reference |
| @class |
Additional behavior described
below |
| @copy-to |
Has no defined purpose in this
context |
| @collection-type |
Has no defined purpose in this
context |
| @format |
? |
| @navtitle |
Provides the author a hint to the title
of purpose of the referenced DITA map |
| @xtrf |
Has no defined purpose in this
context |
| @xtrc |
Has no defined purpose in this
context |
Cascading of metadata elements
Elements that are contained within <topicmeta> or <metadata>
follow the same rules for cascading as apply within a single DITA map. For
example, consider the following code snippets:
Figure 1. test-2.ditamap <map>
<topicref href="a.ditamap" format="ditamap">
<topicmeta>
<shortdesc>This map contains information about Acme defects.</shortdesc>
</topicmeta>
</topicref>
<topicref href="b.ditamap" format="ditamap">
<topicmeta>
<audience type="programmer"/>
</topicmeta>
</topicref>
<mapref href="c.ditamap" format="ditamap"/>
<mapref href="d.ditamap" format="ditamap"/>
</map>
Figure 2. b.ditamap <map>
<topicmeta>
<audience type="writer"/>
</topicmeta>
<topicref href="b-1.dita/>
<topicref href=b-2.dita/>
</map>
When
test-2.ditamap is processed, the
following behavior occurs:
Note: It is possible that a
specialization might define metadata that should replace rather than add to
metadata in the referenced map, but DITA (by default) does not currently
support this behavior.
Cascading in specialized maps
When a <topicref> element or a specialization of a <topicref>
element references a DITA resource, it defines a role for that resource. In
simple maps this is straight-forward; a <topicref> element references a
DITA topic, and a <mapref> element references a DITA map.
However, consider the scenario of a <chapter> element that
references a DITA map. This scenario could take several forms:
- Map contains a single top-level <topicref> element
- The entire branch functions as if it were included in the bookmap; the
top-level <topicref> element is processed as if it were the
<chapter> element.
- Map contains multiple top-level <topicref> elements
- Each top-level <topicref> element is processed as if it were a
<chapter> element (the referencing element).
- Map contains a single <appendix> element
- The <appendix> element is processed as it were a chapter element.
In each of the above cases, resource referenced by the <chapter>
element is treated as a like element. In situations where this should not
happen, the non-default behaviour should be clearly specified. As an example,
a <mapref> element is a convenience element; the top-level
<topicref> elements in the map referenced by a <mapref> element
should not be processed as if they are
<mapref> elements.
In some cases, preserving the role of the referencing element might result
in out-of-context content. For example, a <chapter> element that
references a bookmap might pull in <part> elements that contain nested
<chapter> elements. The result is implementation specific; processors
may or may not choose to treat this as an error, issue a warning, or simply
assign new roles to the problematic elements.
Best,
Kris
Kristen
James Eberlein
Principal consultant, Eberlein Consulting
Secretary,
OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption
Committee
www.eberleinconsulting.com
+1 919 682-2290;
keberlein
(skype)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php