[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita-help] Feedback on latest 13060/13061 Stage-3 Proposals
Dear Stan
With regard to the issue of <element> and @attribute conventions, I don't know which is correct. The existing Arch Spec mixes both. In general, it seems to different in the Lang Ref section to elsewhere. So changing these might be a waste of time. I have also marked them up as <synph>, but am not sure if this is how it's done elsewhere. My feeling is that this will have to be sorted out in an editing process later in the show.
----
On the matter of 13061:
With regards to the approved technical requirements, I don't think we can change that because it's a record of what was approved in Stage 2, isn't it? Now as I see it, ua-window could either be defined in map.mod or in its own module. I am completely out of my depth here (and don't believe it should be our decision anyway), but my guess is that the change should be added to maps.mod. That's what I've done in the proposal.
And that's how I interpreted our approved technical requirement statement of "if implemented as a specialization...". It could be part of the base, or it could be some (domain) specialization. Now, if indeed we are stating what the previously "approved technical specification" was, this Stage 3 proposal is suggesting it be implemented in the base map.mod, and we are saying that in the Modified DTD section.
The same sort of thing applies to the next point about processing specifics are outside the scope of this proposal. I agreed with you. But we did mention them in the previous proposal, and the template text for the "Approved technical requirements" section is "Provide a synopsis of the technical requirements as presented in the stage 2 proposal.", so we can't really change that. Likewise the mention of HTMLAnchorElement.target. We didn't mention it earlier, so we can't add it now.
We only mention <ua-context> in this Stage 3 proposal in that "Approved technical requirements" section, and I'm not sure what the best way to address this is. So I have added a Note that ua-context was subsequently changed to resourceid expansion.
With regard to the question of whether <ua-window> should be within <topicmeta>, I think it needs to be directly under map because topicmeta is permitted inside a topicref, and there would be confusion if a window was associated with a topic. A window belongs to the map as a whole, and should only be defined as a child of map.
With regard to whether left, top, right, height default to pixels, I've added the following (which is the same as for the image element):
>>
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.
<<
----
On the matter of 13060:
I have added a Containment section and table, though I have a few concerns because there is no suitable place for this in the Stage 3 Proposal template. I think there are four scenarios for context hooks: map/topicmeta/resourceid, map/mapref/resourceid, map/topicref/topicmeta/resourceid, and topic/topicmeta/resourceid. The first two are not applicable, as a context hook can only apply to a topic, and not to a map.
As with 13061, on the matter of DTDs, I think we are suggesting that metaDecl.mod is changed, and not that we are adding any additional module file. Wouldn't it be obvious to state that all topics and maps inheriting metaDecl.mod would inherit these new attributes?
With regard to the ua-window attribute, I agree there might be confusion with an attribute and an element with the same name. Looking elsewhere within DITA, adding ref seems to have been used previously (keys, @keyref; @conref), so I have made the attribute name change from ua-window to ua-windowref, leaving the <ua-window> element alone. Because this is a relatively big change, I will also send a separate e-mail around to highlight this.
With regard to the "can" or "must" for the windowing metadata, I was thinking that it could also be defined in the publishing routine, or even in an app itself. I'm happy to change it, but I think it's probably technically more correct as "can"?
All the other changes you mentioned have been incorporated.
So, please find attached two new version of the Stage 3 proposals (in HTML form). I guess we will have to submit them fairly soon, but I think we're quite close now.
Regards
Tony
-----Original Message-----
From: dita-help@lists.oasis-open.org [mailto:dita-help@lists.oasis-open.org] On Behalf Of Dr. Stanley Doherty
Sent: Wednesday, 30 October 2013 11:30 PM
To: dita-help@lists.oasis-open.org
Subject: [dita-help] Feedback on latest 13060/13061 Stage-3 Proposals
GREAT WORK TONY! Wow, this continues to mature -- love it!
All friendly suggestions below - - -
=======================================================================
13061
General: Anticipating editorial feedback down the road about using the <element> and @attribute conventions. Adding @ affects indefinite articles in running text.
Approved technical requirements
- "If implemented as a specialization . . . " -- what would the alternatives be? If this is a map domain specialization, architects would have to add it to their authoring shell DTDs. If we are proposing that we add it to the default map.dtd, we should say so.
- Probably important to note here that downstream HATs or processors will need to figure out how to transform this information. Processng specifics are outside the scope of this proposal.
- The example for JS window.open is great. Perhaps mentioning that will server as input to HTML5 HTMLAnchorElement.target would reduce any perception that we were restricted in supporting any flavor of downstream JS.
- Not sure that I understand the connection here to the <ua-context> element. Does not intersect with 13060 anymore.
Dependencies . . .
- Perhaps add that the sample .mod illustrates what someone would add to a current map authoring shell (in this case map.dtd).
Example . . .
- I would have expected to see <ua-window> within <topicmeta>. Any particular reason it needs to be separate from other map metadata elements?
Attributes . . .
- top/left/height/width measurements in pixels by default?
=======================================================================
13060
General:
- Anticipating editorial feedback down the road about using the <element> and @attribute conventions. Adding @ affects indefinite articles in running text.
- Somewhere near the beginning, including a table about valid containment would help a lot. As I was reading, I was scribbling something like the following cheat sheet.
Container(s) Sample <resourceid> markup Use case description
-------------- ------------------------------- --------------------------
map Scope = all referenced topics
topicmeta
resourceid
map Scope = the referenced topic
topicref - caveats on @source-priority
topicmeta
resourceid
topic Scope = the referenced topic
prolog
resourceid
Are these all the possibilities?
Example . . .
- Perhaps add that the sample .mod illustrates what <resourceid> will look like by default in DITA 1.3. All topics and maps inheriting metaDecl.mod would inherit these new attributes.
- Still scratching my bald head on the @ua-window attribute here. At a minimum, it feels a bit confusing (at least to me) to be defining attributes for a window target with the 13061 <ua-window> element and then calling that definition with an indentically named @ua-window attribute in 13060. I hesitate to suggest any name changes, but would @ua-window-target help with disambiguation?
New architectural specification topic
- Great stuff! Really!
- "user assistnace" typo in para-1
- should "windowing metadata can be defined . . ." in that same sentence actually be "windowing metadata must be defined . . . ". There is no place else.
- "To avoid problems . . . @yield-to-topic attribute" should be "To avoid problems . . . @source-priority attribute" ?
Title: 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.
| 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 |
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-windowref attribute would be required (see Proposal 13061).
| 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 |
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-windowref
CDATA
#IMPLIED"
>
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-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 (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-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>
|
| id attribute definition |
|
|
|
| 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 |
|
|
| context-string attribute | n/a |
|
|
| source-priority attribute | n/a |
|
|
| ua-windowref attribute | n/a |
|
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 relationship (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, @context-string, @source-priority, and @ua-windowref. The @ua-windowref attribute is used to specify 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 @source-priority attribute can be used to indicate how these potential conflicts should be resolved. This attribute can 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.
Allow window and viewport specifications for display of output content to be defined in the ditamap.
This proposal was developed and championed by the DITA Help Subcommittee, under the direction of Tony Self and Stan Doherty.
| 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 |
This proposal is dependent upon Proposal 13060 (enhancing the resourceid element, in which a ua-window attribute references the window name). Modified or new lines in bold:
map.mod
<!-- ============================================================= -->
<!-- ELEMENT NAME ENTITIES -->
<!-- ============================================================= -->
...
<!ENTITY % ua-window "ua-window" >
...
<!-- ============================================================= -->
<!-- ELEMENT DECLARATIONS -->
<!-- ============================================================= -->
<!-- LONG NAME: Map -->
<!ENTITY % map.content
"((%title;)?,
(%topicmeta;)?,
(%ua-window;)*,
(%anchor; |
%data.elements.incl; |
%navref; |
%reltable; |
%topicref;)* )"
>
...
<!-- LONG NAME: User Assistance Window -->
<!ENTITY % ua-window.content "EMPTY"
>
<!ENTITY % ua-window.attributes
"%id-atts;
%select-atts;
name
CDATA
#IMPLIED
top
CDATA
#IMPLIED
left
CDATA
#IMPLIED
height
CDATA
#IMPLIED
width
CDATA
#IMPLIED
on-top
(yes|no)
no
features
CDATA
#IMPLIED
relative
(yes|no)
no
full-screen
(yes|no)
no
>
<!ELEMENT ua-window %ua-window.content;>
<!ATTLIST ua-window %ua-window.attributes;>
...
<!-- ============================================================= -->
<!-- SPECIALIZATION ATTRIBUTE DECLARATIONS -->
<!-- ============================================================= -->
...
<!ATTLIST ua-window %global-atts; class CDATA "- map/ua-window " >
The topic Map and map group elements (2.1.2.2.3) will need to be changed in the Architectural Specification to add the ua-window element. The new definition list item (to be added after topicmeta) is:
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.
The <ua-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.
- map/ua-window
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 ua-window attribute.
<map title="Widget Help">
<ua-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" />
<topicref href="" type="concept">
<topicref href="" type="task" />
<topicref href="" type="task" />
<topicref href="" type="task">
<topicmeta>
<resourceid id="ab43" appname="ua"
appid="5432" context-string="idh_fileedit" ua-window="csh" />
</topicmeta>
</topicref>
</topicref>
</map>
| 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. 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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]