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


Help: OASIS Mailing Lists Help | MarkMail Help

dita-help message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Change to Proposal

Greetings colleagues

Earlier this week, Stan Doherty and myself met (via teleconference) with
Michael Priestley, Kris Eberlein, and Robert Anderson to discuss the
possible overlap between Robert's proposal for changes to <resourceid>, and
our own proposal for <ua-context> as a specialisation of <resourceid>. One
of the issues that had arisen was that our idea of specialising <ua-context>
from <resourceid> was not feasible, as <resourceid> didn't have enough
attributes to specialise from. So in order to create <ua-context>, we'd have
to modify <resourceid>. The consensus was that it might be better to simply
expand <resourceid> to include the attributes that we need for
context-sensitive Help, and not to create a specialised <ua-context>
I have revised the associated proposal 13060 to reflect this changed
approach, and have uploaded it to the DHSC documents area.

I've also attached the HTML version to this mail.

I think it would be a good idea to meet to discuss this change, to ensure
that everyone is happy with it, before proceeding further. We need to have
this discussion before the next scheduled meeting of 3 September. I would
like to propose that we meet at 4.30 pm US EST on Monday 26 August. Is that
particularly uncomfortable for anyone hoping to attend?

Kind regards

Tony Self
Chair -  OASIS DITA Help Subcommittee

Title: DITA 1.3 proposed feature 13060

DITA 1.3 proposed feature 13060

Allow context sensitive Help metadata to be defined in topic and topicref attributes by expanding the resourceid element.

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.)


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
  • 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.


  • 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.


<map title="Widget Help">
 <topicref href="" type="concept">
   <topicref href="" type="task">
     <resourceid id="ab12" appname="ua" appid="1234" context-string="idh_filesave"
     yield-to-topic="true" />
   <topicref href="" type="task">
      <resourceid id="ab34" appname="ua" appid="2345" context-string="idh_filedelete" />
      <resourceid id="ab56" appname="ua" appid="6789" context-string="idh_filekill" />
   <topicref href="" type="task">
       <resourceid id="ab78" appname="ua" appid="5432" context-string="idh_fileedit" ua-window="csh"  />
<task id="fedt">
 <title>Editing a File</title>
   <resourceid id="cd12" appname="ua" appid="5432" context-string="idh_fileedit" ua-window="csh" />
  <context>After you have created a new file, you can edit it.</context> 
	<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"/>
#define idh_filedelete 2345
#define idh_filekill 6789

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]