[OASIS Issue Tracker] Created: (TOSCA-48) Editorial hygiene part 1 - use correct xsd types and normative words

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

Editorial hygiene part 1 - use correct xsd types and normative words
--------------------------------------------------------------------

                 Key: TOSCA-48
                 URL: http://tools.oasis-open.org/issues/browse/TOSCA-48
             Project: OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC
          Issue Type: Improvement
          Components: Spec
            Reporter: Doug Davis 
            Priority: Trivial


Some editorial suggestions to clean the spec.  Might seem minor compared to the big issues
in front of us but these types of hygiene things really need to be done to make for a good spec.

From the proposal, here's the list of things I propose:
- put all types into italics - e.g.    "string" becomes "string"
- add "xs:" to all types - e.g.  "string" becomes "xs:string"
- for consistency put the *,+,? on the closing XML element instead of opening. E.g.  <foo>*..</foo> becomes <foo> ... </foo>*   
- add text make it clear that these "Syntax" blocks are "pseudo schema not real schema
- Allow for the possibility of non-XML formats by using "XML" in the names of the pseudo schema sections
- likewise, when describing the bits of the doc don't use XML terms, use generic terms like properties. This will make it easier when/if we create non-XML versions of things.
- when describing the various properties of the doc use normative language - REQUIRE, OPTIONAL, ...
- put normative keywords in CAPS so we know we used that word on purpose
- add number numbers to all XML snippets .  Not all have them. Also, to align things make the numbering 01 not just 1 (add leading zero)

I've uploaded a version of the doc that shows these edits for one section so people can see the
edits as they would appear if adopted.

proposal is here:  https://www.oasis-open.org/apps/org/workgroup/tosca/download.php/46597/TOSCA-v1.0-wd09-dug.doc

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