OASIS Darwin Information Typing Architecture (DITA) TC

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/ )

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" <robander@us.ibm.com> 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="me.ditaval"/> > <ditavalref href="you.ditaval"/> > <topicref href="branch1.dita">....</topicref> > <topicref href="branch2.dita">....</topicref> > <topicref href="branch3.dita">....</topicref> > <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="this-is-parent.dita"> ... 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="this-is-parent.dita"> ... first ditavalref, then topic >children </topicref> ><topicref href="this-is-parent.dita"> ... 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="sample-from-above.ditamap"> > <ditavalref href="me.ditaval"/> > <ditavalref href="you.ditaval"/> > </mapref> ></map> > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43:

> From: Eliot Kimber <ekimber@contrext.com>
> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC <dita@lists.oasis-open.org>
> 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" <robander@us.ibm.com> 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/ )
>
>

I'm not sure we're sharing the same mental model of what it means to process the *contents* of a root map n times. If my root map is: <map> <title>My Publication</title> <ditavalref href="ditaval1.ditaval"/> <ditavalref href="ditaval2.ditaval"/> ... </map> How many titles are there? I think there are 2, which is clearly not sensible in the context of the map model (maps have at most 1 title). I agree that implying multiple publications is problematic--I'm not wedded to that interpretation, it just seems like the only consistent one. We could instead say that direct-child ditavals within a map simply establish a relationship to those ditaval files with no processing implications at all--a convenience by which authors can hard-code the ditavals they want the publication to be processable with. Editors or processing managers can use that information to provide a list of ditavals to select from at processing time. Or not. Or they can choose to treat it as a signal to produce a separate deliverable for each ditaval: there would be no reason to prohibit that and some users might want it (but I agree that not all users would want that, maybe even most users would not want that). But it is definitely the case that: <map> <mapref href="realmap.ditamap"/> </map> Where realmap.ditamap is the map shown above, has different rendering implications than just processing realmap. In particular, the title of realmap in the second case is *not rendered*, by the rules for the handling of submap titles, and the metadata in the submap does not define the metadata for the publication as a whole (the implications of submap metadata are pretty fuzzy in the current spec, but there's nothing that suggests submap metadata would contribute to the metadata of the publication as a whole, only to the metadata of the things within the scope of that submap). That is, this map is a root map with no title. And that's definitely not what we would intend the result to be. So I think the options are: 1. The DITAVALs imply multiple deliverables (problematic 2. The DITAVALs are informative and have no required processing implications 3. The effective result is a map where the topicrefs and reltables, but not title or metadata, are pushed to a submap, with the ditavalrefs within the submap, e.g.: This: <map> <title>My Publication</title> <ditavalref href="ditaval1.ditaval"/> <ditavalref href="ditaval2.ditaval"/> <topicref href="topic1.dita"/> <topicref href="topic2.dita"/> <reltable> ... </reltable> </map> Becomes two maps: Root map: <map> <title>My Publication</title> <mapref href="submap.ditamap"> <ditavalref href="ditaval1.ditaval"/> <ditavalref href="ditaval2.ditaval"/> </mapref> </map> Submap: <map> <topicref href="topic1.dita"/> <topicref href="topic2.dita"/> <reltable> ... </reltable> </map> This option avoids issues of duplication of the root map title and metadata while preserving the implications for the topicrefs and reltables. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43: > >> From: Eliot Kimber <ekimber@contrext.com> >> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC >><dita@lists.oasis-open.org> >> 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" <robander@us.ibm.com> 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="me.ditaval"/> >> > <ditavalref href="you.ditaval"/> >> > <topicref href="branch1.dita">....</topicref> >> > <topicref href="branch2.dita">....</topicref> >> > <topicref href="branch3.dita">....</topicref> >> > <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="this-is-parent.dita"> ... 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="this-is-parent.dita"> ... first ditavalref, then topic >> >children </topicref> >> ><topicref href="this-is-parent.dita"> ... 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="sample-from-above.ditamap"> >> > <ditavalref href="me.ditaval"/> >> > <ditavalref href="you.ditaval"/> >> > </mapref> >> ></map> >> > >> >Robert D Anderson >> >IBM Authoring Tools Development >> >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) >> >>

Anybody have any interest in simply saying that for the root map, any ditavalrefs after the first one are ignored with a warning? Chris Chris Nitchie (734) 330-2978 chris.nitchie@oberontech.com www.oberontech.com < http://www.oberontech.com/ > Follow us: < https://www.facebook.com/oberontech > < https://twitter.com/oberontech > < http://www.linkedin.com/company/oberon-technologies > On 1/26/15, 2:15 PM, "Eliot Kimber" <ekimber@contrext.com> wrote: >I'm not sure we're sharing the same mental model of what it means to >process the *contents* of a root map n times. > >If my root map is: > ><map> > <title>My Publication</title> > <ditavalref href="ditaval1.ditaval"/> > <ditavalref href="ditaval2.ditaval"/> > ... ></map> > >How many titles are there? I think there are 2, which is clearly not >sensible in the context of the map model (maps have at most 1 title). > >I agree that implying multiple publications is problematic--I'm not wedded >to that interpretation, it just seems like the only consistent one. > >We could instead say that direct-child ditavals within a map simply >establish a relationship to those ditaval files with no processing >implications at all--a convenience by which authors can hard-code the >ditavals they want the publication to be processable with. Editors or >processing managers can use that information to provide a list of ditavals >to select from at processing time. Or not. Or they can choose to treat it >as a signal to produce a separate deliverable for each ditaval: there >would be no reason to prohibit that and some users might want it (but I >agree that not all users would want that, maybe even most users would not >want that). > >But it is definitely the case that: > ><map> > <mapref href="realmap.ditamap"/> ></map> > >Where realmap.ditamap is the map shown above, has different rendering >implications than just processing realmap. In particular, the title of >realmap in the second case is *not rendered*, by the rules for the >handling of submap titles, and the metadata in the submap does not define >the metadata for the publication as a whole (the implications of submap >metadata are pretty fuzzy in the current spec, but there's nothing that >suggests submap metadata would contribute to the metadata of the >publication as a whole, only to the metadata of the things within the >scope of that submap). > >That is, this map is a root map with no title. And that's definitely not >what we would intend the result to be. > >So I think the options are: > >1. The DITAVALs imply multiple deliverables (problematic > >2. The DITAVALs are informative and have no required processing >implications > >3. The effective result is a map where the topicrefs and reltables, but >not title or metadata, are pushed to a submap, with the ditavalrefs within >the submap, e.g.: > >This: > ><map> > <title>My Publication</title> > <ditavalref href="ditaval1.ditaval"/> > <ditavalref href="ditaval2.ditaval"/> ><topicref href="topic1.dita"/> ><topicref href="topic2.dita"/> ><reltable> > ... ></reltable> ></map> > >Becomes two maps: > >Root map: > ><map> ><title>My Publication</title> ><mapref href="submap.ditamap"> ><ditavalref href="ditaval1.ditaval"/> ><ditavalref href="ditaval2.ditaval"/> ></mapref> ></map> > > >Submap: > ><map> ><topicref href="topic1.dita"/> ><topicref href="topic2.dita"/> ><reltable> > ... ></reltable> ></map> > > > >This option avoids issues of duplication of the root map title and >metadata while preserving the implications for the topicrefs and >reltables. > >Cheers, > >E. > >‹‹‹‹‹ >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: > >>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43: >> >>> From: Eliot Kimber <ekimber@contrext.com> >>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC >>><dita@lists.oasis-open.org> >>> 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" <robander@us.ibm.com> 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="me.ditaval"/> >>> > <ditavalref href="you.ditaval"/> >>> > <topicref href="branch1.dita">....</topicref> >>> > <topicref href="branch2.dita">....</topicref> >>> > <topicref href="branch3.dita">....</topicref> >>> > <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="this-is-parent.dita"> ... 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="this-is-parent.dita"> ... first ditavalref, then topic >>> >children </topicref> >>> ><topicref href="this-is-parent.dita"> ... 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="sample-from-above.ditamap"> >>> > <ditavalref href="me.ditaval"/> >>> > <ditavalref href="you.ditaval"/> >>> > </mapref> >>> ></map> >>> > >>> >Robert D Anderson >>> >IBM Authoring Tools Development >>> >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) >>> >>> > > > >--------------------------------------------------------------------- >To unsubscribe from this mail list, you must leave the OASIS TC that >generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >

