Conditional Processing

Hi All,

On Sat, Mar 6, 2010 at 9:10 PM, Shaun McCance <shaunm at gnome.org> wrote:

> Hi folks,
>
> I'd like to talk about how (and if) we should support
> conditional processing in Mallard.  A few people have
> requested this, and it's not out of the question to
> get it into 1.0.
>
> For background, both DocBook and DITA take basically
> the same approach.  Elements can have attributes that
> specify certain things that element is effective for.
> So you have things like these
>
> <para arch="...">
> <p platform="...">
>
> When you hand your document to a processing tool, you
> tell the tool what sorts of things you want to filter
> on.  If you don't explicitly filter on e.g. platform,
> those attributes don't do anything.
>

In order to tell a processing tool what sort of things we're going to filter
on, we not only need the actual in-document conditional text, but we need a
means of telling the tool which of those options we want.  DITA uses ditaval
filtering files to tell the tool what sorts of things to filter on.  My
hunch is that we would need a corresponding mechanism.

Also, you mention not explicitly filtering on a value, but wouldn't some
value need to be specified to prevent inappropriate options from being
displayed?  For example, if you didn't specifically filter on the distro,
the docs could display both Ubuntu- and Fedora-related content.  (Let me
know if I've misunderstood your comment.)

>
> (This is all my general understanding.  Please correct
> me if I'm wrong.)
>
> A problem with using this approach in Mallard is that
> Mallard is used as a deliverable format, so processing
> time is display time.  You don't have the chance to tell
> your processing tool which filters to apply.
>

One way around this is to include filtering options as part of the help
browser.  Have the settings default to a baseline (e.g., desktop user), but
allow for other settings (e.g., advanced user, sysadmin, etc.).


>
> As an example, suppose you had a paragraph that you only
> want shown in Ubuntu, and another you only want shown in
> every other distro.  In DocBook (pre-processing, not on
> the fly in Yelp), you might do something like this:
>
> <para condition="ubuntu">Some Ubuntu stuff</para>
> <para condition="notubuntu">Some other stuff</para>
>
> You would do two builds, the first one requiring ubuntu
> in condition, and the other requiring notubuntu.
>
> So we could go down the road of defining a syntax for
> basic boolean combinations, and get stuff like this:
>
> <p distro="ubuntu">Ubuntu rocks!</p>
> <p distro="fedora">Fedora rocks!</p>
> <p distro="!(ubuntu || fedora)">My distro rocks!</p>
>
> But I don't want to write a parser, especially not in
> XSLT.  So I propose we just use XPath 1.  It's available
> in just about any XML processing tool.  And instead of
> separate conditional attributes, where we have to decide
> whether they OR or AND together, we can just have a single
> attribute.  Then we define some extension functions to get
> certain data.
>
> <p if="mal:key('distro') = 'fedora'">Fedora rocks!</p>
>
> This is really dead simple to implement in XSLT as long
> as your processor supports these EXSLT extensions:
>
> http://www.exslt.org/dyn/functions/evaluate/index.html
> http://www.exslt.org/func/elements/function/index.html
>
> If this is an approach people like, we'd have to decide
> which functions and types of data to specify.


I'm not sure I'm following this, but it sounds like you have a good grasp of
what you think is practical here.


> Mallard
> extensions (and future versions) can always add things
> to this (which is something I really like about this
> approach).  But I do not want conditional processing
> to go in without a very clear specification, because
> authors need to know that their documents will work in
> different environments.
>
> Thoughts?
>

Here's a couple of references from the DITA folks:
http://docs.oasis-open.org/dita/v1.0/archspec/condproc.html
http://docs.leximation.com/dita-fmx/0.02/ditafmx_ref_applyditaval.html

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20100312/acdf7d2a/attachment.html>