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

[Robert D Anderson <robander@us.ibm.com>]

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

/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="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
>
Stan Doherty
Director, Technical Publications
Verivue Inc.