PTC is in the throes of designing a mechanism for associating DITAVAL files with maps, and I want to make sure we don’t wind up doing something that conflicts with the upcoming proposals for DITA 1.3. Unfortunately, our release schedule dictates that we have something in place in the next few weeks, so we really can’t wait. I’ve attached the design we’re planning to go with, in the hopes that interested parties (particularly Robert and Michael, who own 1.3 proposal 13059a, which covers this same ground) will call out potential issues with what they’re working on. In particular, I could use some feedback on these design decisions: 1. A DITAVAL referenced via topicref applies to the branch of a map contained by its parent topicref, including the content, if any, referenced from that topicref. It applies to the whole map if referenced anywhere at the root level. 2. When two DITAVAL files containing contradictory rules are referenced from the same topicref scope, we’re going to take the first rule and ignore subsequent ones. 3. When two DITAVAL files containing contradictory rules are referenced from nested branches in a map, the shallowest rule will be take precedence. This is loosely derived from the way key definition precedence is determined, though that rule applies to map structure and not hierarchy within a single map. Thanks for any feedback you can provide. Chris Chris Nitchie Senior Software Engineer T 734.352.2879 F 734.997.0201 E
cnitchie@ptc.com PTC.com Title: Associating DITAVAL Files with Maps
1 Associating DITAVAL Files with Maps
Starting with this release, you will be able to associate one or more DITAVAL files with some or all of a map. This allows
a great deal of flexibility. If a map should always be published with a given set of rules, you can associate those rules
directly with the map without having to specify them every time the map is published. You can also specify different profiling
settings for different sections in the same map.
To associate a DITAVAL file with a map, reference it via a topicref with the format attribute set to “ditaval” , the scope attribute set to “local” , and the processing-role attribute set to “resource-only” . (Since the default value for scope is “local” in most cases except where another value is inherited from a parent element or conref target, it can generally be omitted.)
<topicref href=
format= ditaval
processing-role= resource-only /> When resolving references to DITAVAL files, the ditapath setting will be consulted.
The portion of the map affected by a DITAVAL file referenced in this way is contained by the parent element of such a reference,
including all elements before and after it at the same level, and elements nested at deeper levels. Specifically, a DITAVAL
reference will apply the rules from the file to:
•
The parent element of the DITAVAL reference.
•
The topic or map, if any, referenced by the parent element of the DITAVAL reference.
•
All markup, including topicmeta contents and topicref elements, occurring within the map branch encapsulated by the parent element of the DITAVAL reference, the only exceptions
being the DITAVAL reference itself and other DITAVAL references at the same level.
•
Any topics or maps referenced via topicref within the branch encapsulated by the parent element of the DITAVAL reference, except where the topicref that references the file is excluded by the effective DITAVAL rules.
So to affect an entire map, place the reference at the root level of the map. To have the rules apply only for part of the
map, place the reference within a topicref (or specialization thereof) containing the region of the map structure to which the rules should apply.
IMPORTANT
Associating a DITAVAL File with a Bookmap
It’s tempting to associate a DITAVAL file with an entire Bookmap by placing the reference within frontmatter . This is incorrect. If you place the reference within frontmatter then its rules will only apply to the frontmatter element and its contents. Instead, place the reference at the root level somewhere in between frontmatter and backmatter in order to have it apply to the whole bookmap.
1.1 Rules for Multiple References
DITAVAL associations are additive. If two DITAVAL files are referenced at the same level in the map, both sets of rules apply
at that level. If the two files contain rules for the same attribute-value pair, the rules from the first file in document
order take precedence. Similarly, if a parent scope and a child scope both reference DITAVAL files, the effective rule set
for the inner scope will be the combination of the rules in the two files. Where there are rules for matching attribute-value
pairs for both the parent and the child scope, the rules from the parent scope overrule those in the child scope. This allows
top-level map authors to override the DITAVAL rules specified in child maps.
Any DITAVAL specified via the composition UI for the whole map is considered to have “global” scope. Normal additivity rules
apply for DITAVAL references within the map, with the global DITAVAL file being considered the top-level rule set.
Note that traditional Arbortext profiling occurs in addition to DITAVAL processing. Since DITAVAL processing is part of the
DITA preprocessing done before standard publishing, DITAVAL filtering occurs before profiling is applied.
1.2 Examples
Appling a DITAVAL File to an Entire Map
You can specify DITAVAL rules for a whole map structure by referencing it from the root level of the map. <map xml:lang= en >
<!-- the <ph> tags will be filtered using the rules in expert.ditaval -->
<title>
<ph audience= Expert >Expert</ph>
<ph audience= Novice >Novice</ph>
Instructions
</title>
<topicref href=
format= ditaval
processing-role= resource-only />
<!-- All topics will be filtered via 'expert.ditaval' -->
<topicref href= />
<topicref href= />
</map>
Profiling the Same TOC with Different Rules
You can use DITAVAL association to have the same set of topics filtered differently by wrapping them in different “wrapper”
maps with different DITAVAL associations.
<map xml:lang= en >
<title>Expert Instructions</title>
<topicref href=
format= ditaval
processing-role= resource-only />
<mapref href= />
</map>
<map xml:lang= en >
<title>Novice Instructions</title>
<topicref href=
format= ditaval
processing-role= resource-only />
<mapref href= />
</map>
Different DITAVAL Rules for Different Sections of a Map
You can use different DITAVAL rules at different locations in the same map structure. In the example below, content affected
by teacher.ditaval will be highlighted in green, and content affected by student.ditaval will be highlighted in orange.
<map xml:lang= en >
<title>Teacher's Guide</title>
<!-- Section One -->
<topichead navtitle= Section One (Teacher) >
<topicref href=
format= ditaval
processing-role= resource-only />
<topicref href= />
</topichead>
<topichead navtitle= Section One (Student) >
<topicref href=
format= ditaval
processing-role= resource-only />
<topicref href= />
</topichead>
<!-- Section Two -->
<topichead navtitle= Section Two (Teacher) >
<topicref href=
format= ditaval
processing-role= resource-only />
<topicref href= />
</topichead>
<topichead navtitle= Section Two (Student) >
<topicref href=
format= ditaval
processing-role= resource-only />
<topicref href= />
</topichead>
</map>
DITAVAL Rule Additivity
Let’s say you had two DITAVAL files.
•
ProjectX.ditaval: <val>
<prop att= product val= ProjectX action= />
<prop att= otherprops val= Green action= color= green />
</val>
•
ProjectY.ditaval: <val>
<prop att= product val= ProjectX action= />
<prop att= product val= ProjectY action= />
<prop att= otherprops val= Red action= color= red />
</val>
When these two DITAVAL files are referenced from nested topicrefs in a map, the effect for the inner scope will be the same
as if you took the prop elements from the ‘inner’ scope and appended them to the DITAVAL file from the ‘outer’ scope.
<map>
<topicref href= >
<topicref href=
format= ditaval
processing-role= resource-only />
<topicref href= >
<topicref href=
format= ditaval
processing-role= resource-only />
</topicref>
</topicref>
</map>
In this example, only the rules in ProjectX.ditaval apply to topic1.dita , but the effective DITAVAL rules for topic2.dita will be the combination of the rules from ProjectX.ditaval and ProjectY.ditaval :
<val>
<!-- From ProjectX -->
<prop att= product val= ProjectX action= />
<prop att= otherprops val= Green action= color= green />
<!-- From ProjectY. Since product= ProjectX is already -->
<!-- defined, the second rule is ignored. -->
<prop att= product val= ProjectX action= />
<prop att= product val= ProjectY action= />
<prop att= otherprops val= Red action= color= red />
</val> So the effective action for product=”ProjectX” is “include.” If the order were reversed, and ProjectY were referenced from
the outer scope and ProjectX from the inner scope, the effective rules at topic2.dita would be reversed:
<val>
<!-- From ProjectY -->
<prop att= product val= ProjectX action= />
<prop att= product val= ProjectY action= />
<prop att= otherprops val= Red action= color= red />
<!-- From ProjectX -->
<prop att= product val= ProjectX action= />
<prop att= otherprops val= Green action= color= green />
</val> So the effective rule for product=”ProjectX” is “exclude.”