Conditional Processing

Kyle Nitzsche <kyle.nitzsche at canonical.com>
Fri Apr 2 12:10:26 EDT 2010

Hi Shaun,

I am curious how the run-time conditional logic would discover the 
current value(s) of keys (mal:key('somekey')='somevalue').
 * Is there some file that needs to be present (and is correct for the 
context) that holds the keys?
 * What process will consult the key and use it? Yelp?
 * Is there a limited set of keys or can keys be arbitrarily added as 
desired?

I am not speaking for ubuntu-docs, but I would *guess* they do not 
currently use conditional processing. However, it occurs to me that 
since ubuntu-docs does have two output formats currently (localized xml 
and html), and that currently the content is identical (another 
*guess*), it may be useful to be able to add some content that is 
targeted at the output format. That is, perhaps some extra text/etc to 
display in the html, and some that's targeted at run-time docs.

Such things could be supported by tagging text for conditions as you 
describe below.

Setting aside specifics, I would say that in *general* the ability to 
easily support "profiling" is important, if only to handle future 
potential needs.

And since I am writing, but on a different topic, I am wondering (again) 
about the performance hit of run-time processing. It now takes more than 
60 seconds to display the Ubuntu Help Center (Karmic) the first time in 
every boot cycle. This is so long that I guess many users conclude the 
application is broken and close it before the help even displays. Does 
mallard/yelp address this somehow (perhaps by only processing/rendering 
the pages that are actually going to be displayed only when they are 
going to be displayed instead of doing all of them)?

I will also note that run-time profiling has the disadvantage that 
content that is not applicable to the current context is *physically* 
present, even though it may never be used on a particular system. If 
used for a lot of content, this wastes disk space, causes packages to be 
larger than necessary, and prevents use of the mechanism for excluding 
information that cannot be included.

Cheers,
Kyle



Shaun McCance wrote:
> On Sat, 2010-03-06 at 21:10 -0600, Shaun McCance 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.
>>     
>
> I haven't gotten a lot of responses on this. That means one
> of two things:
>
> 1) People don't think conditional processing is important.
> 2) People trust that I've thought things through and that
>    what I'm proposing works well.
>
> The Ubuntu folks have pushed for conditional processing
> in the past. Perhaps I should relay this proposal to
> them for comments.
>
>   
>> 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.
>>
>> (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.
>>
>> 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.  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?
>>
>>     
>
>
>
> _______________________________________________
> Mallard-list mailing list
> Mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list_projectmallard.org
>