> Anybody have any interest in simply saying that for the root map, any
> ditavalrefs after the first one are ignored with a warning?

I don't think I like that idea. It's ... probably going to confuse more people than it helps. Even if it makes life much easier for implementers like myself. Again, I fall back to avoiding inconsistency - I don't like that in most contexts, we operate one way, but in just this case, we ignore elements.

FWIW, I chatted with Jarno Elovirta a bit about this and he made one pretty clear point that got me thinking.

There is nothing at all in the spec today that says "one root map produces one publication" (PDF, EPUB, HTML, whatever). You can plausibly have a build that splits up a 1000 page PDF for smaller download size (I believe Jarno has run into that case).

Similarly, a processor could say "give me N root maps and I will render them as one PDF". Maybe it concatenates them, maybe it does something more clever, but that's up to the processor / person wanting the PDF.

As long as you interpret the content properly, and then render that appropriately for your context / format, that's all legal.

The conclusion to this argument is really that the spec cannot mandate "N direct-child ditavalref elements in the root map will create N separate publications". It's up to the processor. It may do that (Jarno suggested he might find this a good default), but it could just as easily create one publication. The spec can't mandate this; all it can (and should) do is to state which content / which elements get filtered based on each <ditavalref> element.

I think Jarno sold me on that argument. Hopefully I've re-interpreted it properly here, and I'm curious what others think.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

Chris Nitchie ---01/26/2015 13:18:19---Anybody have any interest in simply saying that for the root map, any ditavalrefs after the first on

From: Chris Nitchie <chris.nitchie@oberontech.com>
To: Eliot Kimber <ekimber@contrext.com>, "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 01/26/2015 13:18
Subject: Re: [dita] Branch filtering: ditavalref as child of a map
Sent by: <dita@lists.oasis-open.org>



Anybody have any interest in simply saying that for the root map, any
ditavalrefs after the first one are ignored with a warning?

Chris




Chris Nitchie
(734) 330-2978
chris.nitchie@oberontech.com
www.oberontech.com
< http://www.oberontech.com/ >
Follow us:
< https://www.facebook.com/oberontech >
< https://twitter.com/oberontech >
< http://www.linkedin.com/company/oberon-technologies >








On 1/26/15, 2:15 PM, "Eliot Kimber" <ekimber@contrext.com> wrote:

