OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

tosca message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: [OASIS Issue Tracker] Updated: (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:all-tabpanel ]

Paul Lipton  updated TOSCA-48:

        Fix Version/s: CSD04
    Affects Version/s: CSD04

Strawpoll of 8/23 indicated that the editors should incorporate these suggestions (non-semantic) and to inform the TC of any issues and also of what WD will reflect these changes so that the TC can examine and/or close this issue. 

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