[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Latest version of CSH Proposal (13060)
Greetings colleagues In preparation for Monday afternoon's (US time) meeting, please find attached an HTML version of the latest iteration of the context-sensitive Help proposal 13060. The most recent change is to specify that if there are multiple windows with the same name specified in the map, the first window encountered will be used by the ux-windowref attribute. I have also attached the latest incarnation of the associated window definition proposal, 13061. The most recent change to this following its review has been to move the ux-window element to being a child of topicmeta, which allows multiple window definitions to be grouped. This position also better caters for re-use of window definitions in "sub-maps". I will explain these changes at the meeting. Tony Self Chair - OASIS DITA Help SubcommitteeTitle: Stage 3 proposal: Feature #13060
Allow context sensitive Help metadata to be defined in topics and maps by expanding the resourceid element's attribute set.
This proposal was developed and championed by the DITA Help Subcommittee, under the direction of Tony Self and Stan Doherty.
Event | Date | Links |
---|---|---|
Stage 1 proposal accepted | 2 August 2011 | Minutes |
Stage 2 proposal submitted | 26 August 2013 | HTML, DITA |
Stage 2 proposal discussed | 27 August 2013 | Minutes |
Stage 2 proposal approved | 3 September 2013 | Minutes |
Stage 3 proposal submitted to reviewers | 17 October 2013 | DHSC |
Stage 3 proposal (this document) submitted |
The resourceid element would need to be modified in the DTD/Schema files to incorporate new attributes of context-string, source-priority, and ua-windowref. The data and data-about elements should also be allowed within resourceid. A related new ditamap element defining the window referenced in the ua-windowref attribute would be required (see Proposal 13061).
Container(s) | Application |
---|---|
map/topicmeta/resourceid | Not applicable |
map/topicref/topicmeta/resourceid | The referenced topic |
topic/topicmeta/resourceid | The topic |
map/mapref/resourceid | Not applicable |
Changes impact metaDecl.mod (and equivalent Schema file). Modified lines in bold:
<!ENTITY % resourceid.content "(%data.elements.incl;)*" > <!ENTITY % resourceid.attributes "%select-atts; %localization-atts; id CDATA #IMPLIED %conref-atts; appname CDATA #IMPLIED appid CDATA #IMPLIED ua-context-string CDATA #IMPLIED ua-source-priority (topic-and-map | topic-only | map-only | map-takes-priority | topic-takes-priority | -dita-use-conref-target) topic-and-map ua-windowref CDATA #IMPLIED" >
The specification changes for this proposal affect only one topic in the Specification: 3.1.3.1.22 resourceid. The table below shows the changes required in the Specification in addition to those changes already proposed in Proposal 13008.
Location | Text in 1.2 | Proposed changes for related Proposal 13008 | Proposed additions to Proposal 13008 changes |
---|---|---|---|
Short description and introductory text |
The <resourceid> element provides an identifier for applications that require them in a particular format, when the normal id attribute of the topic cannot be used. Each resourceid entry should be unique. While DITA only requires IDs to be unique within a single topic or map, applications using the resourceid will generally require IDs to be universally unique or unique within a given collection of topics. |
The <resourceid> element provides an identifier for applications that must use their own identifier scheme, such as context-sensitive help systems and databases. Multiple appid values may be associated with a single appname value, and multiple appname values may be associated with a single appid value. Because the values for the appid and appname attributes work in combination to specify a specific ID for a specific application, each combination of values for the appid and appname attributes should be unique. Versions of DITA before 1.3 used the id attribute on the <resourceid> element to specify an ID for an external application. This use of the id attribute is deprecated in favor of using the appid attribute. |
|
Example section |
<prolog> <resourceid id="sqlid00375" appname="dbaccess"/> </prolog> |
In the following example, a topic is referenced by three applications. <prolog> <resourceid appid="sqlid00375" appname="dbaccess"/> <resourceid appid="sample" appname="otherApp1"/> <resourceid appid="sample" appname="otherApp2"/> </prolog> A database application with a value of "dbaccess" for the appname attribute references the topic using the ID "sqlid00375". Two other applications use the ID "sample"; differing values for the appname attribute distinguish between these two applications and the <resourceid> elements that are associated with them. If this topic is reused by another author, that author may associate additional <resourceid> elements with the topic by placing them in the map. For example, the following entry in the <topicmeta> indicates that (in addition to the values already specified in the topic), an application with the value of "Author-B-App" references the topic using the ID "FunNewId":<topicref href=""> <topicmeta> <navtitle>Sample: adding a resourceid externally</navtitle> <resourceid appname="Author-B-App" appid="FunNewId"/> </topicmeta> </topicref> |
In the following example, user assistance context hooks are being applied to three topics. The second topic has two hooks for the same topic. <map title="Widget Help"> <topicref href="" type="concept"> <topicref href="" type="task"> <topicmeta> <resourceid id="ab12" appname="ua" appid="1234" ua-context-string="idh_filesave" ua-source-priority="topic-only" /> </topicmeta> </topicref> <topicref href="" type="task"> <topicmeta> <resourceid id="ab34" appname="ua" appid="2345" ua-context-string="idh_filedelete" /> <resourceid id="ab56" appname="ua" appid="6789" ua-context-string="idh_filekill" /> <topicmeta> </topicref> <topicref href="" type="task"> <topicmeta> <resourceid id="ab78" appname="ua" appid="5432" ua-context-string="idh_fileedit" ua-windowref="csh" /> <topicmeta> </topicref> </topicref> </map> In the following example, a user assistance context hook, made up of a context ID (appid) and a context string (ua-context-string) pair, is defined in the prolog of a task topic. A user assistance window is also referenced for this topic. <task id="fedt"> <title>Editing a File</title> <prolog> <resourceid id="cd12" appname="ua" appid="5432" ua-context-string="idh_fileedit" ua-windowref="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> |
Contains section | For all Doctypes, Content Model will
be:(data or data-about) (any number) |
||
id attribute definition |
|
|
|
appname attribute | Contains the name of the application that will use the resource id to identify the topic. | A name for the external application that references the topic. | |
appid attribute definition | n/a |
|
|
ua-context-string attribute | n/a |
|
|
ua-source-priority attribute | n/a |
|
|
ua-windowref attribute | n/a |
|
The consolidated Attributes section would therefore be as in the following table.
Name | Description | Data Type | Default Value | Required? |
---|---|---|---|---|
id |
An anchor point. This ID is the target for references by href and conref attributes and for external applications that refer to DITA content. See ID attribute in the Architectural Specification for more details. Prior to DITA 1.3, this attribute specified a value used by a specific application to identify the topic. That usage is deprecated in favor of using the appid attribute. |
NMTOKEN | #IMPLIED | No |
appname | A name for the external application that references the topic. | CDATA | #IMPLIED | Yes |
appid | An ID used by an application to identify the topic. | CDATA | #IMPLIED | No |
ua-context-string | Contains the value of a user assistance (Help) context-string used to identify the topic. | CDATA | #IMPLIED | No |
ua-source-priority | Contains a value which indicates the precedence of context hooks in the map and context hooks in the topic. (This usage is defined when the attribute is used on resourceid within a DITA map; using this attribute on resourceid within a topic is undefined and reserved for future use.) | (topic-and-map | topic-only | map-only | map-takes-priority | topic-takes-priority | -dita-use-conref-target) | topic-and-map | No |
ua-windowref | Contains the name of the ua-window element which will be used to display this topic when called from a Help API. When there are multiple ua-window elements with that name, the element selected is the one that is first, in document order, within the map document that contains it, and is the first in the map tree in breadth-first order. | CDATA | #IMPLIED | No |
%select-atts; attributes | ||||
%localization-atts; attributes | ||||
%global-atts; attributes | ||||
class |
Help systems for software applications, and other types of User Assistance content such as tooltips, 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 platforms, they can always be considered as metadata. Including context hook metadata in the <resourceid> element in the DITA map (topicref) or in the topic metadata allows processors to generate the header, map, alias and other types of support files required to integrate the user assistance with the application. Some user assistance topics may be required to display in a specific named window or viewport, and this windowing metadata can be defined in the DITA map within the <ua-window> element.
Software application user interfaces can be linked to user assistance information (such as Help systems and tooltips) using context hooks. These hooks are simply identifiers that associate a part of the user interface with the location of a Help topic. Context hooks are sometimes direct links to URLs, but are more often indirect links that use numeric context identifiers and/or context strings in conjunction with an intermediary mapping file that associates the context hook with the location of the Help topic. A similar mapping file is used in the software application to associate the user interface controls with the context hook. A Help API (Application Programming Interface) is typically used to simplify the process for both software developer and Help author. The mapping files used to associate user interface controls and context hooks, and context hooks and Help topics, are known as header files, map files, or alias files, depending upon the Help API.
Context identifiers can define one-to-one relationships with user interface controls and topics, or one-to-many relationships (one Help topic is associated with many user interface controls).
In some Help systems, information topics may be required to display in a specifically sized or featured window. For example, a Help topic may need to be displayed immediately adjacent to the user interface control it supports in a window of a specific size that always remains on top regardless of the focus within the operating system.
Context hook information can be defined within DITA topics and/or within DITA maps, as attributes of the <resourceid> element.
The <ua-window> element provides attributes of @top, @left, @height, @width, @on-top, @features, @relative, and @full-screen.
To avoid problems where context hooks defined in the DITA map potentially conflict with those defined in the topics, a @ua-source-priority attribute can be used to indicate how these potential conflicts should be resolved. This attribute may only be defined in the DITA map.
Context hook and windowing information is ignored if the processor (the software producing the output Help or user assistance files) does not support this metadata.
Allow window and viewport specifications for display of output content to be defined in the ditamap.
This proposal was developed and championed by the DITA Help Subcommittee, under the direction of Tony Self and Stan Doherty.
Event | Date | Links |
---|---|---|
Stage 1 proposal accepted | 2 August 2011 | Minutes |
Stage 2 proposal submitted | 31 July 2013 | HTML, DITA |
Stage 2 proposal discussed | 13 August 2013 | Minutes |
Stage 2 proposal approved | 20 August 2013 | Minutes |
Stage 3 proposal submitted to reviewers | 18 October 2013 | DHSC |
Stage 3 proposal (this document) submitted |
This proposal is dependent upon Proposal 13060 (enhancing the resourceid element, in which a ux-windowref attribute references the window name). Modified or new lines in bold:
map.mod <!-- ============================================================= --> <!-- ELEMENT NAME ENTITIES --> <!-- ============================================================= --> ... <!ENTITY % ux-window "ux-window" > ... <!-- ============================================================= --> <!-- ELEMENT DECLARATIONS --> <!-- ============================================================= --> ... <!-- LONG NAME: Topic Metadata --> <!ENTITY % topicmeta.content "((%navtitle;)?, (%linktext;)?, (%searchtitle;)?, (%shortdesc;)?, (%author;)*, (%source;)?, (%publisher;)?, (%copyright;)*, (%critdates;)?, (%permissions;)?, (%metadata;)*, (%audience;)*, (%category;)*, (%keywords;)*, (%prodinfo;)*, (%othermeta;)*, (%resourceid;)*, (%ux-window;)*, (%data.elements.incl; | %foreign.unknown.incl;)*)" > ... <!-- LONG NAME: User Experience Window --> <!ENTITY % ux-window.content "EMPTY" > <!ENTITY % ux-window.attributes "%id-atts; %select-atts; name CDATA #REQUIRED top CDATA #IMPLIED left CDATA #IMPLIED height CDATA #IMPLIED width CDATA #IMPLIED on-top (yes| no -dita-use-conref-target) no features CDATA #IMPLIED relative (yes| no -dita-use-conref-target) no full-screen (yes| no -dita-use-conref-target) no > <!ELEMENT ux-window %ux-window.content;> <!ATTLIST ux-window %ux-window.attributes;> ... <!-- ============================================================= --> <!-- SPECIALIZATION ATTRIBUTE DECLARATIONS --> <!-- ============================================================= --> ... <!ATTLIST ux-window %global-atts; class CDATA "- map/ux-window " >
bookmap.mod ... <!-- ============================================================= --> <!-- ELEMENT DECLARATIONS --> <!-- ============================================================= --> ... <!-- LONG NAME: Book Metadata --> <!ENTITY % bookmeta.content "((%linktext;)?, (%searchtitle;)?, (%shortdesc;)?, (%author;)*, (%source;)?, (%publisherinformation;)*, (%critdates;)?, (%permissions;)?, (%metadata;)*, (%audience;)*, (%category;)*, (%keywords;)*, (%prodinfo;)*, (%othermeta;)*, (%resourceid;)*, (%ux-window;)*, (%bookid;)?, (%bookchangehistory;)*, (%bookrights;)*, (%data;)*)" >
The topic Map and map group elements (2.1.2.2.3) will need to be changed in the Architectural Specification to add the ux-window element. The new definition list item (to be added after topicmeta) is:
A new topic for the Language Reference section of the specification will be required. The new topic should be added at the end of the map section as 3.1.2.1.11.
The <ux-window> element represents a specification for a window or viewport in which an output user assistance topic or Web page may be displayed if referenced in the topic's or topicref's <resourceid> element.
The <ux-window> element may be used anywhere within a map (including a bookmap), contained in a <topicmeta> element. The window specification defined in the <ux-window> element can be referenced by any <resourceid> element (through the @ux-windowref attribute), regardless of the position of the <ux-window> element in the hierarchy of the map. If more than one <ux-window> element has the same @name attribute, the window specification in the first instance of the element will be used.
- map/ux-window
In this example, a window with a name of csh is defined in the map, and that window name is later referenced in the <resourceid> element's ux-window attribute.
<map title="Widget Help"> <topicmeta> <ux-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" /> </topicmeta> <topicref href="" type="concept"> <topicref href="" type="task" /> <topicref href="" type="task" /> <topicref href="" type="task"> <topicmeta> <resourceid id="ab43" appname="ua" appid="5432" ua-context-string="idh_fileedit" ux-windowref="csh" /> </topicmeta> </topicref> </topicref> </map>
In this example, different window specifications are defined for tablet and desktop presentation.
<map title="Puggles Help"> <topicmeta> <ux-window id="p76" name="ux-tablet" top="5%" left="5%" height="90%" width="90%" features="status=no,toolbar=no,menubar=no,location=no" relative="false", full-screen="no" /> <ux-window id="p80" name="ux-deskop" top="5%" left="55%" height="60%" width="40%" features="status=yes,toolbar=no,menubar=no,location=yes" relative="false", full-screen="no" /> </topicmeta> <topicref href="" type="concept"> ... </topicref> </map>
Name | Description | Data Type | Default Value | Required? |
---|---|---|---|---|
name | The value used to refer to this window definition. | CDATA | #REQUIRED | Yes |
top | The top position of the window. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: 5, 5in, and 10.5cm. | CDATA | #IMPLIED | No |
left | The left position of the window. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels).Possible values include: 5, 5in, and 10.5cm. | CDATA | #IMPLIED | No |
height | The height of the window. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: 5, 5in, and 10.5cm. | CDATA | #IMPLIED | No |
width | The width of the window. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: 5, 5in, and 10.5cm. | CDATA | #IMPLIED | No |
on-top | Indicates whether the window that stays on top of all windows on the desktop rather than staying on top of only the calling window. | (yes | no) | no | No |
features | A list of other features (size, position, scrollbars, etc.) of the window. Each feature name and value must not contain any blank space, and each feature name and value must be separated by a comma or other delimiter character. | CDATA | #IMPLIED | No |
relative | Indicates whether the window dimensions are relative to the calling window, or are absolute positions. | (yes | no) | no | No |
full-screen | Indicates whether the window should be displayed in a maximized state. | (yes | no) | no | No |
%id-atts; attributes | ||||
%select-atts; attributes |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]