DITA Proposed Feature # NN

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

Longer description

When a Help system is invoked from an application, it is desirable to specify the size, position and behaviour of the window containing 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 name will be embedded in the Help system. In other cases, the complete window definition information may be passed in the Help call itself.

To cater for Help systems with embedded window information, it is important for that information to be defined in the ditamap being processed, so that the processor can incorporate the definitions in the generated output file.

This proposal suggests adding a help-window element, valid within the map element. The help-window element would contain optional attributes of name, top, left, height, width, on-top, features, and full-screen. None, one or many help-window elements would be permitted within the parent element.

Example of markup:
  • <map title="Widget Help">
    <help-window name="ua" top="10" left="20" height="400" width="500" 
       features="status=yes,toolbar=no,menubar=no,location=no" 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>

Scope

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

Use Case

TBA

Technical Requirements

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

Costs

Toolkit changes could be implemented as XSLT additions, at a relatively low (and one-off) cost.

Benefits

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.

Time Required

TBA