OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-help message

[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 Subcommittee


Title: Stage 3 proposal: Feature #13060

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.

Champion

This proposal was developed and championed by the DITA Help Subcommittee, under the direction of Tony Self and Stan Doherty.

Tracking information

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    

Approved technical requirements

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

Dependencies or interrelated proposals

This proposal is interrelated to Proposal 13061 (window specifications). This Proposal is also related to Proposal 13008, which proposes one of the changes incorporated in this Proposal.

Containment

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

Modified DTDs

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"
  >

Modified specification documentation

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
  • Description: "The value used by a specific application to identify the topic."
  • Default Value: "#REQUIRED"
  • Required?: "Yes"
  • Description: conref the description of id used by other elements; followed by another paragraph: "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."
  • Default Value: "#IMPLIED"
  • Required?: "No"
 
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
  • Description: "An ID used by an application to identify the topic."
  • Data Type: CDATA
  • Default Value: "#IMPLIED"
  • Required?: "No"
 
ua-context-string attribute n/a  
  • Description: Contains the value of a user assistance (Help) context-string used to identify the topic.
  • Data Type: CDATA
  • Default Value: "#IMPLIED"
  • Required?: "No"
ua-source-priority attribute n/a  
  • Description: Contains a value which indicates the precedence of context hooks in the map and context hooks in the topic. (This attribute is only valid when used within a topicref in a map.)
  • Data Type: (topic-and-map | topic-only | map-only | map-takes-priority | topic-takes-priority | -dita-use-conref-target)
  • Default Value: topic-and-map
  • Required?: "No"
ua-windowref attribute n/a  
  • Description: Contains the name of the ua-window element which will be used to display this topic when called from a Help API.
  • Data Type: CDATA
  • Default Value: "#IMPLIED"
  • Required?: "No"

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        

New architectural specification topic (after 2.1.3.8) - Help systems and other User Assistance

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 attributes that are used for context hooks are:
@appid
An ID used by an application to identify the topic.
@ua-context-string
Contains the value of a user assistance (Help) context-string used to identify the topic.
@ua-source-priority
Contains a value that 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.)
@ua-windowref
Contains the name of the window to be used to display the Help topic, with that window's characteristics separately defined in a <ua-window> element in the DITA map.

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.

Title: Stage 3 proposal: Feature #13061

Stage 3 proposal: Feature #13061

Allow window and viewport specifications for display of output content to be defined in the ditamap.

Champion

This proposal was developed and championed by the DITA Help Subcommittee, under the direction of Tony Self and Stan Doherty.

Tracking information

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    

Approved technical requirements

A new ua-context base element with a ua-window attribute is required (see the separate proposed feature 13060). The features attribute is modelled on the _javascript_ window.open method parameters.
Note: After approval of 13061, the related proposed feature 13060 was changed to expand the resourceid element rather than create a new ua-context element.

Dependencies or interrelated proposals

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:

Modified DTDs

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;)*)"
>

Modified specification documentation

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:

ux-window
The <ux-window> element enables authors to define windowing information for the display of output topics appropriate to the delivery platform. Window management is important in user assistance and Help system outputs, as well as for other hypertext and electronic delivery modes.

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.

ux-window

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.

Inheritance

- map/ux-window

Example

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>

Attributes

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]