OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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

Inactive hide details for Chris Nitchie ---01/26/2015 13:18:19---Anybody have any interest in simply saying that for the root mChris 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 




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]