Draft Stage 3 Proposal for 13060

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 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
                "%select-atts;
                 %localization-atts;
                 id
                    CDATA
                            #IMPLIED
                 %conref-atts;
                 appname
                     CDATA
                            #IMPLIED
                 appid
                     CDATA
                            #IMPLIED
                context-string
                     CDATA
                            #IMPLIED
                 source-priority
                     (topic-and-map | topic-only | map-only | map-takes-priority | topic-takes-priority | -dita-use-conref-target)
                            topic-and-map
                 ua-window 
                     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 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=""> <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" context-string="idh_filesave" source-priority="topic-only" /> </topicmeta> </topicref> <topicref href="" type="task"> <topicmeta> <resourceid id="ab34" appname="ua" appid="2345" context-string="idh_filedelete" /> <resourceid id="ab56" appname="ua" appid="6789" context-string="idh_filekill" /> <topicmeta> </topicref> <topicref href="" type="task"> <topicmeta> <resourceid id="ab78" appname="ua" appid="5432" context-string="idh_fileedit" ua-window="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 (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" 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>
@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"