[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] Commented: (TOSCA-48) Editorial hygiene part 1 - use correct xsd types and normative words
[ http://tools.oasis-open.org/issues/browse/TOSCA-48?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=31553#action_31553 ]
Thomas Spatzier commented on TOSCA-48:
---------------------------------------
Issue has been addressed in wd-13:
https://www.oasis-open.org/apps/org/workgroup/tosca/download.php/47312/latest
Suggest to close this issue if wd-13 is accepted.
> 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
> Affects Versions: CSD04
> Reporter: Doug Davis
> Priority: Trivial
> Fix For: CSD04
>
>
> 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]