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

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

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="install-instructions.dita">
   <ditavalref href="mac.ditaval"/>
</topicref>
<topicref href="install-instructions.dita">
   <ditavalref href="linux.ditaval"/>
</topicref>
<topicref href="install-instructions.dita">
   <ditavalref href="win.ditaval"/>
</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="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.
>
Stan Doherty
Director, Technical Publications
Verivue Inc.