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


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-domains message

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

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

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

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

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.

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

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.


[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:

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