Re: [oslc-domains] Initial documentation for ReSpec conformance clause handling

["Jim Amsden" <jamsden@us.ibm.com>]

Nick,
I applied this to Attachments and it
works great!.  I had to remove class=conformance off some existing
sections that were marking large sections as conformance sections, rather
than individual paragraphs. Attachments used this convention to mark a
conformance clause:

        <section
id="attachment_update_descriptor">
         <h2></h2>

           
When servers update an attachment, they MUST also update any
           
affected <code>oslc:AttachmentDescriptor</code> properties
of the associated attachment descriptor.
        </section>

I decided to change these to:

        <p id="attachment_update_descriptor"
class="conformance">
           
When servers update an attachment, they MUST also update any
           
affected <code>oslc:AttachmentDescriptor</code> properties
of the associated attachment descriptor.
        </p>

so that section numbers weren't added
to the front of the conformance clause since that would be redundant with
the automatically generated reference number.

I added the following conformance clause
in the constraints section so that there would be once for the resource
shapes in the table.

<p class='conformance'>An OSLC
server providing the Attachments capability MUST implement the vocabulary
defined in this section.</p>


I also decided not to mark the clauses
with strength attributes and would prefer to have that column removed from
the table because its redundant with text in the clause itself, and some
have more than one MUST, MAY and/or SHOULD. I don't think we should require
different clauses for these.



Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 "Nicholas Crossley"
<nick_crossley@us.ibm.com>
To:      
 oslc-core@lists.oasis-open.org,
oslc-domains@lists.oasis-open.org
Date:      
 07/03/2018 04:53 AM
Subject:    
   [oslc-domains]
Initial documentation for ReSpec conformance clause handling
Sent by:    
   <oslc-domains@lists.oasis-open.org>

---

Fellow OSLC TC members,

As discussed in meetings last week, I spent some time updating ReSpec to
generate conformance sections and clauses, and I completed initial testing
of those changes early this week. One thing that I said I would do, but
have not, is to number the conformance clauses relative to the section
number in which they appear. I ran out of time to complete that work, so
the numbering is purely sequential across one entire source file. Since
such numbering is not stable anyway, it will not break anything if I improve
that in the future.

Formatting is done using CSS styles with a default stylesheet 'conformance.css'
built into ReSpec - if necessary, you could override those with styles
you provide.

I have not yet had time to convert/upload my notes on the changes to a
wiki, so I'm including them as a Word document attached to this email.
At some point, we should set up the OASIS ReSpec wiki - but possibly not
until we have a truly permanent home for it, not in my personal github
account.

Since we now have a ReSpec that can generate documents acceptable to OASIS
staff without considerable manual post-processing, and since the changes
in this new rev were quite significant, I have updated the version number
from 0.3.x to 1.0.0.

The last stable version in the 0.3.x line is 0.3.8. The versions 0.3.9
and 0.3.10 were intermediate builds for testing while running from the
github server, and should be ignored. If you want to revert, use 0.3.8.

I welcome comments, questions, and other feedback.

Nick.

[attachment "Conformance Clauses in ReSpec 1.docx" deleted by
Jim Amsden/Raleigh/IBM] [attachment "conformance.css" deleted
by Jim Amsden/Raleigh/IBM] 
---------------------------------------------------------------------
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