dita — archive

Branch filtering: ditavalref as child of a map

From: Robert Anderson <[email protected]>
To: [email protected]
Date: Mon, 26 Jan 2015 18:29:00 -0000

This makes me very nervous: > Thus, a map with > multiple direct-child ditavalrefs should produce a separate publication > deliverable for each ditavalref. > .... > So just processing the root map once per ditavalref is the simplest > and least-complicated behavior. For example, with PDF, this means that without looking at a map, an author / a processor cannot know if a publishing process will return one PDF, or two, or many. I don't think that is simple or uncomplicated. For an XHTML build, I would not even know what to expect from a tool (and I acknowledge / remind that my customers care about file names, which isn't the case for Eliot). > Note that if you *dont'* want child ditavalrefs to imply multiple > processing instances of the root map, simply don't do it: you can always > wrap a topicgroup around the top-level topicrefs in your map and put the > ditavalrefs there (assuming your map type allows that). For reltables, you > can push the reltables down into submaps and then use ditavalrefs on the > map reference. I think it's much more straightforward to say - if you want multiple, separate publications, build the root map multiple times with different ditaval profiles. That fits with conceptual models and processing models that have existed since DITA 1.0. I recognize that processing the root map N times for a single publication can result in some quirky edge cases. For example, what is the title of the single publication, if filtering results in different <title> contents? But those quirks are easier to understand / deal with in the markup than the suggested alternative. The markup workarounds are also likely simpler than the markup changes described above. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Eliot Kimber <[email protected]> wrote on 01/24/2015 08:16:43: > From: Eliot Kimber <[email protected]> > To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC <[email protected]> > Date: 01/24/2015 08:16 > Subject: Re: [dita] Branch filtering: ditavalref as child of a map > > I don't think treating root-map ditaval refs as equivalent to a map with a > mapref to the original root map will work because the title and metadata > of root maps are processed in a completely different way than for > submaps--that is, creating multiple maprefs to the original root map is > not equivalent to processing the root map multiple times. > > I think the only reliable meaning for root-map ditavalrefs is that they > imply processing the root map once for each ditavalref. > > That is, they are equivalent to simply processing the root map with the > referenced ditaval specified as the run-time ditaval (and runtime > conditions equivalent to the ditavalref controls for adjusting names). > This approach ensures that all elements of the map are processed with > respect to the active conditions while avoiding issues with things like > replicated titles and metadata or relationship tables. Thus, a map with > multiple direct-child ditavalrefs should produce a separate publication > deliverable for each ditavalref. > > The only reasonable alternative I can think of is to treat the ditavalrefs > as equivalent to map references to a map that contains only the topicref > and reltable children of the root map. However, that would then disallow > having root-level titles and metadata that are filtered per the > ditavalrefs and there seem to be legitimate use cases where you'd want > that. So just processing the root map once per ditavalref is the simplest > and least-complicated behavior. > > For submaps with direct-child ditavalrefs I think it is reasonable to > treat that case as equivalent to having the ditavalrefs in the maprefs to > the submaps. The processing result will be the same in that case. > > Note that if you *dont'* want child ditavalrefs to imply multiple > processing instances of the root map, simply don't do it: you can always > wrap a topicgroup around the top-level topicrefs in your map and put the > ditavalrefs there (assuming your map type allows that). For reltables, you > can push the reltables down into submaps and then use ditavalrefs on the > map reference. > > Note that <bookmap> as currently defined doesn't allow <ditavalref> to > occur as a direct child of the map (because bookmap doesn't allow > unspecialized <topicref> to occur as a child of <bookmap>), so there's no > way to allow <ditavalref> (or any other specialization of topicref) at > that location. So the issue can't come up with bookmap-based publications. > > Cheers, > > Eliot > ————— > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 1/20/15, 9:39 AM, "Robert D Anderson" <[email protected]> wrote: > > >Hi, > > > >Belatedly following up on an action item from the January 6 meeting. Here > >is a sample of the problems involved with having more than one > ><ditavalref> as direct children of a map. Take the following map: > ><map> > > <title>Here is a map for <ph audience="me">ME</ph><ph > >audience="you">YOU</ph></title> > > <topicmeta> ... </topicmeta> > > <ditavalref href= > > > <ditavalref href= > > > <topicref href= > > > <topicref href= > > > <topicref href= > > > <reltable> ... relationship table ... </reltable> > ></map> > > > >Why this is difficult to handle: > > > >The <ditavalref> element is intended to filter the containing element and > >its children. This is easy to understand in the context of a topicref: > ><topicref href= ... ditavalref, then topic children > ></topicref> > > > >When there are multiple <ditavalref> elements in that case, it's easy to > >express using simpler markup -- just duplicate the branch: > ><topicref href= ... first ditavalref, then topic > >children </topicref> > ><topicref href= ... second ditavalref, then topic > >children </topicref> > > > >With the map container, we can't duplicate the root element. Likewise - > ><reltable> can only appear as a child of <map>, so we cannot introduce > >grouping elements to make this simpler. (Note: this already results in > >odd wording related to mapref, where integrating a sub-map requires > >special treatment for reltable.) > > > >From the discussion on January 6, I think it's clear that we expect the > >relationship tables to be processed with the filter, so that links > >continue to work within each copy of the content. Disallowing this would > >mean that at most, only one version of your content could be cross-linked. > > > >It's less clear whether the title or metadata should be processed with > >the filter. I believe Eliot's assumption was no, while my assumption was > >yes. My preference is for consistency - if ditavalref always filters the > >container and its kids (including metadata) within topicref, it should do > >the same within map. > > > >Part of the difficulty comes from the fact that this could be a root map, > >and it could be a submap. > > > >In a root map, the sample above essentially creates two full > >publications, one filtered for "me" and one for "you". If we duplicate > >the title (or metadata), which is used by the publication as a whole? In > >a submap, the title already has little meaning. I'd still prefer to say > >it gets filtered - because then the submap works exactly the same way it > >would if you placed <ditavalref> inside of a reference to this map. > > > >I think further discussion goes to the TC. My preference, if we can, is > >to say that <ditavalref> as a child of map works the same way as > ><ditavalref> inside a reference to the map. This might require special > >treatment for <ditavalref> as child of a root map, where you're > >effectively building one publication with multiple copies of the entire > >content. If the sample map above is a root map, then I think we could say > >it's equivalent to that same map (minus the <ditavalref>) referenced like > >this: > ><map> > > <mapref href= > > > <ditavalref href= > > > <ditavalref href= > > > </mapref> > ></map> > > > >Robert D Anderson > >IBM Authoring Tools Development > >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > >