[dita] Proposal for associating DITAVAL files with Maps

["Nitchie, Chris" <cnitchie@ptc.com>]

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.”