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: Context-Sensitive Help Proposal for DITA 1.3


Greetings colleagues

At the last DITA Help Subcommittee meeting, I promised to summarise the
issues around the proposal for context-sensitive Help that the DHSC
prepared, but which has not yet been progressed. The reason it was not
progressed was because it was thought that a separate proposal by Robert
Anderson (13008) would meet our needs. 

The resourceid element in DITA 1.2 has two attributes: id (required) and
appname. 

The DHSC proposal was for the resourceid element to be specialised to a new
element called ua-context, with attributes of id, context-id,
context-string, ua-window, and yield-to-topic. 
https://www.oasis-open.org/committees/download.php/39555/dita-proposal-csh.h
tml

The 13008 proposal was for the resourceid element to be changed to add a new
attribute of appid, and to make the id attribute optional.
https://www.oasis-open.org/committees/download.php/46783/13008appid-stage3.h

The resourceid element, and therefore the proposed ua-context element, is
permitted in the topic prolog and the topicref othermeta.

As background, a call from an application to a Help system is typically
achieved through a Help API. The context hooks that associate topics with
user interface objects are often name-value pairs (number and name),
strings, numbers, or URLs. Even relatively new APIs follow this pattern, so
the need for context hooks in DITA source would appear to be still valid.
(RoboHelp 10 has an HTML5 Help API which uses a context id in the Help
call.) Workarounds in current DITA processors can extract context hooks from
resourceid elements with a specific appname attribute (eg, "WindowsHelpID")
and create name-value pairs with non-descriptive strings by adding creating
a string from the resourceid id attribute by prefixing it with, for example,
identity_. 

The 13008 proposal isn't flexible enough to meet the requirements set out in
the Use Case for the DHSC proposal. While the 13008 proposal would allow
name-value pairs for context hooks to be stored easily within the resourceid
element, because the extra appid attribute could be used to store the value
needed to identify the resource as a Help context hook, leaving id and
appname for the name-value pair. However, the 13008 proposal does not allow
for the window name to be specified, nor an attribute to indicate whether a
hook in the topic should take preference over the hook in the topicref
(yield-to-topic). Further, the 13008 proposal would probably not allow
aliases, where one string has more than one numeric value, because the id
attribute should be unique within the context of the topic or map. (It is
not unusual for there to be two context strings that both resolve to the
same context number, as in the case where there is a Print button on two
screens, but the same Help topic needs to be displayed when either is
called.

Consequently, there seems to be two courses of action: resurrect the DHSC
proposal, or expand the 13008 proposal to take new attributes.

Your thoughts on these options is sought!

Regards

Tony Self
Chair - DITA Help Subcommittee





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