[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] Commented: (TOSCA-10) Bucket for all Purely Editorial Suggestions (e.g., spelling, grammar)
[ http://tools.oasis-open.org/issues/browse/TOSCA-10?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=31231#action_31231 ]
Paul Lipton commented on TOSCA-10:
-----------------------------------
OASIS staff on September 20th provided the following analysis and suggestions for the next CSD. If there are problems complying with these directives, please contact the co-chairs and/or bring those to the attention of the TC during the editor's report. Otherwise, we will assume that the editors will comply. Thanks in advance.
During the processing for the recently-published CSD04, we noted a few things you'll probably want to fix:
- Document was delivered with change tracking on and comments. For publication, we need to have a "final" version, with all changes accepted and comments removed. The best practice would be for TC members to have access to the change-marked version for their use in evaluating the correctness of the fixes, but for the TC to actually vote on a separate "final" version which has been uploaded to Kavi prior to the approval vote.
- Use of real business domain names in examples:
Line 998 www.sample.com/BillingPractice. (use "example" instead of "sample", which is a real web site.)
This is the only instance left in the spec of such use -
Otherwise, the Editors did a great job of cleaning up those other references to real company URIs.
Three comments on the References section:
- References to OASIS documents are generally not in OASIS Citation format (see the "Citation format" block on the second page for preferred format)
- For [BPEL 2.0] the title of the document (OASIS Web Services Business Process Execution Language
(WS-BPEL) 2.0) actually is a link to http://docs.oasis-open.org/wsbpel/2.0/wsbpel-specification-draft.html .
Following that is the link to the document the TC apparently intended to link to:
http://docs.oasis-open.org/wsbpel/2.0/wsbpel-v2.0.pdf . In the source, the title and underlying link
are black, which makes this not so noticeable unless you happen to hover over the title and see that
underlying link.
Solution: Remove the spurious link in the title and change the referenced document title text to plain text.
- Similar problem for [XML Namespaces]. The title is hot linked to
http://www.w3.org/TR/2001/REC-xml-infoset-20011024/ whereas the actual link to the document
is given as http://www.w3.org/TR/REC-xml-names/
This is the case again for [XML Infoset] where the title of the document is a hot link
(duplicating the visible link) but in this cases no harm done as the proper link target is used.
- Section 12.3 contains several (at least 5) references to .../ns/tosca/... The correct reference should be to .../tosca/ns/...
- There are some inconsistencies in the handling of the links from inline citations to items in "References". The links are scattered throughout the document.
Apparently, the links to references were not created consistently. One reviewer noted: [UNCEFACT XMLNDR] reference field is created as a REF, not a HYPERLINK, as is the [RFC2119] reference in that same section.
Examples of inline citations that are linked correctly:
[XML Namespaces]
#XMLNamespaces
[XML Base]
#XMLBase
[RFC 2396]
#RFC2396
examples which are not linked, or linked only to part of the in-line citations (examples)
[UNCEFACT XMLNDR]
[XML Schema Part 1]
[XML Schema Part 2]
NOte that only parts of the refernces in this extracted text are linked: "All information items defined by TOSCA are identified by one of the XML namespace URIs above [XML Namespaces]. A normative XML Schema [XML Schema Part 1, XML Schema Part 2] document for TOSCA can be obtained by dereferencing one of the XML namespace URIs.
In general, we expect the link to match the identifier strings, which should be equivalent to the citation label as given in the References (not just a portion of the citation label string).
***************
> Bucket for all Purely Editorial Suggestions (e.g., spelling, grammar)
> ----------------------------------------------------------------------
>
> Key: TOSCA-10
> URL: http://tools.oasis-open.org/issues/browse/TOSCA-10
> Project: OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC
> Issue Type: Task
> Components: Spec
> Reporter: Paul Lipton
> Assignee: Thomas Spatzier
>
> Initially, this issue was focused on "Metamodel entity names should be in monospaced typeface." It is now kept open as a general bucket for catching editorial changes that have no semantic import, but are purely textual, e.g., spelling, grammar, font, etc.
> Original monospaced font decision from approved motion made at TC meeting of March 1, 2012 (see meeting minutes at: http://www.oasis-open.org/apps/org/workgroup/tosca/download.php/45330/latest).
> Motion: Entity names from the metamodel in the spec should be specified in a monospaced typeface, such as New Courier.
--
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]