RE: [dita] Branch filtering (proposal 13059a)

["Chris Nitchie" <chris.nitchie@oberontech.com>]

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