[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: conditional processing design
Copying this note from an old post to the DITA forum on developerworks, since it is of interest for today's presentation: ------------------------------------------------------------------------- There have been some questions in the past about how DITA can support conditional processing. This is an example of how it could be done, and a starting point for discussion. Here are the basics: Conditonal processing means filtering or flagging information based on processing-time criteria (could be runtime or buildtime, same process applies. DITA tries to implement conditional processing in a semantically meaningful way: rather than bunches of arbitrary values accumulating in a document over time, with meaning only to the original author, we encourage the authoring of metadata using attributes on content, which can then be leveraged by filtering, flagging, search, or indexing processes, rather than being suitable for filtering only. There are four attributes intended for conditional processing, available on most elements. they are: product: the product that is the subject of the discussion. platform: the platform on which the product is deployed. audience: the intended audience of the text rev: the revision or draft number of the current document otherprops: anything else Each attribute takes zero or more space-delimited string values. For example, you can use the product attribute to identify that an element applies to two particular products. Example source: <p audience="administrator">Set the configuration options: <ul> <li product="extendedprod">Set foo to bar</li> <li product="basicprod extendedprod">Set your blink rate</li> <li>Do some other stuff</li> <li platform="Windows">Do a special thing for Windows</li> </ul> </p> At processing time, you specify the values you want to exclude and the values you want to flag. For example, let's say I want to flag info that applies to administrators,and exclude stuff that applies to the extended product, since I am building the docs for a mixed audience who are using the basic product. Example process conditions: <prop att="audience" val="administrator" action="flag" use="ADMIN"/> <prop att="product" val="extendedprod" action="exclude"/> At output time, you'd want the paragraph flagged, and the first list item excluded (since it applies to extendedprod), but the second list item still included (even though it does apply to extendedprod, it also applies to bsaicprod, which we didn't say to exclude). Result should be something like: ADMIN Set the configuration options: - Set your blink rate - Do some other stuff - Do a special thing for Windows Exclusion logic - when deciding whether to exclude a particular element, evaluate each attribute, and then evaluate the set of attributes: - if all the values in an attribute have been set to "exclude", the attribute evaluates to "exclude" - if any of the attributes evaluate to exclude, the element is excluded. This should make sense if you think it through. If a paragraph applies to three products and you've excluded all of them, you should exclude the paragraph; even if the paragraph applies to an audience or platform that you aren't excluding. Flagging logic Flagging works the same way, except that if everything evaluates to the condition we output an extra flagging element (a text string or an image), instead of just removing the element. Probably the simplest way to flag would be to output the flagging text in an <em> tag in HTML, with a class setting "flag" that you can use CSS to style as white, in small caps with a purple background (use whatever you prefer, I'm just picking a style that I think would stand out). Example output in HTML (assuming everything was set to flag): <p><em class="flag">ADMIN</em> Set the configuration options: <ul> <li><em class="flag">BP </em>Set foo to bar</li> <li><em class="flag">BP </em><em class="flag">EP </em>Set your blink rate</li> <li>Do some other stuff</li> <li><em class="flag">WINDOWS </em>Do a special thing for Windows</li> </ul> </p> The "use" attribute could also take an image element, as long as you know the image will be available at runtime. Some thoughts on authoring This model is intentionally simple, and people with experience authoring with full boolean support may find it restrictive. However, this comes out of our own experiences with writing reusable content: when you have multiple authors working on the same set of documents, a complex processing model quickly becomes more trouble than its worth. Some last thoughts on processing - this model is scalable from simple file systems all the way to full-scale content management; this keeps your content insulated from processing infrastructure - probably the simplest way to incorporate exclusion processing is via a preprocess step, eg with an XSLT transform. The exclusion logic could be combined with content-referencing resolution, so that conrefs are only resolved when they need to be. - for flagging processing, we'd need to extend the final-stage output transform, adding a call in each template to a "flageval" template that would generate a flag if needed. Anyway, I hope this can foster some discussion on conditional processing. Does the scheme make sense? Does it meet your needs? Hoping to hear from folks, Michael Priestley DITA Specialization Architect mpriestl@ca.ibm.com ------------------------------------------------------------------------------------------ Michael Priestley mpriestl@ca.ibm.com Dept PRG IBM Canada phone: 416-915-8262 Toronto Information Development
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]