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

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

     [ http://tools.oasis-open.org/issues/browse/TOSCA-48?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Paul Lipton  updated TOSCA-48:
------------------------------

        Parent: TOSCA-10
    Issue Type: Sub-task  (was: Improvement)

> 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: Sub-task
>          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