>I'm not sure we're sharing the same mental model of what it means to
>process the *contents* of a root map n times.
>
>If my root map is:
>
><map>
> <title>My Publication</title>
> <ditavalref href= >
> <ditavalref href= >
> ...
></map>
>
>How many titles are there? I think there are 2, which is clearly not
>sensible in the context of the map model (maps have at most 1 title).
>
>I agree that implying multiple publications is problematic--I'm not wedded
>to that interpretation, it just seems like the only consistent one.
>
>We could instead say that direct-child ditavals within a map simply
>establish a relationship to those ditaval files with no processing
>implications at all--a convenience by which authors can hard-code the
>ditavals they want the publication to be processable with. Editors or
>processing managers can use that information to provide a list of ditavals
>to select from at processing time. Or not. Or they can choose to treat it
>as a signal to produce a separate deliverable for each ditaval: there
>would be no reason to prohibit that and some users might want it (but I
>agree that not all users would want that, maybe even most users would not
>want that).
>
>But it is definitely the case that:
>
><map>
> <mapref href= >
></map>
>
>Where realmap.ditamap is the map shown above, has different rendering
>implications than just processing realmap. In particular, the title of
>realmap in the second case is *not rendered*, by the rules for the
>handling of submap titles, and the metadata in the submap does not define
>the metadata for the publication as a whole (the implications of submap
>metadata are pretty fuzzy in the current spec, but there's nothing that
>suggests submap metadata would contribute to the metadata of the
>publication as a whole, only to the metadata of the things within the
>scope of that submap).
>
>That is, this map is a root map with no title. And that's definitely not
>what we would intend the result to be.
>
>So I think the options are:
>
>1. The DITAVALs imply multiple deliverables (problematic
>
>2. The DITAVALs are informative and have no required processing
>implications
>
>3. The effective result is a map where the topicrefs and reltables, but
>not title or metadata, are pushed to a submap, with the ditavalrefs within
>the submap, e.g.:
>
>This:
>
><map>
> <title>My Publication</title>
> <ditavalref href= >
> <ditavalref href= >
><topicref href= >
><topicref href= >
><reltable>
> ...
></reltable>
></map>
>
>Becomes two maps:
>
>Root map:
>
><map>
><title>My Publication</title>
><mapref href= >
><ditavalref href= >
><ditavalref href= >
></mapref>
></map>
>
>
>Submap:
>
><map>
><topicref href= >
><topicref href= >
><reltable>
> ...
></reltable>
></map>
>
>
>
>This option avoids issues of duplication of the root map title and
>metadata while preserving the implications for the topicrefs and
>reltables.
>
>Cheers,
>
>E.
>
>‹‹‹‹‹
>Eliot Kimber, Owner
>Contrext, LLC
> http://contrext.com
>
>
>
>
>On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote:
>
>>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43:
>>
>>> From: Eliot Kimber <ekimber@contrext.com>
>>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC
>>><dita@lists.oasis-open.org>
>>> 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" <robander@us.ibm.com> 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/ )
>>>
>>>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe from this mail list, you must leave the OASIS TC that
>generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php  

Maybe it's not so much that we differ on the mental model, it's that we differ on whether <ditavalref> should apply to the title and metadata. I feel quite strongly that it should. I think doing otherwise is inconsistent.

In *any other context* , <ditavalref> applies to the parent and its descendants - including titles and metadata. For simplicity I'll only use one filter set:
<topicref href= locktitle="yes">
<topicmeta>
<navtitle>Title with conditional <ph>phrases</ph></navtitle>
...other metadata that could be conditional...
</topicmeta>
<ditavalref href= >
...other topics...
</topicref>

I don't understand why we would introduce inconsistency in this root map:
<map>
<title>Title with conditional <ph>phrases</ph></title>
<topicmeta>...metadata that could be conditional</topicmeta>
<ditavalref href= >
...topics...
</map>

In a mapref, the filters apply to everything (even if the title is ignored by most processors for most purposes). A ditavalref in a submap is equivalent to the mapref case. Why would it not apply to the title here?

Perhaps this is an edge case, but I know for sure that conditional phrases / keywords exist in map titles today. In DITA 1.2, the ditavalref doesn't enter into it, so the processing is straightforward.

Part of me wonders if we can answer the deeper questions until we answer that one -- does ditavalref, at a map level, result in filtering of the title/metadata? And is that answer the same for root maps vs submaps? I think if we have one answer for root maps and a different answer for submaps, we're adding exceptions that will only serve to complicate things.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )

Eliot Kimber ---01/26/2015 13:26:05---I'm not sure we're sharing the same mental model of what it means to process the *contents* of a roo

From: Eliot Kimber <ekimber@contrext.com>
To: DITA TC <dita@lists.oasis-open.org>
Date: 01/26/2015 13:26
Subject: Re: [dita] Branch filtering: ditavalref as child of a map
Sent by: <dita@lists.oasis-open.org>



I'm not sure we're sharing the same mental model of what it means to
process the *contents* of a root map n times.

If my root map is:

<map>
<title>My Publication</title>
<ditavalref href= >
<ditavalref href= >
...
</map>

How many titles are there? I think there are 2, which is clearly not
sensible in the context of the map model (maps have at most 1 title).

I agree that implying multiple publications is problematic--I'm not wedded
to that interpretation, it just seems like the only consistent one.

We could instead say that direct-child ditavals within a map simply
establish a relationship to those ditaval files with no processing
implications at all--a convenience by which authors can hard-code the
ditavals they want the publication to be processable with. Editors or
processing managers can use that information to provide a list of ditavals
to select from at processing time. Or not. Or they can choose to treat it
as a signal to produce a separate deliverable for each ditaval: there
would be no reason to prohibit that and some users might want it (but I
agree that not all users would want that, maybe even most users would not
want that).

But it is definitely the case that:

<map>
<mapref href= >
</map>

Where realmap.ditamap is the map shown above, has different rendering
implications than just processing realmap. In particular, the title of
realmap in the second case is *not rendered*, by the rules for the
handling of submap titles, and the metadata in the submap does not define
the metadata for the publication as a whole (the implications of submap
metadata are pretty fuzzy in the current spec, but there's nothing that
suggests submap metadata would contribute to the metadata of the
publication as a whole, only to the metadata of the things within the
scope of that submap).

That is, this map is a root map with no title. And that's definitely not
what we would intend the result to be.

So I think the options are:

1. The DITAVALs imply multiple deliverables (problematic

2. The DITAVALs are informative and have no required processing
implications

3. The effective result is a map where the topicrefs and reltables, but
not title or metadata, are pushed to a submap, with the ditavalrefs within
the submap, e.g.:

This:

<map>
<title>My Publication</title>
<ditavalref href= >
<ditavalref href= >
<topicref href= >
<topicref href= >
<reltable>
...
</reltable>
</map>

Becomes two maps:

Root map:

<map>
<title>My Publication</title>
<mapref href= >
<ditavalref href= >
<ditavalref href= >
</mapref>
</map>


Submap:

<map>
<topicref href= >
<topicref href= >
<reltable>
...
</reltable>
</map>



This option avoids issues of duplication of the root map title and
metadata while preserving the implications for the topicrefs and reltables.

Cheers,

E.

—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote:

>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43:
>
>> From: Eliot Kimber <ekimber@contrext.com>
>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC
>><dita@lists.oasis-open.org>
>> 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" <robander@us.ibm.com> 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/ )
>>
>>



---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php  

The problem I'm having is that there's no markup to which a root map with multiple ditavalrefs can be transformed that both reflects the *duplication* of the children of the <map> element and is valid DITA. And in any case, replicating the title and metadata wouldn't make sense in the context of a single deliverable where the root map defines the root deliverable title and metadata. [And while Jarno is correct that the DITA spec doesn't require an exact one-to-one correspondence between root maps and deliverables, it does definitely establish that the normal case is that a root map represents a deliverable and, in particular, that the root map's title and metadata are the title and metadata of that deliverable. But there's also a probably unavoidable fuzziness in the DITA spec because a "publication" is an abstraction distinct from the way that publication might be organized physically into deliverable artifacts: volumes, HTML pages, etc. The problem here is that "a publication" is whatever the person producing it says it is: a single book, a multi-volume set, a whole Web site, part of a Web site. The only thing we know is that we have one root input map.] That is, I can't take this: <map> <title>My Publication</title> <ditavalref href="ditaval1.ditaval"/> <ditavalref href="ditaval2.ditaval"/> </map> and produce any equivalent 1.2 markup in which the title element is duplicated and to which the conditions are locally applied (because we have no non-topicref equivalent of ditavalref). I could produce this DITA 1.3 map: <map> <mapref scope="peer" href="realmap.ditamap"> <ditavalref href="ditava1.ditaval"/> </mapref> <mapref scope="peer" href="realmap.ditamap"> <ditavalref href="ditava2.ditaval"/> </mapref> </map> But we haven't (as far as I know), established what it means to apply a ditavalref to a peer map--maybe we should? And maybe that's the solution to our conundrum. I would certainly read this map as implying So far the branch filtering processing can be defined *entirely* in terms of transforming the original map into a new set of maps where all the implied branches are made explicit and all the conditions are expanded into a global set of condition values. That is, except for the root map, there is a deterministic process by which I can generate a DITA 1.2 map set that exactly implements the intent of the ditavalref elements. However, if ditavalref also applies to the title and metadata of the root map, there is no simple transformation that will result in valid 1.2 markup. We could say that the *content* of the title element is replicated, with different conditions applied, but for the metadata it's a lot more complicated, because some metadata elements are repeatable and some or not (meaning you'd have to replicate their *contents* as for title). For example, using the My Publication map shown above, what would the result title be after processing? I think it has to be "My PublicationMy Publication". That's clearly not the right answer. So it's not clear to me that it would even be useful to have the title and metadata processed n times because there's only one publication (using our normal root map == deliverable) model. The only way it could make sense is if each root ditavalref results in a separate deliverable, which gets us back to my original proposal (and Robert's objection to it). Or said another way: if root-level ditavalrefs do not imply one complete deliverable per ditavalref, then I think it must be the case that only the topicrefs and reltables are replicated because it simply would not make sense to replicate the root title and metadata. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/26/15, 1:54 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >Maybe it's not so much that we differ on the mental model, it's that we >differ on whether <ditavalref> should apply to the title and metadata. I >feel quite strongly that it should. I think doing otherwise is >inconsistent. > >In *any other context*, <ditavalref> applies to the parent and its >descendants - including titles and metadata. For simplicity I'll only use >one filter set: ><topicref href="parent.dita" locktitle="yes"> > <topicmeta> > <navtitle>Title with conditional <ph>phrases</ph></navtitle> > ...other metadata that could be conditional... > </topicmeta> > <ditavalref href="simple.ditaval"/> > ...other topics... ></topicref> > >I don't understand why we would introduce inconsistency in this root map: ><map> > <title>Title with conditional <ph>phrases</ph></title> > <topicmeta>...metadata that could be conditional</topicmeta> > <ditavalref href="simple.ditaval"/> > ...topics... ></map> > >In a mapref, the filters apply to everything (even if the title is >ignored by most processors for most purposes). A ditavalref in a submap >is equivalent to the mapref case. Why would it not apply to the title >here? > >Perhaps this is an edge case, but I know for sure that conditional >phrases / keywords exist in map titles today. In DITA 1.2, the ditavalref >doesn't enter into it, so the processing is straightforward. > >Part of me wonders if we can answer the deeper questions until we answer >that one -- does ditavalref, at a map level, result in filtering of the >title/metadata? And is that answer the same for root maps vs submaps? I >think if we have one answer for root maps and a different answer for >submaps, we're adding exceptions that will only serve to complicate >things. > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > >Eliot Kimber ---01/26/2015 13:26:05---I'm not sure we're sharing the same >mental model of what it means to process the *contents* of a roo > >From: Eliot Kimber <ekimber@contrext.com> >To: DITA TC <dita@lists.oasis-open.org> >Date: 01/26/2015 13:26 >Subject: Re: [dita] Branch filtering: ditavalref as child of a map >Sent by: <dita@lists.oasis-open.org> > >________________________________________ > > > >I'm not sure we're sharing the same mental model of what it means to >process the *contents* of a root map n times. > >If my root map is: > ><map> > <title>My Publication</title> > <ditavalref href="ditaval1.ditaval"/> > <ditavalref href="ditaval2.ditaval"/> > ... ></map> > >How many titles are there? I think there are 2, which is clearly not >sensible in the context of the map model (maps have at most 1 title). > >I agree that implying multiple publications is problematic--I'm not wedded >to that interpretation, it just seems like the only consistent one. > >We could instead say that direct-child ditavals within a map simply >establish a relationship to those ditaval files with no processing >implications at all--a convenience by which authors can hard-code the >ditavals they want the publication to be processable with. Editors or >processing managers can use that information to provide a list of ditavals >to select from at processing time. Or not. Or they can choose to treat it >as a signal to produce a separate deliverable for each ditaval: there >would be no reason to prohibit that and some users might want it (but I >agree that not all users would want that, maybe even most users would not >want that). > >But it is definitely the case that: > ><map> > <mapref href="realmap.ditamap"/> ></map> > >Where realmap.ditamap is the map shown above, has different rendering >implications than just processing realmap. In particular, the title of >realmap in the second case is *not rendered*, by the rules for the >handling of submap titles, and the metadata in the submap does not define >the metadata for the publication as a whole (the implications of submap >metadata are pretty fuzzy in the current spec, but there's nothing that >suggests submap metadata would contribute to the metadata of the >publication as a whole, only to the metadata of the things within the >scope of that submap). > >That is, this map is a root map with no title. And that's definitely not >what we would intend the result to be. > >So I think the options are: > >1. The DITAVALs imply multiple deliverables (problematic > >2. The DITAVALs are informative and have no required processing >implications > >3. The effective result is a map where the topicrefs and reltables, but >not title or metadata, are pushed to a submap, with the ditavalrefs within >the submap, e.g.: > >This: > ><map> > <title>My Publication</title> > <ditavalref href="ditaval1.ditaval"/> > <ditavalref href="ditaval2.ditaval"/> ><topicref href="topic1.dita"/> ><topicref href="topic2.dita"/> ><reltable> > ... ></reltable> ></map> > >Becomes two maps: > >Root map: > ><map> ><title>My Publication</title> ><mapref href="submap.ditamap"> ><ditavalref href="ditaval1.ditaval"/> ><ditavalref href="ditaval2.ditaval"/> ></mapref> ></map> > > >Submap: > ><map> ><topicref href="topic1.dita"/> ><topicref href="topic2.dita"/> ><reltable> > ... ></reltable> ></map> > > > >This option avoids issues of duplication of the root map title and >metadata while preserving the implications for the topicrefs and >reltables. > >Cheers, > >E. > >————— >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: > >>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43: >> >>> From: Eliot Kimber <ekimber@contrext.com> >>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC >>><dita@lists.oasis-open.org> >>> 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" <robander@us.ibm.com> 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="me.ditaval"/> >>> > <ditavalref href="you.ditaval"/> >>> > <topicref href="branch1.dita">....</topicref> >>> > <topicref href="branch2.dita">....</topicref> >>> > <topicref href="branch3.dita">....</topicref> >>> > <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="this-is-parent.dita"> ... 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="this-is-parent.dita"> ... first ditavalref, then topic >>> >children </topicref> >>> ><topicref href="this-is-parent.dita"> ... 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="sample-from-above.ditamap"> >>> > <ditavalref href="me.ditaval"/> >>> > <ditavalref href="you.ditaval"/> >>> > </mapref> >>> ></map> >>> > >>> >Robert D Anderson >>> >IBM Authoring Tools Development >>> >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) >>> >>> > > > >--------------------------------------------------------------------- >To unsubscribe from this mail list, you must leave the OASIS TC that >generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php > >

I forgot to finish my thought: I would read the references to the peer maps with different ditavals as establishing an expectation that two renderings of that publication will be produced, each reflecting a different ditaval. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/26/15, 3:26 PM, "Eliot Kimber" <ekimber@contrext.com> wrote: >But we haven't (as far as I know), established what it means to apply a >ditavalref to a peer map--maybe we should? And maybe that's the solution >to our conundrum. I would certainly read this map as implying

A lot of the trouble we've had in this discussion / in this thread comes from your first point: > The problem I'm having is that there's no markup to which a root map with > multiple ditavalrefs can be transformed that both reflects the > *duplication* of the children of the <map> element and is valid DITA. Why is that a problem? That is - there is no mandate (and cannot be a mandate) that we be able to express all new DITA 1.3 elements or functions using DITA 1.2 markup. With the examples we've considered before this came up, it was straightforward to create equivalent markup. There was some intent behind that - it makes things easier to understand - but it's also something of a happy accident. There is a common problem people have in DITA 1.2; it results in either duplicate maps or lots of duplicate content; this new feature provides a way to condense the markup. However, this does not mean that every edge case must also be expressible with DITA 1.2 markup. For a map with no filter conditions in the title or <metadata>, none of this discussion really matters. It's easier to provide a DITA 1.2 equivalent, and I think applications will be fine handling it, without any change to the current spec / current language. I don't think anybody would find it reasonable to duplicate the title, to end up with a required title of "My PublicationMy Publication", and the spec will never suggest that. So we're only considering a situation that for some might be an edge case. Specifically - here is a simple but very common real-world map, that uses simple, DITA 1.1 markup. (In DITA 1.0, the title was still an attribute.) <map> <title>Using MyProduct on <ph platform="win">Windows</ph><ph platform="linux">Linux</ph></title> ...topicrefs and reltables... </map> With DITA 1.1 and 1.2, the only realistic way to publish that map is with a set of external conditions - otherwise, the title is "Using MyProduct on WindowsLinux". Now assume the map is updated for DITA 1.3 with a single ditavalref: <map> <title>Using MyProduct on <ph platform="win">Windows</ph><ph platform="linux">Linux</ph></title> <ditavalref href= > ...topicrefs and reltables... </map> I think the logical intent, and the logical interpretation, is that the title is filtered with everything else, giving a title of "Using MyProduct on Windows". If the second ditavalref is added, then we end up with: <map> <title>Using MyProduct on <ph platform="win">Windows</ph><ph platform="linux">Linux</ph></title> <ditavalref href= > <ditavalref href= > ...topicrefs and reltables... </map> This is the trickiest scenario, but I think it's still reasonable to expect that the title is filtered. How that is managed, and what ends up in the output, is best left up to the implementation. I can see 3 easily defensible results in a PDF, and there are likely more: 1. Produce two PDFs - one with title "Using MyProduct on Windows", and the other with "Using MyProduct on Linux". 2. Produce one PDF, and warn the author "I'm picking the first of two different titles, you should probably double check". 3. Produce a PDF with each alternate title appearing as a top-level bookmark in the TOC, like two concatenated publications. Maybe both titles appear on the cover page. So again, my argument comes down to consistency. I don't like that in a topic branch, or in a topichead, or in any other location, filtering applies to a title and metadata -- but in this one location it does not. We should not make exceptions here just because we cannot express the meaning using an older version of DITA. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Eliot Kimber <ekimber@contrext.com> wrote on 01/26/2015 15:26:39: > From: Eliot Kimber <ekimber@contrext.com> > To: Robert D Anderson/Rochester/IBM@IBMUS > Cc: DITA TC <dita@lists.oasis-open.org> > Date: 01/26/2015 15:26 > Subject: Re: [dita] Branch filtering: ditavalref as child of a map > > The problem I'm having is that there's no markup to which a root map with > multiple ditavalrefs can be transformed that both reflects the > *duplication* of the children of the <map> element and is valid DITA. And > in any case, replicating the title and metadata wouldn't make sense in the > context of a single deliverable where the root map defines the root > deliverable title and metadata. > > [And while Jarno is correct that the DITA spec doesn't require an exact > one-to-one correspondence between root maps and deliverables, it does > definitely establish that the normal case is that a root map represents a > deliverable and, in particular, that the root map's title and metadata are > the title and metadata of that deliverable. But there's also a probably > unavoidable fuzziness in the DITA spec because a "publication" is an > abstraction distinct from the way that publication might be organized > physically into deliverable artifacts: volumes, HTML pages, etc. The > problem here is that "a publication" is whatever the person producing it > says it is: a single book, a multi-volume set, a whole Web site, part of a > Web site. The only thing we know is that we have one root input map.] > > That is, I can't take this: > > <map> >  <title>My Publication</title> >  <ditavalref href= > >  <ditavalref href= > > </map> > > and produce any equivalent 1.2 markup in which the title element is > duplicated and to which the conditions are locally applied (because we > have no non-topicref equivalent of ditavalref). > > I could produce this DITA 1.3 map: > > <map> >  <mapref scope="peer" href= > >    <ditavalref href= > >  </mapref> >  <mapref scope="peer" href= > >    <ditavalref href= > >  </mapref> > </map> > > But we haven't (as far as I know), established what it means to apply a > ditavalref to a peer map--maybe we should? And maybe that's the solution > to our conundrum. I would certainly read this map as implying > > > So far the branch filtering processing can be defined *entirely* in terms > of transforming the original map into a new set of maps where all the > implied branches are made explicit and all the conditions are expanded > into a global set of condition values. > > That is, except for the root map, there is a deterministic process by > which I can generate a DITA 1.2 map set that exactly implements the intent > of the ditavalref elements. > > However, if ditavalref also applies to the title and metadata of the root > map, there is no simple transformation that will result in valid 1.2 > markup. We could say that the *content* of the title element is > replicated, with different conditions applied, but for the metadata it's a > lot more complicated, because some metadata elements are repeatable and > some or not (meaning you'd have to replicate their *contents* as for > title). > > For example, using the My Publication map shown above, what would the > result title be after processing? I think it has to be "My PublicationMy > Publication". That's clearly not the right answer. > > So it's not clear to me that it would even be useful to have the title and > metadata processed n times because there's only one publication (using our > normal root map == deliverable) model. > > The only way it could make sense is if each root ditavalref results in a > separate deliverable, which gets us back to my original proposal (and > Robert's objection to it). > > Or said another way: if root-level ditavalrefs do not imply one complete > deliverable per ditavalref, then I think it must be the case that only the > topicrefs and reltables are replicated because it simply would not make > sense to replicate the root title and metadata. > > Cheers, > > E. > > ————— > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 1/26/15, 1:54 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: > > >Maybe it's not so much that we differ on the mental model, it's that we > >differ on whether <ditavalref> should apply to the title and metadata. I > >feel quite strongly that it should. I think doing otherwise is > >inconsistent. > > > >In *any other context*, <ditavalref> applies to the parent and its > >descendants - including titles and metadata. For simplicity I'll only use > >one filter set: > ><topicref href= locktitle="yes"> > >  <topicmeta> > >    <navtitle>Title with conditional <ph>phrases</ph></navtitle> > >    ...other metadata that could be conditional... > >  </topicmeta> > >  <ditavalref href= > > >  ...other topics... > ></topicref> > > > >I don't understand why we would introduce inconsistency in this root map: > ><map> > >  <title>Title with conditional <ph>phrases</ph></title> > >  <topicmeta>...metadata that could be conditional</topicmeta> > >  <ditavalref href= > > >  ...topics... > ></map> > >   > >In a mapref, the filters apply to everything (even if the title is > >ignored by most processors for most purposes). A ditavalref in a submap > >is equivalent to the mapref case. Why would it not apply to the title > >here? > > > >Perhaps this is an edge case, but I know for sure that conditional > >phrases / keywords exist in map titles today. In DITA 1.2, the ditavalref > >doesn't enter into it, so the processing is straightforward. > > > >Part of me wonders if we can answer the deeper questions until we answer > >that one -- does ditavalref, at a map level, result in filtering of the > >title/metadata? And is that answer the same for root maps vs submaps? I > >think if we have one answer for root maps and a different answer for > >submaps, we're adding exceptions that will only serve to complicate > >things. > > > >Robert D Anderson > >IBM Authoring Tools Development > >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > > > >Eliot Kimber ---01/26/2015 13:26:05---I'm not sure we're sharing the same > >mental model of what it means to process the *contents* of a roo > > > >From:   Eliot Kimber <ekimber@contrext.com> > >To:   DITA TC <dita@lists.oasis-open.org> > >Date:   01/26/2015 13:26 > >Subject:   Re: [dita] Branch filtering: ditavalref as child of a map > >Sent by:   <dita@lists.oasis-open.org> > > > >________________________________________ > > > > > > > >I'm not sure we're sharing the same mental model of what it means to > >process the *contents* of a root map n times. > > > >If my root map is: > > > ><map> > > <title>My Publication</title> > > <ditavalref href= > > > <ditavalref href= > > > ... > ></map> > > > >How many titles are there? I think there are 2, which is clearly not > >sensible in the context of the map model (maps have at most 1 title). > > > >I agree that implying multiple publications is problematic--I'm not wedded > >to that interpretation, it just seems like the only consistent one. > > > >We could instead say that direct-child ditavals within a map simply > >establish a relationship to those ditaval files with no processing > >implications at all--a convenience by which authors can hard-code the > >ditavals they want the publication to be processable with. Editors or > >processing managers can use that information to provide a list of ditavals > >to select from at processing time. Or not. Or they can choose to treat it > >as a signal to produce a separate deliverable for each ditaval: there > >would be no reason to prohibit that and some users might want it (but I > >agree that not all users would want that, maybe even most users would not > >want that). > > > >But it is definitely the case that: > > > ><map> > > <mapref href= > > ></map> > > > >Where realmap.ditamap is the map shown above, has different rendering > >implications than just processing realmap. In particular, the title of > >realmap in the second case is *not rendered*, by the rules for the > >handling of submap titles, and the metadata in the submap does not define > >the metadata for the publication as a whole (the implications of submap > >metadata are pretty fuzzy in the current spec, but there's nothing that > >suggests submap metadata would contribute to the metadata of the > >publication as a whole, only to the metadata of the things within the > >scope of that submap). > > > >That is, this map is a root map with no title. And that's definitely not > >what we would intend the result to be. > > > >So I think the options are: > > > >1. The DITAVALs imply multiple deliverables (problematic > > > >2. The DITAVALs are informative and have no required processing > >implications > > > >3. The effective result is a map where the topicrefs and reltables, but > >not title or metadata, are pushed to a submap, with the ditavalrefs within > >the submap, e.g.: > > > >This: > > > ><map> > > <title>My Publication</title> > > <ditavalref href= > > > <ditavalref href= > > ><topicref href= > > ><topicref href= > > ><reltable> > > ... > ></reltable> > ></map> > > > >Becomes two maps: > > > >Root map: > > > ><map> > ><title>My Publication</title> > ><mapref href= > > ><ditavalref href= > > ><ditavalref href= > > ></mapref> > ></map> > > > > > >Submap: > > > ><map> > ><topicref href= > > ><topicref href= > > ><reltable> > > ... > ></reltable> > ></map> > > > > > > > >This option avoids issues of duplication of the root map title and > >metadata while preserving the implications for the topicrefs and > >reltables. > > > >Cheers, > > > >E. > > > >————— > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: > > > >>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43: > >> > >>> From: Eliot Kimber <ekimber@contrext.com> > >>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC > >>><dita@lists.oasis-open.org> > >>> 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" <robander@us.ibm.com> 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/ ) > >>> > >>> > > > > > > > >--------------------------------------------------------------------- > >To unsubscribe from this mail list, you must leave the OASIS TC that > >generates this mail.  Follow this link to all your TCs in OASIS at: > > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php > > > > > >

I think I may be seeing the rendering model you have in mind. If I understand your examples below, the implication of two root ditavalrefs is that I either have: A. Two publications, each reflecting one of the ditavalrefs. Whether this is rendered as a single PDF file or multiple is immaterial: the processor is processing the root map twice to produce two essentially independent publications. or B. A single publication with two titles and two sets of metadata, reflecting the effects of the two ditavalrefs. The rest of the publication will be rendered just as it would be if the topicrefs and reltables had been pushed to a submap and the ditavalrefs were in the mapref. Processors are free to implement either or both of these options. (Should processors have the option of not supporting this case?) I think that is sensible: I can see how it might make sense to have a title page that looks like: ------------------------- Installing Foo on Windows PubID: 1344 Installing Foo on OS X PubID: 1345 ------------------------- If that's what you really wanted. Processors should be allowed, but not required, to collapse identical duplicates in the case where the metadata or title is not conditional. That is, we shouldn't mandate non-sensical behavior in the case where a processor could potentially do the obvious right thing (or at least do what the author has requested--some authors might want the title and metadata repeated even when it's not conditional, depending on their conventions for these sort of multi-condition publications). Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/26/15, 4:04 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >A lot of the trouble we've had in this discussion / in this thread comes >from your first point: > >> The problem I'm having is that there's no markup to which a root map >>with >> multiple ditavalrefs can be transformed that both reflects the >> *duplication* of the children of the <map> element and is valid DITA. > >Why is that a problem? > >That is - there is no mandate (and cannot be a mandate) that we be able >to express all new DITA 1.3 elements or functions using DITA 1.2 markup. > >With the examples we've considered before this came up, it was >straightforward to create equivalent markup. There was some intent behind >that - it makes things easier to understand - but it's also something of >a happy accident. There is a common problem people have in DITA 1.2; it >results in either duplicate maps or lots of duplicate content; this new >feature provides a way to condense the markup. However, this does not >mean that every edge case must also be expressible with DITA 1.2 markup. > >For a map with no filter conditions in the title or <metadata>, none of >this discussion really matters. It's easier to provide a DITA 1.2 >equivalent, and I think applications will be fine handling it, without >any change to the current spec / current language. I don't think anybody >would find it reasonable to duplicate the title, to end up with a >required title of "My PublicationMy Publication", and the spec will never >suggest that. > >So we're only considering a situation that for some might be an edge >case. Specifically - here is a simple but very common real-world map, >that uses simple, DITA 1.1 markup. (In DITA 1.0, the title was still an >attribute.) ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > ...topicrefs and reltables... ></map> > >With DITA 1.1 and 1.2, the only realistic way to publish that map is with >a set of external conditions - otherwise, the title is "Using MyProduct >on WindowsLinux". > >Now assume the map is updated for DITA 1.3 with a single ditavalref: ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > <ditavalref href="windows.ditaval"/> > ...topicrefs and reltables... ></map> > >I think the logical intent, and the logical interpretation, is that the >title is filtered with everything else, giving a title of "Using >MyProduct on Windows". > >If the second ditavalref is added, then we end up with: ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > <ditavalref href="windows.ditaval"/> > <ditavalref href="linux.ditaval"/> > ...topicrefs and reltables... ></map> > >This is the trickiest scenario, but I think it's still reasonable to >expect that the title is filtered. How that is managed, and what ends up >in the output, is best left up to the implementation. I can see 3 easily >defensible results in a PDF, and there are likely more: >1. Produce two PDFs - one with title "Using MyProduct on Windows", and >the other with "Using MyProduct on Linux". >2. Produce one PDF, and warn the author "I'm picking the first of two >different titles, you should probably double check". >3. Produce a PDF with each alternate title appearing as a top-level >bookmark in the TOC, like two concatenated publications. Maybe both >titles appear on the cover page. > >So again, my argument comes down to consistency. I don't like that in a >topic branch, or in a topichead, or in any other location, filtering >applies to a title and metadata -- but in this one location it does not. >We should not make exceptions here just because we cannot express the >meaning using an older version of DITA. > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > >Eliot Kimber <ekimber@contrext.com> wrote on 01/26/2015 15:26:39: > >> From: Eliot Kimber <ekimber@contrext.com> >> To: Robert D Anderson/Rochester/IBM@IBMUS >> Cc: DITA TC <dita@lists.oasis-open.org> >> Date: 01/26/2015 15:26 >> Subject: Re: [dita] Branch filtering: ditavalref as child of a map >> >> The problem I'm having is that there's no markup to which a root map >>with >> multiple ditavalrefs can be transformed that both reflects the >> *duplication* of the children of the <map> element and is valid DITA. >>And >> in any case, replicating the title and metadata wouldn't make sense in >>the >> context of a single deliverable where the root map defines the root >> deliverable title and metadata. >> >> [And while Jarno is correct that the DITA spec doesn't require an exact >> one-to-one correspondence between root maps and deliverables, it does >> definitely establish that the normal case is that a root map represents >>a >> deliverable and, in particular, that the root map's title and metadata >>are >> the title and metadata of that deliverable. But there's also a probably >> unavoidable fuzziness in the DITA spec because a "publication" is an >> abstraction distinct from the way that publication might be organized >> physically into deliverable artifacts: volumes, HTML pages, etc. The >> problem here is that "a publication" is whatever the person producing it >> says it is: a single book, a multi-volume set, a whole Web site, part >>of a >> Web site. The only thing we know is that we have one root input map.] >> >> That is, I can't take this: >> >> <map> >> <title>My Publication</title> >> <ditavalref href="ditaval1.ditaval"/> >> <ditavalref href="ditaval2.ditaval"/> >> </map> >> >> and produce any equivalent 1.2 markup in which the title element is >> duplicated and to which the conditions are locally applied (because we >> have no non-topicref equivalent of ditavalref). >> >> I could produce this DITA 1.3 map: >> >> <map> >> <mapref scope="peer" href="realmap.ditamap"> >> <ditavalref href="ditava1.ditaval"/> >> </mapref> >> <mapref scope="peer" href="realmap.ditamap"> >> <ditavalref href="ditava2.ditaval"/> >> </mapref> >> </map> >> >> But we haven't (as far as I know), established what it means to apply a >> ditavalref to a peer map--maybe we should? And maybe that's the solution >> to our conundrum. I would certainly read this map as implying >> >> >> So far the branch filtering processing can be defined *entirely* in >>terms >> of transforming the original map into a new set of maps where all the >> implied branches are made explicit and all the conditions are expanded >> into a global set of condition values. >> >> That is, except for the root map, there is a deterministic process by >> which I can generate a DITA 1.2 map set that exactly implements the >>intent >> of the ditavalref elements. >> >> However, if ditavalref also applies to the title and metadata of the >>root >> map, there is no simple transformation that will result in valid 1.2 >> markup. We could say that the *content* of the title element is >> replicated, with different conditions applied, but for the metadata >>it's a >> lot more complicated, because some metadata elements are repeatable and >> some or not (meaning you'd have to replicate their *contents* as for >> title). >> >> For example, using the My Publication map shown above, what would the >> result title be after processing? I think it has to be "My PublicationMy >> Publication". That's clearly not the right answer. >> >> So it's not clear to me that it would even be useful to have the title >>and >> metadata processed n times because there's only one publication (using >>our >> normal root map == deliverable) model. >> >> The only way it could make sense is if each root ditavalref results in a >> separate deliverable, which gets us back to my original proposal (and >> Robert's objection to it). >> >> Or said another way: if root-level ditavalrefs do not imply one complete >> deliverable per ditavalref, then I think it must be the case that only >>the >> topicrefs and reltables are replicated because it simply would not make >> sense to replicate the root title and metadata. >> >> Cheers, >> >> E. >> >> ————— >> Eliot Kimber, Owner >> Contrext, LLC >> http://contrext.com >> >> >> >> >> On 1/26/15, 1:54 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >> >> >Maybe it's not so much that we differ on the mental model, it's that we >> >differ on whether <ditavalref> should apply to the title and metadata. >>I >> >feel quite strongly that it should. I think doing otherwise is >> >inconsistent. >> > >> >In *any other context*, <ditavalref> applies to the parent and its >> >descendants - including titles and metadata. For simplicity I'll only >>use >> >one filter set: >> ><topicref href="parent.dita" locktitle="yes"> >> > <topicmeta> >> > <navtitle>Title with conditional <ph>phrases</ph></navtitle> >> > ...other metadata that could be conditional... >> > </topicmeta> >> > <ditavalref href="simple.ditaval"/> >> > ...other topics... >> ></topicref> >> > >> >I don't understand why we would introduce inconsistency in this root >>map: >> ><map> >> > <title>Title with conditional <ph>phrases</ph></title> >> > <topicmeta>...metadata that could be conditional</topicmeta> >> > <ditavalref href="simple.ditaval"/> >> > ...topics... >> ></map> >> > >> >In a mapref, the filters apply to everything (even if the title is >> >ignored by most processors for most purposes). A ditavalref in a submap >> >is equivalent to the mapref case. Why would it not apply to the title >> >here? >> > >> >Perhaps this is an edge case, but I know for sure that conditional >> >phrases / keywords exist in map titles today. In DITA 1.2, the >>ditavalref >> >doesn't enter into it, so the processing is straightforward. >> > >> >Part of me wonders if we can answer the deeper questions until we >>answer >> >that one -- does ditavalref, at a map level, result in filtering of the >> >title/metadata? And is that answer the same for root maps vs submaps? I >> >think if we have one answer for root maps and a different answer for >> >submaps, we're adding exceptions that will only serve to complicate >> >things. >> > >> >Robert D Anderson >> >IBM Authoring Tools Development >> >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) >> > >> >Eliot Kimber ---01/26/2015 13:26:05---I'm not sure we're sharing the >>same >> >mental model of what it means to process the *contents* of a roo >> > >> >From: Eliot Kimber <ekimber@contrext.com> >> >To: DITA TC <dita@lists.oasis-open.org> >> >Date: 01/26/2015 13:26 >> >Subject: Re: [dita] Branch filtering: ditavalref as child of a map >> >Sent by: <dita@lists.oasis-open.org> >> > >> >________________________________________ >> > >> > >> > >> >I'm not sure we're sharing the same mental model of what it means to >> >process the *contents* of a root map n times. >> > >> >If my root map is: >> > >> ><map> >> > <title>My Publication</title> >> > <ditavalref href="ditaval1.ditaval"/> >> > <ditavalref href="ditaval2.ditaval"/> >> > ... >> ></map> >> > >> >How many titles are there? I think there are 2, which is clearly not >> >sensible in the context of the map model (maps have at most 1 title). >> > >> >I agree that implying multiple publications is problematic--I'm not >>wedded >> >to that interpretation, it just seems like the only consistent one. >> > >> >We could instead say that direct-child ditavals within a map simply >> >establish a relationship to those ditaval files with no processing >> >implications at all--a convenience by which authors can hard-code the >> >ditavals they want the publication to be processable with. Editors or >> >processing managers can use that information to provide a list of >>ditavals >> >to select from at processing time. Or not. Or they can choose to treat >>it >> >as a signal to produce a separate deliverable for each ditaval: there >> >would be no reason to prohibit that and some users might want it (but I >> >agree that not all users would want that, maybe even most users would >>not >> >want that). >> > >> >But it is definitely the case that: >> > >> ><map> >> > <mapref href="realmap.ditamap"/> >> ></map> >> > >> >Where realmap.ditamap is the map shown above, has different rendering >> >implications than just processing realmap. In particular, the title of >> >realmap in the second case is *not rendered*, by the rules for the >> >handling of submap titles, and the metadata in the submap does not >>define >> >the metadata for the publication as a whole (the implications of submap >> >metadata are pretty fuzzy in the current spec, but there's nothing that >> >suggests submap metadata would contribute to the metadata of the >> >publication as a whole, only to the metadata of the things within the >> >scope of that submap). >> > >> >That is, this map is a root map with no title. And that's definitely >>not >> >what we would intend the result to be. >> > >> >So I think the options are: >> > >> >1. The DITAVALs imply multiple deliverables (problematic >> > >> >2. The DITAVALs are informative and have no required processing >> >implications >> > >> >3. The effective result is a map where the topicrefs and reltables, but >> >not title or metadata, are pushed to a submap, with the ditavalrefs >>within >> >the submap, e.g.: >> > >> >This: >> > >> ><map> >> > <title>My Publication</title> >> > <ditavalref href="ditaval1.ditaval"/> >> > <ditavalref href="ditaval2.ditaval"/> >> ><topicref href="topic1.dita"/> >> ><topicref href="topic2.dita"/> >> ><reltable> >> > ... >> ></reltable> >> ></map> >> > >> >Becomes two maps: >> > >> >Root map: >> > >> ><map> >> ><title>My Publication</title> >> ><mapref href="submap.ditamap"> >> ><ditavalref href="ditaval1.ditaval"/> >> ><ditavalref href="ditaval2.ditaval"/> >> ></mapref> >> ></map> >> > >> > >> >Submap: >> > >> ><map> >> ><topicref href="topic1.dita"/> >> ><topicref href="topic2.dita"/> >> ><reltable> >> > ... >> ></reltable> >> ></map> >> > >> > >> > >> >This option avoids issues of duplication of the root map title and >> >metadata while preserving the implications for the topicrefs and >> >reltables. >> > >> >Cheers, >> > >> >E. >> > >> >————— >> >Eliot Kimber, Owner >> >Contrext, LLC >> > http://contrext.com >> > >> > >> > >> > >> >On 1/26/15, 12:28 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >> > >> >>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 <ekimber@contrext.com> wrote on 01/24/2015 08:16:43: >> >> >> >>> From: Eliot Kimber <ekimber@contrext.com> >> >>> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC >> >>><dita@lists.oasis-open.org> >> >>> 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" <robander@us.ibm.com> >>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="me.ditaval"/> >> >>> > <ditavalref href="you.ditaval"/> >> >>> > <topicref href="branch1.dita">....</topicref> >> >>> > <topicref href="branch2.dita">....</topicref> >> >>> > <topicref href="branch3.dita">....</topicref> >> >>> > <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="this-is-parent.dita"> ... 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="this-is-parent.dita"> ... first ditavalref, then >>topic >> >>> >children </topicref> >> >>> ><topicref href="this-is-parent.dita"> ... 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="sample-from-above.ditamap"> >> >>> > <ditavalref href="me.ditaval"/> >> >>> > <ditavalref href="you.ditaval"/> >> >>> > </mapref> >> >>> ></map> >> >>> > >> >>> >Robert D Anderson >> >>> >IBM Authoring Tools Development >> >>> >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) >> >>> >> >>> >> > >> > >> > >> >--------------------------------------------------------------------- >> >To unsubscribe from this mail list, you must leave the OASIS TC that >> >generates this mail. Follow this link to all your TCs in OASIS at: >> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >> > >> > >> >>