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

["Robert D Anderson" <robander@us.ibm.com>]

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