Stage 3 proposal: Feature #13008

Add @appid as a new optional CDATA attribute on <resourceid> and make the existing @id optional.

Champion

Each version of this proposal was prepared by Robert Anderson.

Tracking information

Event Date Links
Stage 1 proposal accepted June 28, 2011 Minutes from 6/28
Stage 2 proposal submitted December 30, 2011 HTML, DITA
Stage 2 proposal discussed January 3, 2012 Minutes
Stage 2 proposal approved January 10, 2012 Minutes
Stage 3 proposal submitted to reviewers August 20, 2012 Kris Eberlein, Stan Doherty, Don Day
Stage 3 proposal submitted August 28, 2012 This document

Approved technical requirements

  • Add a new attribute named "appid" to the <resourceid> element.
  • Authors that use <resourceid> today can migrate as time permits (@id will be deprecated for use as the application ID, but will still be allowed in the absence of @appid). Those that cannot use <resourceid> today due to the limitations of @id can begin to use it.
  • Tools that currently process resourceid/@id will need to check first for resourceid/@appid, and then fall back to @id if it is not found.

Dependencies or interrelated proposals

Proposals discussed at the DITA for Help subcommittee will likely make use of this change, but this change to resourceid does not depend on or interact with any other submitted proposals.

Modified DTDs

Changes impact metaDecl.mod (and equivalent Schema file). Modified lines in bold:
<!ENTITY % resourceid.attributes
                 "%select-atts;
                  %localization-atts;
                  id 
                      CDATA 
                           #IMPLIED 
                  %conref-atts;
                  appname 
                      CDATA 
                           #IMPLIED 
                  appid
                      CDATA 
                           #IMPLIED" 
>

Modified specification documentation

The specification changes for this requirement are minimal, affecting only one topic, so for ease of review I'm placing the old / new text side by side in this table. All of the changes are in the language specification topic for the <resourceid> element (though the changes from this proposal may lead to new text covered in other proposals, such as from the DITA for Help subcommittee).

Location Text in 1.2 Proposed changes 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.

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