OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-comment message

[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 &quot;values&quot;
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 &quot;values&quot; embedded in the
string. For example, we could use a prefix (&quot;<CODE>Mkt_</CODE>&quot;)
plus descriptor (&quot;<CODE>au</CODE>&quot;) model, viz. 
</P>
<PRE>        otherprops=&quot; 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 &quot;</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) &amp; (Fn_invoicing|Fn_online-banking) &amp; 
        (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 &quot;variable&quot;, 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">&lt;section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">&quot; Fn_invoicing &quot;</FONT></B><FONT COLOR="#000000">&gt;</FONT></FONT>
                ...
<FONT COLOR="#000000">                <FONT FACE="Courier New, monospace">&lt;p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#ff0000">&quot; Fn_banking &quot;</FONT></B><FONT COLOR="#000000">&gt; ... &lt;/p&gt;  </FONT></FONT>
<FONT COLOR="#000000">                        </FONT><SPAN STYLE="background: transparent"><B><FONT FACE="Courier New, monospace"><FONT COLOR="#ff0000">&lt;!-- ILLEGAL CONDITIONAL VALUE --&gt;</FONT></FONT></B></SPAN>
        &lt;/section&gt;</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>&quot;
	Fn_banking &quot;</CODE> into the <CODE>&lt;p&gt;</CODE> child
	element but warn the writer that there was a logical inconsistency
	and highlight the nearest ancestor element (<CODE>&lt;section&gt;</CODE>)
	that was causing the problem, and ask the writer whether to add the
	<CODE>&quot; Fn_banking &quot;</CODE>conditional value to the
	<CODE>condfunc</CODE> attribute of the <CODE>&lt;section&gt;</CODE>
	element.</P>
	<LI><P>XMetaL should prevent the writer from inserting <CODE>&quot;
	Fn_banking &quot;</CODE> into the <CODE>&lt;p&gt;</CODE> child
	element because, by definition, the <CODE>&quot; Fn_invoicing &quot;</CODE>
	value in the <CODE>&lt;section&gt;</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>&quot;
	Fn_banking &quot;</CODE> value up the structure tree and
	thoughtlessly obliterate the value in <CODE>&lt;section&gt;</CODE>
	to produce</P>
</UL>
<PRE><FONT COLOR="#000000">        <FONT FACE="Courier New, monospace">&lt;section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">&quot; Fn_banking &quot;</FONT></B><FONT COLOR="#000000">&gt;</FONT></FONT>
                ...
<FONT COLOR="#000000">                <FONT FACE="Courier New, monospace">&lt;p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">&quot; Fn_banking &quot;</FONT></B><FONT COLOR="#000000">&gt; ... &lt;/p&gt;  </FONT><B><FONT COLOR="#0000ff">&lt;!-- LEGAL VALUE --&gt;</FONT></B></FONT>
        &lt;/section&gt;</PRE><P>
when possibly what you wanted was 
</P>
<PRE><FONT COLOR="#000000">        <FONT FACE="Courier New, monospace">&lt;section condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">&quot; Fn_banking Fn_invoicing &quot;</FONT></B><FONT COLOR="#000000">&gt;</FONT></FONT>
                ...
<FONT COLOR="#000000">                <FONT FACE="Courier New, monospace">&lt;p condfunc=</FONT></FONT><FONT FACE="Courier New, monospace"><B><FONT COLOR="#0000ff">&quot; Fn_banking &quot;</FONT></B><FONT COLOR="#000000">&gt; ... &lt;/p&gt;  </FONT><B><FONT COLOR="#0000ff">&lt;!-- LEGAL VALUE --&gt;</FONT></B></FONT>
        &lt;/section&gt;</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">&quot;
Fn_banking Fn_invoicing &quot;</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">&quot;
Fn_banking &quot;</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">&quot;&quot;</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>&lt;para&gt;</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]