Stage 2 Proposals for DHSC Features

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

Greetings colleagues

As discussed at our last meeting(s), I have re-cast our two DITA 1.3
proposals into the Stage 2 templates, and have attached the two proposals in
DITA and HTML form. 

Would you please check through the proposals, as there is quite a bit of new
detail therein? We will discuss any suggestions for changes or corrections
at our next meeting, scheduled for Monday 22 July at 4.30 pm US EST. (Please
mark that date and time in your diary!) In the meantime, please feel free to
discuss any issues you may have via e-mail.

Best regards

Tony Self
Chair, OASIS DITA Help Subcommittee

Attachment: dita-proposal-csh-win_2.dita
Description: Binary data

Attachment: dita-proposal-csh_2.dita
Description: Binary data

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.

Date and version information

• The latest revision date for this proposed feature document is 2013 July 15.
• 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.

DITA does not provide any suitable metadata containers for context hooks. 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.

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, 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. 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 ua-context element, valid within the topicref element's topicmeta element and the topic element's prolog element. The ua-context element would contain optional attributes of id, context-id, context-string, and ua-window. None, one or many ua-context elements would 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 ua-context and the map's topicref's ua-context should be used.

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 ua-context element could possibly be implemented as a specialisation of resourceid.

If implemented as a specialisation, new DTD/Schema files and alterations to the topic shells would be required. 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.

Provide a detailed description of how the solution will work. Be sure to include the following details:

DTD and Schema modifications

Element

• ua-context element (topic/resourceid topic/ua-context)
  • id attribute
  • context-id attribute
  • context-string attribute
  • yield-to-topic attribute
  • ua-window attribute
  • %global-atts; (xtrf, xtrc) 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 ua-context 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 new element should be relatively easy, as the semantics of the attributes are closely aligned to their practical application. (In other words, Help authors know what a context id and a context string are,and will therefore recognise the purpose of context-id and context-string attributes.

Costs

• Maintainers of the DTDs and XSDs: Some changes to the map module and the topic module.
• Editors of the DITA specification:
  • One new topics will be required (ua-context)
  • Two existing topics will need to be edited (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>
     <ua-context id="ab12" context-id="1234" context-string="idh_filesave"
     yield-to-topic="true" />
     </topicmeta>
   </topicref>
   <topicref href="" type="task">
     <topicmeta>
      <ua-context id="ab34" context-id="2345" context-string="idh_filedelete" />
      <ua-context id="ab56" context-id="6789" context-string="idh_filekill" />
     <topicmeta>
   </topicref>
   <topicref href="" type="task">
     <topicmeta>
       <ua-context id="ab78" context-id="5432" context-string="idh_fileedit" ua-window="csh"  />
     <topicmeta>
   </topicref>
</topicref>
</map>

<task id="fedt">
 <title>Editing a File</title>
 <prolog>
   <ua-context id="cd12" context-id="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>

Title: DITA 1.3 proposed feature 13061

DITA 1.3 proposed feature 13061

Allow window specifications for display of online content to be defined in the ditamap.

Date and version information

• The latest revision date for this proposed feature document is 2013 July 15.
• 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 (or User Assistance) delivery platforms often provide window management features, which allow the Help author to specify the characteristics of a window that a topic displays in. This may apply to the main Help window when invoked, to ensure it displays in a position on the screen that allows the application or controls and its Help to both be seen. This can also apply to a secondary window that displays alongside the main window.

DITA does not provide any suitable metadata containers for window specifications. Including windowing metadata at the ditamap level would allow processors to generate windowing information appropriate to the delivery platform. Window management is also important in non-Help hypertext delivery modes, so windowing metadata containers may have usefulness beyond Help and User Assistance.

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

Proposed solution

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.

The ua-window element cannot be easily specialised from an existing element.

Benefits

Post-processing of Help outputs generated from DITA source would no longer be required, and window 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. It will also benefit authors of other hypertext deliverables that incorporate window management features.

Technical requirements

If implemented as a specialisation, new DTD/Schema files and alterations to the topic shells would be required. Toolkit implementations need to modify the map2hhp and similar collection (book) level transforms. A related new ua-context element with a ua-window attribute would be required (see the separate proposed feature 13060). The features attribute is modelled on the _javascript_ window.Open method parameters.

DTD and Schema modifications

Element

• ua-window element
  • id attribute
  • name attribute
  • top attribute
  • left attribute
  • height attribute
  • width attribute
  • on-top attribute
  • features attribute
  • relative attribute
  • full-screen attribute
• The element is contained by map.
• None, one or many ua-window elements would be permitted within the parent element.
• The element is not translatable.

Processing impact

• Minor changes will be required to transform the ua-window element data into the appropriate Help window metadata for the delivery platform.
• This feature will not impact on other processing features.

Overall usability

There will be little impact on users who do not use Help windowing, as the change only entails one extra optional element in the map. For users creating context-sensitive Help, the use of the new element should be relatively easy, as the semantics of the attributes are closely aligned to that used in the Web browser Document Object Model. Help authors familiar with window management using _javascript_ will recognise the attributes within ua-window.

Costs

• Maintainers of the DTDs and XSDs: Some changes to the map module.
• Editors of the DITA specification:
  • One new topics will be required (ua-window)
  • One existing topic will need to be edited (map).
  • 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 defining the windows, 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">
<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="" type="concept">
   <topicref href="" type="task" />
   <topicref href="" type="task" />
   <topicref href="" type="task">
     <topicmeta>  
       <ua-context context-id="5432" context-string="idh_fileedit" ua-window="csh" />
     </topicmeta>
   </topicref>
</topicref>
</map>