Change to Proposal

Date and version information

The latest revision date for this proposed feature document is 2013 August 16.
This feature was developed by, and continues to be championed by, the OASIS DITA Help Subcommittee.
The proposal for this feature was first drafted on 2008 May 22.
The proposal was revised as a result of discussions and evaluation by the OASIS DITA Help Subcommittee. These discussions are recorded in the minutes of the DITA Help Subcommittee.
Initially accepted for DITA 1.3 on August 2, 2011

Original requirement or use case

Help systems for software applications use context strings and context identifiers as a means to associate a specific Help topic with a part of the software application. Although such context hooks differ across applications, and across Help (or User Assistance) platforms, they can always be considered as metadata.

The only metadata container provided in DITA that is suitable for context hooks is the resourceid element, but it is too limited to be able to store all the context hook metadata required by a range of Help delivery technologies. Including better context hook metadata at the ditamap (topicref) level and the topic level would allow processors to generate the header, mapping or alias text files required to integrate the Help with an application.

Use cases

A Help author is creating a Help system for a software application, which will provide field-level user assistance. The developers are implementing a Help API, which takes parameters of help file name, opening mode, (optional) window name, and (optional) topic number. The Help author needs to generate a context mapping file to associate the topic numbers (or context identifiers) with topic file names, to pass to the development team for integration with the application code. The Help author needs to apply context identifiers to the topic either manually or through some generation process provided by the DITA authoring tool or through scripting. The context identifiers have to be stored in topic or topicref metadata (as they are not visible parts of the content) so that the mapping file can be generated automatically during the publishing process.

Alternatively, the development team might provide a list of context identifiers, in the form of a context mapping file, for the Help author to apply to topics in the Help system. The Help author would then need to associate the context identifiers in the map file with topics by applying topicref or topic metadata.

Proposed solution

This proposal suggests adding a number of extra attributes to the resourceid element, valid within the topicref element's topicmeta element and the topic element's prolog element. The resourceid element would contain optional attributes of id, appname, appid, context-string, and ua-window. None, one or many resourceid elements would still be permitted within the parent element. The yield-to-topic attribute is a Boolean flag to indicate whether the context hooks in the map should be over-ridden by any specified in the topic. (This yield-to-topic attribute is only valid when used within a topicref in amap.) If the yield-to-topic attribute does not exist, processors should assume that both the topic's resourceid and the map's topicref's resourceid should be used.

Another DITA 1.3 proposal to enhance the functionality of the resourceid element (Proposal 13008) by adding an appid does not satisfy the Use Case requirements (window name and yield to topic). (The DITA Help Subcommittee created a comparison table of 13008 vs 13060 features to help with deliberation of this issue.)

Benefits

Post-processing of Help outputs generated from DITA source would no longer be required, and context hook metadata could be maintained within the DITA source rather than outside it. This will benefit all Help authors currently creating context-sensitive Help from DITA source, and will also significantly reduce the technical barrier that currently prevents some authors using DITA for Help content.

Technical requirements

The resourceid would need to be modified in the DTD/Schema files. Toolkit implementations need to add map2context and dita2context transforms. A related new ditamap element defining the window referenced in the ua-window attribute would be required (see Proposal 13061).

DTD and Schema modifications

Element

resourceide element (topic/resourceid)
- id attribute
- appname attribute
- appid attribute
- context-string attribute
- yield-to-topic attribute
- ua-window attribute
- conref attribute
- %global-atts; (xtrf, xtrc) attributes
- %select-atts; attributes
- class attribute
The element is contained by prolog and topicmeta.
The element is not translatable.

Processing impact

Minor changes will be required to transform the resourceid element data into the appropriate Help context metadata for the delivery platform.
This feature will not impact on other processing features, except if a processing feature currently uses a workaround of using the resourceid element to generate context hooks.

Overall usability: There will be little impact on users who do not use context-sensitve Help, as the change only entails one extra optional element in the prolog or topicmeta. For users creating context-sensitive Help, the use of the changed element should be relatively easy, as the semantics of the new attributes are closely aligned to their practical application. The main semantic dischordance is the appid attribute, which in context-sensitive Help semantics, is to be used as the context id.

Costs

Maintainers of the DTDs and XSDs: Some changes to the map module and the topic module.
Editors of the DITA specification:
- Three existing topics will need to be edited (resourceid, topicref and topic).
- No substantial changes to the information architecture will be required.
Vendors of tools: Vendors of tools: Publishing tool changes could be implemented as XSL-T additions, at a relatively low (and one-off) cost. Authoring tool changes would only be required to provide an interface for applying the context hooks, at a relatively low cost.
DITA community-at-large. This feature adds a small degree of complexity, but delivers practical benefits that allow DITA to be used more practically for Help authoring.

Examples

<map title="Widget Help">
 <topicref href="" type="concept">
   <topicref href="" type="task">
     <topicmeta>
     <resourceid id="ab12" appname="ua" appid="1234" context-string="idh_filesave"
     yield-to-topic="true" />
     </topicmeta>
   </topicref>
   <topicref href="" type="task">
     <topicmeta>
      <resourceid id="ab34" appname="ua" appid="2345" context-string="idh_filedelete" />
      <resourceid id="ab56" appname="ua" appid="6789" context-string="idh_filekill" />
     <topicmeta>
   </topicref>
   <topicref href="" type="task">
     <topicmeta>
       <resourceid id="ab78" appname="ua" appid="5432" context-string="idh_fileedit" ua-window="csh"  />
     <topicmeta>
   </topicref>
</topicref>
</map>

<task id="fedt">
 <title>Editing a File</title>
 <prolog>
   <resourceid id="cd12" appname="ua" appid="5432" context-string="idh_fileedit" ua-window="csh" />
 </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>

SetCsh(0,"idh_filedelete",2345,"file_processing/deleting_files.htm");
SetCsh(1,"idh_filekill",6789,"file_processing/kill_files.htm");
</script>

<contexts>
	<context id="idh_filedelete" title="Deleting Files from the Main Panel">
		<description>Files can be deleted from the Main Panel using shortcut keys.</description>
		<command serialization="org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.fileops.delete.cheatsheet)quot; label="Pushing the panic button"/>
		<topic href="" label="Deleting Files from the Main Panel"/>
	</context>
	...
</contexts>

2345=file_processing/deleting_files.htm
6789=file_processing/kill_files.htm

#define idh_filedelete 2345
#define idh_filekill 6789

dita-help message

DITA 1.3 proposed feature 13060