OASIS Darwin Information Typing Architecture (DITA) TC

Before I really dig in to writing up the stage 2 proposal, I want to get some initial feedback on the direction I'm heading (based on very limited prototypes we have in IBM right now). The idea is primarily to apply filtering to a subset of your content, rather than to the whole information set. At the same time, it allows one set of content to be created / published once for multiple audiences. The current plan is to do this by specifying a ditaval file from within your map, so that it only applies to that section of the map. For cases today where a ditaval file is specified for an entire set of information, those conditions would continue to apply to all content, taking precedence over any additional rules based on the design below. For the simple case, one subset of your map could be built as follows: <topicref href="startBranch.dita"> <ditavalref href="novice.ditaval"/> ...other topicrefs... </topicref> The ditavalref (with a default of format="ditaval") is treated as metadata for the parent, much like <subjectref> statements from our classification domain. The meaning here is that startBranch.dita and its children should be processed using the ditaval "novice.ditaval". This is really the simple case - a branch of content uses a specific set of DITAVAL conditions that do not impact the rest of the map. The more complex case allows a single branch to be published for multiple audiences, without having to redefine the branch. For example: <topicref href="install-instructions.dita"> <ditavalref href="mac.ditaval"/> <ditavalref href="linux.ditaval"/> <ditavalref href="win.ditaval"/> ...other topicrefs... </topicref> In this case there is common set of install instructions that differs for mac, linux, and windows. The goal is to be able to define this map context once, while allowing it to be published for each different audience / platform / etc. So in this case, a rendered version of the content would have three instances of the content in install-instructions.dita, each with a different set of filters applied. So that is the idea at a very high level. As mentioned, we have a limited prototype in IBM today. It's limited both because we did not want to go too far ahead of the standard, and because it allowed us to avoid some of the trickier questions until OASIS had a chance to weigh in. Some of the limits / open questions from our prototype: If generating 3 copies of each topic in a branch, how are they named? We have a solution we are using, but I'm not sure if that belongs in the standard or if it should be implementation dependent. What happens if you reference a ditaval within a branch that already references a ditaval? This got very tricky, especially for naming, so our prototype just says "no" right now. At one point we discussed using <ditavalref> as a parent of the branch, but that made hierachies / linking tricky, and also prohibited the more complex use case above of using one branch with multiple profiles. Our implementation has always applied filters at the start of the process, for reasons discussed at length on this and other lists. That is still the case for ditaval files specified at a global level, but for the internal ditaval references, we are processing them much later in the chain. When making multiple copies, each copy must exist (as a file, in memory, whatever) before individual filters are applied; apart from that, I'm not 100% sure what effect processing order has. I know that we process it after most other steps run, which significantly reduces processing time versus copying all files at the start and then doing full processing on each. Thanks for the read ... thoughts from the TC? Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://dita-ot.sourceforge.net/ )

