OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  [dita] Design discussion for associating DITAVAL rules with a map

    Posted 09-01-2011 18:51
    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


  • 2.  Re: [dita] Design discussion for associating DITAVAL rules with amap

    Posted 09-01-2011 19:30
    I started write that I preferred option (1) because that way the topicref declares the dependency in a generic way. However, as <data> can use @keyref rather than @href, option (4) allows you to get the benefits of both if you use a key for the DITAVAL file, e.g.: <map> <topicmeta> <profileref keyref="ditaval-expert"/> </topicmeta> <keydef keys="ditaval-expert" href="../ditavals/ditaval-expert.ditaval" format="ditaval" /> ... </map> I think option (3) is not acceptable, for the reasons you say: it's a misuse of @props. Option (2) would be OK but I would definitely prefer (1) or (4). Thinking about this just now, it seems like there's a bit of a potential bootstrapping issue, in that if a DITAVAL reference were itself conditional there'd be no way to apply the conditionality unless a separate DITAVAL file is specified at run time. Which means at least two phases of filtering, a first phase to determine if any DITAVAL references are applicable and then processing using the effects of those DITAVAL references. There's also a potential interaction with key resolution as well, since some references to DITAVAL files might involve keys and the key definitions might be directly or indirectly conditional. For example, I might have different DITAVAL flagging configurations that I want to be used or not used based on other conditions. The flagging configurations are probably largely invariant for a given publication, but the filtering conditions are not--I want to be able to specify at runtime a set of filtering conditions that will have the effect of selecting the correct flagging configuration. Even if you disallowed making DITAVAL references conditional, you couldn't disallow making the containers of the references or pointers to the containers of references conditional, so you have to address the problem. If the purpose of the reference is really just documentation, e.g., when you run this map, apply this DITAVAL file, then it's fine, because the consumption of the DITAVAL reference is out of band of the regular DITA processing. I don't object to the general idea of referencing DITAVAL files from maps, but I think it would require us to say more about how filtering processing should or must be implemented to account for the case of both run-time and map-referenced DITAVAL files. Cheers, Eliot On 9/1/11 1:50 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote: > 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 > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com


  • 3.  Re: [dita] Design discussion for associating DITAVAL rules with a map

    Posted 09-01-2011 20:05
    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


  • 4.  RE: [dita] Design discussion for associating DITAVAL rules with a map

    Posted 09-01-2011 21:13
    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


  • 5.  Re: [dita] Design discussion for associating DITAVAL rules with amap

    Posted 09-04-2011 14:05
    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 > >