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: Draft Stage 3 Proposal for 13060

Greetings colleagues

I have completed the first cut of the Stage 3 Proposal document for Proposal
13060 (the resourceid element changes), and have attached it here in DITA
and HTML forms.

Would you please read through this document and see if I have correctly
translated the proposal from its earlier incarnation as a Stage 2 proposal
proposal-csh_13060.html)?  In particular, can you check the DTD and
specification sections to make sure I've got this right? 

I am progressing on the other proposal, 13061, and hope to send that through
in about 24 hours.


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.


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 would need to be modified in the DTD/Schema files. 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 (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.

Modified DTDs

Changes impact metaDecl.mod (and equivalent Schema file). Modified lines in bold:

<!ENTITY % resourceid.attributes
                     (topic-and-map | topic-only | map-only | map-takes-priority | topic-takes-priority | -dita-use-conref-target)

Modified specification documentation

The specification changes for this proposal affect only one topic in the Specification: 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 for 1.3
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.

   <resourceid appid="sqlid00375" appname="dbaccess"/>
   <resourceid appid="sample" appname="otherApp1"/>
   <resourceid appid="sample" appname="otherApp2"/>

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="">
     <navtitle>Sample: adding a resourceid externally</navtitle>
     <resourceid appname="Author-B-App" appid="FunNewId"/>

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">
     <resourceid id="ab12" appname="ua" appid="1234" context-string="idh_filesave"
     source-priority="topic-only" />
   <topicref href="" type="task">
      <resourceid id="ab34" appname="ua" 
           appid="2345" context-string="idh_filedelete" />
      <resourceid id="ab56" appname="ua" 
           appid="6789" context-string="idh_filekill" />
   <topicref href="" type="task">
       <resourceid id="ab78" appname="ua" 
            appid="5432" context-string="idh_fileedit" ua-window="csh"  />

In the following example, a user assistance context hook, made up of a context ID (appid) and a context string (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>
   <resourceid id="cd12" appname="ua" 
         appid="5432" context-string="idh_fileedit" ua-window="csh" />
  <context>After you have created a new file, you can edit it.</context> 
@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"
@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"
@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-window attribute n/a  
  • Description: Contains a reference to 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"

Attachment: Stage-3-proposal-13060.dita
Description: Binary data

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]