For topic naming, I think the implication is that there needs to be an implicit @copy-to option so that authors can specify if they want the effective source topic names to be constructed in a way that reflects the specific DITAVAL or condition set. I would expect to be able to specify some sort of label in either the DITAVAL file or on the ditaval reference that could serve this purpose. Maybe something like @copyto-suffix or something? My first instinct is that <ditavalref> should be a specialization of <data> that goes in <topicmeta> so that it's clear that it's a property of the containing topicref and also that isn't itself a topicref. This would be a case where the specializer imposes a specific meaning on @href/@keyref from a specialization of <data>. I will have to think more carefully about the implication of multiple DITAVAL specs used from the hierarchy but my instinct would be that higher-level DITAVALs override lower-level DITAVALs, so the behavior is consistent with keys. But there are probably some tricky edge cases resulting from the interaction of include and exclude. Cheers, E. On 5/15/13 1:13 PM, "Robert D Anderson" <robander@us.ibm.com> wrote: > > > Before I really dig in to writing up the stage 2 proposal, I want to get > some initial feedback on the direction I'm heading (based on very limited > prototypes we have in IBM right now). > > The idea is primarily to apply filtering to a subset of your content, > rather than to the whole information set. At the same time, it allows one > set of content to be created / published once for multiple audiences. The > current plan is to do this by specifying a ditaval file from within your > map, so that it only applies to that section of the map. For cases today > where a ditaval file is specified for an entire set of information, those > conditions would continue to apply to all content, taking precedence over > any additional rules based on the design below. > > For the simple case, one subset of your map could be built as follows: > <topicref href="startBranch.dita"> > <ditavalref href="novice.ditaval"/> > ...other topicrefs... > </topicref> > > The ditavalref (with a default of format="ditaval") is treated as metadata > for the parent, much like <subjectref> statements from our classification > domain. The meaning here is that startBranch.dita and its children should > be processed using the ditaval "novice.ditaval". This is really the simple > case - a branch of content uses a specific set of DITAVAL conditions that > do not impact the rest of the map. > > The more complex case allows a single branch to be published for multiple > audiences, without having to redefine the branch. For example: > <topicref href="install-instructions.dita"> > <ditavalref href="mac.ditaval"/> > <ditavalref href="linux.ditaval"/> > <ditavalref href="win.ditaval"/> > ...other topicrefs... > </topicref> > > In this case there is common set of install instructions that differs for > mac, linux, and windows. The goal is to be able to define this map context > once, while allowing it to be published for each different audience / > platform / etc. So in this case, a rendered version of the content would > have three instances of the content in install-instructions.dita, each with > a different set of filters applied. > > So that is the idea at a very high level. As mentioned, we have a limited > prototype in IBM today. It's limited both because we did not want to go too > far ahead of the standard, and because it allowed us to avoid some of the > trickier questions until OASIS had a chance to weigh in. Some of the > limits / open questions from our prototype: > > If generating 3 copies of each topic in a branch, how are they named? We > have a solution we are using, but I'm not sure if that belongs in the > standard or if it should be implementation dependent. > What happens if you reference a ditaval within a branch that already > references a ditaval? This got very tricky, especially for naming, so > our prototype just says "no" right now. > At one point we discussed using <ditavalref> as a parent of the branch, > but that made hierachies / linking tricky, and also prohibited the more > complex use case above of using one branch with multiple profiles. > Our implementation has always applied filters at the start of the > process, for reasons discussed at length on this and other lists. That > is still the case for ditaval files specified at a global level, but for > the internal ditaval references, we are processing them much later in > the chain. When making multiple copies, each copy must exist (as a file, > in memory, whatever) before individual filters are applied; apart from > that, I'm not 100% sure what effect processing order has. I know that we > process it after most other steps run, which significantly reduces > processing time versus copying all files at the start and then doing > full processing on each. > > Thanks for the read ... thoughts from the TC? > > Robert D Anderson > IBM Authoring Tools Development > Chief Architect, DITA Open Toolkit ( http://dita-ot.sourceforge.net/ ) > > > --------------------------------------------------------------------- > 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, RSI Content Solutions "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.rsicms.com www.rsuitecms.com Book: DITA For Practitioners, from XML Press, http://xmlpress.net/publications/dita/practitioners-1/

