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

[Eliot Kimber <ekimber@contrext.com>]

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