"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.
From: Kristen James Eberlein
[mailto:]
Sent: Sunday, February 28,
2010 8:52 PM
To: DITA TC
Subject: [dita] New topic about
"Map-to-map cascading"
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>
