Re: [oslc-core] Specification authoring tools + usage of vocabs and shapes

[Nick Crossley <ncrossley@us.ibm.com>]

I've played with these as well, copying code from Steve's Core specs.  It is working well for my as-yet-unpublished Configuration Management revised draft.

Should we take an OASIS copy of http://sspeiche.github.io/respec/builds/oasis/respec-oasis-common.js into the Core SVN repo, or somewhere not OSLC-specific?

Nick.


Steve K Speicher---11/25/2014 02:13:22 PM---For some time and in various WGs, we've discussed whether certain items  are considered "spec" or no

From: Steve K Speicher/Raleigh/IBM@IBMUS
To: "OASIS OSLC Core TC Discussion List" <oslc-core@lists.oasis-open.org>
Date: 11/25/2014 02:13 PM
Subject: [oslc-core] Specification authoring tools + usage of vocabs and shapes
Sent by: <oslc-core@lists.oasis-open.org>

---

For some time and in various WGs, we've discussed whether certain items are considered "spec" or not.  It also has been desired to limit the amount of specification development we need to do, so we've done some work in the past to automate generation of human readable HTML tables from things such as OSLC Resource Shapes. 

I've completed some initial work (some more to do), that shows promise in automating this.  So I wanted to share the progress with you. 

Take for example this sample specification, namely these 2 sections: 
Shapes : http://sspeiche.github.io/respec/examples/oslc/template-spec.html#shape 
Vocabulary : http://sspeiche.github.io/respec/examples/oslc/template-spec.html#rdf-vocabulary 

To enable the first, all that is needed is to include the OASIS version of ReSpec and this bit of HTML: 

        <div title='RDF Shape for Template' 
                data-include='./template-spec-shape.ttl' 
                data-oninclude='shapeToSpec' 
                data-include-sync='true' 
                data-include-replace='true' 
                data-include-format='html'></div> 

and obviously provide the shape in Turtle format. 

Likewise for vocabulary definition, you can just do: 

        <div title='RDF Vocabulary for Template' 
                data-include='./template-spec-vocab.ttl' 
                data-oninclude='vocabToSpec' 
                data-include-sync='true' 
                data-include-replace='true' 
                data-include-format='html'></div>                 

This gives us great flexibility in being able to change the template and generation of the HTML without needing to go touch every spec under development.  Note, when we are ready to publish a document through the OASIS publication process it will be transformed to raw HTML and scripts removed. 

I've already started to use this in real specs and is looking to be a great aide http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/attachments-v3.html#resources 

Feedback welcome (positive, problems, ideas to make it better)  Not welcoming criticism of my JS skills, well maybe on a different thread. 

Thanks,
Steve Speicher
IBM Rational Software
OSLC - Lifecycle integration inspired by the web -> http://open-services.net