Re: [dita] Removing normative language for comments

["Robert D Anderson" <robander@us.ibm.com>]

Realized I didn't complete this paragraph --

We have similar requirements in the XSD topic (10) and RNG topic (3). These comments clearly do not meet the RFC guidelines. The only thing I could think of that might actually require these was Eliot's RNG->DTD/XSD tool

I meant to say - the only thing I could think of was that tool, but Eliot confirmed that it does not rely on the RNG comments to work.

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)

Robert D Anderson---01/30/2015 13:29:03---Hi, Kris and I are working through some of the DTD/XSD/RNG coding topics, as

From: Robert D Anderson/Rochester/IBM@IBMUS
To: DITA TC <dita@lists.oasis-open.org>
Date: 01/30/2015 13:29
Subject: [dita] Removing normative language for comments
Sent by: <dita@lists.oasis-open.org>

---

Hi,

Kris and I are working through some of the DTD/XSD/RNG coding topics, as mentioned at this week's TC.

One of the remaining issues is that we have a lot of normative rules regarding comments. As a reminder, per RFC 2119, "SHOULD" means that "the full implications must be understood and carefully weighed" before breaking a rule. Also, the term "SHOULD" is "only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm".

In the case of comments, this means according to our spec, even the removal of  must be carefully weighed because it has potential for causing harm. The single topic governing how to create a DTD Document type shell has 10 normative comment rules like this:

Topic shells SHOULD use the comment:

<!-- ============================================================= -->
<!--                    TOPIC ENTITY DECLARATIONS                  -->
<!-- ============================================================= -->  

That topic also says a shell SHOULD begin with a comment stating its purpose, and SHOULD include all the comments described later.

We have similar requirements in the XSD topic (10) and RNG topic (3). These comments clearly do not meet the RFC guidelines. The only thing I could think of that might actually require these was Eliot's RNG->DTD/XSD tool
	
If the TC agrees, I'd like to resolve this as follows:
* In the configuration section, state that the OASIS provided shells will include comments, so that they illustrate patterns and are easy to use as templates.
* Where we have other required comments - constraints, specializations, etc - do the same.
* Remove the 25 comment requirements from the Doctype Shell section
* Where we have other required comments, do the same

With the move of file names into one consolidated area, and the removal of comments, I think this will turn most of our coding topics into shorter lists of actual coding requirements, making them easier to explain and easier to follow.

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)