Robert, FWIW, Arbortext 6.0 M040 and later has this functionality using <data name="ditavalref" href="{ditaval file}"> from within topicmeta, so it could apply to the whole map or just a single branch. It doesn't support multiple renderings of a branch; if more than one DITAVAL file is present, they all apply; if there are conflicting actions for an attribute, the first rule wins; if there are multiple values for the same attribute with the same action, they are additive. It seemed pretty simple when I spec'd it out that way, but when I actually implemented it, it was a lot more complicated than I initially planned for (I wound up spending something like 3x the time I'd planned). Since you could have branches specifying DITAVALs within branches specifying DITAVALs, managing the 'effective' set of rules at any given level involved lots of stacks of contexts and resolution of conflicting rules (we went with 'outermost wins'). I do wonder if simply having multiple DITAVALs associated with a branch *should* result in multiple renderings of that branch instead of being cumulative. It seems like it would be reasonable to specify multiple DITAVAL files for different categorizations, e.g. <ditavalref href="ProductLine-123.ditaval"/> <!-- Selects the product line --> <ditavalref href="Technician.ditaval"/> <!-- Selects the audience --> I think it might be better to have semantic markup for specifying multiple renderings of a branch, something like <renderConfig> <ditavalref href="ditaval1.ditaval"/> </renderConfig> <renderConfig> <ditavalref href="ditaval2.ditaval"/> </renderConfig> And now that I write that down, it seems to me that you could put other things inside one of those rendering configurations, like key definitions (or links to key-defining maps), 'print' settings, etc. I'm not sure I'd want to burden this proposal with that kind of stuff, but it seems like it would be a reasonable extension. Anyway, just food for thought. Chris
Original Message----- From: Robert D Anderson [ mailto:robander@us.ibm.com ] Sent: Wednesday, May 15, 2013 2:13 PM To: dita Subject: [dita] Branch filtering (proposal 13059a) Before I really dig in to writing up the stage 2 proposal, I want to get some initial feedback on the direction I'm heading (based on very limited prototypes we have in IBM right now). The idea is primarily to apply filtering to a subset of your content, rather than to the whole information set. At the same time, it allows one set of content to be created / published once for multiple audiences. The current plan is to do this by specifying a ditaval file from within your map, so that it only applies to that section of the map. For cases today where a ditaval file is specified for an entire set of information, those conditions would continue to apply to all content, taking precedence over any additional rules based on the design below. For the simple case, one subset of your map could be built as follows: <topicref href="startBranch.dita"> <ditavalref href="novice.ditaval"/> ...other topicrefs... </topicref> The ditavalref (with a default of format="ditaval") is treated as metadata for the parent, much like <subjectref> statements from our classification domain. The meaning here is that startBranch.dita and its children should be processed using the ditaval "novice.ditaval". This is really the simple case - a branch of content uses a specific set of DITAVAL conditions that do not impact the rest of the map. The more complex case allows a single branch to be published for multiple audiences, without having to redefine the branch. For example: <topicref href="install-instructions.dita"> <ditavalref href="mac.ditaval"/> <ditavalref href="linux.ditaval"/> <ditavalref href="win.ditaval"/> ...other topicrefs... </topicref> In this case there is common set of install instructions that differs for mac, linux, and windows. The goal is to be able to define this map context once, while allowing it to be published for each different audience / platform / etc. So in this case, a rendered version of the content would have three instances of the content in install-instructions.dita, each with a different set of filters applied. So that is the idea at a very high level. As mentioned, we have a limited prototype in IBM today. It's limited both because we did not want to go too far ahead of the standard, and because it allowed us to avoid some of the trickier questions until OASIS had a chance to weigh in. Some of the limits / open questions from our prototype: If generating 3 copies of each topic in a branch, how are they named? We have a solution we are using, but I'm not sure if that belongs in the standard or if it should be implementation dependent. What happens if you reference a ditaval within a branch that already references a ditaval? This got very tricky, especially for naming, so our prototype just says "no" right now. At one point we discussed using <ditavalref> as a parent of the branch, but that made hierachies / linking tricky, and also prohibited the more complex use case above of using one branch with multiple profiles. Our implementation has always applied filters at the start of the process, for reasons discussed at length on this and other lists. That is still the case for ditaval files specified at a global level, but for the internal ditaval references, we are processing them much later in the chain. When making multiple copies, each copy must exist (as a file, in memory, whatever) before individual filters are applied; apart from that, I'm not 100% sure what effect processing order has. I know that we process it after most other steps run, which significantly reduces processing time versus copying all files at the start and then doing full processing on each. Thanks for the read ... thoughts from the TC? Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://dita-ot.sourceforge.net/ ) --------------------------------------------------------------------- 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