Summary of Context-Sensitive Help Progress

["Tony Self" <tself@hyperwrite.com>]

Dear colleagues

At the last meeting, I promised to summarise where we were up to with
respect to context-sensitive Help before the next meeting. So, on the death
knell, here's that summary. There are probably three key discussion points:

. Context Numbers and Strings
. Window Descriptions
. Implementation Scenarios.

I suggest we recommence discussion on each of these three separately. If you
have any suggestions or comments, please respond to the list.

Regards

Tony Self



Context Numbers and Strings
---------------------------
Although context-sensitive Help (CSH) is possible with DITA 1.1, the options
are not flexible and do not cater for the full range of use cases. A
proposal was made to allow more complex context sensitive Help metadata to
be defined in topic and topicref attributes.

Including context hook metadata at the ditamap (topicref) level and the
topic level would allow processors to generate the header, map or alias text
files required to integrate the Help with an application.

This proposal suggests adding a help element, valid within the topicref
element's topicmeta element and the topic elements' prolog element. The help
element would contain optional attributes of help-id, help-string, and
help-window. None, one or many help elements would be permitted within the
parent element. 

The code sample below illustrates the proposed use:

<map title="Widget Help">
 <topicref href="file_ops.dita" type="concept">
   <topicref href="saving.dita" type="task">
     <topicmeta>
     <help help-id="1234" help-string="idh_filesave" />
     </topicmeta>
   </topicref>
   <topicref href="deleting.dita" type="task">
     <topicmeta>
      <help help-id="2345" help-string="idh_filedelete" />
							<help help-id="6789"
help-string="idh_filekill" />
     <topicmeta>
   </topicref>

   <topicref href="editing.dita" type="task">
     <topicmeta>
       <help help-id="5432" help-string="idh_fileedit" help-window="ua"  />
     <topicmeta>
   </topicref>
</topicref>
</map><task id="fedt">
 <title>Editing a File</title>
 <prolog>
   <help help-id="5432" help-string="idh_fileedit" help-window="ua" />
 </prolog>
 <taskbody>
  <context>After you have created a new file, you can edit it.</context> 
  <steps>
   <step><cmd>Open...</cmd></step>
   <step><cmd>Edit...</cmd></step>
   <step><cmd>Save...</cmd></step>
  </steps>
 </taskbody>
</task>

More information:
http://www.oasis-open.org/apps/org/workgroup/dita-help/download.php/28362/di
ta-proposal-csh1.html


Window Descriptions
-------------------
To cater for Help systems with embedded window information, it is important
for that information to be defined in the ditamap being processed, so that
the processor can incorporate the definitions in the generated output file. 

A proposal was made to add a help-window element, valid within the map
element. The help-window element would contain optional attributes of name,
top, left, height, width, on-top, features, and full-screen. None, one or
many help-window elements would be permitted within the parent element. The
code sample below illustrates the proposed use:

<map title="Widget Help">
<help-window name="ua" top="10" left="20" height="400" width="500" 
   features="status=yes,toolbar=no,menubar=no,location=no" full-screen="no"
/>
 <topicref href="file_ops.dita" type="concept">
   <topicref href="saving.dita" type="task" />
   <topicref href="deleting.dita" type="task" />
   <topicref href="editing.dita" type="task">
     <topicmeta>
       <help help-id="5432" help-string="idh_fileedit" help-window="ua"  />
     <topicmeta>
   </topicref>
</topicref>
</map>

More information at:
http://www.oasis-open.org/apps/org/workgroup/dita-help/download.php/28370/di
ta-proposal-csh-win.html

Implementation Scenarios
------------------------
There are probably four different CSH implementation scenarios, and we
should make sure that any proposals we make will work in each of those four.
The scenarios are:

. Map Files Externally Managed - Incorporated in Build File
. Map Files Derived from ditamap
. Derived from DITA Topics
. Intermediate XML Map File

More information at:
http://wiki.oasis-open.org/dita/Implementation_Scenarios