[OASIS Issue Tracker] Commented: (WSCALENDAR-306) Text andReference Issues PR02

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ http://tools.oasis-open.org/issues/browse/WSCALENDAR-306?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=25369#action_25369 ] 

Toby Considine commented on WSCALENDAR-306:
-------------------------------------------

Converted to multiple issues and re-entered

> Text and Reference Issues PR02
> ------------------------------
>
>                 Key: WSCALENDAR-306
>                 URL: http://tools.oasis-open.org/issues/browse/WSCALENDAR-306
>             Project: OASIS Web Services Calendar (WS-Calendar) TC
>          Issue Type: Bug
>    Affects Versions: pr02
>         Environment: William Cox
>            Reporter: William Cox
>            Assignee: Toby Considine
>
> Section 1 line 2 and the rest of the specification:
> Change "Semantic Model" to "information model" throughout the document
> Footnote 2 and 4 page 9
> Footnote is repeated. Note that only the first use a a registered trademark could or should be footnoted. 
> Footnote 3 page 9
> Is OPC UA a trademark? If not, why is it footnoted?
> Lines 1-2
> The emphasis on Web services seems strange; consider "The information model of WS-Calendar is intended to be used to define information payloads for Web services and Service-style interactions [SOA-RM]."
> Sentence starting line 4:
> "Agreement on when something should or did occur is fundamental to negotiating service use."
> Line 13
> "agent" has many meanings. Perhaps "actor" would be a better choice? Agency is not what's suggested here.
> Cover and starting on line 59:
> The RFCs listed seem to be out of sync (in the normative references. Verify that current dates are used; Vavailability has been recently updated.
> Why are there normative references to WS-Management, WS-Security, DP-WS, XRD, and others including e.g. lines 71, 74, and more?  If there is no use of something in a document it seems strange to label it a normative reference.
> Can you have a normative reference to a non-normative document? e.g. line 93. Date also seems off.
> DP-WS has a hyphen on line 24 and not on line 64
> Line 34 there is no reference for [EITC] and [EMIX]; these should be non-normative references. Likewise EDXL and oBIX on lines 35-36
> Lines 43-48: the intent matters less that what is produced in the document in our hands.
> Line 49 delete "(WS-Calendar)" This paragraph is out of date; the schemas contain all of xcal as updated, so what the "document" might not prevent is something that is explicitly in and required by the schemas for PR02. Rewrite this paragraph to reflect the current reality.
> Line 59
> Is Calendar Resource Schema truly a normative reference? Where is it cited or used?
> Line 105
> Is the "Draft xCal" superseded by the contributions and the work in the schemas that are part of this work product? Reword.
> Line 119
> The reference should be something like [NIST Framework] - the title has been turned into a reference shorthand by bolding it. Other places this happened is on lines 59, 105 (should be [xCal Draft]), 119, 124, 131,, and maybe 136.
> Line 124 
> I believe that this should be [NAESB_PAP04] and reference both the first and second release.
> Line 147
> Replace "An ancillary..." with "An additional..." or "Another...". (mild preference)
> Line 180
> Capitalization is variable, look at VTODO and vtodo in the first two lines.  
> There is no normative reference to which [XCAL] is connected. Perhaps "xCAL Draft" is what's meant?
> For Gluon add in definition a footnote "Sometimes referred to as a Calendar Gluon". Or correct use of "Calendar Gluon" in the rest of the document to "Gluon" [preferred].
> Line 205
> Compare this first paragraph with e.g. line 43 which talks about what the intent was; this paragraph is in better voice describing how the work was produced.
> Line 223
> The section title again may lead to confusion between whether this is an information model or a service definition. it is the former; and time semantics are not critical to JUST WS-Calendar.  Please reconsider the focus and message of this paragraph.
> line 234
> Footnote 6 should have an informative reference [SOA-RM] rather than the "...found in the normative references..." wording.  Add [SOA-RM] reference on line 227.
> Line 253 "start at a particular instant of time UTC" does not read well. Where is a definition of the acronym UTC? Starting with what is UTC (a single sentence) would make the rest of this section more clear. Is there a normative reference or informative reference?
> Line 303
> "Duration" was defined on line 180, and should be capitalized. "schedule" is not defined and should be (and might be as "Schedules" on line 1020). "time" is not defined and probably shouldn't be.  
> Line 343
> "granularity" is not title case; capitalize.
> All:
> Ensure that defined or called out terms (e.g. Duration, Schedule, ...) are uniformly capitalized and that non-defined terms are not.
> Line 344
> This discussion is weakened by the lack of either italics or quotation marks around the strings such as "1M". Are the parentheses part of the string? or is (1M) a format definition? If the latter there should be a normative reference (I think they're as defined in ISO 8601 BTW)
> Line 354-356
> We have Intervals, now we have Time Segments? I don't find a definition, and it seems very similar.  
> Change "are a critical component of service alignment using WS-Calendar" to "are a critical way to describe service coordination."
> The final sentence is incomprehensible as written. And it uses "time segment" which was capitalized in the first sentence. And how are "terms about time" contained "within a particular time segment"?!
> Line 362
> An Interval is NOT a "unit of service delivery." It's a span of time. The description of "bound to time" should reference "Bound" in table 1-6, and should reference those Semantics Decribing Intervals"
> Line 369
> "Linked to a specific date and time" should be "Bound to a specific [date and] time" The word "tied" could be used, but you've already defined Bound.
> Line 370
> This sentence conflates WS-Calendar, iCalendar, xCal, AND talks about a WS-Calendar MESSAGE. This is an INFORMATION MODEL. Fix this sentence.
> Line 1321
> Why is "Service Advertisements" in the heading? This is more than just "service adv" - should this be "describing" or "managing" "start times"?
> On 1322, you usually write "start date and time". On 1323 "start-times" is hyphenated, but not elsewhere.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira