dita — archive

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