RE: [dita] Proposal for associating DITAVAL files with Maps

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

Thanks again, all, for the discussion at this morning's meeting. Here are my takeaways (all subject to internal review).

1. Instead of using <topicref format="ditaval" processing-role="resource-only"/> for DITAVAL references, we will use <data name="ditavalref"/> inside topicmeta.
2. DITAVAL references may be filtered by the top-level DITAVAL file specified as a processing parameter, but may not be filtered according to other DITAVAL references within the map.
3. The proposal for 13059a will provide a mechanism by which a branch may be replicated for each DITAVAL file associated with it. It's my hope that the final 13059a proposal will allow both the 'replicate for each DITAVAL file' case and the 'process once using the rules from all DITAVAL files' case. The PTC implementation will only cover the latter. When there are conflicts between multiple DITAVAL files referenced from the same scope, the first rule takes precedence.
4. When a DITAVAL file referenced from a parent (closer-to-root) branch contains rules that conflict with rules in a DITAVAL file referenced from a child branch, the parent branch's rules take precedence.

One additional note on #2. One of the ideas Paul Grosso had when we were doing our design was a PI, analogous to the <?xml-stylesheet?> PI, that could be placed before the root element of the top-level map, identifying the DITAVAL file to use for that map. If something like this were adopted, then I'd suggest that other DITAVAL references could also be filtered by any DITAVAL file(s) referenced in this way.

Chris

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Tuesday, November 29, 2011 10:13 AM
To: Nitchie, Chris; dita
Subject: Re: [dita] Proposal for associating DITAVAL files with Maps

Can you define what you mean by "shallowest rule"? Do you mean the one
highest in the topicref hierarchy or do you mean closest to the descendant
topicrefs.

I have a small concern about having a referenced DITAVAL apply to its parent
as well as its siblings and descendants.

How would you handle the case where a child ditaval reference is conditional
and processing that ditaval would make it inapplicable?

For example:

<topicref href="some-topic-01.dita">
  <topicref href="ditaval-expert-only.ditaval" format="ditaval"
   audience="beginner"
/>
  <topicref href="ditaval-beginner-only.ditaval" format="ditaval"
   audience="expert"
/>
</topicref>

Where export-only sets audience="expert" to include and all others to
ignore.

It's the first child of the parent, and so would be applicable, except that
it makes itself inapplicable, making the second one applicable, which then
makes the first one applicable.

What if the parent is conditional and the child DITAVAL makes it
inapplicable, e.g:

<topicref href="some-topic-01.dita"
  audience="beginner"
>
  <topicref href="ditaval-expert-only.ditaval" format="ditaval"
  />
</topicref>

Having the child affect the parent would certainly disallow any sort of
naïve top-down application of conditionality.

If there are higher applicability definitions, does the child-referenced
DITAVAL override the higher-level DITAVAL?

Consider:


<topicref href="ditaval-beginner-only.ditaval" format="ditaval"
  />
<topicref href="some-topic-01.dita"
  audience="beginner"
>
  <topicref href="ditaval-expert-only.ditaval" format="ditaval"
  />
</topicref>

Here "beginner" is applicable and "expert" is inapplicable, so is the
reference to some-topic-01.dita applicable or inapplicable?

I think naïve author expectation would be that it is applicable, but by the
rules stated, it is inapplicable.

If the reference to the DITAVAL (via some new attribute) was on the parent
then I think it would be clearer how the DITAVAL scopes are constructed. But
obviously that requires definition of a new attribute.

Or the DITAVAL association could be done with metadata within <topicmeta>,
which would at least clearly bind the association to the topicref it applies
to. This could be done with a specialization of <data>. If the value was
always a key reference then you could still use a topicref to bind to the
actual DITAVAL file within the map, e.g.:

<map>
 <keydef keys="ditaval-expert-only"
  href="ditavals/expert-only.ditaval"
  format="ditaval"
/>
 <topicref href="some-topic-01.dita">
  <topicmeta>
    <data name="ditaval-ref" value="ditaval-expert-only"/>
  </topicmeta>
   ...
 </topicref>
</map>

Since good practice would be to use keys for DITAVAL references in any case
(because you should use keys for all references), I don't think the change
from <topicref> to <data> would materially change the authoring aspect. I
would expect profiling-aware editors to manage the DITAVAL association
details anyway.

Cheers,

E. 



On 11/28/11 4:35 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> 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
>  
>  
>  
>  <http://www.ptc.com/>
> 
> Chris Nitchie
> Senior Software Engineer
> 
> T 734.352.2879   F 734.997.0201
> E cnitchie@ptc.com <mailto:cnitchie@ptc.com>
> 
> PTC.com <http://www.ptc.com/>
>  
>  

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com