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: RE: [dita-help] Review of Stage 3 Proposals


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.

Title: Stage 3 proposal: Feature #13061

Stage 3 proposal: Feature #13061

Allow window and viewport specifications for display of output content to be defined in the ditamap.

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

Approved technical requirements

If implemented as a specialization, new DTD/Schema files and alterations to the topic shells would be required. Toolkit implementations need to modify the map2hhp and similar collection (book) level transforms. A related new ua-context element with a ua-window attribute would be required (see the separate proposed feature 13060). The features attribute is modelled on the _javascript_ window.open method parameters.

Dependencies or interrelated proposals

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:

Modified DTDs

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


      

Modified specification documentation

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:

ua-window
The <ua-window> element enables authors to define windowing information for the display of output topics appropriate to the delivery platform. Window management is important in user assistance and Help system outputs, as well as for other hypertext delivery modes

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.

ua-window

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.

Inheritance

- map/ua-window

Example

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>

Attributes

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

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"

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

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 assistnace 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-window. The @ua-window 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 @yield-to-topic 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.



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