OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: 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...

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...

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/)

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]