When a Help system is invoked from an application, it is desirable to specify the size, position and behaviour of the window displaying the Help content. Some Help Application Programming Interfaces (APIs) provide for a window name to be passed in the Help call. In some cases, the definition for the window of the called window definition will be embedded in the Help system. In other cases, the complete window definition information will be passed in the Help call itself.
To cater for Help systems with embedded window information, it is important to define that information in the ditamap being processed, so that the processor can incorporate the definitions in the generated output file.
This proposal suggests adding a ua-window element, valid within the map element. The ua-window element would contain optional attributes of id, name, top, left, height, width, on-top, features, relative, and full-screen. None, one or many ua-window elements would be permitted within the parent element. The relative attribute is a Boolean flag used to indicate whether the window dimensions are relative to the calling window, or are absolute positions.
<map title="Widget Help"> <ua-window id="fg23" name="csh" top="10" left="20" height="400" width="500" features="status=yes,toolbar=no,menubar=no,location=no" relative="true", 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>
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) topic number and (optional) window descriptor. The window descriptor is used to define the dimensions and other characateristics of the window into which a Help topic will display. The Help author wants to control the window descriptor, rather than the developer, as the window characteristics are dependent upon the nature of the topic content. The Help author therefore must create and store keyed window definitions at the publication (ditamap) level, and pass the window descriptor (keys) to the developer for integration with the application code.
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 the defining window descriptors and characteristics, at a relatively low cost.
Post-processing of Help outputs generated from DITA source would no longer be required, and window metadata could be maintained within the DITA source rather than outside it.