#568 "How to edit the Guidelines" and chapter organization

[Martin Holmes]

The "How to edit the Guidelines" document (TCW20) has this in its section "Organization of the Guidelines chapters":

a <specGrp> for the whole module is given at the end of the chapter: 
it includes the other specifications either directly (by means of an 
entity reference) or indirectly (by means of a <specGrpRef> pointing 
to a preceding <specGrp> ).

One aspect of this -- the mention of entity references -- is now obsolete, and I'll change it to refer to the XIncludes we currently use. In addition, though, the AI chapter violates the pattern described here; its <specGrpRef>s are included not in a <specGrp> but in its <moduleSpec>. Rather than changing this directly, I'm raising a ticket in case anyone can remember how or why that came about; there might be some special circumstances I'm not aware of.

[Martin Holmes]

• Description has changed:

Diff:

--- old
+++ new
@@ -1,7 +1,10 @@
 The "How to edit the Guidelines" document (TCW20) has this in its section "Organization of the Guidelines chapters":

 ~~~~~
-a <specGrp> for the whole module is given at the end of the chapter: it includes the other specifications either directly (by means of an entity reference) or indirectly (by means of a <specGrpRef> pointing to a preceding <specGrp> ).
+a <specGrp> for the whole module is given at the end of the chapter: 
+it includes the other specifications either directly (by means of an 
+entity reference) or indirectly (by means of a <specGrpRef> pointing 
+to a preceding <specGrp> ).
 ~~~~~

 One aspect of this -- the mention of entity references -- is now obsolete, and I'll change it to refer to the XIncludes we currently use. In addition, though, the AI chapter violates the pattern described here; its `<specGrpRef>`s are included not in a `<specGrp>` but in its `<moduleSpec>`. Rather than changing this directly, I'm raising a ticket in case anyone can remember how or why that came about; there might be some special circumstances I'm not aware of.

[James Cummings]

Assigning to MartinH

[Lou Burnard]

The reference to entity references should certainly be replaced by a reference to xIncludes.

[Sebastian Rahtz]

The <specGrpRef>s are outside the <moduleSpec> in the AI chapter, so assuming this ticket can be closed. It does not appear to ever having been intentional that such thing should appear inside the moduleSpec