Issues for Mailing list of the Common Variability Language (CVL) 1.0 Finalization Task Force

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 18583: The Table of Contents (page v) has some unnecessary and out-of-place number 1s for the first few lines
Issue 18586: Compliance level
Issue 18587: Orphaned headings (such as Choice on page 2 and VConfiguration on page 3) should be avoided
Issue 18588: document refers to its numbered components as Chapters - call them clauses and subclauses
Issue 18589: 7.1 refers to the RFP. There is no need for a specification to discuss its own history
Issue 18590: typos
Issue 18591: In 7.3.8 would it also be correct to say allColor = Printer->forAll(p | p.color)?
Issue 18592: 7.3.10 uses the function max() which should be specified in clause 3
Issue 18593: The textual parts of the definitions in 8.3 refer to OCL when I think they should refer to BCL.
Issue 18594: CVL typos and minor editorials
Issue 18595: CVL Manual?
Issue 18596: Section 10.1.1.1.2
Issue 18597: Clause 10 has many indentation, spacing, punctuation and bolding errors
Issue 18598: Clause 10 needs a detailed review by a good English writer.
Issue 18599: More CVL typos
Issue 18600: Clause 10 should be an annex
Issue 18601: What is intended to be normative?
Issue 18602: Descriptions have a lot of text and are sometimes redundant
Issue 18603: Where in the spec does it say how a MOFRef string works?
Issue 18604: 1.2.34.23 has a lot of weird references. Also 11.2.44.2.
Issue 18605: 11.2.46.3 has a weird type.
Issue 18606: 11.2.47.3 types Real as TODO ERROR.
Issue 18607: Clauses 12-15 ought to be condensed into a single clause 0
Issue 18608: Kermeta is used in 16. There needs to be a reference to Kermeta in clause 3
Issue 18609: Editorial issues

Issue 18583: The Table of Contents (page v) has some unnecessary and out-of-place number 1s for the first few lines (cvl-ftf)

The Table of Contents (page v) has some unnecessary and out-of-place number 1s for the first few lines

Clause 2 specifies the compliance levels. It would be an improvement to the specification if each construct excluded by the high compliance level stated that fact locally

Orphaned headings (such as Choice on page 2 and VConfiguration on page 3) should be avoided

The document refers to its numbered components as Chapters – I think they ought to be called Clauses and Subclauses (especially if there are aspirations for becoming an ISO spec as suggested by 6.3). They are also occasionally called Sections and Subsections.  I think that top level clauses should start on new pages, and there should be no dangling paragraphs. I would recommend referring to ISO document rules and following them.

 

7.1 refers to the RFP. There is no need for a specification to discuss its own history.  So, just say “Figure 1 shows …”, and “CVL is executable …”.  Also some of section 7 is written using the royal “we”: it would be better to write it all consistently in a passive voice

In the first line of text under Figure 8 is an unnecessary “Fig.”

 

The last line of page 14 says “2 two”.

 

The constraint in Figure 11 incorrectly capitalizes Speed.

 

The paragraph after Figure 18 says “if an only if”.

In 7.3.8 would it also be correct to say allColor = Printer->forAll(p | p.color)?  If so it might be worth saying so, to emphasize further that color can be thought of as a logical (Boolean) property of each Printer

7.3.10 uses the function max(). Say that this function is defined in the OCL spec, and which one. In fact, clause 3 should specify this.

The textual parts of the definitions in 8.3 refer to OCL when I think they should refer to BCL.

The second paragraph of 7.5.5 contains an unnecessary “we”.

8.3.1.3 says “special a name”.

 

Under Figure 57 it says “we show en example”.

10.1.1 refers to “the CVL Manual”.  This is the first I’ve heard of this document.  There are several references to the manual in clause 10.  Reading on, it appears the the Manual is in fact clause 11.2.  Going back to 6.2, it does mention the manual.  But this is confusing.  Calling it the Manual somewhat impedes anybody from subsequently publishing a book called the CVL Reference Manual (as was done for UML).  I’d encourage you simply to refer to 11.2.  In the UML 2.5 spec, for what it is worth, the analogous generated part is called “Classifier Descriptions”.

10.1.1.1.2 has a “cvl” that should be capitalized. Also in that section, the notation “#” is used where a UML reader would expect to see “::”.

Clause 10 has many indentation, spacing, punctuation and bolding errors. Also suddenly we have heading numbering down to 7 levels, whereas earlier in the document we seemed to stop at 3.  Figure references in clause 10 are both number and caption, whereas in the rest of the document references are number only.

10.2 starts “On this part” meaning “In this part”.  Has the author changed in clause 10?  The English has deteriorated significantly.  Clause 10 needs a detailed review by a good English writer.

 

Figure 79 has a thick black line up it, on my screen and printer                                                                                                                     In clause 11.2, there are some occurrence of html markup like <br>.                                                                                                          11.2.8.5 and similar sections: Layout is dense, undifferentiated and very hard to read

Overall I am unconvinced that clause 10 is adding a great deal of value to this specification, and given its other problems listed above, I wonder if it would be better as an Annex.  Also 6.2 did not refer to clause 10 at all, saying to go to clause 16 to find the semantics.

Clause 11 is entitled “Mandatory CVL Normative Specifications”.  This begs the question of what else is intended to be normative.  Unless otherwise stated, the whole spec is normative. Perhaps some of the Annexes are informative?  You need to say. Annex B says it in its first sentence, but the heading of the Annex needs to say “Informative” if that is the case.

11.2.11.1 and similar sections: Description is a lot of text which is redundant with earlier descriptions.  These descriptions in the model should be terser and defer detail to the main explanation.  11.2.16.1 is a particularly bad example.

11.2.23.2 and 11.2.28.3. MOFRef is a string. Where in the spec does it say how this string works? If it doesn’t say, surely that is a severe impediment to interoperability?

1.2.34.23 has a lot of weird references. Also 11.2.44.2.

11.2.46.3 has a weird type.

11.2.47.3 types Real as TODO ERROR.

Clauses 12-15 ought to be condensed into a single clause 0, so they can easily be removed when the beta document is published without renumbering everything after them.

Kermeta is used in 16.  There needs to be a reference to Kermeta in clause 3.  I found 16.1 amost completely impenetrable, since I don’t know Kermeta. What relationship does clause 16 have to clause 10?

I would prefer Annex A’s headings to be A.1, A.1.1 etc rather than 16.1 etc. Similarly for B.                                                                      16.2.1.4 is empty.                                                                                                                                                                                                     The example after 16.2.1.6 ought to have a heading to be consistent with 16.2.1.5.
Steps of 16.2.1.9 are numbered starting at 6.
Figure 104 has messed-up layout – the diagrams need the compartments expanding, and the (b) class model caption is wrongly placed.