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] Feedback on latest 13060/13061 Stage-3 Proposals

For DITA 1.3, we'll have the XML mention domain and hopefully will be able to round up the resources to implement the markup throughout the spec.


Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
+1 919 682-2290; kriseberlein (skype)

On 11/1/2013 12:00 PM, Tony Self wrote:
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.



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


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?


- 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

map                                            Scope = the referenced topic
  topicref                                     - caveats on @source-priority

topic                                          Scope = the referenced topic

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

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:

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