[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Stage 2 Proposals for DHSC Features
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
DITA 1.3 proposed feature 13060Allow context sensitive Help metadata to be defined in topic and topicref attributes. Date and version information
Original requirement or use caseHelp 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 casesA 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 solutionThis 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. BenefitsPost-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 requirementsThe 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:
Costs
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> |
DITA 1.3 proposed feature 13061Allow window specifications for display of online content to be defined in the ditamap. Date and version information
Original requirement or use caseHelp (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 casesA 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 solutionWhen 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. BenefitsPost-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 requirementsIf 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.
Costs
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> |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]