Robert, et al, For reference, attached is the functional specification for the Arbortext implementation of branch filtering via referenced DITAVAL. Thanks to Dave Helfinstine and PTC for making this content available. Chris Title: Chapter 1. Associating DITAVAL Files with Maps Chapter 1. Associating DITAVAL Files with Maps Table of Contents Rules for Multiple References DITAVAL Association by Key Reference Filtering of DITAVAL References Examples Starting with this release, you will be able to associate one or more DITAVAL files with some or all of a map. This allows a great deal of flexibility. If a map should always be published with a given set of rules, you can associate those rules directly with the map without having to specify them every time the map is published. You can also specify different profiling settings for different sections in the same map. To associate a DITAVAL file with a map, reference it via a data element within topicmeta with a name attribute of ditavalref and an href attribute referencing the DITAVAL file. <data name= ditavalref href= /> When resolving references to DITAVAL files, the ditapath setting will be consulted. The portion of the map affected by a DITAVAL file referenced in this way is contained by the parent topicref of such a reference, including the topicref itself. More specifically, it applies to: The parent topicref of the DITAVAL reference. The topic or map, if any, referenced by that topicref. All markup, including topicmeta contents and topicref elements, occurring within the map branch encapsulated by the parent topicref, except for other DITAVAL references. Any topics or maps referenced via topicref within the branch encapsulated by the parent element of the DITAVAL reference, except where the topicref that references the file is excluded by the effective DITAVAL rules. So to affect an entire map, place the reference within topicmeta within the root-level map element. To have the rules apply only for part of the map, place the reference within the topicmeta of a topicref (or specialization thereof) containing the region of the map structure to which the rules should apply. Note This design was discussed at the DITA Technical Committee meeting on November 29, 2011 and met with provisional approval. The minutes for this meeting can be found at
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/44501/latest/minutes20111129.txt . One of the things that will likely be part of the DITA 1.3 proposal is the ability to duplicate a section of a map (or 'branch' in DITA terminology), once for each DITAVAL file associated with that branch. We will not be supporting this use-case in this release. We will treat the DITAVAL associations as additive, and apply all files to the specified region. We expect the markup for the branch duplication use-case to be different from what we're using. Rules for Multiple References DITAVAL associations are additive. If two DITAVAL files are referenced at the same level in the map, both sets of rules apply at that level. If the two files contain rules for the same attribute-value pair, the rules from the first file in document order take precedence. Similarly, if a parent scope and a child scope both reference DITAVAL files, the effective rule set for the inner scope will be the combination of the rules in the two files. Where there are rules for matching attribute-value pairs for both the parent and the child scope, the rules from the parent scope overrule those in the child scope. This allows top-level map authors to override the DITAVAL rules specified in child maps. Any DITAVAL specified via the composition UI for the whole map is considered to have global scope. Normal additivity rules apply for DITAVAL references within the map, with the global DITAVAL file being considered the top-level rule set. Note that traditional Arbortext profiling occurs in addition to DITAVAL processing. Since DITAVAL processing is part of the DITA preprocessing done before standard publishing, DITAVAL filtering occurs before profiling is applied. DITAVAL Association by Key Reference Note that the data element supports the keyref attribute. When specified, the keyref will be resolved the same as any other reference. So, for example, you could specify this DITAVAL association in your map: <data name= ditavalref keyref= productDitaval /> And define the productDitaval key just like any other key definition, elsewhere in the map. <keydef keys= productDitaval format= ditaval href= /> Filtering of DITAVAL References Note that DITAVAL references can, themselves, be marked for conditional processing. DITAVAL references can not be filtered by rules from other DITAVAL references. They can only be filtered from the rules passed in via composition parameters. This is because the act of finding DITAVAL references must happen before DITAVAL filtering from those references can occur. For example, consider this: <topicref href= > <topicmeta> <data name= ditavalref href= product= ProjectY /> </topicmeta> </topicref> This says, essentially, When publishing for Project Y, flag expert regions in red. However, the filtering of this DITAVAL reference based on @product will only occur based on rules from the DITAVAL passed in to the composition operation. If a higher scope references a DITAVAL file that would exclude product= ProjectY , that filtering will be ignored. So this has no effect: <map> <title>Map Title</title> <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= > <topicmeta> <!-- This will not be filtered out because one ditaval reference cannot remove others --> <data name= ditavalref href= product= ProjectY /> </topicmeta> </topicref> </map> Examples Example 1.1. Appling a DITAVAL File to an Entire Map You can specify DITAVAL rules for a whole map structure by referencing it from topicmeta within the top-level map element. <map xml:lang= en > <!-- the <ph> tags will be filtered using the rules in expert.ditaval --> <title> <ph audience= Expert >Expert</ph> <ph audience= Novice >Novice</ph> Instructions </title> <topicmeta> <data name= ditavalref href= /> </topicmeta> <!-- All topics will be filtered via 'expert.ditaval' --> <topicref href= /> <topicref href= /> </map> Example 1.2. Profiling the Same TOC with Different Rules You can use DITAVAL association to have the same set of topics filtered differently by wrapping them in different wrapper maps with different DITAVAL associations. <map xml:lang= en > <title>Expert Instructions</title> <topicmeta> <data name= ditavalref href= /> </topicmeta> <mapref href= /> </map> <map xml:lang= en > <title>Novice Instructions</title> <topicmeta> <data name= ditavalref href= /> </topicmeta> <mapref href= /> </map> Example 1.3. Different DITAVAL Rules for Different Sections of a Map You can use different DITAVAL rules at different locations in the same map structure. In the example below, content affected by teacher.ditaval will be highlighted in green, and content affected by student.ditaval will be highlighted in orange. <map xml:lang= en > <title>Teacher's Guide</title> <!-- Section One --> <topichead navtitle= Section One (Teacher) > <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= /> </topichead> <topichead navtitle= Section One (Student) > <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= /> </topichead> <!-- Section Two --> <topichead navtitle= Section Two (Teacher) > <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= /> </topichead> <topichead navtitle= Section Two (Student) > <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= /> </topichead> </map> Example 1.4. DITAVAL Rule Additivity Let's say you had two DITAVAL files. ProjectX.ditaval: <val> <prop att= product val= ProjectX action= /> <prop att= otherprops val= Green action= color= green /> </val> ProjectY.ditaval: <val> <prop att= product val= ProjectX action= /> <prop att= product val= ProjectY action= /> <prop att= otherprops val= Red action= color= red /> </val> When these two DITAVAL files are referenced from nested topicrefs in a map, the effect for the inner scope will be the same as if you took the prop elements from the 'inner' scope and appended them to the DITAVAL file from the 'outer' scope. <map> <topicref href= > <topicmeta> <data name= ditavalref href= /> </topicmeta> <topicref href= > <topicmeta> <data name= ditavalref href= /> </topicmeta> </topicref> </topicref> </map> In this example, only the rules in ProjectX.ditaval apply to topic1.dita , but the effective DITAVAL rules for topic2.dita will be the combination of the rules from ProjectX.ditaval and ProjectY.ditaval : <val> <!-- From ProjectX --> <prop att= product val= ProjectX action= /> <prop att= otherprops val= Green action= color= green /> <!-- From ProjectY. Since product= ProjectX is already --> <!-- defined, the second rule is ignored. --> <prop att= product val= ProjectX action= /> <prop att= product val= ProjectY action= /> <prop att= otherprops val= Red action= color= red /> </val> So the effective action for product= ProjectX is include. If the order were reversed, and ProjectY were referenced from the outer scope and ProjectX from the inner scope, the effective rules at topic2.dita would be reversed: <val> <!-- From ProjectY --> <prop att= product val= ProjectX action= /> <prop att= product val= ProjectY action= /> <prop att= otherprops val= Red action= color= red /> <!-- From ProjectX --> <prop att= product val= ProjectX action= /> <prop att= otherprops val= Green action= color= green /> </val> So the effective rule for product= ProjectX is exclude. On May 20, 2013, at 4:51 PM, Robert D Anderson <
robander@us.ibm.com > wrote: Hi Stan - that alternate organization would be functionally the same, but would require maintaining three copies of the branch. In most cases where we have found the branch filtering to be useful, the branch (in this example the install instructions) is much deeper, sometimes with a large number of topics. Placing the three <ditavalref> together in one branch -- either using this method or using something like the <topicmeta> version Eliot and Chris mentioned -- means that the author only maintains the one common organization. In the case where it really is one topic - I think your sample would indeed be easier to picture for the author, or for somebody trying to understand this concept - but it will get painful if you are trying to work with a big chunk of content. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit (
http://dita-ot.sourceforge.net/ ) From: Stan Doherty <
stan@modularwriting.com > To: Robert D Anderson/Rochester/IBM@IBMUS, Cc: dita <
dita@lists.oasis-open.org > Date: 05/20/2013 16:31 Subject: Re: [dita] Branch filtering (proposal 13059a) Thanks -- I am now grokking your multi-platform example. When published, the TOC would contain the following chapters: 1. What's new 2. Installing on Mac 3. Installing on Windows 4. Installing on Linux 5. Common tasks 6. Reference info 7. Appendixes / etc Although I still imagine it as being organized with a flat, 1:1 ratio of topics and ditavalref calls. Would this one work as well? the same? <topicref href= > <ditavalref href= /> </topicref> <topicref href= > <ditavalref href= /> </topicref> <topicref href= > <ditavalref href= /> </topicref> :-) /stan On May 20, 2013 at 3:00 PM Robert D Anderson <
robander@us.ibm.com > wrote: Hi Stan, I think it would depend on what you mean by two-pass / how you implement filtering. In the prototype implementation I've got now, it uses 2 passes, mostly to simplify that processing. We specify a global set of DITAVAL conditions at the start of a process - those apply to everything, and we filter as we first encounter each element, so that anything filtered out is removed that first possible point. Further along in our processing stream, we duplicate the branch of content for each extra set of conditions, filtering as we do so. As to the usefulness, a more extensive example might be helpful. Imagine a set of content where virtually everything is common - concepts, reference info, how to use , even most of the tasks within the product; however, the install instructions differ by platform, as in the sample below. The design below allows us to create all of our information at once - all of the common info is processed and appears in the final product docs only once: <map> <topicref> What's new branch...</topicref> <topicref>Installing as below, with 3 ditavalref conditions</topicref> <topicref> Common tasks branch</topicref> <topicref> Reference info branch...</topicref> <topicref>Appendixes / index / etc</topicref> </map> When published, the TOC would contain the following chapters: 1. What's new 2. Installing on Mac 3. Installing on Windows 4. Installing on Linux 5. Common tasks 6. Reference info 7. Appendixes / etc The primary alternatives we have for creating this today are: *) Three documents, each filtered for one OS. Makes online searching difficult because results for most sections appear 3 times, 2/3 chance of following into the wrong book *) Publish the install section on its own, outside of this document, using something like Eclipse to dynamically pull together *) Publish most of these independently and then assemble together I believe this was the main use case that led us down the path of multiple filters in a branch -- a case where most information in a large document is common, but just a few sections differ for platform or audience. The main problem with that was the search one, where building the document once for each condition results in many search hits for the common pages. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit (
http://dita-ot.sourceforge.net/ ) From: Stan Doherty <
stan@modularwriting.com > To: Robert D Anderson/Rochester/IBM@IBMUS, dita <
dita@lists.oasis-open.org >, Date: 05/20/2013 14:39 Subject: Re: [dita] Branch filtering (proposal 13059a) Hi Robert -- I like this very much -- but have to confess that I am still gnawing on the usefulness of your use case (below). Would this require two-pass filtering? The more complex case allows a single branch to be published for multiple audiences, without having to redefine the branch. For example: <topicref href= > <ditavalref href= /> <ditavalref href= /> <ditavalref href= /> ...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. /stan On May 15, 2013 at 2: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= > <ditavalref href= /> ...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= > <ditavalref href= /> <ditavalref href= /> <ditavalref href= /> ...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 Stan Doherty Director, Technical Publications Verivue Inc. Stan Doherty Director, Technical Publications Verivue Inc. --------------------------------------------------------------------- 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 Chris Nitchie Oberon Technologies, Inc. 2640 Wildwood Trail Saline, MI 48176 Main: 734.666.0400 Direct: 734.330.2978 Email:
chris.nitchie@oberontech.com www.oberontech.com