[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Design discussion for associating DITAVAL rules with amap
I understood there to be two different requirements: 1. Bind a map to a *global* DITAVAL file. This is what I understood Seth Park to be asking for. 2. Bind a subtree of the map to a DITAVAL file. In the second case I agree that if the conditions in effect for the container of the DITAVAL ref apply to the ref, then there's no problem--the referenced DITAVAL can't affect it's own intepretation. But in the first case, there could be an issue where you have, for example, two global DITAVALs referenced and your intent is that the first affects the inclusion of the second. That's probably simply not allowable, but I wanted to make sure we've thought about it. With regard to where the element occurs with in the container, we have not, to date, made any specific accommodation to processors that can't do lookahead. If you're using a SAX processor to do the filtering, you're simply going to have to accumulate the children of the parent before you can apply any filtering-aware processing to them. That shouldn't be a problem for any XML processor. Granted, good practice would argue for putting such references first, but it can't be a requirement. And you could also define a constraint module that enforced the requirement if it's important to you. Cheers, E. On 9/1/11 4:12 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote: > This is basically the same as our approach, which is reassuring. Thanks. > > One question it raises, though, is whether it's more appropriate to use a > topicref specialization or a metadata domain. I think I prefer the metadata > approach. To simplify processing, it would be nice to be able to assume that > ditaval rules for a given scope appear early in that scope, and metadata > necessarily comes before other child topicrefs. For example, this would > require two map passes: > > <topicgroup> > <topicref href="A.dita"/> > <topicref href="B.dita"/> > <ditavalref href="expert.ditaval"/> > </topicgroup> > > While this only takes one: > > <topicgroup> > <topicmeta> > <ditavalref href="expert.ditaval"/> > </topicmeta> > <topicref href="A.dita"/> > <topicref href="B.dita"/> > </topicgroup> > > Also, I'm pretty touchy about overburdening topicref. I devoutly wish keydef > was its own thing, for instance. I'm convinced that a lot of the complexity > complaints about DITA stem from the fact that predicting how a given topicref > will (or, in the case of we poor application developers, should) affect output > can take a lot of work, especially for newcomers. But I think that ship has > sailed, and as such I don't feel that strongly one way or the other in this > case. > > As for conditional processing issues Eliot raises, I'm not sure I understand > the problem. Since a ditaval reference only applies to its container, you > could pick up and drop rules during normal map processing. You'd have to apply > conditional processing before picking up new DITAVAL rules, but that shouldn't > be too difficult. So say you had this: > > <map> > <topicmeta> > <ditavalref href="expertFlagging.ditaval" product="NewFancyEngine"/> > </topicmeta> > ... > </map> > > If you specified a DITAVAL file at the command-line, those would be the > global, "baseline" rules. If those rules excluded product="NewFancyEngine", > then the step that picked up new DITAVAL rules as it went along would never > see the ditavalre. Maybe I'm not understanding the concern, but I think it's > manageable. > > Chris > > -----Original Message----- > From: Robert D Anderson [mailto:robander@us.ibm.com] > Sent: Thursday, September 01, 2011 4:05 PM > To: Nitchie, Chris > Cc: dita > Subject: Re: [dita] Design discussion for associating DITAVAL rules with a map > > The approach we've been experimenting with over the last month is sort of a > combination between Chris's options (1) and (4). > > In particular, we've got a domain that defines a topicref specialization > called <ditavalref>. It defaults the attributes format="ditaval" and > processing-role="resource-only". > > The element itself is specified as a child of the branch that it's meant to > filter. The logic here is very similar to the subjectdef element we've got > in DITA 1.2. For example, when you assign a subject, you do something like > this: > <topicref href="thing.dita"> > <subjectdef keyref="thing-subject"/> > > So, similarly, when the ditavalref is specified as a child of <topicref>, > it's done like this: > <topicref href="productA.dita"> > <ditavalref href="filter-for-A.ditaval"/> > ...other topics... > > This allows for filter conditions that apply to that entire branch without > impacting other branches. It gets much more complicated when you have two > ditavalref elements as children; we have very strong use cases around this, > which actually helped push us towards this design, but I'm wary of going > into too much detail in this email and distracting from the core idea of > the <ditavalref> element on a branch. > > It's worth noting that when using this element, it is distinct from a > DITAVAL file that's associated with the whole map as you would do so today > (in DITA-OT terms, that would be one passed in from the command line). So, > you can still apply a global set of filters, but then use this new > capability for finer grained control within a document. > > Provided that general approach makes sense, I'll go in to more detail about > the more complicated aspects, such as how we're trying to handle multiple > ditavalref elements on a single branch. > > Robert D Anderson > IBM Authoring Tools Development > Chief Architect, DITA Open Toolkit > > > > From: "Nitchie, Chris" <cnitchie@ptc.com> > To: "dita" <dita@lists.oasis-open.org> > Date: 09/01/2011 14:56 > Subject: [dita] Design discussion for associating DITAVAL rules with a > map > > > > There are a number of proposals on the DITA 1.3 list - 13036 and 13059 in > particular - related to associating DITAVAL rules with all or part of a > map. At PTC, we're in the progress of designing out features for our next > release, which will ship early next year (i.e. well before DITA 1.3 is > baked). One of our requirements, though, is this capability - associating > conditional processing rules with a map. With that in mind, we've been > doing some thinking around potential designs. We'll almost certainly need > to implement something well before DITA 1.3 is finalized, and we really > don't want to do something that is completely out of line (or worse, > contradictory to) what finally winds up in the standard. So I wanted to run > our current thinking by the group and get some feedback. > > There are a couple of ways we could do this via specialization/custom > processing without having to modify DITA 1.2. > > 1. As a rule, <topicref format="ditaval" href="..."/> specifies > the rules to apply to the whole map. TBD what happens when there are more > than one. > 2. A new @base attribute specialization that would be ignored on > everything but the root map element, specifying the DITAVAL file to use for > the whole map, e.g. <map profileref="expert.ditaval"> > 3. Similar to #2, but use @props instead of @base, and allow it > to be applied on any map or topicref element, thus allowing the rules to be > scoped, e.g. <topicgroup profileref="expert.ditaval">. > 4. Similar to #3, but implemented as a metadata domain > specialization, e.g. <topicgroup><topicmeta><profileref > href="expert.ditaval">. > > My current thinking is that Option 4 provides the greatest flexibility > while breaking the fewest rules. Option 1 isn't flexible enough and could > produce confusing results if a sub-map unexpectedly references a ditaval > file. Option 2 is easy to implement and use, but isn't very flexible. > Option 3 is simpler for authors to see and understand, but it's a violation > of the way @props specializations are supposed to work (it should be a > space-delimited set of values to use in conditional processing). So I think > a new metadata element is what's called for. > > So to associate a DITAVAL file with a whole map: > > <map> > <title>Expert Book</title> > <topicmeta> > <profileref href="expert.ditaval"/> > </topicmeta> > ... > </map> > > To repeat the same topic with different profiles: > > <topicref href="chapter1.dita"> > <topicmeta> > <profileref href="student.ditaval"/> > </topicmeta> > </topicref> > <topicref href="chapter1.dita"> > <topicmeta> > <profileref href="teacher.ditaval"/> > </topicmeta> > </topicref> > > You could also nest profiles: > > <topicref href="expertsGuide.dita"> > <topicmeta> > <profileref href="expert.ditaval"/> > </topicmeta> > <topicref href="changingTheOil.dita"> > <topicmeta> > <profileref href="productX.ditaval"/> > </topicmeta> > </topicref> > </topicref> > > In this case, the effective rules for "changingTheOil.dita" would be the > combination of the rules in "expert.ditaval" and "productX.ditaval". > > There's an open question of what to do in this case if the nested DITAVALS > specify conflicting rules. For example, if "expert.ditaval" contained this > for some reason: > > <prop action="include" att="product" val="ProductY"/> > > And productX.ditaval contained this: > > <prop action="exclude" att="product" val="ProductY"/> > > What would be the effective action for product="ProductY"? There are a > couple of potential solutions - outermost wins, innermost wins, explicit > "include" trumps, or it might interact with some of the other new DITAVAL > proposals for cascading behavior in 1.3 - but we haven't settled on an > answer yet. > > I think in the majority of cases, you'll just have one DITAVAL file > associated with the whole map, but I think there are use cases we'll want > to support with different profiling rules at different locations in the > same map. Does this proposal, rough though it is, sound like reasonable > start? > > At this point, we're still in the design phase, and no implementation has > happened yet, so we're not married to one approach over another. I'd just > like to know whether we should drastically rethink the above in light of > the intentions of those folks designing other DITAVAL changes for 1.3. > > Chris > > > Chris Nitchie > Senior Software Engineer > > T 734.352.2879 F 734.997.0201 > E cnitchie@ptc.com > > PTC.com > > > > --------------------------------------------------------------------- > 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 > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]