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

[Kazuhiro Funakoshi <k-f@bk.jp.nec.com>]

Arthur,

OK, I tried using ReSpec[1] as Steve suggested. The result is in our trunk.
Workflow should be also changed as [2] and dotlit is not required any
more(same for npm, nvm).

I still use Markdown in these documents for editing. However, now no Turtle
blocks or Markdown tables we need. Turtle files are now first class citizen
and tables are automatically generated as html with ReSpec. This means no
consistency problems left. This is done by adding that div block into
Markdown and HTML headers are automatically inserted with my pandoc.sh(I
changed it to include header.html at end of HTML header block).

BTW, I met a thing is, Steve's ReSpec seems not accepts multiple oslc:range
properties. Is this a correct behavior to ResourceShape 2.0? Because
oslc:range seems not said to be oslc:Zero-or-one, and we have a property as
promcode:producedFor from Artifact toward either ScopeItem or WorkItem.

[1] e.g.
http://tools.oasis-open.org/version-control/browse/wsvn/oslc-promcode/shape/
trunk/Artifact.html
[2] https://wiki.oasis-open.org/oslc-promcode/shape/readme

-- 
Kaz

-----Original Message-----
From: oslc-promcode@lists.oasis-open.org
[mailto:oslc-promcode@lists.oasis-open.org] On Behalf Of Arthur Ryman
Sent: Friday, November 28, 2014 1:51 AM
To: Funakoshi Kazuhiro(船越 和大)
Cc: Steve K Speicher; oslc-promcode@lists.oasis-open.org
Subject: RE: [oslc-promcode] Re: Fw: [oslc-core] Specification authoring
tools + usage of vocabs and shapes

Kaz,

Thanks for improving the wiki pages. I'd like to discuss markdown. See my
other reply about using XSLT to generate HTML from RDF.

I like literate programming, however it seems that with markdown, we need to
duplicate information, which causes a maintenance problem. The same
information appears both in the markdown table and the inlined Turtle.

With the XSLT approach, we can generate the HTML from the TTL source. This
means we can generate consistent wiki pages, e.g. including titles, links,
etc. Also, with XSLT we can easily add more columns to the table. Your
current shapes only specify a few of the properties. If we include more,
then the markdown tables will have to be manually edited. 

For example, I think we should include oslc:valueShape [1] where the range
of a property is a resource type defined by PROMCODE. You are currently
including oslc:range. When oslc:range specifies a type defined by PROMCODE,
then we should also include oslc:valueShape and provide a link to the shape
resource that describes the type. We need stable URIs for this purpose,
which is one reason I asked Chet how we could get stable URIs. To do this
right, we need a clean URI that is independent of the content type (ttl,
html, etc.). That clean URL should be the value of oslc:valueShape. We
should also implement server-based content negotiation, so when an HTML
agent requests the shape resource, it gets redirected to the wiki page. As a
tactical step, we could use the WSVN URI as the value of oslc:valueShape,
and write some XSLT logic to map that into a link to the wiki page URL when
we generate the HTML source.

With Steve's technology, we embed the TTL in a specification document, so
either approach works.

[1] http://www.w3.org/Submission/shapes/#valueShape
_________________________________________________________
Arthur Ryman
Chief Data Officer
SWG | Rational
905.413.3077 (phone) | 416.939.5063 (cell) IBM InterConnect 2015




From:   Kazuhiro Funakoshi <k-f@bk.jp.nec.com>
To:     Arthur Ryman/Toronto/IBM@IBMCA, Steve K Speicher 
<sspeiche@us.ibm.com>, "oslc-promcode@lists.oasis-open.org" 
<oslc-promcode@lists.oasis-open.org>
Date:   11/27/2014 01:34 AM
Subject:        RE: [oslc-promcode] Re: Fw: [oslc-core] Specification 
authoring tools + usage of vocabs and shapes
Sent by:        <oslc-promcode@lists.oasis-open.org>



Arthur and Steve,

Thank you for forwarding the email. It is a very good news for me.

I summed up my approach at [1]. It only reduces the cost of writing HTML.
However, the consistency between Turtle block and table written in Markdown
needs to be verified by human(yes, just a little bit easier than before
because they are in the same file). This means editing on them are easier
than before, but we still have risk to make inconsistent document.

In your approach, tables are automatically generated. This means no risk
left, but still need to write some HTML or wiki. So I think in our PROMCODE
TC, we can combine them as: (1)writing documents in Markdown, (2) and
generate tables and Turtle block from Turtle file to HTML, (3) then combine
them. At least, Turtle files and Markdown files should be version controlled
in this case. I will try this next time.

[1] https://wiki.oasis-open.org/oslc-promcode/shape/readme

--
Kaz

-----Original Message-----
From: oslc-promcode@lists.oasis-open.org
[mailto:oslc-promcode@lists.oasis-open.org] On Behalf Of Arthur Ryman
Sent: Thursday, November 27, 2014 4:40 AM
To: Steve K Speicher; oslc-promcode@lists.oasis-open.org
Subject: [oslc-promcode] Re: Fw: [oslc-core] Specification authoring tools 
+
usage of vocabs and shapes

Steve,

Thx for the pointer. This looks like it will be useful when it comes time to
producing the OASIS specification.

fyi, Kaz has been using Markdown, pandoc, and doclit to generate Turtle and
HTML. This partially overlaps with your tool. We could still use your tool
to generate HTML tables within the overall specification. I've asked Kaz to
create a writeup of his approach.
_________________________________________________________
Arthur Ryman
Chief Data Officer
SWG | Rational
905.413.3077 (phone) | 416.939.5063 (cell) IBM InterConnect 2015




From:   Steve K Speicher/Raleigh/IBM@IBMUS
To:     Arthur Ryman/Toronto/IBM@IBMCA
Date:   11/25/2014 05:32 PM
Subject:        Fw: [oslc-core] Specification authoring tools + usage of 
vocabs and shapes


This post to the PROMCODE list failed.  I think it has to do with me being
an observer and not a member of the list.

Anyway, if you don't mind please forwarding to the list and interested in
your feedback as well on this.

----- Forwarded by Steve K Speicher/Raleigh/IBM on 11/25/2014 05:31 PM
-----

From:   Steve K Speicher/Raleigh/IBM
To:     oslc-promcode@lists.oasis-open.org
Date:   11/25/2014 05:17 PM
Subject:        Fw: [oslc-core] Specification authoring tools + usage of 
vocabs and shapes


Hopefully your TC could find this tool as useful.  It is fairly limited on
documentation of the extensions currently provided, I've been trying to keep
the template spec complete with all the new features.

----- Forwarded by Steve K Speicher/Raleigh/IBM on 11/25/2014 05:15 PM
-----

From:   Steve K Speicher/Raleigh/IBM@IBMUS
To:     "OASIS OSLC Core TC Discussion List" 
<oslc-core@lists.oasis-open.org>
Date:   11/25/2014 05: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-vocabu

lary 


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

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


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 




---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

Attachment: smime.p7s
Description: S/MIME cryptographic signature