[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Public Comment
Comment from: hedley.finger@myob.com Name: Hedley Finger Title: Tech. Comms Tools & Processes Specialist Organization: MYOB Australia Pty Ltd, and associated companies worldwide Regarding Specification: %select-atts; [[This is the text of an email sent to Su-Laine Yeo, a user-interface designer for XMetaL at Blast Radius. You might find it worthy to bring to the attention of the committee. I have been banging on about the need to somehow specialise or extend the %select-atts; to cater for those who need more conditional attributes for some time. I believe the committee is working on this and may have a solution different to this proposal. However, this proposal at least states the problem succinctly.]] <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252"> <TITLE></TITLE> <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.4 (Win32)"> <META NAME="AUTHOR" CONTENT="Hedley Finger"> <META NAME="CREATED" CONTENT="20050812;16215224"> <META NAME="CHANGEDBY" CONTENT="Hedley Finger"> <META NAME="CHANGED" CONTENT="20050812;16225460"> <STYLE> <!-- @page { size: 21cm 29.7cm; margin: 2cm } P { margin-bottom: 0.21cm } --> </STYLE> </HEAD> <BODY LANG="en-AU" DIR="LTR"> <P>Sure hope that the formatting is preserved in the HTML version of this message. Although I have set HTML formatting in Lotus Notes, somehow the formatting sometimes disappears!</P> <H4>*** Representing conditional content switches as attributes ***</H4> <P>The <TT>%select-atts;</TT> attributes in the DITA Language Reference are specified as CDATA, i.e. the values in these attributes are a single string, with the separate conditional "values" embedded as non-space characters separated by spaces. The Epic profiles and FrameMaker plus Sourcerer model these effectively as NMTOKENS that allow multiple values separated by a CR. As you can see, it would be a trivial matter to transform from an NMTOKENS to a CDATA representation, either programmatically or with an XSLT mapping. So it would be easy to move the source content between XMetaL, Epic, or FrameMaker.</P> <P>A real problem for us is that the DITA model just does not have enough conditional attributes. We could shovel a lot of them into <CODE>otherprops</CODE> if there was some way to extract a boolean expression out of the conditional "values" embedded in the string. For example, we could use a prefix ("<CODE>Mkt_</CODE>") plus descriptor ("<CODE>au</CODE>") model, viz. </P> <PRE> otherprops=" Mkt_au Mkt_nz Mkt_sg Fn_invoicing Fn_online-banking Plat_win-xp Plat_win-98 Plat_mac-osx Plat_linux-rh Plat_linux-mdk "</PRE><P> which would be interpreted by XMetaL and the DITA toolchain (grouping conditional values by prefix) as </P> <PRE> (Mkt_au|Mkt_nz|Mkt_sg) & (Fn_invoicing|Fn_online-banking) & (Plat_win-xp|Plat_win-98|Plat_mac-osx|Plat_linux-rh|Plat_linux-mdk)</PRE><P> XMetaL, etc. could then look up a table of truth values for each conditional "variable", substitute into the boolean expression, and then reveal/conceal the content in the conditioned element accordingly.</P> <P>The other way to go is to just break the DITA <CODE>%select-atts;</CODE> by adding more custom conditional attributes of our own. I expect that customers to whom conditional content is very important may opt for either approach, and Blast Radius should consider how to support either approach.</P> <H4>*** Setting conditional values ***</H4> <P>It would be nice if users could just insert conditional values into the CDATA string by selecting them from a pick list of legal values, i.e. writers would not have to remember what they were and type them in correctly with no mistakes, e.g. forgetting to put in the leading and trailing space in the CDATA string or accidentally inserting a hyphen (-) instead of an underscore (_) after the prefix. The list of legal values could be configured by the sys admin to prevent cowboy values from being invented by writers without regard to how they would be processed down the toolchain.</P> <P>In terms of previewing the effect of setting conditional truth values, it would be nice if you could combine the Sourcerer and Epic methods (I assume you have copies of your competitors' apps!). Thus, </P> <UL STYLE="margin-left: 0.4cm"> <LI><P><FONT FACE="Tahoma, sans-serif">You could set individual truth values by clicking check boxes in a dialogue as you can in the <B>Profile</B> dialogue in Epic.</FONT></P> <LI><P><FONT FACE="Tahoma, sans-serif">You could save a named set of truth values available for recall (the FM Sourcerer method) so the writer could switch quickly between different sets without having to tediously click checkboxes for each different set (as you now have to do in Epic).</FONT></P> <LI><P><FONT FACE="Tahoma, sans-serif">Once you have named sets, the writer could also apply an entire set to an element.</FONT></P> </UL> <P>The DITA model <CODE>AND</CODE>s nested conditions, so in this non-example, </P> <PRE><FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">" Fn_invoicing "</FONT></B><FONT COLOR="#000000">></FONT></FONT> ... <FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#ff0000">" Fn_banking "</FONT></B><FONT COLOR="#000000">> ... </p> </FONT></FONT> <FONT COLOR="#000000"> </FONT><SPAN STYLE="background: transparent"><B><FONT FACE="Courier New, monospace"><FONT COLOR="#ff0000"><!-- ILLEGAL CONDITIONAL VALUE --></FONT></FONT></B></SPAN> </section></PRE><P> <FONT COLOR="#000000"><FONT FACE="Helv, sans-serif">There are two approaches to this problem:</FONT></FONT></P> <UL STYLE="margin-left: 0.4cm"> <LI><P>XmetaL could temporarily allow the writer to insert <CODE>" Fn_banking "</CODE> into the <CODE><p></CODE> child element but warn the writer that there was a logical inconsistency and highlight the nearest ancestor element (<CODE><section></CODE>) that was causing the problem, and ask the writer whether to add the <CODE>" Fn_banking "</CODE>conditional value to the <CODE>condfunc</CODE> attribute of the <CODE><section></CODE> element.</P> <LI><P>XMetaL should prevent the writer from inserting <CODE>" Fn_banking "</CODE> into the <CODE><p></CODE> child element because, by definition, the <CODE>" Fn_invoicing "</CODE> value in the <CODE><section></CODE> ancestor element means that the entire element is only relevant to Invoicing, therefore an attempt to designate a child element as only relevant to Banking is incorrect. Epic allows you to really mess up your document as it offers you the ability to <I>all-too-easily </I>back-propagate the <CODE>" Fn_banking "</CODE> value up the structure tree and thoughtlessly obliterate the value in <CODE><section></CODE> to produce</P> </UL> <PRE><FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">" Fn_banking "</FONT></B><FONT COLOR="#000000">></FONT></FONT> ... <FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">" Fn_banking "</FONT></B><FONT COLOR="#000000">> ... </p> </FONT><B><FONT COLOR="#0000ff"><!-- LEGAL VALUE --></FONT></B></FONT> </section></PRE><P> when possibly what you wanted was </P> <PRE><FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">" Fn_banking Fn_invoicing "</FONT></B><FONT COLOR="#000000">></FONT></FONT> ... <FONT COLOR="#000000"> <FONT FACE="Courier New, monospace"><p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">" Fn_banking "</FONT></B><FONT COLOR="#000000">> ... </p> </FONT><B><FONT COLOR="#0000ff"><!-- LEGAL VALUE --></FONT></B></FONT> </section></PRE><P> When I was evaluating Epic I set up a sample document with complex profiling (conditioning) to test the boolean model and was really pissed off to find I had unintentionally deleted conditional values in a number of generations of ancestors back up the structure tree. This would be a nightmare for us, particularly if the writer did not realise that had happened, and checked a corrupted file back in which subsequently made its way into the release build.</P> <P>At least Sourcerer (a) informs you when you attempt a logical inconsistency and (b) does not let you destroy your conditioning with a click of the mouse.</P> <P><FONT FACE="Helv, sans-serif"><FONT COLOR="#000000">So if XMetaL is to allow writers to back-propagate conditional values in order to resolve logical inconsistencies, it should stop on each affected ancestor attribute and offer a choice of (a) augmenting the current string (</FONT></FONT><CODE><B><FONT FACE="Cumberland, monospace"><FONT COLOR="#0000ff">" Fn_banking Fn_invoicing "</FONT></FONT></B></CODE><FONT COLOR="#000000"><FONT FACE="Helv, sans-serif">), </FONT><FONT FACE="Tahoma, sans-serif">(b)</FONT> <FONT FACE="Tahoma, sans-serif">replacing the current string (</FONT></FONT><CODE><B><FONT FACE="Cumberland, monospace"><FONT COLOR="#0000ff">" Fn_banking "</FONT></FONT></B></CODE><FONT FACE="Helv, sans-serif"><FONT COLOR="#000000">), or removing the current string (</FONT></FONT><CODE><B><FONT FACE="Cumberland, monospace"><FONT COLOR="#0000ff">""</FONT></FONT></B></CODE><FONT FACE="Helv, sans-serif"><FONT COLOR="#000000">). No doubt your own technical writers (and my colleagues -- add your 2c worth, guys!) can mull over other choices that could automatically be offered!</FONT></FONT></P> <H4>*** Signalling the presence of conditioned content ***</H4> <P>Both FrameMaker and RoboHTML indicate the presence of conditions with visual signals. In the case of FrameMaker, this is a combination of rulings (<U>under</U>, <U>double</U>, over, <STRIKE>thru</STRIKE>, <U>dotted under</U>, <U>dashed under</U>, etc.) and colours. RoboHTML indicates their presence with only a background colour hatching. FrameMaker's native behaviour is to <CODE>OR</CODE> the truth values of conditions. In Australia, we built an in-house utility to also <CODE>AND</CODE> conditions, along the lines of the model presented above and in my previous messages, both to you and in various forums: framemaker-dita, dita-users, xml-doc, etc.</P> <P>In this model, each conditional attribute (say, platform) had its own colour, say <FONT COLOR="#99ccff">duck-egg blue</FONT>. Then each value in the platform condition had its own ruling. So if you saw a content range that was coloured <FONT COLOR="#99ccff">duck-egg blue</FONT>, you knew that platform differences were indicated. Within the coloured range, you could see different rulings, e.g. strikethru might indicate <STRIKE><FONT COLOR="#99ccff">Plat_linux-rh</FONT></STRIKE> and underrule might indicate <U><FONT COLOR="#99ccff">Plat_linux-mdk</FONT></U>.</P> <P>When two different conditions overlap on a range, (say, platform and audience), the overlap was always coloured <FONT COLOR="#ff00ff">magenta</FONT> to indicate the presence of different conditional atttributes. The overlap was always <FONT COLOR="#ff00ff">magenta</FONT> whatever the colours of the overlapped conditions.</P> <P>These visual indications warn the writer that conditions are present and to carefully examine the values of the conditional attributes before making changes.</P> <P>It would be rather nice if XMetaL could have three document views: no tags, tags only, only tags with conditional attribute-values also displayed (other tags suppressed). This avoids annoying the writer by making them open the attributes dialogue to see what the conditional values were. It also avoids swamping writers with all attribute values when they are really only interested in the conditional attributes. You could also have the structure view display all tags, all tags except common tags like <CODE><para></CODE> as you do now, all attributes, or only conditional attributes.</P> <H4>*** Configuring conditions ***</H4> <P>With a tech. comms team dispersed across the world, it would be nice if an administrator could predefine</P> <UL STYLE="margin-left: 0.4cm"> <LI><P>legal conditional values</P> <LI><P>sets of conditional truth values</P> <LI><P>visual indicators for conditional values</P> </UL> <P>in some centrally located configuration file, preventing cowboy configurations. (But, in addition, writers might want to configure and save various personal condition sets to preview the application of conditions while writing.) In fact, it would be nice if an administrator could have a central configuration to ensure a standard operating environment for all writers in the organisation.</P> <H4>*** Exporting XML with or without conditions ***</H4> <P><FONT FACE="Helv, sans-serif"><FONT COLOR="#000000">In most cases, when a release build is required, the truth values of the conditions are set and the revealed XML content (minus the hidden content) is exported and the conditional attributes and their values are stripped from the output. I call this <I>compile-time conditioning</I>. That is, once you set the truth values, you get your PDF or HTML Help </FONT></FONT><CODE><FONT FACE="Cumberland, monospace"><FONT COLOR="#000000">*.chm</FONT></FONT></CODE><FONT COLOR="#000000"> <FONT FACE="Helv, sans-serif">file or whatever and you don't need the conditions any more.</FONT></FONT></P> <P><FONT COLOR="#000000"><FONT FACE="Helv, sans-serif"><FONT SIZE=3>But we are developing content where the access permissions and activated functionality of the application won't be known until the application is launched and the user logs in. So we want to leave the conditional attributes and their values in the deliverable. The help brower would then obtain the truth values from an application configuration file or by a call to the application's API, and process the content on the fly, removing hidden content just before the page is displayed. I call this <I>runtime conditioning.</I></FONT></FONT></FONT></P> <P><FONT SIZE=3>So XMetaL should be able to support either compile-time or runtime conditioning on export to any downstream tool. </FONT> </P> <H4>*** Business case for advanced condition management ***</H4> <P>Implementing rich condition management would give Blast Radius a very compelling story to tell to any customer contemplating extensive single-sourcing for different deliverables (different markets, different user groups, on-line help, PDF files, printed output, web sites) and repurposing (user documentation, training, and customer support). What is proposed above combines the best features of the only two viable XML editors for complex conditioned XML documents. And this story could extend beyond DITA. I know that Epic either stores profiles as metadata or modifies the schema to add conditional attributes, removing both hidden content and conditional attributes when exporting XML so that is conforms to the original schema. It does this for DocBook, DITA, and arbitrary schemas provided by clients.</P> <H4>*** Evaluation licences ***</H4> <P>My current evaluation licences for Epic and XMetaL have expired. I am certainly keen to assist you with evaluating interface designs and mock-ups, and taking alpha and beta implementations for a test drive. Without committing my colleagues, I am sure they would also like to participate. Just remember that although Mirjana sits near me in Melbourne, Australia, Dan is in Richmond, Virginia, and Carolyn is in Rockaway, New Jersey, so we can't really look over each others' shoulders.</P> <H4>*** Webex demos ***</H4> <P>I will get back to you with a time and date; gotta look at my trusty World Clock to figure out what time suits Vancouver and all the locations above!</P> <P>Regards,<BR><FONT FACE="Tahoma, sans-serif"><FONT COLOR="#000000">Hedley</FONT></FONT></P> <P STYLE="margin-bottom: 0cm"><BR> </P> </BODY> </HTML>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]