[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
I think I may be seeing the rendering model you have in mind. If I understand your examples below, the implication of two root ditavalrefs is that I either have: A. Two publications, each reflecting one of the ditavalrefs. Whether this is rendered as a single PDF file or multiple is immaterial: the processor is processing the root map twice to produce two essentially independent publications. or B. A single publication with two titles and two sets of metadata, reflecting the effects of the two ditavalrefs. The rest of the publication will be rendered just as it would be if the topicrefs and reltables had been pushed to a submap and the ditavalrefs were in the mapref. Processors are free to implement either or both of these options. (Should processors have the option of not supporting this case?) I think that is sensible: I can see how it might make sense to have a title page that looks like: ------------------------- Installing Foo on Windows PubID: 1344 Installing Foo on OS X PubID: 1345 ------------------------- If that's what you really wanted. Processors should be allowed, but not required, to collapse identical duplicates in the case where the metadata or title is not conditional. That is, we shouldn't mandate non-sensical behavior in the case where a processor could potentially do the obvious right thing (or at least do what the author has requested--some authors might want the title and metadata repeated even when it's not conditional, depending on their conventions for these sort of multi-condition publications). Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 1/26/15, 4:04 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: >A lot of the trouble we've had in this discussion / in this thread comes >from your first point: > >> 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. > >Why is that a problem? > >That is - there is no mandate (and cannot be a mandate) that we be able >to express all new DITA 1.3 elements or functions using DITA 1.2 markup. > >With the examples we've considered before this came up, it was >straightforward to create equivalent markup. There was some intent behind >that - it makes things easier to understand - but it's also something of >a happy accident. There is a common problem people have in DITA 1.2; it >results in either duplicate maps or lots of duplicate content; this new >feature provides a way to condense the markup. However, this does not >mean that every edge case must also be expressible with DITA 1.2 markup. > >For a map with no filter conditions in the title or <metadata>, none of >this discussion really matters. It's easier to provide a DITA 1.2 >equivalent, and I think applications will be fine handling it, without >any change to the current spec / current language. I don't think anybody >would find it reasonable to duplicate the title, to end up with a >required title of "My PublicationMy Publication", and the spec will never >suggest that. > >So we're only considering a situation that for some might be an edge >case. Specifically - here is a simple but very common real-world map, >that uses simple, DITA 1.1 markup. (In DITA 1.0, the title was still an >attribute.) ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > ...topicrefs and reltables... ></map> > >With DITA 1.1 and 1.2, the only realistic way to publish that map is with >a set of external conditions - otherwise, the title is "Using MyProduct >on WindowsLinux". > >Now assume the map is updated for DITA 1.3 with a single ditavalref: ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > <ditavalref href="windows.ditaval"/> > ...topicrefs and reltables... ></map> > >I think the logical intent, and the logical interpretation, is that the >title is filtered with everything else, giving a title of "Using >MyProduct on Windows". > >If the second ditavalref is added, then we end up with: ><map> > <title>Using MyProduct on > <ph platform="win">Windows</ph><ph >platform="linux">Linux</ph></title> > <ditavalref href="windows.ditaval"/> > <ditavalref href="linux.ditaval"/> > ...topicrefs and reltables... ></map> > >This is the trickiest scenario, but I think it's still reasonable to >expect that the title is filtered. How that is managed, and what ends up >in the output, is best left up to the implementation. I can see 3 easily >defensible results in a PDF, and there are likely more: >1. Produce two PDFs - one with title "Using MyProduct on Windows", and >the other with "Using MyProduct on Linux". >2. Produce one PDF, and warn the author "I'm picking the first of two >different titles, you should probably double check". >3. Produce a PDF with each alternate title appearing as a top-level >bookmark in the TOC, like two concatenated publications. Maybe both >titles appear on the cover page. > >So again, my argument comes down to consistency. I don't like that in a >topic branch, or in a topichead, or in any other location, filtering >applies to a title and metadata -- but in this one location it does not. >We should not make exceptions here just because we cannot express the >meaning using an older version of DITA. > >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/26/2015 15:26:39: > >> From: Eliot Kimber <ekimber@contrext.com> >> To: Robert D Anderson/Rochester/IBM@IBMUS >> Cc: DITA TC <dita@lists.oasis-open.org> >> Date: 01/26/2015 15:26 >> Subject: Re: [dita] Branch filtering: ditavalref as child of a map >> >> 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 >> > >> > >> >>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]