Re: [dita] Branch filtering: ditavalref as child of a map

[Chris Nitchie <chris.nitchie@oberontech.com>]

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
>