Conditional Processing

Shaun McCance <shaunm at gnome.org>
Fri Mar 12 17:15:52 EST 2010

On Fri, 2010-03-12 at 15:47 -0600, Jim Campbell wrote:
> 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.) 

Right.  So the issue is that, without an author-controlled build
run, the author can't specify values to filter on.  So we have to
define the keys and appropriate values as best we can, and build
them directly into help viewers.

For most things, I'm thinking of something like this:

<p if="mal:key('arch') = 'x86_64'">64-bit FTW</p>

Programs like Yelp would implement the mal:key function to return
values for keys.  They would have to be able to find those values
programmatically.  A lot of stuff could be gotten from uname.  For
distro name, Yelp will probably need a compile-time option that we
encourage distros to set.  (Banshee does this, by the way.)

We'd want to specify standard keys and common values.  And probably
define mal:key to return '' whenever the key is not understood.  We
need authors to have some assurance of getting the right output.

I probably spent too much of my previous email explaining what I
don't want to do.  Is this more clear?

--
Shaun