Hi Stan (and all)

The 13060 (resourceid) proposal is similar in scope to Robert Anderson’s proposal 13008, and unless I’m missing something, the structure of our proposal is pretty much identical to his. And that’s, I guess, as it should be, because his is a proposal to add attributes to resourceid, and ours is a proposal to add attributes to resourceid. But I have a nervous feeling that I must be missing something?

13061 (ua-window) is more complicated, because it is a new element. However, it is not as complicated as 13097, which is an entire new information type. Bearing in mind I am pushing the envelope of my capabilities here, with a new ua-window element within the map element, will there be anything other than map.mod that needs to be changed in the DTDs? Unless we are going to pull ua-window out into its own module (and as I say, I don’t have the requisite DTD skills to be definitive here), the new element should only impact that one file, shouldn’t it? I used the navref as a guide in this regard, as I thought it was a similar element in the sense that it only lives in the map and has no “contains” elements. The navref element is only mentioned in map.mod and mapgroup.mod. The ua-window element won’t be valid in the mapgroup elements (topicgroup, topichead, etc) because windows are defined way at the top of the map structure.

I went through map.mod in more detail, though, and as a result, I have expanded the modified DTD section of the proposal to show the sections affected, and bolding our new stuff.

In Section B of the Typical Stage 3 Outline information, I think the feature.mod, feature.ent and feature.dtd are therefore not applicable for our proposal.

I wonder whether you were also suggesting that we need an Architectural Specification change topic (Secction C Part 1). My view is that we only need to make changes in the Language Reference, but I am not firm on this either. I have found that we needed to change one of the topics in the Architectural Spec, and I’ve added this to the proposal too.

I’ve attached the latest HTML version of 13061 (windowing) so you can see what I mean.

What do you think?

And I also put together a new topic about Help and user assistance support for the Architectural Spec, and I’ve added that to the 13060 (context hook) proposal, even though it refers to both resourceid and ua-window. I think this is a useful addition… hope you all agree.

Tony

From: Stan Doherty [mailto:stan@modularwriting.com]
Sent: Thursday, 24 October 2013 11:51 PM
To: dita-help@lists.oasis-open.org; tself@hyperwrite.com
Cc: stan.doherty@mathworks.com
Subject: Re: [dita-help] Review of Stage 3 Proposals

Hi Tony --

Mea culpa -- I have been heads-down this past week finishing a talk (DITA and HTML5 jumpstart) for Joe's WritersUA conference next week.

What you have in the current Stage-3 documents is all good, but there quite a bit of additional material for the complete Stage-3 package (see outline below). Most of the missing material should be relatively easy to develop and I am able to make time this weekend+Monday+Tuesday to help with *.dtd, *.mod, *.ent, doc updates -- whatever. I can do a skypecall tonight (Thursday 07:30/EST or later) or tomorrow night to coordinate if you'd like.

I have also attached a few of the submitted Stage-3 PDFs from TechComm or from other TC members.

* proposal-13097-Troubleshooting_Stage3_08oct13.pdf: Bob Thomas' Stage-3 proposal for the new Troubleshooting

elements and topic. Perhaps the most complete of the set (including a plug-in).

* Proposal_13102_ReleaseManagement_Stage3.pdf: Tom Chiak's Stage-3 proposal for the release management

domain. It may be decent model for <ua-window>.

* Proposal_13008_resourceid_Stage3.pdf: Robert's @appid proposal for resourceid. Could be cloned in some sections

for 13060.

* proposal-13035-xmldomain-stage-3.dita.pdf: Eliot's xmldomain proposal. A nice clean example of Stage-3 for a set of

new elements. Perhaps a model for <ua-window>.

Sorry, again, to be late with this review. I'd be gald to help in whatever ways that I can this weekend.

/stan

TYPICAL STAGE-3 OUTLINE

--------------------------------------------------------------------------------------

A. Stage-3 Proposal Template
   1. Champion <section>
   2. Tracking information <section>
      - <ul> or (more often) a table with columns
        of Event, Date, and Links
      - (Optional) Link to available DITA-OT plug-in.
   3. Approved technical requirements
      - Text summary of what was approved in Stage-2 (changed
        or added) by way of attributes, elements, or topics --
        OR
      - Table specifying the changes/additions and a brief
        description of each item.
   4. Dependencies or inter-related proposals:
      - DITA 1.3 proposal # + one-line description

B. Structural implementation
   1. (If applicable) feature.dtd listing (with optional description or
      commentary. Showing a specialized version of topic.dtd with
      new elements integrated seems to be sufficient.
   2. (If applicable) feature.mod listing (with optional description or
      commentary.
   3. (If applicable) feature.ent listing (with optional description or
      commentary.

C. Specification documentation
   1. Changes to the Architectural Specification
      - Overview description of the changes
      - Ready-to-insert <sections> or topics
      - One or more examples
      - Topic-by-topic updates or additions to the ArchSpec
   2. Changes to the Reference Spec
      - Overview description of the changes
      - Ready-to-insert <sections> or topics
      - One or more examples
      - Attributes table (no fancy xrefs a la the current spec)
      - Topic-by-topic updates or additions to the RefSpec
        > Each new element gets a ref topic

> On October 23, 2013 at 6:24 PM Tony Self <tself@hyperwrite.com> wrote:
>
> Greetings colleagues
>
> The deadline for the Stage 3 Proposals submission is looming, and I haven't
> received any comments back yet. I think I will have to submit it as is in
> the next couple of days if I don't hear anything further, so I hope it is
> essentially correct!
>
> Regards
>
> Tony Self
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail. Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>

Stan Doherty
Director, Technical Publications
Verivue Inc.

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.	CDATA	#IMPLIED	No
left	The left position of the window.	CDATA	#IMPLIED	No
height	The height of the window.	CDATA	#IMPLIED	No
width	The width of the window.	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. The string must not contain any blank space, each feature name and value must be separated by a comma.	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

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

dita-help message

Stage 3 proposal: Feature #13061

Champion

Tracking information

Approved technical requirements

Dependencies or interrelated proposals

Modified DTDs

Modified specification documentation

ua-window

Inheritance

Example

Attributes

Stage 3 proposal: Feature #13060

Champion

Tracking information

Approved technical requirements

Dependencies or interrelated proposals

Modified DTDs

Modified specification documentation

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